: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.
