1 
  2 
  3 07/04/86  mmi_
  4 
  5 This subroutine primarily provides a means of retrieving information
  6 about a data base model (Mrds_Model_Interface_).  There is also an
  7 entry to create a data base in the same manner as the create_mrds_db
  8 command.  This interface replaces dmd_ which is obsolete.
  9 
 10 
 11 Entry points in mmi_:
 12        (List is generated by the help command)
 13 
 14 
 15 :Entry:close_model:  07/04/86  mmi_$close_model
 16 
 17 Function:  This entry closes a given opening of the data base model.
 18 
 19 
 20 Syntax:
 21 declare mmi_$close_model entry (char(*), fixed bin(35));
 22 call mmi_$close_model (opening_name, error_code);
 23 
 24 
 25 Arguments:
 26 opening_name (Input) (char(*))
 27    is the name given in the call to mmi_$open_model for the opening of
 28    the model that is to be closed.
 29 error_code (Output) (fixed bin(35))
 30    is a standard status code.  If the name given does not refer to a
 31    current model opening, the code mrds_error_$open_name_not_known will
 32    be returned.
 33 
 34 
 35 :Entry:create_db:  07/04/86 mmi_$create_db
 36 
 37 Function:  This entry provides a go/no-go subroutine interface to
 38 create_mrds_db.
 39 
 40 
 41 Syntax:
 42 declare mmi_$create_db entry options (variable);
 43 call mmi_$create_db ("source_path", {"db_path",} {"-list",}
 44    {"-secure",} {"-temp_dir", "temp_dir_path",} {"-force"} code);
 45 
 46 
 47 Notes:  where the arguments are the same character string arguments as
 48 given at command level to the create_mrds_db command except that code
 49 must be declared fixed bin(35).  The same option and features are
 50 available.  However, the error code of the first error encountered is
 51 returned since it is a go/no-go interface.
 52 
 53 
 54 Since create_mrds_db was written for command level, some of its error
 55 codes do not provide much detail.  Therefore, a listing should be
 56 requested to provide full information.
 57 
 58 
 59 If the -temp_dir {path} is given, path should be a separate character
 60 string argument from "-temp_dir".
 61 
 62 
 63 If character variables rather than constants are used in the call to
 64 mmi_$create_db, then trailing blanks should be suppressed (e.g., with
 65 the PL/I built-in "rtrim", described in the PL/I Language
 66 Specification).
 67 
 68 
 69 :Entry:get_authorization:  07/04/86  mmi_$get_authorization
 70 
 71 Function:  This entry returns the user class of the caller for a given
 72 data base.
 73 
 74 
 75 Syntax:
 76 declare mmi_$get_authorization entry (char(*), ptr, fixed bin, ptr,
 77    fixed bin(35));
 78 call mmi_$get_authorization (database_path, area_ptr,
 79    structure_version, mrds_authorization_ptr, error_code);
 80 
 81 
 82 Arguments:
 83 database_path (Input) (char(*))
 84    is the relative or absolute pathname of the data base, with or
 85    without the .db suffix.  This path must refer to a version 4 data
 86    base.
 87 area_ptr (Input) (pointer)
 88    is a pointer to a freeing area supplied by the caller in which the
 89    mrds_authorization structure is to be allocated.
 90 structure_version (Input) (fixed bin)
 91    is the desired structure version the user wishes to have returned.
 92 mrds_authorization_ptr (Output) (pointer)
 93    is a pointer to the allocated structure.  This structure is
 94    described in the Notes below.
 95 
 96 
 97 error_code (Output) (fixed bin(35))
 98    is a standard status code.  It may be one of the following;
 99    error_table_$area_too_small
