1 03/05/82  inquire_
  2 
  3 The inquire_ subroutine provides an interface to the Inquire Personal
  4 User Database Manager.
  5 
  6 
  7 Entry points in inquire_:
  8    (List is generated by the help command.)
  9 
 10 
 11 :Entry: fields_from_userid: 02/06/82  inquire_$fields_from_userid
 12 
 13 Function: Returns the values of the specified set of fields in the
 14 given user's Inquire entry.  If a particular field's privacy
 15 switch is set, a null string is returned for that value.
 16 
 17 
 18 Syntax:
 19 declare inquire_$fields_from_userid entry (char(*) var, ptr, ptr, ptr,
 20      fixed bin(35));
 21 call inquire_$fields_from_userid (userid, field_names_ptr, area_ptr,
 22      field_values_ptr, code);
 23 
 24 
 25 Arguments:
 26 userid
 27    is the userid of the user for whom data is being requested.  (Input)
 28 field_names_ptr
 29    is a pointer to a standard inq_field_names structure, as declared in
 30    inquire_dcls.incl.pl1.  This specifies the set of fields whose
 31    values are to be returned.  (Input)
 32 area_ptr
 33    is a pointer to an area in which the return structure will be
 34    allocated.  It must not be null.  (Input)
 35 field_values_ptr
 36    is a pointer to a standard inq_field_values structure, as declared
 37    in inquire_dcls.incl.pl1, if the retrieval was successful.  This
 38    contains the values found in the selected fields of the specified
 39    user's entry, in the same order as specified in inq_field_names.
 40    (Output)
 41 code
 42    if positive it is a standard system error code.  If it is
 43    negative, then it is the index into inq_field_names of the
 44    first unrecognized field name.  (Output)
 45 
 46 
 47 Notes:  Because userids are unique in the Inquire database, there will
 48 only be one element in the entry array.
 49 
 50 
 51 :Entry: fields_from_lname:  02/08/82  inquire_$fields_from_lname
 52 
 53 
 54 Function:  This entry retrieves the values of a given set of fields
 55 from all the entries whose last_name field matches the specified last
 56 name.  If a particular field's privacy switch is set, a null string is
 57 returned for that value.
 58 
 59 
 60 Syntax:
 61 declare inquire_$fields_from_lname entry (char(*) var, ptr, ptr, ptr,
 62      fixed bin(35));
 63 call inquire_$fields_from_lname (last_name, field_names_ptr, area_ptr,
 64      field_values_ptr, code);
 65 
 66 
 67 Arguments:
 68 last_name
 69    is the last name to be matched against in the database.  (Input)
 70 field_names_ptr
 71    is a pointer to a standard inq_field_names structure, as declared in
 72    inquire_dcls.incl.pl1.  This specifies the set of fields whose
 73    values are to be returned.  (Input)
 74 area_ptr
 75    is a pointer to an area in which the return structure will be
 76    allocated.  It must not be null.  (Input)
 77 field_values_ptr
 78    is a pointer to a standard inq_field_values structure, as declared
 79    in inquire_dcls.incl.pl1, if the retrieval was successful.  This
 80    contains the values found in the selected fields of the specified
 81    users' entries, in the same order as specified in inq_field_names.
 82    (Output)
 83 code
 84    if positive it is a standard system error code.  If it is
 85    negative, then it is the index into inq_field_names of the
 86    first unrecognized field name.  (Output)
 87 
 88 
 89 :Entry: set_fields:  02/08/82  inquire_$set_fields
 90 
 91 
 92 Function:  Replaces the specified fields' values in the caller's
 93 entry.
 94 
 95 
 96 Syntax:
 97 declare inquire_$set_fields entry (ptr, ptr, fixed bin(35));
 98 call inquire_$set_fields (field_names_ptr, field_values_ptr, code);
 99 
