:Info: transaction: txn: 08/23/90 transaction, txn Syntax as a command: txn key {-control_args} Syntax as an active function: [txn key {-control_args}] Function: enables you to define and execute atomic operations interactively. You can invoke the services of the transaction manager to begin, commit, abort, rollback, abandon, or kill a transaction. There is also a status request for displaying information about the current transaction. There is an execute request to wrap a given command line in a transaction. This command is part of the command level interface to Multics data management (DM) (see the Programmer's Reference Manual). Arguments: key designates the operation to be performed. See "List of operations" below for a description of each operation, its command syntax line, and specific application. Control arguments: can be one or more control arguments, depending on the particular operation. List of keywords: (For detailed documentation of any key, type "help txn.KEY" where KEY is the name of the key.) abandon abandons the current transaction. abort aborts the current transaction. begin begins a new transaction. commit commits the current transaction. execute wraps a command line with a transaction. kill deletes the current transaction without rollback. rollback rolls back the current transaction. status prints information about transactions. :Info: transaction.abandon: txn.abandon: 08/23/90 transaction abandon Syntax as a command: txn abandon Syntax as an active function: [txn abandon] Function: your process surrenders control of the transaction to the DM Daemon, which aborts it as part of its normal caretaker responsibilities. The active function returns true if the transaction is successfully abandoned, false otherwise. Notes: By abandoning a transaction, your process can start another transaction without waiting for the abort operation to conclude (your process is still charged for the abort). The data locked by the original transaction remains inaccessible, however, until the rollback is completed. :Info: transaction.abort: txn.abort: 03/01/85 transaction abort Syntax as a command: txn abort Syntax as an active function: [txn abort] Function: aborts the current transaction so that, in effect, it never existed. Any modifications to protected files caused by the aborted transaction are rolled back, and references to the transaction are removed from system tables. The active function returns true if the transaction is successfully aborted, false otherwise. :Info: transaction.begin: txn.begin: 03/01/85 transaction begin Syntax as a command: txn begin {-control_args} Syntax as an active function: [txn begin {-control_args}] Function: starts a transaction by reserving a slot in the transaction definition table (TDT) for your process, with a unique transaction identifier, date/time of the start, pathname of the before journal, and other information pertinent to the transaction (see the status operation). If your process already owns a transaction, an error occurs. The active function returns true if a transaction is started successfully, false otherwise. Control arguments: -no_wait, -nwt causes an error if the data management system (DMS) is not currently invoked. (Default) -wait N, -wt N if DMS is not currently invoked, wait N seconds before starting the transaction. An error occurs if DMS is still not up after the elapsed time. -wait_indefinitely, -wti if DMS is not currently invoked, wait as long as necessary to start the transaction. The status of DMS is checked at 10-second intervals, and notification is given when command line execution begins. Notes: This operation is a tool for isolating and testing the transaction startup function. In a production environment the transaction execute command is the recommended method of starting transactions from command level because it builds in the atomicity: it begins the transaction, executes a command line, and then terminates the transaction, within the one request (see the execute operation). :Info: transaction.commit: txn.commit: 03/01/85 transaction commit Syntax as a command: txn commit Syntax as an active function: [txn commit] Function: signals successful completion of the currently active transaction. Modifications made to protected files by this transaction are considered permanent. Any locks held by the transaction are released, making the data public again. The active function returns true if the commit operation is successful, false otherwise. :Info: transaction.execute: transaction.e: txn.execute: txn.e: 08/23/90 transaction execute Syntax as a command: txn execute {-control_args} {command_line} Syntax as an active function: [txn execute {-control_args} {command_line}] Function: starts a transaction, executes a command line, and, provided the command line is successfully executed, commits the transaction. Control arguments govern what action to take based on conditions encountered. The active function returns true if the execute operation is successful, false otherwise. Arguments: command_line specifies the command line to be executed as part of the transaction. Enclose it in quotes if it contains parentheses, brackets, or semicolons. If you omit it, the system prompts "Command line:". Control arguments: -abandon_on CONDITION_LIST abandons the transaction and results in a nonlocal exit of the command line if any of the listed conditions is encountered during command line execution. Separate the listed conditions by commas, with no intervening whitespace. The list can include any_other. The default action is as described under "Notes" below. This control argument is incompatible with -existing_transaction_allowed and -existing_transaction_required. -abort_on CONDITION_LIST aborts the transaction and results in a nonlocal exit of the command line if any of the listed conditions is encountered during command line execution. Separate the listed conditions by commas, with no intervening whitespace. The list can include any_other. The default action is as described under "Notes" below. This control argument is incompatible with -existing_transaction_allowed and -existing_transaction_required. -command_level, -cl places your process at the next command level, from which commands can be entered in the transaction. You can use the start or release command to exit this command level. -existing_transaction_allowed, -eta accepts the existing transaction (if one already exists in your process) as the origin of command line execution. No new transaction is begun. This control argument is incompatible with -retry_on and -suspend_on. (Default: to return an error if a transaction already exists) -existing_transaction_required, -etr requires that a transaction already exist in your process; returns an error if no transaction exists. This control argument is incompatible with -retry_on and -suspend_on. (Default: to return an error if a transaction already exists) -no_action_on CONDITION_LIST overrides any special action (e.g., -abandon_on, -retry_on) you previously specified in the command line for the listed conditions. The default action (see "Notes") is also overridden. -no_existing_transaction_allowed, -neta causes an error if a transaction already exists in your process. (Default) -no_wait, -nwt causes an error if DMS is not currently invoked. (Default) -retry_on N CONDITION_LIST executes the command line up to N times if any of the listed conditions is encountered during command line execution. If N is 0, the command line is not retried. Separate the listed conditions by commas, with no intervening whitespace. The list can include any_other. The default action is as described under "Notes" below. -suspend_on CONDITION_LIST suspends the transaction and goes to the next command level if any of the listed conditions is encountered during command line execution. Separate the listed conditions by commas, with no intervening whitespace. The list can include any_other. The default action is as described under "Notes" below. -wait N, -wt N if DMS is not currently invoked, waits N seconds before starting the transaction and executing the command line (you are notified when command line execution begins). An error condition is returned if DMS is still not up after the elapsed time. This operation is useful for absentee jobs submitted to perform operations within transactions. -wait_indefinitely, -wti if DMS is not currently invoked, waits as long as necessary to start the transaction and execute the command line. The status of DMS is checked at 10-second intervals, and notification is given when command line execution begins. Notes: If a transaction already exists in your process, the default action is -no_action_on any_other; otherwise the default action is -suspend_on any_other -abort_on cleanup. A transaction begun by txn execute is committed unless the command line fails to execute properly, in which case the transaction is aborted. A transaction severity code (displayable by the "severity transaction" command) denotes the status of the execute operation, as follows: 0 the operation was completed without errors and was not retried. 1 the operation was completed, but was retried one or more times. 2 the operation failed; the transaction was aborted or abandoned. 3 the operation failed; the transaction could not be aborted or abandoned. 4 the transaction could not be begun. The active function returns true if the severity after execution is 0 or 1; false if it is 2, 3, or 4. If a transaction is currently suspended in your process, the txn execute command gets an error and the active function returns false. :Info: transaction.kill: txn.kill: 03/01/85 transaction kill Syntax as a command: txn kill {ID} Syntax as an active function: [txn kill {ID}] Function: expunges the current or specified transaction with no attempt to preserve consistency of any DM files that might have been modified by this transaction. Killing a transaction may destroy the consistency of any databases that the transaction is using; therefore use this operation when neither you nor the Daemon is able to complete the transaction. The active function returns true if the operation is executed successfully, false otherwise. Arguments: ID is the unique identifier of the transaction to be killed (obtainable through txn status). (Default: the current transaction in your process) Access required: You need re access to dm_daemon_gate_. :Info: transaction.rollback: txn.rollback: 03/01/85 transaction rollback Syntax as a command: txn rollback Syntax as an active function: [txn rollback] Function: rolls back the current transaction to its beginning (txn begin), undoing any changes to protected files caused by the transaction and releasing the locks held by it. The transaction is still considered active in your process. The active function returns true if the transaction was successfully rolled back, false otherwise. :Info: transaction.status: txn.status: transaction.st: txn.st: 03/01/85 transaction status Syntax as a command: txn st {-control_args} Syntax as an active function: [txn st {-control_args}] Function: displays information about the current transaction, selected transactions, or all transactions, depending on the nature of the request and your access permissions. The active function takes only one information control argument. Control arguments for selecting transactions: If you supply no control arguments, or lack the proper access, only information pertaining to your current transaction is displayed. -abandoned displays the requested information about all TDT entries marked as abandoned. -all, -a displays the requested information about all TDT entries. -dead displays the requested information about all TDT entries belonging to dead processes. -transaction_id ID, -tid ID, -id ID displays the requested information about the transaction with unique identifier ID, where ID is a decimal integer. Transaction identifiers are assigned at txn begin time and can be viewed by the txn status command. -transaction_index N, -tix N, -index N displays the requested information about entry number N in the TDT. TDT entry indexes are of interest mainly to data management maintainers and can be viewed by the txn status command. Control arguments for selecting information: If you give none of the following control arguments, all information is displayed for each TDT entry selected. You can specify only one control argument for the active function. -before_journal_path, -bj_path returns the pathname of the before journal used by the current transaction. -date_time_begun, -dtbg, -begun returns the date and starting time of each transaction. -error, error_info returns a description of the latest error, if any, to have occurred while processing each transaction. -owner identifies the owner (User_id.Project_id) of each TDT entry. -process_id, -pid returns the octal process_id of the owner of each TDT entry. -rollback_count, -rbc returns the number of times each transaction has been rolled back. -state indicates the state of each transaction, which must be one of the following: no transaction (e.g., the process might have owned a transaction, which has been taken over by the DM Daemon) in progress {Error - } OPERATION, calling PROGRAM_NAME, which gives the operation currently in progress, such as abort or commit, and the entry point being called; and is followed by an error message if appropriate. -switches, -switch, -sw lists those transactions that are either abandoned, killed, or suspended or whose owner processes are dead. -total, -tt prints totals information for the TDT, including: number of slots available (not yet reserved by processes) number in use (i.e., reserved by processes at first invocation of DMS) number of entries owned by dead processes (of the number in use) number of abandoned entries (of the number in use) number of entries occupied by transactions (i.e., slots reserved by processes that have started transactions) number of transactions in error. -transaction_id, -tid, -id supplies the unique identifier of each transaction. Use of -transaction_id with a specific transaction ID returns information about that transaction. -transaction_index, -tix, -index returns the index of entries in the TDT. This index is mainly of interest to data management maintainers. Use of -transaction_index with a specific integer N returns information about a given TDT entry number. Notes: You can't use the following control arguments with the active function: -abandoned, -all, -dead, and -total. You need re access to dm_admin_gate_ to view the status of any other user's transactions. ----------------------------------------------------------- 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