1 03/15/85  transaction_manager_
  2 
  3 
  4 Entry points in transaction_manager_ begin and end transactions on
  5 behalf of users, return information about transactions, and recover
  6 transactions after system failure.
  7 
  8 
  9 Entry points in transaction_manager_:
 10    (List is generated by the help command)
 11 
 12 
 13 :Entry:  abandon_txn:  03/15/85 transaction_manager_$abandon_txn
 14 
 15 
 16 Function:  This entry point relinquishes control of the current
 17 transaction, causing it to be adjusted (aborted unless a commit was
 18 already in progress) by the DM daemon (Data_Management.Daemon).  The
 19 caller is immediately given a new TDT entry and can begin another
 20 transaction.
 21 
 22 
 23 Syntax:
 24 declare transaction_manager_$abandon_txn entry (bit (36) aligned, fixed
 25      bin(35));
 26 call transaction_manager_$abandon_txn (txn_id, code);
 27 
 28 
 29 Arguments:
 30 txn_id
 31    is the identifier of the current transaction, or "0"b to default to
 32    the current transaction.  (Input) If txn_id is neither "0"b nor the
 33    transaction identifier of the current transaction,
 34    dm_error_$transaction_not_current is returned.  This argument can be
 35    used as a check to be sure which transaction is being abandoned.
 36 code
 37    is a standard system status code.  (Output)
 38 
 39 
 40 :Entry:  abort_txn:  03/15/85 transaction_manager_$abort_txn
 41 
 42 
 43 Function:  This entry point aborts the current transaction, returning
 44 all modified DM files to the state they were in before the transaction
 45 began.
 46 
 47 
 48 Syntax:
 49 declare transaction_manager_$abort_txn entry (bit(36) aligned, fixed
 50      bin(35));
 51 call transaction_manager_$abort_txn (txn_id, code);
 52 
 53 
 54 Arguments:
 55 txn_id
 56    is the identifier of the current transaction, or "0"b to default to
 57    the current transaction.  (Input) If txn_id is neither "0"b nor the
 58    transaction identifier of the current transaction,
 59    dm_error_$transaction_not_current is returned.  This argument can be
 60    used as a check to be sure which transaction is being aborted.
 61 code
 62    is a standard system status code.  (Output)
 63 
 64 
 65 Notes:  If the transaction has already been abandoned, this entry point
 66 causes the DM daemon to abort it immediately.
 67 
 68 This entry point will retry abort of a transaction that was left in an
 69 error state by a previous abort or rollback.  It will not attempt abort
 70 of a transaction left in error by any other operation.
 71 
 72 
 73 :Entry:  begin_txn:  03/15/85 transaction_manager_$begin_txn
 74 
 75 
 76 Function:  This entry point begins a transaction on behalf of the
 77 caller, by generating a unique transaction identifier and recording it
 78 in a TDT entry as the current transaction for the process.  Other
 79 information, such as owner name, begin time, and transaction state
 80 (in-progress) are also recorded.  The transaction id is passed to the
 81 before journal manager to begin the transaction.
 82 
 83 
 84 Syntax:
 85 declare transaction_manager_$begin_txn (fixed bin(17), bit(36), bit(36)
 86      aligned, fixed bin(35));
 87 call transaction_manager_$begin_txn (begin_mode,
 88      before_journal_opening_id, txn_id, code);
 89 
 90 
 91 Arguments:
 92 begin_mode
 93    determines which of several protocols to use.  (Input) The only mode
 94    currently available is normal mode.
 95    TM_NORMAL_MODE
 96       requires locks to accompany all gets and puts, and requires all
 97       updates to be journalized.
 98 before_journal_opening_id
 99    is the opening identifier of the before journal to be used by this