100 
101 Arguments:
102 field_names_ptr
103    is a pointer to a standard inq_field_names structure, as declared in
104    inquire_dcls.incl.pl1.  This specifies the set of fields whose
105    values are to be modified.  (Input)
106 field_values_ptr
107    is a pointer to a standard inq_field_values structure, as declared
108    in inquire_dcls.incl.pl1, if the retrieval was successful.  This
109    contains the new values to be stored into the user's entry, in the
110    same order as specified in inq_field_names.  (Input)
111 code
112    if positive it is a standard system error code.  If it is
113    negative, then it is the index into inq_field_names of the
114    first unrecognized field name.  (Output)
115 
116 
117 Notes:  If the user does not have an entry, one will be created, and
118    the specified fields will be filled in.  The entry thus created will
119    have its privacy flag on, but the privacy switches of the fields
120    will all be off.
121 
122 
123 :Entry: delete_entry:  03/05/82  inquire_$delete_entry
124 
125 
126 Function:  Deletes the caller's entry from the Inquire database.
127 
128 
129 Syntax:
130 declare inquire_$delete_entry (fixed bin (35));
131 call inquire_$delete_entry (code);
132 
133 
134 Arguments:
135 code
136    Is a standard system error code.
137 
138 
139 :Entry: get_field_privacy_flags:  02/08/82  inquire_$get_field_privacy_flags
140 
141 
142 Function:  Returns the privacy flag settings for the given fields in
143 the caller's entry.
144 
145 
146 Syntax:
147 declare inquire_$get_field_privacy_flags entry (ptr, ptr, fixed
148      bin(35));
149 call inquire_$get_field_privacy_flags (field_names_ptr,
150      field_privacies_ptr, code);
151 
152 
153 Arguments:
154 field_names_ptr
155    is a pointer to a standard inq_field_names structure, as declared in
156    inquire_dcls.incl.pl1.  This specifies the set of fields whose
157    privacy flags will be returned.  (Input)
158 field_privacies_ptr
159    is a pointer to a standard inq_field_privacies structure, as
160    declared in inquire_dcls.incl.pl1.  It will be filled in with the
161    values of the privacy flags of the specified fields, in the order in
162    which they were specified in inq_field_names.  (Output)
163 code
164    if positive it is a standard system error code.  If it is
165    negative, then it is the index into inq_field_names of the
166    first unrecognized field name.  (Output)
167 
168 
169 Notes:  In the inq_field_privacies structure, a value of "1"b for a
170 privacy flag signifies that the field is private; a "0"b value means it
171 is public.
172 
173 
174 :Entry: set_field_privacy_flags: 02/08/82  inquire_$set_field_privacy_flags
175 
176 
177 Function:  Sets the privacy flags for the given fields in
178 the caller's entry.
179 
180 
181 Syntax:
182 declare inquire_$set_field_privacy_flags entry (ptr, ptr, fixed
183      bin(35));
184 call inquire_$set_field_privacy_flags (field_names_ptr,
185      field_privacies_ptr, code);
186 
187 
188 Arguments:
189 field_names_ptr
190    is a pointer to a standard inq_field_names structure, as declared in
191    inquire_dcls.incl.pl1.  This specifies the set of fields whose
192    privacy flags will be changed.  (Input)
193 field_privacies_ptr
194    is a pointer to a standard inq_field_privacies structure, as
195    declared in inquire_dcls.incl.pl1.  It contains the new
196    values of the privacy flags of the specified fields, in the order in
197    which they were specified in inq_field_names.  (Output)
198 code
199    if positive it is a standard system error code.  If it is
200    negative, then it is the index into inq_field_names of the
201    first unrecognized field name.  (Output)
202 
203 
204 Notes:  In the inq_field_privacies structure, a value of "1"b for a
205 privacy flag signifies that the field is private; a "0"b value means it
206 is public.
207 
208 
209 :Entry: get_entry_privacy_flag: 02/08/82  inquire_$get_entry_privacy_flag
210 
211 
212 Function:  Returns the value of the privacy flag for the caller's
213 entry.
214 
215 
216 Syntax:
217 declare inquire_$get_entry_privacy_flag entry (bit (1), fixed bin (35));
218 call inquire_$get_entry_privacy_flag (privacy_flag, code);
219 
220 
221 Arguments:
222 privacy_flag
223    The value of the privacy flag setting of the caller's entry.
224    If the  value is "1"b, then the entry is private.  (Output)
225 code
226    A standard system error code.
227 
228 
229 :Entry: set_entry_privacy_flag: 02/08/82  inquire_$set_entry_privacy_flag
230 
231 
232 Function:  Sets the value of the privacy flag of the caller's
233 entry.
234 
235 
236 Syntax:
237 declare inquire_$set_entry_privacy_flag entry (bit (1), fixed bin (35));
238 call inquire_$set_entry_privacy_flag (privacy_flag, code);
239 
240 
241 Arguments:
242 privacy_flag
243    The new value of the privacy flag setting of the caller's entry.
244    If the  value is "1"b, then the entry is private.  (Input)
245 code
246    A standard system error code.  (Output)
247 
248 
249 :Entry: get_all_userids: 02/09/82  inquire_$get_all_userids
250 
251 
252 Function:
253 Returns the userid fields of every non-private entry in the
254 Inquire database.
255 
256 
257 Syntax:
258 declare inquire_$get_all_userids entry (ptr, ptr, fixed bin,
259      fixed bin(35));
260 call inquire_$get_all_userids (area_ptr, userids_ptr,
261      userid_count, code);
262 
263 
264 Arguments:
265 area_ptr
266    is an area in which the userids will be allocated.  If it is
267    null, then no userids will be returned, although the
268    userid_count will be set.  (Input)
269 userids_pptr
270    is a pointer to the returned array of userids, as declared in
271    inquire_dcls.  This will not be set if the area_ptr is null.
272    (Output)
273 userid_count
274    is the number of elements in the userid array pointed to by
275    userids_ptr, or that would be returned had the area_ptr not
276    been null.  (Output)
277 code
278    is a standard system error code.
279 
280 
281 :Entry: close_db: 02/12/82  inquire_$close_db
282 
283 
284 Function: Close the Inquire database, which is normally kept open for
285 the entire process for efficiency.  Use of this entry should not
286 usually be necessary.
287 
288 
289 Syntax:
290 declare inquire_$close_db entry (fixed bin (35));
291 call inquire_$close_db (code);
292 
293 
294 Arguments:
295 code
296    is a standard system error code.
297 
298 
299 :Entry: close_db_no_code: 02/12/82  inquire_$close_db_no_code
300 
301 
302 Function: The same as the close_db entrypoint, except that no error
303 code is returned.
304 
305 
306 Syntax:
307 declare inquire_$close_db_no_code entry ();
308 call inquire_$close_db_no_code ();