1 :Info: transaction: txn: 1990-08-23  transaction, txn
  2 
  3 Syntax as a command:  txn OPERATION {-control_args}
  4 
  5 
  6 Syntax as an active function:  [txn OPERATION {-control_args}]
  7 
  8 
  9 Function: enables you to define and execute atomic operations
 10 interactively.  You can invoke the services of the transaction manager
 11 to begin, commit, abort, rollback, abandon, or kill a transaction.
 12 There is also a status request for displaying information about the
 13 current transaction.  There is an execute request to wrap a given
 14 command line in a transaction.  This command is part of the command
 15 level interface to Multics data management (DM) (see the Programmer's
 16 Reference Manual).
 17 
 18 
 19 Arguments:
 20 OPERATION
 21    designates the operation to be performed.  See "List of operations"
 22    below.
 23 
 24 
 25 List of operations:
 26    For details of any operation, type:  help txn.OPERATION
 27 abandon
 28    abandons the current transaction.
 29 abort
 30    aborts the current transaction.
 31 begin
 32    begins a new transaction.
 33 commit
 34    commits the current transaction.
 35 
 36 
 37 execute, e
 38    wraps a command line with a transaction.
 39 kill
 40    deletes the current transaction without rollback.
 41 rollback
 42    rolls back the current transaction.
 43 status, st
 44    prints information about transactions.
 45 
 46 
 47 Control arguments:
 48 -control_args
 49    depend on the particular operation being performed.
 50 
 51 
 52 :Info: txn.abandon:  1990-08-23  txn abandon operation
 53 
 54 Syntax as a command:  txn abandon
 55 
 56 
 57 Syntax as an active function:  [txn abandon]
 58 
 59 
 60 Function: your process surrenders control of the transaction to the DM
 61 Daemon, which aborts it as part of its normal caretaker
 62 responsibilities.  The active function returns true if the transaction
 63 is successfully abandoned, false otherwise.
 64 
 65 
 66 Arguments:
 67 abandon
 68    the operation being performed.
 69 
 70 
 71 Notes: By abandoning a transaction, your process can start another
 72 transaction without waiting for the abort operation to conclude (your
 73 process is still charged for the abort).  The data locked by the
 74 original transaction remains inaccessible, however, until the rollback
 75 is completed.
 76 
 77 
 78 :Info: txn.abort:  1985-03-01  txn abort operation
 79 
 80 Syntax as a command:  txn abort
 81 
 82 
 83 Syntax as an active function:  [txn abort]
 84 
 85 
 86 Function: aborts the current transaction so that, in effect, it never
 87 existed.  Any modifications to protected files caused by the aborted
 88 transaction are rolled back, and references to the transaction are
 89 removed from system tables.  The active function returns true if the
 90 transaction is successfully aborted, false otherwise.
 91 
 92 
 93 Arguments:
 94 abort
 95    the operation being performed.
 96 
 97 
 98 :Info: txn.begin:  1985-03-01  txn begin operation
 99 
