1 :Info: mtape_: 2020-12-26 mtape_ I/O module
2
3 Syntax as a command:
4 io_call attach SWITCHNAME mtape_ VOLUME_SPECs -control_args
5
6
7 Syntax of attach description:
8 mtape_ VOLUME_SPECs -control_args
9
10
11 Function: The mtape_ I/O module supports I/O to/from tapes in
12 - ANSI standard format
13 - IBM standard format
14 - IBM unlabeled format
15 - IBM Disk Operating System DOS formatted
16
17 For details not described in this info segment, see the Multics
18 Subroutines and I/O Modules manual order no. AG93 description of the
19 mtape_ I/O module.
20
21
22 Arguments:
23 attach
24 is the iox_ operation to be performed by the io_call command.
25 SWITCHNAME
26 is the name of an I/O switch to be attached to the mtape_ I/O
27 module.
28 mtape_
29 is the I/O module name.
30
31
32 Arguments for volume specification:
33 Each VOLUME_SPEC argument requires a VOL_NAME, which may be
34 followed by a -comment control argument.
35 VOL_NAME
36 label of a volume in the volume set to be attached.
37
38
39 Control arguments for volume specification:
40 -volume VOL_NAME
41 used when VOL_NAME begins with hyphen - character, VOL_NAME is a
42 label of a volume in the volume set to be attached.
43 -comment VNi_STR, -com VNi_STR
44 an optional message to be displayed on the operator console at the
45 time this VOL_NAME is to be mounted. The comment text VNi_STR may
46 be from 1 to 64 characters in length and must be quoted if it
47 contains embedded white space. The optional comment specification
48 must follow its corresponding volume specification and precede the
49 next volume specification.
50
51
52 Control arguments attach description:
53 -default_volume_type STR, -dvt STR
54 specifies the volume type STR to be used for Per-Format module
55 selection see "Notes on tape format selection" below when an
56 unreadable or unlabeled tape is mounted for potential output
57 operations and no "-volume_type" control argument is given.
58 Permissable values for this control argument are "ansi", or "ibm".
59 Default value is "ansi".
60
61
62 -density N, -den N
63 specifies the recording density for output operations in bits per
64 inch BPI. For input operations, the density is determined and
65 set automatically by RCP. Permissible values are 200, 556, 800,
66 1600 and 6250. Default density is 1600 BPI.
67
68
69 -device N, -dv N
70 specifies the number of tape devices that will be requested to be
71 used simultaneously for multi-volume operations. Permissible
72 values are from 1 to 63. Default is 1 device.
73
74
75 -display, -ds
76 specifies that the entire attach description, after it has been
77 parsed and any necessary defaults added, will be displayed on the
78 user_output I/O switch.
79 -no_display, -nds
80 specifies that the attach description will not be displayed.
81 Default
82
83
84 -error, -err
85 specifies that verbose error messages will be displayed when
86 exception conditions e.g. unrecoverable tape errors are
87 detected. Default
88 -no_error, -nerr
89 specifies that only error codes will be returned upon detection of
90 exception conditions.
91
92
93 -label, -lbl
94 specifies that volume and file label records exist and or are to
95 be recorded by the selected Per-Format module. Default
96 -no_label, -no_labels, -nlbl
97 specifies that volume and file label records do not exist or are
98 not to be recorded by the selected Per-Format module. If this
99 control argument is given when attempting to select a Per-Format
100 module that does not accept unlabeled tape volumes, the attachment
101 is aborted.
102
103
104 -ring, -rg
105 specifies that volumes are to be mounted with write rings
106 installed.
107 -no_ring, -nrg
108 specifies that volumes are to be mounted with no write rings
109 installed. Default
110
111
112 -speed N1N2...Nn, -ips N1N2...Nn
113 specifies desired tape drive speeds in inches per second IPS.
114 permissible values are 75, 125 and 200. If more than one speed
115 device is to be used, the optional second and third speed
116 specification must be separated by commas as shown. If this
117 control argument is omitted, RCP will pick any available speed
118 device.
119
120
121 -system, -sys
122 specifies that the user is requesting to be considered a system
123 process.
124 -no_system, -nsys
125 specifies that the user is not to be considered a system process.
126 Default
127
128
129 -track N, -tk N
130 specifies the track type of the tape drive to be used.
131 Permissible values are 7 or 9. Default is 9 track.
132
133
134 -volume_type STR, -vt STR
135 specifies the volume type to be used in Per-Format module
136 selection See "Notes on tape format selection" below.
137 Permissable values for this control argument are "ansi", or "ibm".
138 No Default. The volume type is determined by RCP for labeled
139 volumes and by the "-default_volume_type" specification for
140 unlabeled or unreadable volumes.
141
142
143 -wait, -wt
144 specifies that when tape devices are not immediately available
145 from RCP for a requested volume mount, the mtape_ I/O module
146 should wait for the number of minutes specified by the
147 "-wait_time" control argument or its default value, before
148 reporting an error on the initial volume mount or subsequent
149 volume switching.
150 -no_wait, -nwt
151 specifies that the mtape_ I/O module will not wait for an
152 available device to become free, but instead report an error
153 immediately. Default
154
155
156 -wait_time N, -wtm N
157 specifies the time in minutes that the mtape_ I/O module will
158 wait for unavailable tape drives to become available for volume
159 mounts when the "-wait" control argument is specified.
160 Permissible values range from 1 to 1440 minutes 24 hours.
161 Default wait time is 10 minutes.
162
163
164 List of opening modes:
165 The following I/O opening modes are supported by mtape_.
166 sequential_input
167 read data blocks from tape media.
168 sequential_output
169 write data blocks to tape media.
170
171
172 List of operations:
173 mtape_ implements the following I/O setup operations. For details
174 on any operation, type: help mtape_.OPERATION
175
176 open_file, open
177 opens an mtape_ I/O switch for reading or writing a file from the
178 attached volume set.
179 close_file, close
180 closes an mtape_ I/O switch to end operations on the current file.
181 detach, detach_iocb
182 detaches an mtape_ I/O switch to end operations on the volume set.
183
184
185 List of i/o operations:
186 The following standard iox_ operations are supported by mtape_.
187 For details about any operation, type: help iox_$OPERATION
188 read_record
189 read records from an mtape_ file, when opened for sequential_input.
190 write_record
191 write records to an mtape_ file, when opened for sequential_output.
192 position
193 when opened for sequential_input, mtape_ supports all positioning
194 types appropriate for sequential_input.
195 control
196 executes a special mtape_ operation. See "List of controls" and
197 "List of control operations" below.
198
199
200 List of controls:
201 Controls with the following ORDERNAMEs require no additional data.
202 The info_ptr argument should be a null pointer. To use these
203 controls from a command line, type:
204 io_call control SWITCHNAME ORDERNAME
205
206 force_end_of_volume, feov
207 simulates detection of the end of tape reflective foil upon
208 the next write block operation. The PFM will then close out
209 the volume by writing the EOV trailer labels and request a
210 volume switch for the next volume in the volume sequence
211 list. The I/O switch must be open for sequential_output.
212
213
214 ring_in, rin
215 requires that the I/O switch is closed and will cause all
216 currently mounted volumes of the volume set to be demounted.
217 When the next file opening is performed, the required volume
218 will be re-mounted with the write ring installed.
219
220
221 List of control operations:
222 Controls with the following ORDERNAMEs accept info_ptr values. For
223 details about inputs/outputs for each control order, type:
224 help mtape_.ORDERNAME
225
226 file_status, fst
227 returns a pointer to a structure that contains the status of
228 the current file specified by the open description.
229 file_set_status, fsst
230 returns a pointer to an array of structures defining the
231 file status for all files in the current file set.
232 hardware_status, hwst
233 returns a pointer to a structure that contains hardware status
234 for the last I/O operation.
235
236
237 volume_status, vst
238 returns a pointer to a structure that contains the status of
239 the current volume.
240 volume_set_status, vsst
241 returns a pointer to an array of structures defining the
242 volume status for all volumes in the current volume set.
243 io_call
244 executes one of the above mtape_ control operations on behalf of
245 the io_call command. The details for each control include
246 "Syntax as a command" and/or "Syntax as an active function"
247 sections describing how inputs for the control are given via the
248 io_call command, or how outputs from the control are displayed or
249 returned as the active function result.
250
251
252 Notes on tape format selection:
253 Unlike other Multics tape I/O modules, mtape_ will process tapes
254 in several different formats currently limited to ANSI and IBM
255 formats. In order to accommodate this capability, the mtape_ I/O
256 module itself does all of the physical tape I/O and error
257 recovery, but allows all logical file and record level I/O to be
258 performed by a format specific subroutine known as a Per-Format
259 module PFM. Selection of the appropriate PFM is performed at
260 attach time after the first volume has been mounted. In the
261 absence of a "-volume_type" specification, the PFM is selected on
262 the basis of the volume_type info returned by RCP.
263
264
265 Notes on user settable defaults:
266 The default values for the attach, open, close and detach
267 descriptions were picked for their sensibility and the authors
268 experience in how most people process tapes. However, it is
269 recognized that for whatever reason different people and or
270 groups of people may want different default values to suit their
271 needs. Therefore, a command has been written which will allow
272 the attach, open, close and detach description default values to
273 be tailored to a particular groups or persons needs. For further
274 information, type: help mtape_set_defaults
275
276
277 Notes on user label processing:
278 Each labeled volume set may include user-specified volume and file
279 labels. Generation of output labels and validation of input labels is
280 performed by a user label subroutine. This routine is referenced by
281 the -label_entry open description argument.
282
283 For information about the calling sequence and functions of the label
284 processing routine, type:
285 help mtape_user_label_rtn_
286
287
288 :Info: mtape_.open_file: mtape_.open: 2020-06-17 mtape_ open_file operation
289
290 Syntax as a command:
291 io_call open_file SWITCHNAME OPENING_MODE -control_args
292 io_call open SWITCHNAME OPENING_MODE
293
294
295 Syntax of open description:
296 -control_args
297
298
299 Function:
300 Opening a file is accomplished by calling the iox_$open_file entry
301 which accepts a character string "open description" argument. The
302 open description is one or more control arguments giving file
303 attribute and positioning information to the selected per-format
304 module PFM. Both the ANSI and IBM PFMs accept sequential_input and
305 sequential_output opening modes.
306
307 The iox_$open entry is also supported. It passes an empty string
308 description to the open_file entry, thereby applying default open
309 description values. For information about iox_ entrypoints, type:
310 help iox_$open_file or help iox_$open
311
312
313 Arguments:
314 open_file
315 is the I/O operation to be performed when open description control
316 arguments are provided.
317 open
318 is the I/O operation to be performed when default values are
319 acceptable for each opening description control argument.
320 SWITCHNAME
321 is the name of an I/O switch attached using the mtape_ I/O module.
322 OPENING_MODE
323 may be any mode given in "List of opening modes below.
324
325
326 List of opening modes:
327 The following I/O opening modes are supported by mtape_. Each
328 description ends numeric value followed by constant name from
329 iox_modes.incl.pl1 for that opening mode. For iox_ details, type:
330 help iox_$open_file
331
332 sequential_input, sqi
333 read records from the tape media. 4 = Sequential_input
334 sequential_output, sqo
335 write records to the tape media. 5 = Sequential_output
336
337
338 Control arguments for open description all tape formats:
339 -append, -app
340 specifies that the requested file is to be appended to the
341 end of the file set as a new file. The requested opening
342 mode must be sequential_output or the file opening will be
343 aborted.
344 -no_append, -napp
345 specifies that the requested file is not to be appended to
346 the end of the file set. Default
347
348
349 -block N, -bk N
350 specifies the block size in bytes for output operations and
351 is also required for input operations for IBM unlabeled or
352 DOS formatted tapes. For input operations on standard
353 labeled IBM or ANSI tape files, the block size is obtained
354 from the the file header label record. Permissible values
355 are from 18 to 99996 bytes. Defaults are 2048 bytes for
356 ANSI and 8192 bytes for IBM formats.
357
358
359 -comment STR, -com STR
360 specifies a user comment to be displayed on the user_output
361 I/O switch, after the file has been successfully opened.
362 The comment text STR may be from 1 to 80 characters in
363 length.
364
365
366 -default_fixed_record N, -dfr N
367 specifies the record length to be used for "f" or "fb" formats in
368 the absence of a "-record" specification. The intended purpose of
369 this control argument is to supply a default value for record size
370 without having to include a "-record" specification in the open
371 description. If the user wishes to explicitly specify the record
372 length, the "-record" control argument should be used. Although
373 the "-default_fixed_record" control argument may appear in a users
374 open description and be processed accordingly, this would not be
375 considered the "proper" method of explicitly supplying the record
376 length. The default value of "N" is set to 80 for 80 character
377 records for both the ANSI and IBM PFMs. This default value may
378 be changed by the default setting mechanism see "Notes on user
379 settable defaults" below.
380
381
382 -default_spanned_record N, -dsr N
383 specifies the record length to be used for ANSI "s" or "sb"
384 formats, or IBM "vs" or "vbs" formats, in the absence of a
385 "-record" specification. The intended purpose of this
386 control argument is to supply a default value for record
387 size without having to include a "-record" specification in
388 the open description. If the user wishes to explicitly
389 specify the record length, the "-record" control argument
390 should be used. Although the "-default_spanned_record"
391 control argument may appear in a users open description and
392 be processed accordingly, this would not be considered the
393 "proper" method of explicitly supplying the record length.
394 The default value of "N" is set to 1044480
395 sys_info$max_seg_size * 4 for both the ANSI and IBM PFMs.
396
397
398 This default value may be changed by the default setting mechanism
399 see "Notes on user settable defaults" below.
400
401
402 -default_variable_record N, -dvr N
403 specifies the record length to be used for ANSI "d" or "db"
404 formats, or IBM "v" or "vb" format in the absence of a
405 "-record" specification. The intended purpose of this
406 control argument is to supply a default value for record
407 size without having to include a "-record" specification in
408 the open description. If the user wishes to explicitly
409 specify the record length, the "-record" control argument
410 should be used. Although the "-default_variable_record"
411 control argument may appear in a users open description and
412 be processed accordingly, this would not be considered the
413 "proper" method of explicitly specifying the record length.
414 The default value of "N" is set equal to the default block
415 size i.e. 2048 for ANSI and 8192 for IBM.
416
417
418 This default value may be changed by the default setting mechanism
419 see "Notes on user settable defaults" below.
420
421
422 -display, -ds
423 specifies that the entire open description, after it has
424 been parsed and any necessary defaults added, is to be
425 displayed on the user_output I/O switch.
426 -no_display, -nds
427 specifies that the open description will not be displayed on
428 the user_output I/O switch. Default
429 -expires date, -exp date
430 specifies the expiration date of the file to be created,
431 where date must be of a form acceptable to the
432 convert_date_to_binary_ subroutine.
433
434
435 -extend, -ext
436 specifies extension of an existing file.
437 -no_extend, -next
438 specifies that the requested file is not to be extended.
439 Default
440 -force, -fc
441 specifies that the expiration date of the file being overwritten
442 is to be ignored.
443 -no_force, -nfc
444 specifies that the expiration date of a file being
445 overwritten is not to be ignored. If the expiration date is
446 not in the past, the user is queried for permission to
447 overwrite the file. Default
448
449
450 -format F, -fmt F
451 specifies the record format of the file. Permissible values
452 for ANSI: U, F, D, S, FB, DB, and SB; for IBM: U, F, V, VS,
453 FB, VB, and VBS. They may be specified in either upper or
454 lower case. Default values are DB for ANSI format and VB
455 for IBM formats.
456 -label_entry entry, -lbe entry
457 specifies the entry point of a user subroutine which will be
458 called to process the contents of user label records on
459 input and generate the contents of same, for subsequent
460 writing by mtape_ on output. See "Notes on user label processing"
461 below.
462
463
464 -last_file, -lf
465 specifies that the file to be processed is the last file of
466 the file set.
467 -not_last_file, -nlf
468 specifies that the file to be processed may not be the last
469 file of the file set. Default
470 -mode STR, -md STR
471 specifies the encoding mode used to record the file data.
472 Permissible values of STR are ascii, ebcdic or binary.
473 Default for ANSI format is ascii; for IBM format the
474 default is ebcdic.
475
476
477 -modify, -mod
478 specifies modification of an existing file while retaining
479 the file attributes as recorded in the original files header
480 label records.
481 -no_modify, -nmod
482 specifies that modification of an existing file is not to be
483 performed. Default
484 -name STR, -nm STR
485 specifies the file identifier of the requested file. STR
486 can be from 1 to 17 characters.
487
488
489 -next_file, -nf
490 specifies the file to be processed as the "next" or first
491 file of the file set. This control argument is intended to
492 be used when sequentially processing files. For output
493 operations, if -name and or -number are not specified, the
494 values of their respective fields are fabricated by using
495 the next sequential number as the file sequence number and
496 forming the file name by concatenating the string "FILE"
497 with the alpha-numeric representation of the file number.
498 i.e. "FILE0001". Default
499 -not_next_file, -nnf
500 specifies that the requested file is not the next file.
501
502
503 -number N, -nb N
504 specifies the file sequence number or numerical position
505 within the file set. Permissible values range from 1 to
506 9999.
507
508
509 -record N, -rec N
510 specifies the logical record length in bytes. Permissible
511 values range from 18 to 1044480 sys_info$max_seg_size * 4
512 bytes, but the legality of the record size is dependent on
513 the record format specified with the "-format" control
514 argument and the block size. In general the record size
515 must be <= the block size with the exception of "spanned
516 record" formats i.e. ANSI S or SB formats and IBM VS or
517 VBS formats, where the record size may be the max
518 allowable. No default value. The default record size is
519 determined by the value of the appropriate "-default_fixed
520 spanned variable_record" specification.
521
522
523 -replace STR, -rpl STR
524 specifies replacement of an existing file, where STR is the
525 file identifier to use in the search for the file to be
526 replaced.
527
528
529 Control arguments for open description ansi tape format:
530 -buffer_offset, -bo
531 specifies that each block will be recorded with an 8
532 character prefix. See "Notes on ansi block prefix" below.
533 -no_buffer_offset, -nbo
534 specifies that no block prefix will be recorded in each data
535 block. Default
536
537
538 -generate, -gen
539 specifies creating a new "generation" of an existing file by
540 replacement. The file attributes recorded in the file
541 header remains the same as the replaced file, but the
542 generation number in the file header is incremented by 1.
543 -no_generate, -ngen
544 specifies that a new generation of an existing file will not
545 be created. Default
546
547
548 Control arguments for open description ibm tape format:
549 -dos
550 specifies that the file to be processed is in IBM DOS
551 format. IBM DOS files contain only one header label the HDR1
552 label and do not retain any information as to file format,
553 block length and record length. It is therefore necessary
554 to specify the "-block", "-record" and "-format" control
555 arguments or allow the default values for same to be used
556 even when opening an IBM DOS file for input.
557 -no_dos, -ndos
558 specifies that the file to be processed is not in IBM DOS
559 format but is in fact in IBM standard OS/VS format.
560 Default
561
562
563 -system_use
564 specifies that when opening for output, certain fields of
565 the HDR2 and EOV2 label records will be used to record the
566 recording mode ASCII EBCDIC or BINARY, and the volume
567 name of the next volume in the volume sequence list. The
568 fields used for these purposes are HDR2 character position
569 40 for recording mode recorded as an EBCDIC "1" "2" or
570 "3" for ASCII EBCDIC or BINARY respectively, and EOV2
571 character positions 41 - 46 for the next volume name. The
572 IBM OS/VS Tape Labels specification marks these fields as
573 "reserved for future use". It is therefore recommended that
574 the "-system_use" control argument not be used in an
575 interchange environment.
576
577
578 -no_system_use
579 specifies that the HDR2 and EOV2 label record fields
580 mentioned above will not be corrupted. Default
581
582
583 Notes on ansi block prefix:
584 dcl 1 tape_block aligned based,
585 2 block_size fixed dec 7 0 unaligned,
586 2 block_number fixed dec 7 0 unaligned,
587 2 block_data char tape_block.block_size - 8 unaligned;
588
589 block_size
590 is the block size in 9 bit bytes, including the block_size and
591 block_number elements 8 characters long.
592 block_number
593 is the numerical sequence number of the block within the current
594 physical file, starting at block number 0.
595 block_data
596 is the user specified data recorded in the block. The length of
597 this field is governed by the user specified block length.
598
599
600 An ansi-format tape block written with the -block_offset control
601 argument includes a prefix describing each data block. Each block
602 is written to tape using the tape_block template shown below.
603
604 The block_size and block_number field are recorded in the packed fixed
605 decimal pl1 data type, so that they may be written in the same manner
606 without regard to interface recording mode nine bit or binary. The
607 buffer offset prefix length is recorded in the ANSI HDR2 label record
608 buffer offset field character positions 51 and 52.
609
610
611 Notes on user settable defaults:
612 The default values for the attach, open, close and detach descriptions
613 were picked for their sensibility and the authors experience in how
614 most people process tapes. However, it is recognized that for
615 whatever reason different people and or groups of people may want
616 different default values to suit their needs. Therefore, a command
617 has been written which will allow the attach, open, close and detach
618 description default values to be tailored to a particular groups or
619 persons needs. For further information, type "help
620 mtape_set_defaults".
621
622
623 Notes on user label processing:
624 Each labeled volume set may include user-specified volume and file
625 labels. Generation of output labels and validation of input labels is
626 performed by a user label subroutine. This routine is referenced by
627 the -label_entry open description argument see above.
628
629 For information about the calling sequence and functions of the label
630 processing routine, type:
631 help mtape_user_label_rtn_
632
633
634 :Info: mtape_.close_file: mtape_.close: 2020-06-17 mtape_ close_file operation
635
636 Syntax as a command:
637 io_call close_file SWITCHNAME -control_args
638 io_call close SWITCHNAME
639
640
641 Syntax of close description:
642 -control_args
643
644
645 Function:
646 Closing a file is accomplished by calling the iox_$close_file
647 entry which accepts as one of its arguments a character string
648 "close description". The close description supplies close option
649 information to the selected Per-Format Module PFM.
650
651 The iox_$close entry is also supported. It passes an empty string
652 description to the close_file entry, thereby applying default close
653 description values. For information about iox_ entrypoints, type:
654 help iox_$close_file or help iox_$close
655
656
657 Arguments:
658 close_file
659 is the I/O operation to be performed when close description control
660 arguments are provided.
661 close
662 is the I/O operation which may be called when default values are
663 acceptable for each close description control argument.
664 SWITCHNAME
665 is the name of an I/O switch attached using the mtape_ I/O module.
666
667
668 Control arguments:
669 -close_position STR, -cls_pos STR
670 specifies where to physically position the tape volume
671 within the bounds of the file that is being closed. The
672 values of STR are case insensitive and may be selected from
673 "bof" for beginning of file, "eof" for end of file and
674 "leave" to leave the tape positioned where it is. Default
675 close position is "leave".
676 -comment STR, -com STR
677 specifies a user comment to be displayed on the user_output
678 I/O switch, after the file has been successfully closed.
679 The comment text STR may be from 1 to 80 characters in
680 length.
681
682
683 -display, -ds
684 specifies that the entire close description, after it has
685 been parsed and any necessary defaults added, is to be
686 displayed on the user_output I/O switch.
687 -no_display, -nds
688 specifies that the close description will not be displayed
689 on the user_output I/O switch. Default
690
691
692 Notes on user settable defaults:
693 The default values for the attach, open, close and detach descriptions
694 were picked for their sensibility and the authors experience in how
695 most people process tapes. However, it is recognized that for
696 whatever reason different people and or groups of people may want
697 different default values to suit their needs. Therefore, a command
698 has been written which will allow the attach, open, close and detach
699 description default values to be tailored to a particular groups or
700 persons needs. For further information, type: help mtape_set_defaults
701
702
703 :Info: mtape_.detach: mtape_.detach_iocb: 2020-06-17 mtape_ detach operation
704
705 Syntax as a command:
706 io_call detach SWITCHNAME -control_args
707 io_call detach_iocb SWITCHNAME
708
709
710 Syntax of detach description:
711 -control_args
712
713
714 Function:
715 Detaching the I/O switch is accomplished by calling the iox_$detach
716 entry which accepts as one of its arguments a character string "detach
717 description". The detach description supplies mtape_ with detach
718 option information.
719
720 The iox_$detach_iocb entry is also supported. It passes an empty
721 string description to the detach entry, thereby applying default
722 detach description values. For information about iox_ entrypoints,
723 type: help iox_$detach or help iox_$detach_iocb
724
725
726 Control arguments:
727 -comment STR, -com STR
728 specifies the contents of an optional comment to be
729 displayed on the operator console when demounting the first
730 volume found that is still mounted. The comment may be from
731 1 to 65 characters in length.
732 -display, -ds
733 specifies that the entire detach description, after it has
734 been parsed and any necessary defaults added, is to be
735 displayed on the user_output I/O switch.
736 -no_display, -nds
737 specifies that the detach description will not be displayed
738 on the user_output I/O switch. Default
739
740
741 -rewind, -rew
742 specifies that the remaining mounted volumes are to be
743 rewound to load point upon detachment. Default
744 -unload, -unld
745 specifies that the remaining mounted volumes are to be
746 physically unloaded from the tape drive upon detachment.
747
748
749 Notes on user settable defaults:
750 The default values for the attach, open, close and detach descriptions
751 were picked for their sensibility and the authors experience in how
752 most people process tapes. However, it is recognized that for
753 whatever reason different people and or groups of people may want
754 different default values to suit their needs. Therefore, a command
755 has been written which will allow the attach, open, close and detach
756 description default values to be tailored to a particular groups or
757 persons needs. For further information, type: help mtape_set_defaults
758
759
760 :Info: mtape_.file_status: mtape_.fst: 1985-02-18 mtape_ file_status control
761
762 Control order: file_status, fst
763
764 The iox_$control info_ptr argument points to a structure that reports
765 the status of the current file specified by the open description.
766 File attribute as well as error summary information is included.
767
768
769 Syntax:
770 call iox_$control iocb_ptr "file_status" info_ptr code;
771
772
773 Arguments for iox_$control:
774 info_ptr
775 points to the following structure, or is a null pointer. See
776 "Notes on the info_ptr" below.
777
778 dcl 1 mtape_fst aligned based info_ptr,
779 2 version char 8,
780 2 file_type fixed bin,
781 2 file_state fixed bin,
782 2 error_code fixed bin 35,
783 2 file_id char 32,
784 2 file_seq fixed bin,
785 2 begin_vol_index fixed bin,
786 2 end_vol_index fixed bin,
787 2 file_sections fixed bin,
788 2 generation fixed bin,
789 2 gen_version fixed bin,
790 2 creation char 6,
791 2 expiration char 6,
792 2 file_format char 3,
793 2 block_len fixed bin,
794 2 reclen fixed bin 21,
795 2 recording_mode char 6,
796 2 block_count fixed bin 35,
797 2 read_errors fixed bin 35,
798 2 write_errors fixed bin 35;
799
800
801 List of elements:
802 version
803 is the current structure version. If info_ptr is nonnull on input,
804 the caller must set the version element to fst_version_1.
805 Otherwise mtape_ will set the version element in the structure it
806 allocates.
807 file_type
808 is the encoded file set type as determined by RCP, and could have
809 one of the following values.
810 4 = IBM file set
811 5 = ANSI file set
812
813
814 file_state
815 is the current state of this file and could have one of the
816 following values:
817 0 = No information available I/O switch never opened
818 1 = File not open
819 2 = File open
820 3 = File open and locked for error
821
822 The "locked for error" state referenced above is defined as an
823 error or circumstance that prevents continued processing of this
824 file. For example, parity error while reading, reached end of
825 information, no next volume available, etc.
826
827
828 error_code
829 is the error code when mtape_fst.file_state is equal to 3 above,
830 otherwise equal to 0.
831 file_id
832 is the file name or identifier as recorded in the appropriate file
833 label record. This field. will be blank for unlabeled formats.
834 file_seq
835 is the numerical order of this file within the file set.
836 begin_vol_index
837 is the numerical index of the first volume set member on which this
838 file resides.
839 end_vol_index
840 is the numerical index of the last volume set member on which this
841 file resides.
842
843
844 file_sections
845 is a count of the number of volumes on which this file resides.
846 generation
847 is the generation number of this file for those formats that
848 support several "generations" of files. If this is the first
849 generation, or if the format does not support several generations,
850 then this field will be equal to 0.
851 gen_version
852 is the generation version number for those formats that support
853 file generations. If this is the first generation, or if the
854 format does not support several generations, then this field will
855 be equal to 0.
856 creation
857 is the Julian creation date of this file in the form "yyddd".
858
859
860 expiration
861 is the expiration creation date of this file in the form "yyddd".
862 If no expiration date was specified at file creation time, then the
863 field will contain the string "00000".
864 file_format
865 is the encoded alphabetic representation of the volume type
866 specific file format e.g. "VBS" for IBM variable spanned block
867 format "DB" for ANSI variable record blocked format etc.
868 block_len
869 is the maximum block length of each block within this file.
870 reclen
871 is the maximum record length of the logical records within this
872 file.
873
874
875 recording_mode
876 is the numeric indication of the recording mode of this file. The
877 following values are defined:
878 0 = Unknown or unspecified
879 1 = ASCII
880 2 = EBCDIC
881 3 = Binary
882 block_count
883 is the number of tape blocks contained in this file. If the file is
884 still open, this number represents the number of blocks processed
885 thus far.
886
887
888 read_errors
889 is a count of the number of read errors recoverable as well as
890 unrecoverable encountered while reading this file. Note that read
891 errors recovered by the hardware auto retry are not counted. Only
892 Multics reread operations with varying threshold and deskew
893 settings are counted.
894 write_errors
895 is a count of the number of write errors recoverable as well as
896 unrecoverable encountered while writing this file.
897
898
899 Notes on the info_ptr:
900 The mtape_fst structure declaration shown above can be found in the
901 include file "mtape_file_status.incl.pl1". If the iox_$control
902 info_ptr argument is null, then mtape_ will allocate the structure
903 returned to the caller; the caller must free that structure.
904
905
906 Syntax as a command:
907 io_call control SWITCHNAME fst
908
909
910 Arguments for io_call:
911 SWITCHNAME
912 is the name of an I/O switch attached to the mtape_ I/O module.
913 file_status, fst
914 is the name of the control order to be performed.
915
916
917 Notes on the io_call command:
918 When the io_call command performs an mtape_ control order, any data
919 normally returned by that control order is interpreted by mtape_ and
920 displayed on the user's terminal.
921
922
923 :Info: mtape_.file_set_status: mtape_.fsst: 1985-02-18 mtape_ file_set_status control
924
925 Control order: file_set_status, fsst
926
927 The iox_$control info_ptr argument points to a structure holding an
928 array of file status for all files in the current file set.
929
930
931 Syntax:
932 call iox_$control iocb_ptr "file_set_status" info_ptr code;
933
934
935 Arguments for iox_$control:
936 info_ptr
937 points to the following structure, or is a null pointer. See
938 "Notes on the info_ptr" below.
939
940 dcl 1 mtape_fsst aligned based info_ptr,
941 2 version char 8,
942 2 file_set_id char 32,
943 2 file_type fixed bin,
944 2 nfiles fixed bin,
945 2 fs_stat mtape_fsst nfiles refer mtape_fsst.nfiles,
946 3 file_state fixed bin,
947 3 error_code fixed bin 35,
948 3 file_id char 32,
949 3 file_seq fixed bin,
950 3 begin_vol_index fixed bin,
951 3 end_vol_index fixed bin,
952 3 file_sections fixed bin,
953 3 generation fixed bin,
954 3 gen_version fixed bin,
955 3 creation char 6,
956 3 expiration char 6,
957 3 file_format char 3,
958 3 block_len fixed bin,
959 3 reclen fixed bin 21,
960 3 recording_mode char 6,
961 3 block_count fixed bin 35,
962 3 read_errors fixed bin 35,
963 3 write_errors fixed bin 35;
964
965
966 List of elements:
967 version
968 is the current structure version. If info_ptr is nonnull on input,
969 then the caller must set the version field to fsst_version 1. If
970 null, mtape_ will set the version element in the structure it
971 allocates.
972 file_set_id
973 is the file set identifier recorded in the file labels. This is
974 usually the volume name of the first volume in the volume set.
975 file_type
976 is the encoded file set type as determined by RCP, and could have
977 one of the following values.
978 4 = IBM file set
979 5 = ANSI file set
980
981
982 nfiles
983 is the number of files in the file set.
984 fs_stat
985 is an array of structures of file set members, which appears below
986 in sequential order. See "Notes on the mtape_fsst structure"
987 below.
988
989
990 file_state
991 is the current state of this file and could have one of the
992 following values:
993 0 = No information available I/O switch never opened
994 1 = File not open
995 2 = File open
996 3 = File open and locked for error
997
998 The "locked for error" state referenced above is defined as an
999 error or circumstance that prevents continued processing of this
1000 file. For example, parity error while reading, reached end of
1001 information, no next volume available, etc.
1002
1003
1004 error_code
1005 is the error code when mtape_fst.file_state is equal to 3 above,
1006 otherwise equal to 0.
1007 file_id
1008 is the file name or identifier as recorded in the appropriate file
1009 label record. This field. will be blank for unlabeled formats.
1010 file_seq
1011 is the numerical order of this file within the file set.
1012 begin_vol_index
1013 is the numerical index of the first volume set member on which this
1014 file resides.
1015 end_vol_index
1016 is the numerical index of the last volume set member on which this
1017 file resides.
1018
1019
1020 file_sections
1021 is a count of the number of volumes on which this file resides.
1022 generation
1023 is the generation number of this file for those formats that
1024 support several "generations" of files. If this is the first
1025 generation, or if the format does not support several generations,
1026 then this field will be equal to 0.
1027 gen_version
1028 is the generation version number for those formats that support
1029 file generations. If this is the first generation, or if the
1030 format does not support several generations, then this field will
1031 be equal to 0.
1032 creation
1033 is the Julian creation date of this file in the form "yyddd".
1034
1035
1036 expiration
1037 is the expiration creation date of this file in the form "yyddd".
1038 If no expiration date was specified at file creation time, then the
1039 field will contain the string "00000".
1040 file_format
1041 is the encoded alphabetic representation of the volume type
1042 specific file format e.g. "VBS" for IBM variable spanned block
1043 format "DB" for ANSI variable record blocked format etc.
1044 block_len
1045 is the maximum block length of each block within this file.
1046 reclen
1047 is the maximum record length of the logical records within this
1048 file.
1049
1050
1051 recording_mode
1052 is the numeric indication of the recording mode of this file. The
1053 following values are defined:
1054 0 = Unknown or unspecified
1055 1 = ASCII
1056 2 = EBCDIC
1057 3 = Binary
1058 block_count
1059 is the number of tape blocks contained in this file. If the file is
1060 still open, this number represents the number of blocks processed
1061 thus far.
1062
1063
1064 read_errors
1065 is a count of the number of read errors recoverable as well as
1066 unrecoverable encountered while reading this file. Note that read
1067 errors recovered by the hardware auto retry are not counted. Only
1068 Multics reread operations with varying threshold and deskew
1069 settings are counted.
1070 write_errors
1071 is a count of the number of write errors recoverable as well as
1072 unrecoverable encountered while writing this file.
1073
1074
1075 Notes on the info_ptr:
1076 The mtape_fsst declaration can be found in the include file
1077 "mtape_file_status.incl.pl1". If the iox_$control info_ptr argument
1078 is null, then mtape_ will allocate the structure returned to the
1079 caller; the caller must free that structure.
1080
1081 Note that mtape_fsst.fs_stat has an adjustable array dimension. If
1082 the info_ptr points to storage allocated by the caller, the caller
1083 must set the variable mtape_fsst_nfiles to the maximum number of files
1084 in the file set for which data is to be returned before allocating the
1085 structure. This variable is declared in the include file.
1086
1087
1088 Syntax as a command:
1089 io_call control SWITCHNAME fsst
1090
1091
1092 Arguments for io_call:
1093 SWITCHNAME
1094 is the name of an I/O switch attached to the mtape_ I/O module.
1095 file_set_status, fsst
1096 is the name of the control order to be performed.
1097
1098
1099 Notes on the io_call command:
1100 When the io_call command performs an mtape_ control order, any data
1101 normally returned by that control order is interpreted by mtape_ and
1102 displayed on the user's terminal.
1103
1104
1105 :Info: mtape_.hardware_status: mtape_.hwst: 1985-02-18 mtape_ hardware_status control
1106
1107 Control order: hardware_status, hwst
1108
1109 The iox_$control info_ptr argument points to a structure that reports
1110 the hardware status stored by last tape I/O operation.
1111
1112
1113 Syntax:
1114 call iox_$control iocb_ptr "hardware_status" info_ptr code;
1115
1116
1117 Arguments for iox_$control:
1118 info_ptr
1119 points to the following structure, or is a null pointer. See
1120 "Notes on the info_ptr" below.
1121
1122 dcl 1 mtape_hardware_status aligned based info_ptr,
1123 2 version char8,
1124 2 description char 256 varying,
1125 2 pad bit 36,
1126 2 iom_status bit 72,
1127 2 iom_lpw bit 72;
1128
1129
1130 List of elements:
1131 version
1132 is the current structure version. If info_ptr is nonnull on input,
1133 then the caller must set the version element to hwst_version_1. If
1134 null, mtape_will set the version number in the structure it
1135 allocates.
1136 description
1137 is the English language description of this hardware status.
1138 iom_status
1139 is the raw I/O status words returned from the last I/O operation.
1140 A definition for the format of these status words can be found in
1141 the include file iom_status.incl.pll.
1142
1143
1144 iom_lpw
1145 is the I/O List Pointer Word as it appeared at the termination of
1146 the last I/O operation. A definition of the format of the LPW can
1147 be found in the include file iom_lpw.incl.pll.
1148
1149
1150 Notes on the info_ptr:
1151 The mtape_hardware_status structure declaration shown above can be
1152 found in the include file "mtape_hardware_status.incl.pl1". If the
1153 iox_$control info_ptr is null, then mtape_ will allocate the structure
1154 for the caller; the caller must free that structure.
1155
1156
1157 Syntax as a command:
1158 io_call control SWITCHNAME hwst
1159
1160
1161 Arguments for io_call:
1162 SWITCHNAME
1163 is the name of an I/O switch attached to the mtape_ I/O module.
1164 hardware_status, hwst
1165 is the name of the control order to be performed.
1166
1167
1168 Notes on the io_call command:
1169 When the io_call command performs an mtape_ control order, any data
1170 normally returned by that control order is interpreted by mtape_ and
1171 displayed on the user's terminal.
1172
1173
1174 :Info: mtape_.volume_status: mtape_.vst: 1985-02-18 mtape_ volume_status control
1175
1176 Control order: volume_status, vst
1177
1178 The iox_$control info_ptr argument points to a structure that reports
1179 the status of the current volume. The returned status contains volume
1180 attribute as well as volume error summary information.
1181
1182
1183 Syntax:
1184 call iox_$control iocb_ptr "volume_status" info_ptr code;
1185
1186
1187 Arguments for iox_$control:
1188 info_ptr
1189 points to the following structure, or is a null pointer. See
1190 "Notes on the info_ptr" below.
1191
1192 dcl 1 mtape_vst aligned based info_ptr,
1193 2 version char 8,
1194 2 volume_type fixed bin,
1195 2 volume_name char 32,
1196 2 volume_id char 32,
1197 2 mounted bit 1,
1198 2 device_name char 8,
1199 2 volume_index fixed bin,
1200 2 mounts fixed bin,
1201 2 tot_error_stats,
1202 3 read,
1203 4 errors fixed bin 35,
1204 4 operations fixed bin 35,
1205 3 write,
1206 4 errors fixed bin 35,
1207 4 operations fixed bin 35,
1208 3 orders,
1209 4 errors fixed bin 35,
1210 4 operations fixed bin 35,
1211 3 successful retry 7 fixed bin 35,
1212 2 rel error_stats,
1213 3 read,
1214 4 errors fixed bin 35,
1215 4 operations fixed bin 35,
1216 3 write,
1217 4 errors fixed bin 35,
1218 4 operations fixed bin 35,
1219 3 orders,
1220 4 errors fixed bin 35,
1221 4 operations fixed bin 35,
1222 3 successful_retry 7 fixed bin 35;
1223
1224
1225 List of elements:
1226 version
1227 is the current structure version. If info_ptr is nonnull on input,
1228 the caller must set the version element to vst_version_1. If null,
1229 then mtape_ will set the version element in the structure it
1230 allocates.
1231 volume_type
1232 is the encoded volume type as determined by RCP, and could have one
1233 of the following values.
1234 4 = IBM labeled volume
1235 5 = ANSI labeled volume
1236 6 = Unlabeled volume
1237
1238
1239 volume_name
1240 is the name of the current volume as specified in the volume
1241 sequence list i.e. attach description.
1242 volume_id
1243 is the name of the current volume as recorded in the volume label.
1244 For unlabeled volumes, this field will be blank.
1245 mounted
1246 is a flag indicating the mounted state of the current volume. A
1247 "1"b indicates that the volume. is mounted, "O"b indicates that the
1248 volume is not currently mounted.
1249 device_name
1250 is the name of the tape device that the current volume is mounted
1251 on e.g. "tape_O1". If the volume is currently unmounted, this
1252 field will be blank.
1253
1254
1255 volume_index
1256 is the numerical order of this volume within the volume set.
1257 mounts
1258 is a count the number of times the current volume has been mounted
1259 during this attachment.
1260 tot_error_stats
1261 is a block representing the error statistics for the current volume
1262 inclusive of all of the mounts during the current attachment. The
1263 block includes the number of errors perportioned with the number of
1264 operations for read, write and order i.e. non-data transfer
1265 operations like forward space file, as well as a metering array
1266 of the number of times that read operations were successfully
1267 retried for each of the combinations of deskew window and threshold
1268 changes.
1269
1270
1271 rel_error_stats
1272 is the same as tot_error_stats above except it is the error
1273 statistics for the current mount only.
1274
1275
1276 Notes on the info_ptr:
1277 The mtape_vst structure declaration shown above can be found in the
1278 include file "mtape_volume_status.incl.pl1". If the iox_$control
1279 info_ptr argument is null, then mtape_ will allocate the structure
1280 returned to the caller; the caller must free that structure.
1281
1282
1283 Syntax as a command:
1284 io_call control SWITCHNAME vst
1285
1286
1287 Arguments for io_call:
1288 SWITCHNAME
1289 is the name of an I/O switch attached to the mtape_ I/O module.
1290 volume_status, vst
1291 is the name of the control order to be performed.
1292
1293
1294 Notes on the io_call command:
1295 When the io_call command performs an mtape_ control order, any data
1296 normally returned by that control order is interpreted by mtape_ and
1297 displayed on the user's terminal.
1298
1299
1300 :Info: mtape_.volume_set_status: mtape_.vsst: 1985-02-18 mtape_ volume_set_status control
1301
1302 Control order: volume_set_status, vsst
1303
1304 The iox_$control info_ptr argument points to a structure holding an
1305 array of volume status for all volumes in the current volume set.
1306
1307
1308 Syntax:
1309 call iox_$control iocb_ptr "volume_set_status" info_ptr code;
1310
1311
1312 Arguments for iox_$control:
1313 info_ptr
1314 points to the following structure, or is a null pointer. See
1315 "Notes on the info_ptr_ below.
1316
1317 dcl 1 mtape_vsst aligned based info_ptr,
1318 2 version char 8,
1319 2 volume_type fixed bin,
1320 2 nvolumes fixed bin,
1321 2 vs_stat mtape_vsst_nvolumes refer mtape vsst.nvolumes,
1322 3 volume name char 32,
1323 3 volume_id char 32,
1324 3 mounted bit 1,
1325 3 device_name char 8,
1326 3 volume_index fixed bin,
1327 3 mounts fixed bin,
1328 3 tot error stats,
1329 4 read,
1330 5 errors fixed bin 35,
1331 5 operations fixed bin 35,
1332 4 write,
1333 5 errors fixed bin 35,
1334 5 operations fixed bin 35,
1335 4 orders,
1336 5 errors fixed bin 35,
1337 5 operations fixed bin 35,
1338 4 successful_retry 7 fixed bin
1339 3 rel error stats,
1340 4 read,
1341 5 errors fixed bin 35,
1342 5 operations fixed bin 35,
1343 4 write,
1344 5 errors fixed bin 35,
1345 5 operations fixed bin 35,
1346 4 orders,
1347 5 errors fixed bin 35,
1348 5 operations fixed bin 35,
1349 4 successful_retry 7 fixed bin 35;
1350
1351
1352 List of elements:
1353 version
1354 is the current structure version. If info_ptr is nonnull on input,
1355 the caller must set the version element to vsst_version_1. If
1356 null, then mtape_ will set the version element in the structure it
1357 allocates.
1358 volume_type
1359 is the encoded volume type as determined by RCP, and could have one
1360 of the following values.
1361 4 = IBM labeled volume
1362 5 = ANSI labeled volume
1363 6 = Unlabeled volume
1364
1365
1366 nvolumes
1367 is the number of volumes in the volume set.
1368 vs_stat
1369 is an array of structures of volume set members, which appears
1370 below in sequential order. See "Notes on the mtape_vsst structure"
1371 below.
1372
1373
1374 volume_name
1375 is the name of the current volume as specified in the volume
1376 sequence list i.e. attach description.
1377 volume_id
1378 is the name of the current volume as recorded in the volume label.
1379 For unlabeled volumes, this field will be blank.
1380 mounted
1381 is a flag indicating the mounted state of the current volume. A
1382 "1"b indicates that the volume. is mounted, "O"b indicates that the
1383 volume is not currently mounted.
1384 device_name
1385 is the name of the tape device that the current volume is mounted
1386 on e.g. "tape_O1". If the volume is currently unmounted, this
1387 field will be blank.
1388
1389
1390 volume_index
1391 is the numerical order of this volume within the volume set.
1392 mounts
1393 is a count the number of times the current volume has been mounted
1394 during this attachment.
1395
1396
1397 tot_error_stats
1398 is a block representing the error statistics for the current volume
1399 inclusive of all of the mounts during the current attachment. The
1400 block includes the number of errors perportioned with the number of
1401 operations for read, write and order i.e. non-data transfer
1402 operations like forward space file, as well as a metering array
1403 of the number of times that read operations were successfully
1404 retried for each of the combinations of deskew window and threshold
1405 changes.
1406 rel_error_stats
1407 is the same as tot_error_stats above except it is the error
1408 statistics for the current mount only.
1409
1410
1411 Notes on the info_ptr:
1412 The mtape_vsst declaration can be found in the include file
1413 "mtape_volume_status.incl.pl1". If the iox_$control info_ptr argument
1414 is null, then mtape_ will allocate the structure returned to the
1415 caller; the caller must free that structure.
1416
1417 Note that mtape_vsst.vs_stat has an adjustable array dimension. If
1418 the info_ptr points to storage allocated by the caller, the caller
1419 must set the variable mtape_vsst_nvolumes to the maximum number of
1420 volumes in the volume set for which data is to be returned before
1421 allocating the structure. This variable is declared in the include
1422 file.
1423
1424
1425 Syntax as a command:
1426 io_call control SWITCHNAME vsst
1427
1428
1429 Arguments for io_call:
1430 SWITCHNAME
1431 is the name of an I/O switch attached to the mtape_ I/O module.
1432 volume_set_status, vsst
1433 is the name of the control order to be performed.
1434
1435
1436 Notes on the io_call command:
1437 When the io_call command performs an mtape_ control order, any data
1438 normally returned by that control order is interpreted by mtape_ and
1439 displayed on the user's terminal.
1440
1441
1442 :Info: mtape_.io_call: 1985-02-18 mtape_ io_call control
1443
1444 Control order: io_call
1445
1446 Executes one of the other control operations initiated by the io_call
1447 command. For any control operation that would normally return a
1448 structure to the user, this control will display an interpretation
1449 of the data on the user terminal. The format of the structure input
1450 to the io_call order can be found in the include file
1451 "io_call_info.incl.pl1".
1452
1453
1454 Syntax:
1455 call iox_$control iocb_ptr "io_call" info_ptr code;
1456
1457
1458 Arguments for iox_$control:
1459 info_ptr
1460 points to the following structure that describes input data for the
1461 control operation to be performed. The structure may be found in
1462 "io_call_info.incl.pl1".
1463
1464 dcl 1 io_call_info aligned based info_ptr,
1465 2 version fixed bin,
1466 2 caller_name char 32,
1467 2 order_name char 32,
1468 2 report entry variable options variable,
1469 2 error entry variable options variable,
1470 2 af_returnp ptr,
1471 2 af_returnl fixed bin,
1472 2 fill 5 bit 36 aligned,
1473 2 nargs fixed bin,
1474 2 max_arglen fixed bin,
1475 2 args 0 refer io_call_info.nargs
1476 char 0 refer io_call_info.max_arglen varying;
1477
1478
1479 List of elements:
1480 version
1481 is 1.
1482 caller_name
1483 is program name that should be reported in any error messages.
1484 order_name
1485 is the control order to be performed by mtape_. For a list of
1486 supported control order names, type: help mtape_ -brief
1487 report
1488 an entrypoint with a calling sequence like ioa_ on which mtape_
1489 reports contents of structures that would have been returned by the
1490 target control order.
1491 error
1492 an entry with a calling sequence like com_err_ on which mtape_
1493 displays error messages.
1494
1495
1496 af_returnp
1497 points to the active function return string when io_call is invoked
1498 in an active string e.g. io_call control ... The mtape_ I/O
1499 module does not support active function control orders.
1500 af_returnl
1501 is the maximum length of this active function return valuel.
1502 nargs
1503 is the number of character varying strings passed as arguments to
1504 the io_call order. None of the mtape_ control orders accept such
1505 arguments so this should always be 0.
1506 max_arglen
1507 is the maximum length of any of the arguments. Since mtape_ does
1508 not use such arguments this may be set to 4.
1509
1510
1511 args
1512 is the array of arguments to be passed by the io_call control
1513 command to the mtape_ target control order. mtape_ does not
1514 require such arguments and ignores any arguments that are passed.
1515
1516
1517 Syntax as a command:
1518 io_call control SWITCHNAME ORDERNAME
1519
1520
1521 Arguments for io_call:
1522 SWITCHNAME
1523 is the name of an I/O switch attached to the mtape_ I/O module.
1524 ORDERNAME
1525 is the name of the mtape_ control order to be performed using the
1526 io_call command.
1527
1528
1529 Notes on the io_call command:
1530 When the io_call command performs an mtape_ control order mtape_
1531 interprets the data normally returned by that control order and
1532 displays that on the user's terminal.
1533
1534
1535 :Info: mtape_get_defaults: 1985-02-18 mtape_get_defaults
1536
1537 Syntax as a command: mtape_get_defaults OPN -control_args
1538
1539
1540 Function: prints default arguments set by the mtape_set_defaults
1541 command. It prints the default arguments stored in a specified value
1542 segment that are associated with a given volume type and tape
1543 processing operation.
1544
1545
1546 Arguments:
1547 OPN
1548 is the type of tape operation attach open close or detach that
1549 uses the default arguments.
1550
1551
1552 Control arguments:
1553 -pathname path -pn path
1554 specifies the pathname of a value segment to be searched for default
1555 arguments. It is incompatible with -use_search_list.
1556 -use_search_list -usl
1557 specifies that each value segment in the mtape_arguments search list
1558 is to be searched for default arguments and that the final default
1559 linear form that the mtape_ argument processing subroutine uses is
1560 to be printed. Default
1561 -volume_type VT -vt VT
1562 specifies the volume type ansi or ibm used by mtape_ to select the
1563 per-format module for tape processing. Give -volume_type when you
1564 specify either the open or close operations; omit it when you supply
1565 either the attach or detach operations.
1566
1567
1568 :Info: mtape_set_defaults: 1985-02-18 mtape_set_defaults
1569
1570 Syntax as a command: mtape_set_defaults OPN -control_args
1571
1572
1573 Function: sets default arguments used by the mtape_ I/O module.
1574 For information about the current defaults type:
1575 help mtape_get_defaults
1576
1577
1578 Arguments:
1579 OPN
1580 is the type of tape operation attach open close or detach that
1581 uses the default arguments.
1582
1583
1584 Control arguments:
1585 -arguments ARGS -argument -ag ARGS
1586 are the arguments appropriate to the specified operation and tape
1587 format. They must be syntactically correct and appropriate to the
1588 conditions under which they are applied. You must supply
1589 -arguments which must be the last one specified on the command
1590 line.
1591 -pathname path -pn path
1592 is the name of the value segment in which the requested default
1593 values are stored. If you omit it the value segment >udd>user
1594 project>user name>user name.value is used.
1595
1596
1597 -volume_type VT -vt VT
1598 specifies the volume type ansi or ibm used by mtape_ to select the
1599 per-format module for tape processing. Give -volume_type when you
1600 specify either the open or close operations; omit it when you supply
1601 either the attach or detach operations. This control argument
1602 along with -operation defines restrictions on the specification of
1603 the default arguments see the mtape_ I/O module in the Subroutines
1604 manual.
1605
1606
1607 Notes: The command sets the default arguments associated with a given
1608 volume type and tape processing operation. These default arguments are
1609 eventually used to complete attach open close and detach
1610 descriptions when you have not explicitly supplied all the necessary
1611 information.
1612
1613 The default arguments specified in the command line are processed by
1614 the mtape_ argument processing subroutine to assure that they follow
1615 all the restrictions imposed by their intended future usage. The
1616 result of this processing is then converted to a character string and
1617 is stored in the data space of a specified value segment. The stored
1618 value is later located and used as default information for argument
1619 processing when tapes are being processed by the mtape_ I/O module see
1620 the Programmer's Reference Manual for tape processing.
1621
1622
1623 Notes on using default arguments: When it is necessary to use default
1624 arguments in a particular application they are located by the mtape_
1625 argument processing routine using the mtape_arguments search list. The
1626 default mtape_arguments mtape_args search list is as follows:
1627 mtape_arguments
1628 mtape_args
1629 >udd>user project>user name>user name.value
1630 >site>mtape_arguments.value
1631 >sss>mtape_arguments.value
1632
1633 You can add or delete search paths as necessary using the search paths
1634 commands.
1635
1636
1637 In locating default arguments the mtape_ argument processing routine
1638 looks in every value segment in the search list and takes the
1639 appropriate default arguments from each if it finds them. Whether a
1640 group of default arguments is determined to be appropriate for an
1641 application depends on the volume type and tape processing operation
1642 for which is intended.
1643
1644 Default arguments from value segments at the top of the search list
1645 take precedence over those from value segments at the bottom.
1646 Equivalently arguments on the right side of an argument list take
1647 precedence over arguments on the left. This means that after all
1648 default arguments for a particular application have been gathered from
1649 the search list if an argument occurs more than once the argument
1650 with the highest precedence is retained and the others are excluded.
1651 The result is called the default linear form.
1652
1653
1654 :Info: mtape_user_label_rtn_: 2020-06-27 mtape_user_label_rtn_
1655
1656 Function:
1657 In order to process user defined file labels when the "-label_entry"
1658 open description argument is used the entry variable argument to the
1659 "-label_entry" control argument must conform to the following calling
1660 sequence in order to be called properly by mtape_ and its Per-Format
1661 modules.
1662
1663
1664 Syntax:
1665 dcl mtape_user_label_rtn_ entry ptr char * fixed bin
1666 fixed bin fixed bin fixed bin 35;
1667
1668 call mtape_user_label_rtn_ iocb_ptr user_label_data label_number
1669 label_type file_section_number code;
1670
1671
1672 Arguments:
1673 iocb_ptr
1674 is a pointer to the I/O control block through which the
1675 mtape_ I/O module is attached. A user_label_entry routine
1676 may wish to know more information about the file for which
1677 it is processing user labels. This can be accomplished by
1678 calling the iox_$control entry with this iocb_ptr and
1679 executing the mtape_ "file_status" control operation.
1680 user_label_data
1681 is the actual contents of the user label record to be
1682 processed INPUT or written OUTPUT. For ANSI and IBM
1683 user label records the length of this field will be 76
1684 characters on input and truncated to same on output.
1685
1686
1687 label_number
1688 is the number of the user label record within the file label
1689 group. The ANSI and IBM standards allow from 1 to 9 user
1690 label records within a file label group UHL1 - UHL9 and
1691 UTL1 - UTL9.
1692 label_type
1693 is the encoded file label group type that the
1694 user_label_entry is being called to process label records
1695 for. Its possible values are as follows:
1696 1 = Beginning of file BOF label group
1697 2 = End of volume EOV label group
1698 3 = End of file EOF label group
1699
1700
1701 file_section_number
1702 is the section number of the file for which the
1703 user_label_entry routine is being called to process user
1704 labels for. For multi-volume files this would essentially
1705 be the number of the volume the first volume on which a
1706 file resides being number 1 on which this file "section"
1707 resides. For single volume files the file_section_number
1708 would always be a 1.
1709
1710
1711 code
1712 is a standard system error code. When writing user labels
1713 the user_label_entry routine should set code to
1714 error_table_$end_of_info in order to tell the caller that no
1715 more user labels are to be written. Otherwise the
1716 user_label_entry is called repeatedly to generate user label
1717 data until the maximum number of user labels have been
1718 written.
1719
1720
1721 Notes on processing user labels:
1722
1723 The user label routine is called by the open open_file close
1724 close_file operations and when the end of a tape volume is
1725 encountered. The routine must be written to monitor the input
1726 argument values user_label_data label_number label_type and
1727 code in order to process each type of label correctly.
1728
1729
1730 For output the user label routine is called repeatedly upon open
1731 close and volume end to support writing of up to nine user
1732 labels. The call loop is terminated after the ninth call or when
1733 the error_table_$end_of_info error code is returned. For input
1734 the routine is called once for each user label found on the tape.
1735
1736
1737 To determine whether the label processing routine is being called
1738 to process labels read from a tape or to build new labels for
1739 writing the value of the user_label_data parameter should be
1740 checked. If the value is set to spaces then the label should be
1741 constructed by the routine and stored in user_label_data.
1742 Otherwise the information contained in user_label_data should be
1743 processed as input.
1744
1745
1746 The label_type parameter value is set by the caller. The label
1747 processing routine should check this value to determine the type
1748 of user label to process.
1749
1750
1751 The label_number parameter value is set by the caller. The label
1752 processing routine should check this value to determine which
1753 label within type should be processed.
1754
1755
1756 It is up to the writer of the routine to set the code parameter
1757 to error_table_$end_of_info and return it. Setting this value
1758 will stop the call loop for the current label building operation.
1759
1760
1761 :hcom:
1762
1763
1764
1765 /****^ HISTORY COMMENTS:
1766 1 change2020-06-22GDixon, approve2021-02-22MCR10088,
1767 audit2021-05-27Swenson, install2021-05-27MR12.6g-0056:
1768 A) Convert existing mtape_.info I/O module description to Operation
1769 Format now supported by verify_info.
1770 B) Provide detailed information for all mtape_ control orders.
1771 END HISTORY COMMENTS */
1772
1773
1774