1 08/27/79 This info segment describes how the MR7.0b release of Multics TP
  2 differs from the Transaction Processing manual, Order no.  CC96-01.
  3 
  4 
  5 Page ii, Preface: ADD at the end:
  6 
  7                         Implementation Restriction
  8 
  9      The implementation of the -use_xcn_mode control argument of tp_start is
 10 not complete.  This control argument should not be used.  All claims about and
 11 references to commiting transactions, rolling back transactions, having
 12 database changes appear atomically and rolling back database changes after a
 13 crash should be ignored.  In particular, the transaction_call_ interfaces
 14 described in section 4 and the -transaction attach description control
 15 argument of vfile_ described in MPM Subroutines are not completely
 16 implemented.
 17 
 18 
 19 Page 1-1, List of Features: ADD "if the -use_xcn_mode control argument of
 20 tp_start was specified" to the first two items.
 21 
 22 
 23 Page 1-2, second paragraph: ADD to the end: "This applies only if the
 24 -use_xcn_mode control argument of tp_start was specified."
 25 
 26 
 27 Page 1-3, Figure 1-1: REPLACE "Monitor" by "Subsystem".
 28 
 29 
 30 Page 1-4, third paragraph: REPLACE the beginning of the third sentence from
 31 "Databases" to "If the -use_xcn_mode control argument of tp_start was
 32 specified, databases".  INSERT "be" after "changes to" in the fourth line.
 33 
 34 
 35 Page 2-4, Step 10: REPLACE the first exec_com, the second paragraph and the
 36 second exec_com by:
 37 
 38  & Prepare MRDS databases
 39  application_open_mrds_db db_id1 dsm_path1
 40  application_ready_mrds_file db_id1 file_name1 rdy_mode1 collection_delay_time1
 41  .
 42  .
 43  .
 44  application_ready_mrds_file db_id1 file_nameI rdy_modeI collection_delay_timeI
 45  .
 46  .
 47  .
 48  application_open_mrds_db db_idN dsm_pathN
 49  .
 50  .
 51  .
 52  &quit
 53 
 54 The application_open_mrds_db and application_ready_mrds_file commands are
 55 written by the TP Administrator.  See Section 6 for more information about
 56 writing these commands.  The following is tp_init_database.ec for the
 57 Sample_TP project:
 58 
 59  & Prepare MRDS databases
 60  sample_tp_open_mrds_db people <databaes>people_db
 61  sample_tp_ready_mrds_file people people monitor_retrieve 90
 62  sample_tp_open_mrds_db inventory <databases>inventory
 63  sample_tp_ready_mrds_file inventory inventory update 300
 64  sample_tp_ready_mrds_file inventory parts update 300
 65  &quit
 66 
 67 
 68 Page 2-5, Step 11: DELETE "All segments in the comands directory are
 69 explicitly initiated to reduce overhead." REPLACE the example worker process
 70 absentee control segment by the following:
 71 
 72  change_wdir &1
 73  tp_worker_init_tcf [wd]
 74  &
 75  & Attach and open I/O switches
 76  io_call attach parts vfile_ <databases>parts -stationary -transaction tcf_
 77           -share
 78  io_call open parts keyed_sequential_update
 79  io_call control parts set_wait_time -collection_delay_time 300
 80  &
 81  tp_worker_start &ec_name [wd]
 82  &quit
 83 
 84 ADD to the end of the last paragraph: "The commitment mechanism is used only
 85 if the -use_xcn_mode control argument of tp_start was specified.  If this
 86 control argument was not specified, omit "-transaction tcf_" from the attach
 87 description."
 88 
 89 
 90 Page 3-4, tp_cancel: ADD to the paragraph description: "This command may only
 91 be used while transaction processing is running."
 92 
 93 
 94 Page 3-5, tp_change_deadline: ADD to the paragraph description: "This command
 95 may only be used while transaction processing is running."
 96 
 97 
 98 Page 3-6, tp_display_current_xcns: REPLACE "TP command name and TP_user_id" by
 99 "TP_user_id and TP command name".  ADD to the paragraph description: "This