100 Syntax as a command:  txn begin {-control_args}
101 
102 
103 Syntax as an active function:  [txn begin {-control_args}]
104 
105 
106 Function: starts a transaction by reserving a slot in the transaction
107 definition table (TDT) for your process, with a unique transaction
108 identifier, date/time of the start, pathname of the before journal, and
109 other information pertinent to the transaction (see the status
110 operation).  If your process already owns a transaction, an error
111 occurs.  The active function returns true if a transaction is started
112 successfully, false otherwise.
113 
114 
115 Arguments:
116 begin
117    the operation being performed.
118 
119 
120 Control arguments:
121 -no_wait, -nwt
122    causes an error if the data management system (DMS) is not currently
123    invoked.  (Default)
124 -wait N, -wt N
125    if DMS is not currently invoked, wait N seconds before starting the
126    transaction.  An error occurs if DMS is still not up after the
127    elapsed time.
128 -wait_indefinitely, -wti
129    if DMS is not currently invoked, wait as long as necessary to start
130    the transaction.  The status of DMS is checked at 10-second
131    intervals, and notification is given when command line execution
132    begins.
133 
134 
135 Notes: This operation is a tool for isolating and testing the
136 transaction startup function.  In a production environment the
137 transaction execute command is the recommended method of starting
138 transactions from command level because it builds in the atomicity: it
139 begins the transaction, executes a command line, and then terminates
140 the transaction, within the one request (see the execute operation).
141 
142 
143 :Info: txn.commit:  1985-03-01  txn commit operation
144 
145 Syntax as a command:  txn commit
146 
147 
148 Syntax as an active function:  [txn commit]
149 
150 
151 Function: signals successful completion of the currently active
152 transaction.  Modifications made to protected files by this transaction
153 are considered permanent.  Any locks held by the transaction are
154 released, making the data public again.  The active function returns
155 true if the commit operation is successful, false otherwise.
156 
157 
158 Arguments:
159 commit
160    the operation being performed.
161 
162 
163 :Info: txn.execute: txn.e:  1990-08-23  txn execute operation
164 
165 
166 Syntax as a command:  txn e {-control_args} {COMMAND_LINE}
167 
168 
169 Syntax as an active function:
170    [txn e {-control_args} {COMMAND_LINE}]
171 
172 
173 Function: starts a transaction, executes a command line, and, provided
174 the command line is successfully executed, commits the transaction.
175 Control arguments govern what action to take based on conditions
176 encountered.  The active function returns true if the execute operation
177 is successful, false otherwise.
178 
179 
180 Arguments:
181 execute, e
182    the operation being performed.
183 COMMAND_LINE
184    specifies the command line to be executed as part of the
185    transaction.  Enclose it in quotes if it contains parentheses,
186    brackets, or semicolons.  If you omit it, the system prompts
187    "Command line:".
188 
189 
190 Control arguments:
191 -abandon_on CONDITION_LIST
192    abandons the transaction and results in a nonlocal exit of the
193    command line if any of the listed conditions is encountered during
194    command line execution.  Separate the listed conditions by commas,
195    with no intervening whitespace.  The list can include any_other.
196    The default action is as described under "Notes" below.  This
197    control argument is incompatible with -existing_transaction_allowed
198    and -existing_transaction_required.
199 
200 
201 -abort_on CONDITION_LIST
202    aborts the transaction and results in a nonlocal exit of the command
203    line if any of the listed conditions is encountered during command
204    line execution.  Separate the listed conditions by commas, with no
205    intervening whitespace.  The list can include any_other.  The
206    default action is as described under "Notes" below.  This control
207    argument is incompatible with -existing_transaction_allowed and
208    -existing_transaction_required.
209 -command_level, -cl
210    places your process at the next command level, from which commands
211    can be entered in the transaction.  You can use the start or release
212    command to exit this command level.
213 
214 
215 -existing_transaction_allowed, -eta
216    accepts the existing transaction (if one already exists in your
217    process) as the origin of command line execution.  No new
218    transaction is begun.  This control argument is incompatible with
219    -retry_on and -suspend_on.  (Default: to return an error if a
220    transaction already exists)
221 -existing_transaction_required, -etr
222    requires that a transaction already exist in your process; returns
223    an error if no transaction exists.  This control argument is
224    incompatible with -retry_on and -suspend_on.  (Default: to return
225    an error if a transaction already exists)
226 -no_action_on CONDITION_LIST
227    overrides any special action (e.g., -abandon_on, -retry_on) you
228    previously specified in the command line for the listed conditions.
229    The default action (see "Notes") is also overridden.
230 
231 
232 -no_existing_transaction_allowed, -neta
233    causes an error if a transaction already exists in your process.
234    (Default)
235 -no_wait, -nwt
236    causes an error if DMS is not currently invoked.  (Default)
237 -retry_on N CONDITION_LIST
238    executes the command line up to N times if any of the listed
239    conditions is encountered during command line execution.  If N is 0,
240    the command line is not retried.  Separate the listed conditions by
241    commas, with no intervening whitespace.  The list can include
242    any_other.  The default action is as described under "Notes" below.
243 
244 
245 -suspend_on CONDITION_LIST
246    suspends the transaction and goes to the next command level if any
247    of the listed conditions is encountered during command line
248    execution.  Separate the listed conditions by commas, with no
249    intervening whitespace.  The list can include any_other.  The
250    default action is as described under "Notes" below.
251 -wait N, -wt N
252    if DMS is not currently invoked, waits N seconds before starting the
253    transaction and executing the command line (you are notified when
254    command line execution begins).  An error condition is returned if
255    DMS is still not up after the elapsed time.  This operation is
256    useful for absentee jobs submitted to perform operations within
257    transactions.
258 
259 
260 -wait_indefinitely, -wti
261    if DMS is not currently invoked, waits as long as necessary to start
262    the transaction and execute the command line.  The status of DMS is
263    checked at 10-second intervals, and notification is given when
264    command line execution begins.
265 
266 
267 Notes: If a transaction already exists in your process, the default
268 action is -no_action_on any_other; otherwise the default action is
269 -suspend_on any_other -abort_on cleanup.
270 
271 A transaction begun by txn execute is committed unless the command line
272 fails to execute properly, in which case the transaction is aborted.
273 
274 
275 A transaction severity code (displayable by the "severity transaction"
276 command) denotes the status of the execute operation, as follows:
277    0  the operation was completed without errors and was not retried.
278    1  the operation was completed, but was retried one or more times.
279    2  the operation failed; the transaction was aborted or abandoned.
280    3  the operation failed; the transaction could not be aborted or
281       abandoned.
282    4  the transaction could not be begun.
283 
284 The active function returns true if the severity after execution is 0
285 or 1; false if it is 2, 3, or 4.
286 
287 If a transaction is currently suspended in your process, the txn
288 execute command gets an error and the active function returns false.
289 
290 
291 :Info: txn.kill:  1985-03-01  txn kill operation
292 
293 Syntax as a command:  txn kill {ID}
294 
295 
296 Syntax as an active function:  [txn kill {ID}]
297 
298 
299 Function: expunges the current or specified transaction with no
300 attempt to preserve consistency of any DM files that might have been
301 modified by this transaction.  Killing a transaction may destroy the
302 consistency of any databases that the transaction is using; therefore
303 use this operation when neither you nor the Daemon is able to complete
304 the transaction.  The active function returns true if the operation is
305 executed successfully, false otherwise.
306 
307 
308 Arguments:
309 kill
310    the operation being performed.
311 ID
312    is the unique identifier of the transaction to be killed (obtainable
313    through txn status).  (Default: the current transaction in your
314    process)
315 
316 
317 Access required: You need re access to dm_daemon_gate_.
318 
319 
320 :Info: txn.rollback:  1985-03-01  txn rollback operation
321 
322 Syntax as a command:  txn rollback
323 
324 
325 Syntax as an active function:  [txn rollback]
326 
327 
328 Function: rolls back the current transaction to its beginning (txn
329 begin), undoing any changes to protected files caused by the
330 transaction and releasing the locks held by it.  The transaction is
331 still considered active in your process.  The active function returns
332 true if the transaction was successfully rolled back, false otherwise.
333 
334 
335 Arguments:
336 rollback
337    the operation being performed.
338 
339 
340 :Info: txn.status: txn.st:  1985-03-01  txn status operation
341 
342 
343 Syntax as a command:  txn st {-control_args}
344 
345 
346 Syntax as an active function:  [txn st {-control_args}]
347 
348 
349 Function: displays information about the current transaction, selected
350 transactions, or all transactions, depending on the nature of the
351 request and your access permissions.  The active function takes only
352 one information control argument.
353 
354 
355 Arguments:
356 status, st
357    the operation being performed.
358 
359 
360 Control arguments for selecting transactions: If you supply no control
361    arguments, or lack the proper access, only information pertaining to
362    your current transaction is displayed.
363 -abandoned
364    displays the requested information about all TDT entries marked as
365    abandoned.
366 -all, -a
367    displays the requested information about all TDT entries.
368 -dead
369    displays the requested information about all TDT entries belonging
370    to dead processes.
371 
372 
373 -transaction_id ID, -tid ID, -id ID
374    displays the requested information about the transaction with unique
375    identifier ID, where ID is a decimal integer.  Transaction
376    identifiers are assigned at txn begin time and can be viewed by the
377    txn status command.
378 -transaction_index N, -tix N, -index N
379    displays the requested information about entry number N in the TDT.
380    TDT entry indexes are of interest mainly to data management
381    maintainers and can be viewed by the txn status command.
382 
383 
384 Control arguments for selecting information: If you give none of the
385    following control arguments, all information is displayed for each
386    TDT entry selected.  You can specify only one control argument for
387    the active function.
388 -before_journal_path, -bj_path
389    returns the pathname of the before journal used by the current
390    transaction.
391 -date_time_begun, -dtbg, -begun
392    returns the date and starting time of each transaction.
393 -error, error_info
394    returns a description of the latest error, if any, to have occurred
395    while processing each transaction.
396 -owner
397    identifies the owner (User_id.Project_id) of each TDT entry.
398 
399 
400 -process_id, -pid
401    returns the octal process_id of the owner of each TDT entry.
402 -rollback_count, -rbc
403    returns the number of times each transaction has been rolled back.
404 -state
405    indicates the state of each transaction, which must be one of the
406    following:
407       no transaction (e.g., the process might have owned a transaction,
408          which has been taken over by the DM Daemon)
409       in progress
410       {Error - } OPERATION, calling PROGRAM_NAME, which gives the
411          operation currently in progress, such as abort or commit, and
412          the entry point being called; and is followed by an error
413          message if appropriate.
414 
415 
416 -switches, -switch, -sw
417    lists those transactions that are either abandoned, killed, or
418    suspended or whose owner processes are dead.
419 -total, -tt
420    prints totals information for the TDT, including:
421       number of slots available (not yet reserved by processes)
422       number in use (i.e., reserved by processes at first invocation of
423          DMS)
424       number of entries owned by dead processes (of the number in use)
425       number of abandoned entries (of the number in use)
426       number of entries occupied by transactions (i.e., slots reserved
427          by processes that have started transactions)
428       number of transactions in error.
429 
430 
431 -transaction_id, -tid, -id
432    supplies the unique identifier of each transaction.  Use of
433    -transaction_id with a specific transaction ID returns information
434    about that transaction.
435 -transaction_index, -tix, -index
436    returns the index of entries in the TDT.  This index is mainly of
437    interest to data management maintainers.  Use of -transaction_index
438    with a specific integer N returns information about a given TDT
439    entry number.
440 
441 
442 Notes: You can't use the following control arguments with the active
443 function: -abandoned, -all, -dead, and -total.
444 
445 You need re access to dm_admin_gate_ to view the status of any other
446 user's transactions.
447 
448 
449 :hcom:
450 
451 
452 
453 /****^  HISTORY COMMENTS:
454   1) change(2020-06-14,GDixon), approve(2021-02-22,MCR10088),
455      audit(2021-05-27,Swenson), install(2021-05-27,MR12.6g-0056):
456       A) Convert to Operation Format supported by the verify_info command.
457                                                    END HISTORY COMMENTS */
458 
459 
460