03/15/85 transaction_manager_ Entry points in transaction_manager_ begin and end transactions on behalf of users, return information about transactions, and recover transactions after system failure. Entry points in transaction_manager_: (List is generated by the help command) :Entry: abandon_txn: 03/15/85 transaction_manager_$abandon_txn Function: This entry point relinquishes control of the current transaction, causing it to be adjusted (aborted unless a commit was already in progress) by the DM daemon (Data_Management.Daemon). The caller is immediately given a new TDT entry and can begin another transaction. Syntax: declare transaction_manager_$abandon_txn entry (bit (36) aligned, fixed bin(35)); call transaction_manager_$abandon_txn (txn_id, code); Arguments: txn_id is the identifier of the current transaction, or "0"b to default to the current transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the current transaction, dm_error_$transaction_not_current is returned. This argument can be used as a check to be sure which transaction is being abandoned. code is a standard system status code. (Output) :Entry: abort_txn: 03/15/85 transaction_manager_$abort_txn Function: This entry point aborts the current transaction, returning all modified DM files to the state they were in before the transaction began. Syntax: declare transaction_manager_$abort_txn entry (bit(36) aligned, fixed bin(35)); call transaction_manager_$abort_txn (txn_id, code); Arguments: txn_id is the identifier of the current transaction, or "0"b to default to the current transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the current transaction, dm_error_$transaction_not_current is returned. This argument can be used as a check to be sure which transaction is being aborted. code is a standard system status code. (Output) Notes: If the transaction has already been abandoned, this entry point causes the DM daemon to abort it immediately. This entry point will retry abort of a transaction that was left in an error state by a previous abort or rollback. It will not attempt abort of a transaction left in error by any other operation. :Entry: begin_txn: 03/15/85 transaction_manager_$begin_txn Function: This entry point begins a transaction on behalf of the caller, by generating a unique transaction identifier and recording it in a TDT entry as the current transaction for the process. Other information, such as owner name, begin time, and transaction state (in-progress) are also recorded. The transaction id is passed to the before journal manager to begin the transaction. Syntax: declare transaction_manager_$begin_txn (fixed bin(17), bit(36), bit(36) aligned, fixed bin(35)); call transaction_manager_$begin_txn (begin_mode, before_journal_opening_id, txn_id, code); Arguments: begin_mode determines which of several protocols to use. (Input) The only mode currently available is normal mode. TM_NORMAL_MODE requires locks to accompany all gets and puts, and requires all updates to be journalized. before_journal_opening_id is the opening identifier of the before journal to be used by this transaction. (Input) If zero, a before journal is assigned by default to this transaction. txn_id is the identifier of the newly created transaction. (Output) It is generated by transaction_manager_$begin_txn and is guaranteed to be unique across all Multics systems. Transaction identifiers are not reusable. code is a standard system status code. (Output) :Entry: commit_txn: 03/15/85 transaction_manager_$commit_txn Function: This entry point commits the current transaction. Any modifications made to DM files since the transaction began become permanent and visible to other transactions, as if all the changes were made in the same instant. Syntax: declare transaction_manager_$commit_txn entry (bit(36) aligned, fixed bin(35)); call transaction_manager_$commit_txn (txn_id, code); Arguments: txn_id is the identifier of the current transaction, or "0"b to default to the current transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the current transaction, dm_error_$transaction_not_current is returned. This argument can be used as a check to be sure which transaction is being committed. code is a standard system status code. (Output) Notes: This entry point will retry commit of a transaction that was left in an error state by a previous commit. It will not, however, attempt to commit a transaction left in error by any other operation. :Entry: get_current_ids: 03/15/85 transaction_manager_$get_current_ids Function: This entry point returns the identifier of the current transaction, the most recent checkpoint number, and the number of times this transaction has been rolled back. Syntax: declare transaction_manager_$get_current_ids entry (bit(36)aligned, fixed bin, fixed bin, fixed bin (35)); call transaction_manager_$get_current_ids (txn_id, checkpoint_id, rollback_count, code); Arguments: txn_id is the identifier of the current transaction. (Output) checkpoint_id is the number of the most recent checkpoint. This value is currently always zero. (Output) rollback_count is the number of times this transaction has been rolled back. (Output) code is a standard system status code. (Output) :Entry: get_current_txn_id: 03/15/85 transaction_manager_$get_current_txn_id Function: This entry point returns the identifier of the current transaction, and tells whether the transaction is suspended or in error. Syntax: declare transaction_manager_$get_current_txn_id entry (bit(36) aligned, fixed bin(35)); call transaction_manager_$get_current_txn_id (txn_id, code); Arguments: txn_id is the identifier of the current transaction. (Output) code is one of the codes listed below. (Output) :Entry: get_state_description: 03/15/85 transaction_manager_$get_state_description Function: This entry point generates a character string description of a numeric state returned by transaction_manager_$get_txn_info or transaction_manager_$get_txn_info_index. Syntax: declare transaction_manager_$get_state_description entry (fixed bin) returns (char(*)); state_description = transaction_manager_$get_state_description (state); :Entry: get_tdt_size: 03/15/85 transaction_manager_$get_tdt_size Function: This entry point returns the number of entries allocated in the TDT. This number can be used as an upper bound for looping through all TDT entries. Syntax: dcl transaction_manager_$get_tdt_size entry returns (fixed bin); number = txn_$get_tdt_size (); Arguments: There are no arguments. :Entry: get_tdt_index: 03/15/85 transaction_manager_$get_tdt_index Function: This entry point returns the index of the TDT entry occupied by a specified transaction. Syntax: declare transaction_manager_$get_tdt_index entry (bit(36) aligned, fixed bin(35)) returns (fixed bin); txn_index = transaction_manager_$get_tdt_index (txn_id, code); Arguments: txn_id is the identifier of a transaction. (Input) If it is "0"b, the current transaction is used. code is a standard system status code. (Output) Access required: The caller requires re access to dm_admin_gate_ to obtain the index of another user's transaction. :Entry: get_txn_info: 03/15/85 transaction_manager_$get_txn_info Function: This entry point returns a structure containing all the information in the TDT about a transaction. Syntax: declare transaction_manager_$get_txn_info entry (bit(36) aligned, ptr, fixed bin(35)); call transaction_manager_$get_txn_info (txn_id, txn_info_ptr, code); Arguments: txn_id is the identifier of a transaction, or "0"b to default to the current transaction. (Input) txn_info_ptr is a pointer to the txn_info structure, declared in dm_tm_txn_info.incl.pl1. (Input) code is a standard system status code. (Output) Access required: The caller requires re access to dm_admin_gate_ to obtain information about another user's transaction. :Entry: get_txn_info_index: 03/15/85 transaction_manager_$get_txn_info_index Function: This entry point returns the same information as transaction_manager_$get_txn_info but accepts the index of a TDT entry rather than a transaction identifier. The transaction command, for example, calls this entry point with numbers 1 through transaction_manager_$get_tdt_size() to print information for the entire TDT. Syntax: declare transaction_manager_$get_txn_info_index entry (fixed bin, ptr, fixed bin(35)); call transaction_manager_$get_txn_info_index (txn_index, txn_info_ptr, code); Arguments: txn_index is the index of a TDT entry. (Input) txn_info_ptr is a pointer to the txn_info structure, declared in dm_tm_txn_info.incl.pl1. (Input) code is a standard system status code. (Output) Access required: The caller requires re access to dm_admin_gate_ to obtain information about another user's transaction. :Entry: handle_conditions: 03/15/85 transaction_manager_$handle_conditions Function: This entry point, intended to be called by "any_other" handlers in user programs, temporarily suspends the current transaction during an interruption caused by a signalled condition. When invoked, it suspends the current transaction, allows the condition to propagate, and resumes the transaction when control returns. Syntax: declare transaction_manager_$handle_conditions entry (); call transaction_manager_$handle_conditions (); Arguments: There are no arguments. :Entry: kill_txn: 03/15/85 transaction_manager_$kill_txn Function: This entry point is intended to be called by the owner of a transaction when the owner cannot end the transaction normally and does not want the daemon to try to abort it for reasons of efficiency. Killing a transaction can destroy the consistency of the databases changed during the transaction, and is therefore appropriate only if consistency is no longer an issue (for example, if the databases are to be deleted). As with $abandon_txn, calling this entry point frees the user to begin a new transaction. Syntax: declare transaction_manager_$kill_txn entry (bit(36) aligned, fixed bin(35)); call transaction_manager_$kill_txn (txn_id, code); Arguments: txn_id is the identifier of the transaction to be killed. (Input) If it is "0"b, the current transaction is used. code is a standard system status code. (Output) Access required: The caller requires re access to dm_admin_gate_. :Entry: resume_txn: 03/15/85 transaction_manager_$resume_txn Function: This entry point reactivates a suspended transaction, once again allowing data operations on protected files. Syntax: declare transaction_manager_$resume_txn entry (fixed bin(35)); call transaction_manager_$resume_txn (code); Arguments: code is a standard system status code. (Output) :Entry: rollback_txn: 03/15/85 transaction_manager_$rollback_txn Function: This entry point rolls the current transaction back to its beginning, by replacing all modifications to protected files caused by the transaction, with the before images preserved in the appropriate before journal. The transaction remains current for the user process. Syntax: declare transaction_manager_$rollback_txn entry (bit(36) aligned, fixed bin, fixed bin(35)); call transaction_manager_$rollback_txn (txn_id, checkpoint_number, code); Arguments: txn_id is the identifier of the current transaction, or "0"b to default to the current transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the current transaction, dm_error_$transaction_not_current is returned. This argument can be used as a check to be sure which transaction is being rolled back. checkpoint_number must currently be 0. (Input) code is a standard system status code. (Output) Notes: This entry point will retry rollback of a transaction that was left in an error state by a previous rollback. It will not attempt to rollback a transaction left in error by any other operation. :Entry: suspend_txn: 03/15/85 transaction_manager_$suspend_txn Function: This entry point puts the current transaction into a suspended state wherein it is temporarily unusable. Data operations to protected files are not allowed while the transaction is suspended, that is, until $resume_txn is called. Since the suspended transaction has not been completed, no new transaction can be begun. Syntax: declare transaction_manager_$suspend_txn entry (fixed bin(35)); call transaction_manager_$suspend_txn (code); Arguments: code is a standard system status code. (Output) Notes: Suspension has the following effects: 1. The current transaction is temporarily unusable. As a result, the entry point $get_current_txn_id returns "0"b and the error code dm_error_$transaction_suspended. 2. No data operations on protected files are allowed while the transaction is suspended. 3. Both $begin_txn and $commit_txn return dm_error_$transaction_suspended. 4. Both $abort_txn and $adjust_tdt_entry (called by DMS) work on suspended transactions. :Entry: user_shutdown: 03/15/85 transaction_manager_$user_shutdown Function: This entry point shuts down DMS in the calling process. All TDT entries belonging to the caller's Person.Project are adjusted before DMS is turned off. If the calling process is not currently using DMS, the entry does a return. Information about the adjusted TDT entries is returned in the structure tm_shutdown_info, declared in dm_tm_shutdown_info.incl.pl1. Syntax: dcl transaction_manager_$user_shutdown entry (ptr, ptr, fixed bin(35)); call transaction_manager_$user_shutdown (area_ptr, tm_shutdown_info_ptr, code); Arguments: area_ptr is a pointer to an area in which to allocate the shutdown_info structure. (Input) tm_shutdown_info_ptr is the returned pointer to tm_shutdown_info, found in the dm_tm_shutdown_info.incl.pl1 include file. (Output) code is a standard 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