100 command may only be used while transaction processing is running."
101 
102 
103 Page 3-7, tp_get_xcn_status: REPLACE the paragraph description by:
104 
105      The tp_get_xcn_status command prints information about transactions.  If
106 the transaction has not been processed the following information is printed:
107 transaction number, state, TP user who submitted it, TP command name, if it is
108 test mode, I/O process it was submitted from, submission time and deadline.
109 If the transaction is running, the following information is also printed:
110 worker process, time started and time from submission to processing.  If the
111 transaction has finished running, the following information is also printed:
112 time finished, start to finish time, submit to finish time and if nonzero the
113 vcpu time, page faults and retries.  If the transaction was canceled, the
114 information for an unprocessed transaction is printed along with the
115 cancelation time as the finish time and the time from submission to
116 cancelation.  This command may only be used while transaction processing is
117 running.
118 
119 REPLACE the description for control_arg by "may be -brief or -bf to print only
120 the transaction number and its state."
121 
122 
123 Page 3-8, tp_list_pending_requests: ADD to the paragraph description: "This
124 command may only be used while transaction processing is running." REPLACE the
125 description of the -long control argument by: "prints the transaction number,
126 position in the queue, deadline, TP user who submitted it and submission time
127 for each pending transaction.  The default prints only the position in the
128 queue and transaction number."
129 
130 
131 Page 3-9, tp_start: ADD to the control arguments section:
132 
133 -use_xcn_mode specifies that vfile_'s transaction mode should be used in this
134 TP subsystem.  This allows database changes in a transaction to appear
135 atomically and allows transactions to be rolled back.
136 
137 -no_use_xcn_mode specifies that vfile_'s transaction mode should not be used
138 in this TP subysystem.  This is the default.
139 
140 ADD to the "Notes" section:
141 
142      The -new_master control argument is incompatible with the -use_xcn_mode
143 and the -no_use_xcn_mode control arguments.  If the -no_use_xcn_mode control
144 argument is specified and Multics crashes in the middle of a transaction or
145 before the transaction is marked as completed, the transacton is rerun.
146 Database changes made by the transaction before the crash are not rolled back.
147 If an application only reads databases, or an application is not written to
148 depend upon transaction mode, then it is more efficient to specify
149 -no_use_xcn_mode.  Also, test mode is not available if -no_use_xcn_mode is
150 specified.
151 
152 
153 Page 3-11, tp_who: ADD to the paragraph description: "This command may only be
154 used while transaction processing is running." ADD to the description of the
155 TP_user_id argument: "The default prints information about all TP users that
156 are signed on." REPLACE the description of the -long control argument by:
157 "prints the I/O process name, device channel name, baud rate, terminal type,
158 terminal id and TP_user_id.  The default prints the TP_user_id and I/O process
159 name." ADD to the description of the -io_process control argument: "More than
160 one -io_process control argument may be specified."
161 
162 
163 Page 3-13, tp_rollback_transaction_: ADD the following as a "Notes" section:
164 
165      Database changes are rolled back only if the -use_xcn_mode control
166 argument of tp_start was specified.
167 
168 
169 Page 3-14, tp_verify_transaction_: ADD the following as a "Notes" section:
170 
171      If the -no_use_xcn_mode control argument of tp_start was specified, the
172 code argument will always be zero since asynchronous changes only occur in
173 transaction mode.
174 
175 
176 Page 3-20, tp_io_enter_test_mode: ADD the following as a "Notes" section:
177 
178      Test mode transactions may be run only if the -use_xcn_mode control
179 argument of tp_start was specified.
180 
181 
182 Page 3-22, tp_io_get_xcn_status: REPLACE the paragraph description by:
183 
184      The tp_io_get_xcn_status command prints information about transactions
185 submitted by the TP user.  If the transaction has not been processed the
186 following information is printed: transaction number, state, TP command name,
187 if it is test mode, submission time and deadline.  If the transaction is
188 running, the following information is also printed: time started and time from
189 submission to processing.  If the transaction has finished running, the
190 following information is also printed: time finished, start to finish time,
191 submit to finish time and if nonzero the vcpu time, page faults and retries.
192 If the transaction was canceled, the information for an unprocessed
193 transaction is printed along with the cancelation time as the finish time, and
194 the time from submission to cancelation.
195 
196 REPLACE the description for control_arg by "may be -brief or -bf to print only
197 the transaction number and its state."
198 
199 
200 Page 3-23, tp_io_list_pending_requests: In the paragraph description, REPLACE
201 "user" by "TP user".  REPLACE the description of the -long control argument
202 by: "prints the transaction number, position in the queue, deadline and
203 submission time for each pending transaction.  The default prints only the
204 position in the queue and transaction number."
205 
206 
207 Page 3-35, tp_meters: REPLACE the seven metering information points in the
208 paragraph description by:
209 
210 x^Ho    number of unprocessed, successful, commitment failure and error
211      transactions.  Cancelations are included in the error total.
212 
213 x^Ho    number of transactions submitted and submissions per minute, broken down
214      by I/O process and by TP user.
215 
216 x^Ho    for processed transactions, the number, number per minute, average
217      submisission to start time, average start to finish time, average vcpu
218      time, average page faults and average retries, broken down by worker
219      process and by TP command.
220 
221  REPLACE the usage line by:
222 
223           tp_meters {path} {-control_args}
224 
225 ADD to the description of the path argument: "The default is tp.tpinq in the
226 working directory."
227 
228 
229 Page 3-38, tp_shrink_q: REPLACE the usage line by:
230 
231           tp_shrink_q {path} {-control_args}
232 
233 ADD to the description of the path argument: "The default is tp.tpinq in the
234 working directory.  ADD to the first paragraph in the "Notes" section: "One of
235 the -delete or -output_description control arguments must be specified."
236 
237 
238 Page 5-1: ADD to the end of the first paragraph: "If the -no_use_xcn_mode
239 control argument of tp_start was specified, database changes from incomplete
240 transactions are not discarded." REPLACE "Then the worker process rolls back
241 ...  next transaction." in the third paragraph by: "If the -use_xcn_mode
242 control argument of tp_start was specified, any changes made by the
243 transaction are rolled back.  The worker process then goes on to the next
244 transaction." ADD to the end of the last paragraph: "Asynchronous changes only
245 occur if the -use_xcn_mode control argument of tp_start was specified."
246 
247 
248 Page 6-2, File Input/Output section: ADD to the end of the second paragraph:
249 "The commitment mechanism is used only if the -use_xcn_mode control argument
250 of tp_start was specified.  If the -no_use_xcn_mode control argument was
251 specified, asynchronous changes don't occur and it is not necessary to handle
252 the asynchronous change problem."
253 
254 
255 Page 6-3, Using MRDS section: REPLACE by:
256 
257      All databases used by any TPR should be opened in tp_init_database.ec to
258 reduce the overhead associated with a TPR.  All files of a database that will
259 be used should also be readied.  When a TPR is invoked, all its databases
260 should be open and all files that it will use should be ready.  TPRs should
261 not finish a file or close a database.  The -control control argument of
262 create_mrds_db should be used and should specify the TP subsystem's TCF if
263 vfile_'s transaction mode is used in this TP subsytem.
264 
265      The TP Administrator should write two commands for tp_init_database.ec.
266 See Section 2, Step 10.  The first command, application_open_mrds_db, is used
267 to open a MRDS database.  This command should save the MRDS database index in
268 an external static variable.  The database id argument, db_id, is used to
269 identify which database is being opened and consequently which external static
270 variable to save the database index in.  If vfile_'s transaction mode is being
271 used, application_open_mrds_db should also call dsl_$set_tcf_switch to change
272 the TCF I/O switch to tcf_.
273 
274      The second command, application_ready_mrds_file, is used to ready a MRDS
275 file.  This command should use the database id argument, db_id, to identify
276 which database contains the file and consequently which external static
277 variable contains the database index for the open database.  The file to ready
278 and the ready mode are arguments on the command line, file_name and rdy_mode
279 respectively.  If transaction mode is being used, a collection delay time
280 should be specified.  The collection delay time should be longer than the real
281 time any transaction that uses the file will require.  The
282 application_ready_mrds_file command should call dsl_$set_collection_delay_time
283 with the specified collection delay time.  To ensure repeatability if an
284 asynchronous change occurs in transaction mode, only the monitor_retrieve or
285 update ready modes should be used.
286 
287      The remaining problem is how to get the database index to a TPR.  Call
288 conventions should pass the database indices to TPRs as arguments.  A call
289 convention should pass all the database indices that any TPR using the call
290 convention may need.  If the TPR is written in PL/I, it may use the external
291 static variable containing a database index directly.
292 
293 
294 Page 6-5, Commitment and Rollback Features: ADD to the beginning of the first
295 paragraph: "This section describes the commitment mechanism enabled by the
296 -use_xcn_mode control argument of tp_start."
297 
298 
299 Page 6-6: ADD the following paragraph at the end:
300 
301      If the -no_use_xcn_mode control argument of tp_start was specified, the
302 commitment mechanism is disabled.  All database changes made by TPRs are
303 performed immediately.  Their effect is permanent and other users will see the
304 change when the change is made.  Commitments and roll backs are not performed
305 if transaction mode is not being used.