100       if the supplied area could not contain the mrds_authorization
101       structure.
102    error_table_$badcall
103       if the area_ptr was null.
104    mrds_error_$no_data base
105       if the given path does not refer to a MRDS data base.
106    mrds_error_$not_freeing_area
107       if the supplied area does not have the attribute "freeing".
108    error_table_$unimplemented_version
109       if the given structure version is unknown.
110 
111 
112    mrds_error_$version_not_supported
113       if the data base path does not refer to a version 4 MRDS data
114       base.
115 
116 
117 Notes:  The user class information for the specified data base is
118 returned in the following structure;
119 
120 declare 1 mrds_authorization aligned
121           based (mrds_authorization_ptr),
122         2 version fixed bin,
123         2 administrator bit(1) unal,
124         2 normal_user bit(1) unal,
125         2 mbz bit(34) unal;
126 
127 
128 :Entry:get_model_attributes:  07/04/86  mmi_$get_model_attributes
129 
130 Function:  This entry returns attribute information for a particular
131 relation in the data base model.
132 
133 
134 Syntax:
135 declare mmi_$get_model_attributes entry (char(*), char(*), ptr,
136    fixed bin, ptr, fixed bin(35));
137 call mmi_$get_model_attributes (opening_name, relation_name, area_ptr,
138    structure_version, mrds_db_model_rel_attrs_ptr, error_code);
139 
140 
141 Arguments:
142 opening_name (Input) (char(*))
143    is the name used in the call to mmi_$open_model.
144 relation_name (Input) (char(*))
145    is the name of the relation for which the attribute information is
146    desired.
147 area_ptr (Input) (pointer)
148    is a pointer to a user-supplied freeing area in which the attribute
149    information will be allocated.
150 structure_version (Input) (fixed bin)
151    is the desired version of the attribute information structure to be
152    allocated.
153 mrds_db_model_rel_attrs_ptr (Output) (pointer)
154    is a pointer to the allocated attribute information structure
155    described in the Notes below.
156 
157 
158 error_code (Output) (fixed bin(35))
159    is the standard status code.  It may be one of the following:
160    error_table_$area_too_small
161       if the supplied area could not hold the attribute information
162       structure.
163    error_table_$badcall
164       if the area_ptr was null.
165    error_table_$unimplemented_version
166       if the structure version given was unknown.
167    mrds_error_$no_model_access
168       if the user does not have "r" access to the relation model
169       segment for the given relation.
170    mrds_error_$no_model_rel
171       if the relation name given is not in the model definition.
172 
173 
174    mrds_error_$not_freeing_area
175       if the supplied area does not have the attribute "freeing".
176    mrds_error_$open_name_not_known
177       if the name given does not refer to a current model opening.
178 
179 
180 Notes:  The attribute information is returned in the following
181 structure:
182 declare 1 mrds_db_model_rel_attrs aligned
183           based (mrds_db_model_rel_attrs_ptr),
184         2 version fixed bin,
185         2 attribute_count fixed bin,
186         2 mbz1 bit(36) unal,
187         2 attribute (0
188           refer (mrds_db_model_rel_attrs.attribute_count)),
189           3 name char(32),
190           3 domain char(32),
191           3 user_data_type bit(36),
192           3 indexed bit(1) unal,
193           3 mbz2 bit(35) unal;
194 
195 
196 If the data base is secured, this interface is only usable by a DBA.
197 If the data base is not secured, the user must have "r" access to the
198 model segment for the relation involved.
199 
200 
201 :Entry:get_model_info:  07/04/86  mmi_$get_model_info
202 
203 Function:  This entry returns information about the data base model
204 creation.
205 
206 
207 Syntax:
208 declare mmi_$get_model_info entry (char(*), ptr, fixed bin, ptr,
209    fixed bin(35));
210 call mmi_$get_model_info (opening_name, area_ptr, structure_version,
211    mrds_db_model_info_ptr, error_code);
212 
213 
214 Arguments:
215 opening_name (Input) (char(*))
216    is the name used in the call to mmi_$open_model.
217 area_ptr (Input) (pointer)
218    is a pointer to a user-supplied freeing area in which the model
219    information will be allocated.
220 structure_version (Input) (fixed bin)
221    is the desired structure version of the model information.
222 mrds_db_model_info_ptr (Output) (pointer)
223    the pointer to the allocated model information structure as
224    described in the Notes below.
225 
226 
227 error_code (Output) (fixed bin(35))
228    is the standard status code.  It may be one of the following:
229    error_table_$area_too_small
230       if the area could not hold the model information structure.
231    error_table_$badcall
232       if the area_ptr was null.
233    error_table_$unimplemented_version
234       if the supplied structure version is unknown.
235    mrds_error_$no_model_access
236       if the user does not have "r" access to the db_model segment.
237    mrds_error_$not_freeing_area
238       if the supplied area does not have the attribute "freeing".
239    mrds_error_$open_name_not_known
240       if the opening_name does not refer to a current model opening.
241 
242 
243 Notes:  The model information is returned in the following structure:
244 declare 1 mrds_db_model_info aligned,
245         2 version fixed bin,
246         2 model_version fixed bin,
247         2 db_type fixed bin,
248         2 dmfile_ attributes,
249           3 protected bit(1) unal,
250           3 rollback bit(1) unal,
251           3 concurrency bit(1) unal,
252           3 mbz bit(33) unal,
253         2 creator_id char(32),
254         2 creation_time fixed bin(71);
255 
256 
257 The latest version of the structure is version 2.  Programs using the
258 version 1 structure will continue to execute correctly.
259 
260 
261 If the data base is secured, this interface is only usable by a DBA.
262 If the data base is not secured, the user must have "r" access to the
263 db_model segment under the data base directory.
264 
265 
266 :Entry:get_model_relations:  07/04/86  mmi_$get_model_relations
267 
268 Function:  This entry returns information about all the relations in
269 the given model opening.
270 
271 
272 Syntax:
273 declare mmi_$get_model_relations entry (char(*), ptr, fixed bin, ptr,
274    fixed bin(35));
275 call mmi_$get_model_relations (opening_name, area_ptr,
276    structure_version, mrds_db_model_relations_ptr, error_code);
277 
278 
279 Arguments:
280 opening_name (Input) (char(*))
281    is the name used in the call to mmi_$open_model.
282 area_ptr (Input) (pointer)
283    is a pointer to a user-supplied freeing area in which the relation
284    information will be allocated.
285 structure_version (Input) (fixed bin)
286    is the desired structure version of the relation information.
287 mrds_db_model_relations_ptr (Output) (pointer)
288    is the pointer to the allocated structure of relation information in
289    the form described in Notes below.
290 
291 
292 error_code (Output) (fixed bin(35))
293    is the standard status code.  It may be one of the following:
294    error_table_$area_too_small
295       if the area could not hold the relation information.
296    error_table_$badcall
297       if the area_ptr was null.
298    error_table_$unimplemented_version
299       if the given structure version is unknown.
300    mrds_error_$no_model_access
301       if the user does not have "r" access to the db_model segment.
302    mrds_error_$not_freeing_area
303       if the supplied area does not have the attribute "freeing".
304    mrds_error_$open_name_not_known
305       if the opening_name does not refer to a current model opening.
306 
307 
308 Notes:  The relation information is returned in the following
309 structure:
310 declare 1 mrds_db_model_relations aligned
311           based (mrds_db_model_relations_ptr),
312         2 version,
313         2 relation_count fixed bin,
314         2 mbz1 bit(36) unal,
315         2 relation (0
316           refer (mrds_db_model_relations.relation_count)),
317           3 name char(32),
318           3 mbz2 bit(36) unal;
319 
320 
321 Currently, the only structure version available is 1.
322 
323 
324 If the  data base is secured, this  interface is usable only by  a DBA.  If
325 the  data base is  not secured, the  user must have  "r" access to  the
326 db_model segment under the data base directory.
327 
328 
329 :Entry:get_secured_state:  07/04/86  mmi_$get_secured_state
330 
331 Function:  This entry returns the secured state of the given data base.
332 
333 
334 Syntax:
335 declare mmi_$get_secured_state entry (char(*), ptr, fixed bin,
336    ptr, fixed bin(35));
337 call mmi_$get_secured_state (database_path, area_ptr,
338    structure_version, database_state_ptr, error_code);
339 
340 
341 Arguments:
342 database_path (Input) (char(*))
343    is the relative or absolute pathname of the data base whose secured
344    state is desired.  It must refer to a version 4 data base.  The
345    suffix need not be present.
346 area_ptr (Input) (pointer)
347    is a pointer to a user-supplied freeing area in which the data base
348    state information will be allocated.
349 structure_version (Input) (fixed bin)
350    is the desired version of the structure containing data base state
351    information.
352 database_state_ptr (Output) (pointer)
353    the pointer to the allocated data base state information as
354    contained in the structure described in the Notes below.
355 
356 
357 error_code (Output) (fixed bin(35))
358    is the standard status code.  It may be one of the following:
359    error_table_$area_too_small
360       if the supplied area could not hold the data base state
361       information.
362    error_table_$badcall
363       if the area_ptr was null.
364    error_table_$insufficient_access
365       if the user has no access to both the data base directory and the
366       db_model segment.
367    error_table_$unimplemented_version
368       if the supplied structure version is unknown.
369    mrds_error_$no_data base
370       if the given path does not refer to a MRDS data base.
371 
372 
373    mrds_error_$no_model_access
374       if the user does not have "r" access to the data base db_model
375       segment.
376    mrds_error_$not_freeing_area
377       if the supplied area does not have the attribute "freeing".
378    mrds_error_$version_not_supported
379       if the path given is to a data base whose version is less than 4.
380 
381 
382 Notes The data base state information is returned in the following
383 structure:
384 declare 1 database_state aligned
385           based (database_state_ptr),
386         2 version fixed bin,
387         2 unsecured bit(1) unal,
388         2 secured bit(1) unal,
389         2 mbz bit(34) unal;
390 
391 
392 Currently, the only structure version available is one.
393 
394 
395 :Entry:open_model:  07/04/86  mmi_$open_model
396 
397 Function:  This entry opens the data base model for retrieving
398 information about relations, attributes, and creation of the model.
399 There may be multiple openings of the same data base model or different
400 data base models.
401 
402 
403 Syntax:
404 declare mmi_$open_model entry (char(*), char(*), fixed bin(35));
405 call mmi_$open_model (database_path, opening_name, error_code);
406 
407 
408 Arguments:
409 database_path (Input) (char(*))
410      is the relative or absolute pathname of the data base, whose data
411      model is to be opened.  Version 4 data bases need not have the .db
412      suffix supplied.
413 opening_name (Input) (char(*))
414      a user-supplied name, to be used in other mmi_ calls referencing
415      this opening when obtaining model information.
416 
417 
418 error_code (Output) (fixed bin(35))
419      is the standard status code.  It may be one of the following:
420    error_table_$insufficient_access
421         if the data base has been secured and the user is not a DBA.
422    mrds_error_$no_database
423         if no data base exists at the given pathname.
424    mrds_error_$no_model_access
425         if the user does not have "r" access to the data base model
426         segment.
427    mrds_error_$open_name_already_known
428         if the opening_name supplied was not unique, within PL/I
429         comparison rules, compared to other opening names already used
430         in the user's process.
431 
432 
433    mrds_error_$too_many_open_names
434         if the combined lengths and number of opening_names used in the
435         user's process exceeded the storage capability of the open name
436         manager.
437 
438 
439 Notes:  The opening_name may be any number of ASCII characters.
440 Current capability is for more than 1000 opening_names of reasonable
441 length for version 4 models, but only 64 for models of version 3.
442 Opening_names must be unique to PL/I comparison rules within the user's
443 process.  (The entry unique_chars_, described in MPM Subroutines, can
444 be used to generate unique names.)
445 
446 
447 If the data base is secured, this interface is only usable by a DBA.
448 If the data base is not secured, the user must have at least "r" access
449 to the db_model segment under the data base directory.
450 
451 
452 :Entry:quiesce_db:  07/04/86  mmi_$quiesce_db
453 
454 Function:  This entry allows the DBA to quiesce a given data base for
455 such purposes as data base backup or other exclusive activities that
456 require a consistent and non-active data base.  The data base can be
457 returned to a non-quiescent state by use of the mmi_$unquiesce_db
458 entrypoint.
459 
460 
461 Syntax:
462 declare mmi_$quiesce_db entry (char(*), fixed bin(17), fixed bin(35));
463 call mmi_$quiesce_db (database_path, wait_time, error_code);
464 
465 
466 Arguments:
467 database_path        (Input) (char(*))
468    is the relative or absolute pathname of the data base to be
469    quiesced.  Version 4 data bases need not have the db suffix
470    supplied.
471 wait_time (Input) (fixed bin(17))
472    sets the amount of time that an attempt to quiesce waits for
473    conflicting data base users to depart before failing (see "Notes").
474 error_code (Output) (fixed bin(35))
475    is the standard status code.
476 
477 
478 Notes:  Time specified for wait_time is in seconds.  A long wait is
479 needed if the data base is open by many users; otherwise, a short
480 wait_time will suffice.  For a simple go/nogo test, give a wait_time of
481 1 second.
482 
483 
484 :Entry:unquiesce_db:  07/04/86  mmi_$unquiesce_db
485 
486 Function:  This entry returns a data base that is in a quiescent state
487 (by either mmi_$quiesce_db or the quiesce_mrds_db command) to a
488 non-quiescent state.
489 
490 
491 Syntax:
492 declare mmi_$unquiesce_db entry (char(*), fixed bin(35));
493 call mmi_$unquiesce_db (database_path, error_code);
494 
495 
496 Arguments:
497 database_path (Input) (char(*))
498    is the relative or absolute pathname of the data base to be freed.
499    Version 4 data bases need not have the db suffix supplied.
500 error_code (Output) (fixed bin(35))
501    is the standard status code.