100    transaction.  (Input) If zero, a before journal is assigned by
101    default to this transaction.
102 txn_id
103    is the identifier of the newly created transaction.  (Output) It is
104    generated by transaction_manager_$begin_txn and is guaranteed to be
105    unique across all Multics systems.  Transaction identifiers are not
106    reusable.
107 code
108    is a standard system status code.  (Output)
109 
110 
111 :Entry:  commit_txn:  03/15/85 transaction_manager_$commit_txn
112 
113 
114 Function:  This entry point commits the current transaction.  Any
115 modifications made to DM files since the transaction began become
116 permanent and visible to other transactions, as if all the changes were
117 made in the same instant.
118 
119 
120 Syntax:
121 declare transaction_manager_$commit_txn entry (bit(36) aligned, fixed
122      bin(35));
123 call transaction_manager_$commit_txn (txn_id, code);
124 
125 
126 Arguments:
127 txn_id
128    is the identifier of the current transaction, or "0"b to default to
129    the current transaction.  (Input) If txn_id is neither "0"b nor the
130    transaction identifier of the current transaction,
131    dm_error_$transaction_not_current is returned.  This argument can be
132    used as a check to be sure which transaction is being committed.
133 code
134    is a standard system status code.  (Output)
135 
136 
137 Notes:  This entry point will retry commit of a transaction that was
138 left in an error state by a previous commit.  It will not, however,
139 attempt to commit a transaction left in error by any other operation.
140 
141 
142 :Entry: get_current_ids: 03/15/85 transaction_manager_$get_current_ids
143 
144 
145 Function:  This entry point returns the identifier of the current
146 transaction, the most recent checkpoint number, and the number of times
147 this transaction has been rolled back.
148 
149 
150 Syntax:
151 declare transaction_manager_$get_current_ids entry (bit(36)aligned,
152      fixed bin, fixed bin, fixed bin (35));
153 call transaction_manager_$get_current_ids (txn_id, checkpoint_id,
154      rollback_count, code);
155 
156 
157 Arguments:
158 txn_id
159    is the identifier of the current transaction.  (Output)
160 checkpoint_id
161    is the number of the most recent checkpoint.  This value is
162    currently always zero.  (Output)
163 rollback_count
164    is the number of times this transaction has been rolled back.
165    (Output)
166 code
167    is a standard system status code.  (Output)
168 
169 
170 :Entry: get_current_txn_id: 03/15/85 transaction_manager_$get_current_txn_id
171 
172 
173 Function:  This entry point returns the identifier of the current
174 transaction, and tells whether the transaction is suspended or in
175 error.
176 
177 
178 Syntax:
179 declare transaction_manager_$get_current_txn_id entry (bit(36) aligned,
180      fixed bin(35));
181 call transaction_manager_$get_current_txn_id (txn_id, code);
182 
183 
184 Arguments:
185 txn_id
186    is the identifier of the current transaction.  (Output)
187 code
188    is one of the codes listed below.  (Output)
189 
190 
191 :Entry: get_state_description: 03/15/85 transaction_manager_$get_state_description
192 
193 
194 Function:  This entry point generates a character string description of
195 a numeric state returned by transaction_manager_$get_txn_info or
196 transaction_manager_$get_txn_info_index.
197 
198 
199 Syntax:
200 declare transaction_manager_$get_state_description entry (fixed bin)
201      returns (char(*));
202 state_description = transaction_manager_$get_state_description (state);
203 
204 
205 :Entry:  get_tdt_size:  03/15/85 transaction_manager_$get_tdt_size
206 
207 
208 Function:  This entry point returns the number of entries allocated in
209 the TDT.  This number can be used as an upper bound for looping through
210 all TDT entries.
211 
212 
213 Syntax:
214 dcl transaction_manager_$get_tdt_size entry returns (fixed bin);
215 number = txn_$get_tdt_size ();
216 
217 
218 Arguments:
219    There are no arguments.
220 
221 
222 :Entry:  get_tdt_index:  03/15/85 transaction_manager_$get_tdt_index
223 
224 
225 Function:  This entry point returns the index of the TDT entry occupied
226 by a specified transaction.
227 
228 
229 Syntax:
230 declare transaction_manager_$get_tdt_index entry (bit(36) aligned,
231      fixed bin(35)) returns (fixed bin);
232 txn_index = transaction_manager_$get_tdt_index (txn_id, code);
233 
234 
235 Arguments:
236 txn_id
237    is the identifier of a transaction.  (Input) If it is "0"b, the
238    current transaction is used.
239 code
240    is a standard system status code.  (Output)
241 
242 
243 Access required:
244 The caller requires re access to dm_admin_gate_ to obtain the index of
245 another user's transaction.
246 
247 
248 :Entry:  get_txn_info:  03/15/85 transaction_manager_$get_txn_info
249 
250 
251 Function:  This entry point returns a structure containing all the
252 information in the TDT about a transaction.
253 
254 
255 Syntax:
256 declare transaction_manager_$get_txn_info entry (bit(36) aligned, ptr,
257      fixed bin(35));
258 call transaction_manager_$get_txn_info (txn_id, txn_info_ptr, code);
259 
260 
261 Arguments:
262 txn_id
263    is the identifier of a transaction, or "0"b to default to the
264    current transaction.  (Input)
265 txn_info_ptr
266    is a pointer to the txn_info structure, declared in
267    dm_tm_txn_info.incl.pl1.  (Input)
268 code
269    is a standard system status code.  (Output)
270 
271 
272 Access required:
273 The caller requires re access to dm_admin_gate_ to obtain information
274 about another user's transaction.
275 
276 
277 :Entry: get_txn_info_index: 03/15/85 transaction_manager_$get_txn_info_index
278 
279 
280 Function:  This entry point returns the same information as
281 transaction_manager_$get_txn_info but accepts the index of a TDT entry
282 rather than a transaction identifier.  The transaction command, for
283 example, calls this entry point with numbers 1 through
284 transaction_manager_$get_tdt_size() to print information for the entire
285 TDT.
286 
287 
288 Syntax:
289 declare transaction_manager_$get_txn_info_index entry (fixed bin, ptr,
290      fixed bin(35));
291 call transaction_manager_$get_txn_info_index (txn_index, txn_info_ptr,
292      code);
293 
294 
295 Arguments:
296 txn_index
297    is the index of a TDT entry.  (Input)
298 txn_info_ptr
299    is a pointer to the txn_info structure, declared in
300    dm_tm_txn_info.incl.pl1.  (Input)
301 code
302    is a standard system status code.  (Output)
303 
304 
305 Access required:
306 The caller requires re access to dm_admin_gate_ to obtain information
307 about another user's transaction.
308 
309 
310 :Entry: handle_conditions: 03/15/85 transaction_manager_$handle_conditions
311 
312 
313 Function:  This entry point, intended to be called by "any_other"
314 handlers in user programs, temporarily suspends the current transaction
315 during an interruption caused by a signalled condition.  When invoked,
316 it suspends the current transaction, allows the condition to propagate,
317 and resumes the transaction when control returns.
318 
319 
320 Syntax:
321 declare transaction_manager_$handle_conditions entry ();
322 call transaction_manager_$handle_conditions ();
323 
324 
325 Arguments:
326    There are no arguments.
327 
328 
329 :Entry:  kill_txn:  03/15/85 transaction_manager_$kill_txn
330 
331 
332 Function:  This entry point is intended to be called by the owner of a
333 transaction when the owner cannot end the transaction normally and does
334 not want the daemon to try to abort it for reasons of efficiency.
335 Killing a transaction can destroy the consistency of the databases
336 changed during the transaction, and is therefore appropriate only if
337 consistency is no longer an issue (for example, if the databases are to
338 be deleted).  As with $abandon_txn, calling this entry point frees the
339 user to begin a new transaction.
340 
341 
342 Syntax:
343 declare transaction_manager_$kill_txn entry (bit(36) aligned, fixed
344      bin(35));
345 call transaction_manager_$kill_txn (txn_id, code);
346 
347 
348 Arguments:
349 txn_id
350    is the identifier of the transaction to be killed.  (Input) If it is
351    "0"b, the current transaction is used.
352 code
353    is a standard system status code.  (Output)
354 
355 
356 Access required:
357 The caller requires re access to dm_admin_gate_.
358 
359 
360 :Entry:  resume_txn:  03/15/85 transaction_manager_$resume_txn
361 
362 
363 Function:  This entry point reactivates a suspended transaction, once
364 again allowing data operations on protected files.
365 
366 
367 Syntax:
368 declare transaction_manager_$resume_txn entry (fixed bin(35));
369 call transaction_manager_$resume_txn (code);
370 
371 
372 Arguments:
373 code
374    is a standard system status code.  (Output)
375 
376 
377 :Entry:  rollback_txn:  03/15/85 transaction_manager_$rollback_txn
378 
379 
380 Function:  This entry point rolls the current transaction back to its
381 beginning, by replacing all modifications to protected files caused by
382 the transaction, with the before images preserved in the appropriate
383 before journal.  The transaction remains current for the user process.
384 
385 
386 Syntax:
387 declare transaction_manager_$rollback_txn entry (bit(36) aligned, fixed
388      bin, fixed bin(35));
389 call transaction_manager_$rollback_txn (txn_id, checkpoint_number,
390      code);
391 
392 
393 Arguments:
394 txn_id
395    is the identifier of the current transaction, or "0"b to default to
396    the current transaction.  (Input) If txn_id is neither "0"b nor the
397    transaction identifier of the current transaction,
398    dm_error_$transaction_not_current is returned.  This argument can be
399    used as a check to be sure which transaction is being rolled back.
400 checkpoint_number
401    must currently be 0.  (Input)
402 code
403    is a standard system status code.  (Output)
404 
405 
406 Notes:  This entry point will retry rollback of a transaction that was
407 left in an error state by a previous rollback.  It will not attempt to
408 rollback a transaction left in error by any other operation.
409 
410 
411 :Entry:  suspend_txn:  03/15/85 transaction_manager_$suspend_txn
412 
413 
414 Function:  This entry point puts the current transaction into a
415 suspended state wherein it is temporarily unusable.  Data operations to
416 protected files are not allowed while the transaction is suspended,
417 that is, until $resume_txn is called.  Since the suspended transaction
418 has not been completed, no new transaction can be begun.
419 
420 
421 Syntax:
422 declare transaction_manager_$suspend_txn entry (fixed bin(35));
423 call transaction_manager_$suspend_txn (code);
424 
425 
426 Arguments:
427 code
428    is a standard system status code.  (Output)
429 
430 
431 Notes:  Suspension has the following effects:
432 
433 1.   The current transaction is temporarily unusable.  As a result, the
434      entry point $get_current_txn_id returns "0"b and the error code
435      dm_error_$transaction_suspended.
436 
437 2.   No data operations on protected files are allowed while the
438      transaction is suspended.
439 
440 3.   Both $begin_txn and $commit_txn return
441      dm_error_$transaction_suspended.
442 
443 4.   Both $abort_txn and $adjust_tdt_entry (called by DMS) work on
444      suspended transactions.
445 
446 
447 :Entry:  user_shutdown:  03/15/85  transaction_manager_$user_shutdown
448 
449 
450 Function:
451 This  entry  point  shuts  down  DMS  in the calling process.  All TDT entries
452 belonging  to  the  caller's  Person.Project are adjusted before DMS is turned
453 off.   If  the  calling  process  is not currently using DMS, the entry does a
454 return.
455 
456 Information  about  the  adjusted  TDT  entries  is  returned in the structure
457 tm_shutdown_info, declared in dm_tm_shutdown_info.incl.pl1.
458 
459 
460 Syntax:
461 dcl transaction_manager_$user_shutdown entry (ptr, ptr, fixed
462     bin(35));
463 call transaction_manager_$user_shutdown (area_ptr,
464     tm_shutdown_info_ptr, code);
465 
466 
467 Arguments:
468 area_ptr
469    is a pointer to an area in which to allocate the shutdown_info
470    structure.  (Input)
471 tm_shutdown_info_ptr
472    is  the  returned pointer  to  tm_shutdown_info, found  in the
473    dm_tm_shutdown_info.incl.pl1 include file.  (Output)
474 code
475    is a standard system status code.  (Output)