03/15/85 before_journal_manager_ The before_journal_manager_ subroutine provides the means to manipulate, and obtain information about, before journals. Before journals are used to store before images of protected data management (DM) files, for the purpose of rolling back modifications to these files in the event of failure. Entry points in before_journal_manager_: (List is generated by the help command) :Entry: close_bj: 03/15/85 before_journal_manager_$close_bj Function: This entry point closes the specified before journal, making it unavailable to the current process. A journal can be opened more than once in a process, in which case the same opening id is returned for each open request. In that case, the close operation merely decreases by one the number of journal openings in the process. If a close_bj request is issued by a process on a journal while the process still has an active transaction in that journal, the journal cannot be closed and an error code is returned to the caller. If the journal to be closed was the default before journal for the process, the before journal which was last opened in the process (if any) becomes the default before journal (see "Notes" under the set_default_bj entry). Syntax: declare before_journal_manager_$close_bj entry (bit(36) aligned, fixed bin(35)); call before_journal_manager_$close_bj (bj_opening_id, code); Arguments: bj_opening_id is the opening identifier of the before journal. (Input) code is a standard system error code. (Output) :Entry: create_bj: 03/15/85 before_journal_manager_$create_bj Function: This entry point creates a before journal file as specified by the input arguments. Syntax: declare before_journal_manager_$create_bj entry (char(*), char(*), fixed bin, fixed bin, fixed bin(35)); call before_journal_manager_$create_bj (dir_name, entry_name, n_control_intervals, control_interval_size, code); Arguments: dir_name is the pathname of the directory in which the before journal is to be created. (Input) entry_name is the entry name of the before journal to be created. The .bj suffix must be included. (Input) n_control_intervals is the size of the journal expressed in the number of control intervals. (Input) A before journal is a circular file; when information is no longer useful (i.e., before images for committed or aborted transactions), it will be overwritten, allowing the space to be reused. In estimating the size of a journal, you should consider the number of transactions to be using the journal simultaneously, as well as their profiles, i.e., their length in time and the rate at which they modify data, to optimize performance. control_interval_size is the size of the before journal control interval in number of bytes. (Input) The size is currently fixed at 4096. code is a standard system error code. (Output) :Entry: get_bj_path_from_oid: 03/15/85 before_journal_manager_$get_bj_path_from_oid Function: This entry point returns the directory pathname and the entry name of the specified before journal. For this operation to be successful, the before journal must be open in the current process. If a zero code is returned, the operation is successful and the dir_name and entry_name arguments are set to the proper values. If a nonzero code is returned, the operation did not succeed and the values of dir_name and entry_name are left unchanged. Syntax: declare before_journal_manager_$get_bj_path_from_oid entry (bit(36) aligned, char(*), char(*), fixed bin(35)); call before_journal_manager_$get_bj_path (bj_oid, dir_name, entry_name, code); Arguments: bj_oid is the opening identifier of the before journal for which the pathname is requested. (Input) dir_name is the pathname of the directory in which the before journal resides. (Output) entry_name is the entry name of the before journal. (Output) code is a standard system error code. (Output) :Entry: get_default_bj: 03/15/85 before_journal_manager_$get_default_bj Function: This entry point returns the opening identifier of the before journal to be used as the default in those cases where a before journal specification is expected but not supplied. The rules for determining this default before journal are described in "Notes" under the set_default_bj entry point. If the journal which is to serve as the default before journal is not open at the time of this call, it is opened automatically. Syntax: declare before_journal_manager_$get_default_bj entry (bit(36) aligned, fixed bin(35)); call before_journal_manager_$get_default_bj (bj_oid, code); Arguments: bj_oid is the opening identifier of the current default before journal. (Output) code is a standard system error code. (Output) :Entry: open_bj: 03/15/85 before_journal_manager_$open_bj Function: This entry point makes the before journal specified by the pathname, ready for use by any transaction of the current process. A process may have several before journals open at the same time, and may also have the same journal opened more than one time. When a transaction is started, one of the open journals must be associated with the transaction, if the transaction needs a before journal. One can expect that in most cases, a process will open only one before journal, which will be used by all its transactions. This entry may also change the default before journal for the process to the newly opened journal (see "Notes" under set_default_bj). Syntax: declare before_journal_manager_$open_bj entry (char(*), char(*), bit(36) aligned, fixed bin(35)); call before_journal_manager_$open_bj (dir_name, entry_name, bj_opening_id, code); Arguments: dir_name is the pathname of the directory in which the before journal to be opened resides. (Input) entry_name is the entry name of the before journal to be opened. The .bj suffix must be included (Input) bj_opening_id is the opening identifier of the journal. (Output) This specifier must be used subsequently by the current process to identify this journal. code is a standard system error code. (Output) Notes: When a before journal is opened, it is remembered in a per system table containing the pathnames and unique identifiers of all before journals opened in the system. This table is used after a system crash to determine which journals must be reopened and examined in order to perform a rollback operation. To preserve the integrity of this table, it is written out to disk automatically each time it is updated with a newly opened journal. If a process opens the same before journal more than one time, the opening identifier received from the open_bj will be the same for each call. The process must close a before journal the same number of times it opens it, to render the journal inaccessible through the same opening identifier. :Entry: set_default_bj: 03/15/85 before_journal_manager_$set_default_bj Function: This entry point causes the specified before journal to become the default before journal. When no before journal is explicitly specified by the user at the beginning of a transaction, the default before journal for the process will be assigned to the transaction. The default before journal must be one of the before journals open in the process. Syntax: declare before_journal_manager_$set_default_bj entry (bit(36) aligned, fixed bin(35)); call before_journal_manager_$set_default_bj (bj_opening_id, code); Arguments: bj_opening_id is the opening identifier of the before journal. (Input) code is a standard system error code. (Output) Notes: Several before_journal_manager_ entries expect an opening id to specify which before journal to use. If bj_opening_id is null, the following default assignments are attempted, in the order in which they are mentioned below, until one of them succeeds: The current default before journal in this process, if there is one; otherwise, The most recently open before journal among those that are still open, if there is one; otherwise, The system before journal. If the system before journal has not been opened yet in the current process, it is automatically opened. :Entry: set_transaction_storage_limit: 03/15/85 before_journal_manager_$set_transaction_storage_limit Syntax: declare before_journal_manager_$set_transaction_storage_limit entry (char (*), char(*), fixed bin (35), fixed bin (35)); call before_journal_manager_$set_transaction_storage_limit (dir_name, entryname, storage_limit, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the before journal. (Input) storage_limit is the maximum number of bytes a single transaction may use in the before journal. code is a storage system status code. (Output) ----------------------------------------------------------- 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