07/04/86 mmi_ This subroutine primarily provides a means of retrieving information about a data base model (Mrds_Model_Interface_). There is also an entry to create a data base in the same manner as the create_mrds_db command. This interface replaces dmd_ which is obsolete. Entry points in mmi_: (List is generated by the help command) :Entry:close_model: 07/04/86 mmi_$close_model Function: This entry closes a given opening of the data base model. Syntax: declare mmi_$close_model entry (char(*), fixed bin(35)); call mmi_$close_model (opening_name, error_code); Arguments: opening_name (Input) (char(*)) is the name given in the call to mmi_$open_model for the opening of the model that is to be closed. error_code (Output) (fixed bin(35)) is a standard status code. If the name given does not refer to a current model opening, the code mrds_error_$open_name_not_known will be returned. :Entry:create_db: 07/04/86 mmi_$create_db Function: This entry provides a go/no-go subroutine interface to create_mrds_db. Syntax: declare mmi_$create_db entry options (variable); call mmi_$create_db ("source_path", {"db_path",} {"-list",} {"-secure",} {"-temp_dir", "temp_dir_path",} {"-force"} code); Notes: where the arguments are the same character string arguments as given at command level to the create_mrds_db command except that code must be declared fixed bin(35). The same option and features are available. However, the error code of the first error encountered is returned since it is a go/no-go interface. Since create_mrds_db was written for command level, some of its error codes do not provide much detail. Therefore, a listing should be requested to provide full information. If the -temp_dir {path} is given, path should be a separate character string argument from "-temp_dir". If character variables rather than constants are used in the call to mmi_$create_db, then trailing blanks should be suppressed (e.g., with the PL/I built-in "rtrim", described in the PL/I Language Specification). :Entry:get_authorization: 07/04/86 mmi_$get_authorization Function: This entry returns the user class of the caller for a given data base. Syntax: declare mmi_$get_authorization entry (char(*), ptr, fixed bin, ptr, fixed bin(35)); call mmi_$get_authorization (database_path, area_ptr, structure_version, mrds_authorization_ptr, error_code); Arguments: database_path (Input) (char(*)) is the relative or absolute pathname of the data base, with or without the .db suffix. This path must refer to a version 4 data base. area_ptr (Input) (pointer) is a pointer to a freeing area supplied by the caller in which the mrds_authorization structure is to be allocated. structure_version (Input) (fixed bin) is the desired structure version the user wishes to have returned. mrds_authorization_ptr (Output) (pointer) is a pointer to the allocated structure. This structure is described in the Notes below. error_code (Output) (fixed bin(35)) is a standard status code. It may be one of the following; error_table_$area_too_small if the supplied area could not contain the mrds_authorization structure. error_table_$badcall if the area_ptr was null. mrds_error_$no_data base if the given path does not refer to a MRDS data base. mrds_error_$not_freeing_area if the supplied area does not have the attribute "freeing". error_table_$unimplemented_version if the given structure version is unknown. mrds_error_$version_not_supported if the data base path does not refer to a version 4 MRDS data base. Notes: The user class information for the specified data base is returned in the following structure; declare 1 mrds_authorization aligned based (mrds_authorization_ptr), 2 version fixed bin, 2 administrator bit(1) unal, 2 normal_user bit(1) unal, 2 mbz bit(34) unal; :Entry:get_model_attributes: 07/04/86 mmi_$get_model_attributes Function: This entry returns attribute information for a particular relation in the data base model. Syntax: declare mmi_$get_model_attributes entry (char(*), char(*), ptr, fixed bin, ptr, fixed bin(35)); call mmi_$get_model_attributes (opening_name, relation_name, area_ptr, structure_version, mrds_db_model_rel_attrs_ptr, error_code); Arguments: opening_name (Input) (char(*)) is the name used in the call to mmi_$open_model. relation_name (Input) (char(*)) is the name of the relation for which the attribute information is desired. area_ptr (Input) (pointer) is a pointer to a user-supplied freeing area in which the attribute information will be allocated. structure_version (Input) (fixed bin) is the desired version of the attribute information structure to be allocated. mrds_db_model_rel_attrs_ptr (Output) (pointer) is a pointer to the allocated attribute information structure described in the Notes below. error_code (Output) (fixed bin(35)) is the standard status code. It may be one of the following: error_table_$area_too_small if the supplied area could not hold the attribute information structure. error_table_$badcall if the area_ptr was null. error_table_$unimplemented_version if the structure version given was unknown. mrds_error_$no_model_access if the user does not have "r" access to the relation model segment for the given relation. mrds_error_$no_model_rel if the relation name given is not in the model definition. mrds_error_$not_freeing_area if the supplied area does not have the attribute "freeing". mrds_error_$open_name_not_known if the name given does not refer to a current model opening. Notes: The attribute information is returned in the following structure: declare 1 mrds_db_model_rel_attrs aligned based (mrds_db_model_rel_attrs_ptr), 2 version fixed bin, 2 attribute_count fixed bin, 2 mbz1 bit(36) unal, 2 attribute (0 refer (mrds_db_model_rel_attrs.attribute_count)), 3 name char(32), 3 domain char(32), 3 user_data_type bit(36), 3 indexed bit(1) unal, 3 mbz2 bit(35) unal; If the data base is secured, this interface is only usable by a DBA. If the data base is not secured, the user must have "r" access to the model segment for the relation involved. :Entry:get_model_info: 07/04/86 mmi_$get_model_info Function: This entry returns information about the data base model creation. Syntax: declare mmi_$get_model_info entry (char(*), ptr, fixed bin, ptr, fixed bin(35)); call mmi_$get_model_info (opening_name, area_ptr, structure_version, mrds_db_model_info_ptr, error_code); Arguments: opening_name (Input) (char(*)) is the name used in the call to mmi_$open_model. area_ptr (Input) (pointer) is a pointer to a user-supplied freeing area in which the model information will be allocated. structure_version (Input) (fixed bin) is the desired structure version of the model information. mrds_db_model_info_ptr (Output) (pointer) the pointer to the allocated model information structure as described in the Notes below. error_code (Output) (fixed bin(35)) is the standard status code. It may be one of the following: error_table_$area_too_small if the area could not hold the model information structure. error_table_$badcall if the area_ptr was null. error_table_$unimplemented_version if the supplied structure version is unknown. mrds_error_$no_model_access if the user does not have "r" access to the db_model segment. mrds_error_$not_freeing_area if the supplied area does not have the attribute "freeing". mrds_error_$open_name_not_known if the opening_name does not refer to a current model opening. Notes: The model information is returned in the following structure: declare 1 mrds_db_model_info aligned, 2 version fixed bin, 2 model_version fixed bin, 2 db_type fixed bin, 2 dmfile_ attributes, 3 protected bit(1) unal, 3 rollback bit(1) unal, 3 concurrency bit(1) unal, 3 mbz bit(33) unal, 2 creator_id char(32), 2 creation_time fixed bin(71); The latest version of the structure is version 2. Programs using the version 1 structure will continue to execute correctly. If the data base is secured, this interface is only usable by a DBA. If the data base is not secured, the user must have "r" access to the db_model segment under the data base directory. :Entry:get_model_relations: 07/04/86 mmi_$get_model_relations Function: This entry returns information about all the relations in the given model opening. Syntax: declare mmi_$get_model_relations entry (char(*), ptr, fixed bin, ptr, fixed bin(35)); call mmi_$get_model_relations (opening_name, area_ptr, structure_version, mrds_db_model_relations_ptr, error_code); Arguments: opening_name (Input) (char(*)) is the name used in the call to mmi_$open_model. area_ptr (Input) (pointer) is a pointer to a user-supplied freeing area in which the relation information will be allocated. structure_version (Input) (fixed bin) is the desired structure version of the relation information. mrds_db_model_relations_ptr (Output) (pointer) is the pointer to the allocated structure of relation information in the form described in Notes below. error_code (Output) (fixed bin(35)) is the standard status code. It may be one of the following: error_table_$area_too_small if the area could not hold the relation information. error_table_$badcall if the area_ptr was null. error_table_$unimplemented_version if the given structure version is unknown. mrds_error_$no_model_access if the user does not have "r" access to the db_model segment. mrds_error_$not_freeing_area if the supplied area does not have the attribute "freeing". mrds_error_$open_name_not_known if the opening_name does not refer to a current model opening. Notes: The relation information is returned in the following structure: declare 1 mrds_db_model_relations aligned based (mrds_db_model_relations_ptr), 2 version, 2 relation_count fixed bin, 2 mbz1 bit(36) unal, 2 relation (0 refer (mrds_db_model_relations.relation_count)), 3 name char(32), 3 mbz2 bit(36) unal; Currently, the only structure version available is 1. If the data base is secured, this interface is usable only by a DBA. If the data base is not secured, the user must have "r" access to the db_model segment under the data base directory. :Entry:get_secured_state: 07/04/86 mmi_$get_secured_state Function: This entry returns the secured state of the given data base. Syntax: declare mmi_$get_secured_state entry (char(*), ptr, fixed bin, ptr, fixed bin(35)); call mmi_$get_secured_state (database_path, area_ptr, structure_version, database_state_ptr, error_code); Arguments: database_path (Input) (char(*)) is the relative or absolute pathname of the data base whose secured state is desired. It must refer to a version 4 data base. The suffix need not be present. area_ptr (Input) (pointer) is a pointer to a user-supplied freeing area in which the data base state information will be allocated. structure_version (Input) (fixed bin) is the desired version of the structure containing data base state information. database_state_ptr (Output) (pointer) the pointer to the allocated data base state information as contained in the structure described in the Notes below. error_code (Output) (fixed bin(35)) is the standard status code. It may be one of the following: error_table_$area_too_small if the supplied area could not hold the data base state information. error_table_$badcall if the area_ptr was null. error_table_$insufficient_access if the user has no access to both the data base directory and the db_model segment. error_table_$unimplemented_version if the supplied structure version is unknown. mrds_error_$no_data base if the given path does not refer to a MRDS data base. mrds_error_$no_model_access if the user does not have "r" access to the data base db_model segment. mrds_error_$not_freeing_area if the supplied area does not have the attribute "freeing". mrds_error_$version_not_supported if the path given is to a data base whose version is less than 4. Notes The data base state information is returned in the following structure: declare 1 database_state aligned based (database_state_ptr), 2 version fixed bin, 2 unsecured bit(1) unal, 2 secured bit(1) unal, 2 mbz bit(34) unal; Currently, the only structure version available is one. :Entry:open_model: 07/04/86 mmi_$open_model Function: This entry opens the data base model for retrieving information about relations, attributes, and creation of the model. There may be multiple openings of the same data base model or different data base models. Syntax: declare mmi_$open_model entry (char(*), char(*), fixed bin(35)); call mmi_$open_model (database_path, opening_name, error_code); Arguments: database_path (Input) (char(*)) is the relative or absolute pathname of the data base, whose data model is to be opened. Version 4 data bases need not have the .db suffix supplied. opening_name (Input) (char(*)) a user-supplied name, to be used in other mmi_ calls referencing this opening when obtaining model information. error_code (Output) (fixed bin(35)) is the standard status code. It may be one of the following: error_table_$insufficient_access if the data base has been secured and the user is not a DBA. mrds_error_$no_database if no data base exists at the given pathname. mrds_error_$no_model_access if the user does not have "r" access to the data base model segment. mrds_error_$open_name_already_known if the opening_name supplied was not unique, within PL/I comparison rules, compared to other opening names already used in the user's process. mrds_error_$too_many_open_names if the combined lengths and number of opening_names used in the user's process exceeded the storage capability of the open name manager. Notes: The opening_name may be any number of ASCII characters. Current capability is for more than 1000 opening_names of reasonable length for version 4 models, but only 64 for models of version 3. Opening_names must be unique to PL/I comparison rules within the user's process. (The entry unique_chars_, described in MPM Subroutines, can be used to generate unique names.) If the data base is secured, this interface is only usable by a DBA. If the data base is not secured, the user must have at least "r" access to the db_model segment under the data base directory. :Entry:quiesce_db: 07/04/86 mmi_$quiesce_db Function: This entry allows the DBA to quiesce a given data base for such purposes as data base backup or other exclusive activities that require a consistent and non-active data base. The data base can be returned to a non-quiescent state by use of the mmi_$unquiesce_db entrypoint. Syntax: declare mmi_$quiesce_db entry (char(*), fixed bin(17), fixed bin(35)); call mmi_$quiesce_db (database_path, wait_time, error_code); Arguments: database_path (Input) (char(*)) is the relative or absolute pathname of the data base to be quiesced. Version 4 data bases need not have the db suffix supplied. wait_time (Input) (fixed bin(17)) sets the amount of time that an attempt to quiesce waits for conflicting data base users to depart before failing (see "Notes"). error_code (Output) (fixed bin(35)) is the standard status code. Notes: Time specified for wait_time is in seconds. A long wait is needed if the data base is open by many users; otherwise, a short wait_time will suffice. For a simple go/nogo test, give a wait_time of 1 second. :Entry:unquiesce_db: 07/04/86 mmi_$unquiesce_db Function: This entry returns a data base that is in a quiescent state (by either mmi_$quiesce_db or the quiesce_mrds_db command) to a non-quiescent state. Syntax: declare mmi_$unquiesce_db entry (char(*), fixed bin(35)); call mmi_$unquiesce_db (database_path, error_code); Arguments: database_path (Input) (char(*)) is the relative or absolute pathname of the data base to be freed. Version 4 data bases need not have the db suffix supplied. error_code (Output) (fixed bin(35)) is the standard status code. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved