The M$CVOL service causes the monitor to 'terminate the reading or writing of data in the magnetic tape reel currently associated with a specific DCB, and to advance to the next reel of the volume set.
For free and managed tapes, the current reel is terminated and the next reel positioned to its beginning.
For input files on labeled tape, the current file section is positioned to its end and determination made (by reading the following label group) of the
existence of a subsequent file section. If no such file section exists, M$CVOL will ALTRET with an end-of-file error and leave the current file positioned to its end. If a subsequent file section exists, the current volume is dismounted, and 'the next mounted and positioned to the first record of the next file section. Any UTLs following the EOV label group are returned if UTL is specified. Any UHLs following the HDR label group of the next file section are returned if UHL is specified. Both UTLs and UHLs are returned in VLP ULBL format.
For output files on labeled and managed tape, the current file section is truncated after the last whole record.
In addition, for output files on labeled tape, an EOV label is written
followed by any UTLs specified by UTL. The current volume is dismounted, and the next mounted and positioned ready to write the next record of the file (first of the next file section) after writing necessary VOL1, HDR and UHL labels as required or specified by UHL.
Note: On input, UTLs and UHLs are returned to their separate buffers
contiguously packed. The first word of the user label areas will contain the number of labels of that type returned. On output, UTLs and UHLs are written from the user's respective label buffers which are contiguously packed. The first word of the user label areas will contain the number of labels of that type to write. Any labels not containing the proper first three characters will cause termination of user label writing.
CVOL control should only be used with unspanned tape files, since spanned tape files may have records which cross volume boundaries. It is not possible to process these records if the user takes CVOL control.
CE55-01 MODULE 6-2 Page 141
Tape Commands, Options, and Calls
M$READ . READ RECORD
The MSREAD service causes a specified data record to be read into a user buffer in memory. The MSREAD service is used for all types of files and devices for which input is appropriate.
The user normally provides a buffer that is large enough to contain the maximum length record. In the normal case if a record exceeds buffer size, the record is truncated and this condition is reported as an error. If a record is smaller than buffer size the remainder of the buffer is unchanged from its previous contents. The MSREAD service also provides the option (CONT) to issue several calls to read successive portions of a single large record.
M$WRITE . WRITE RECORD
The MSWRITE service causes a data record stored in a buffer in memory to be written. The MSWRITE service is used for all types of files and devices for which output is appropriate.
The user normally provides a buffer to accommodate the maximum length record.
To write records of varying sizes, the user adjusts the FPT field BUF which contains a vector: BUF .BUFS points to the start of the buffer and BUF .BOUND specifies the record length minus 1. The user typically adjusts the BOUND field before writing each variable-length record to the record length minus 1.
MSWRITE provides options comparable to the options available on the MSREAD service.
M$PRECORD . POSITION TO RECORD
The MSPRECORD service permits the user to change position within a disk or tape file. Based on the parameters supplied, the monitor positions by key or positions forward or backward by a specified number of records.
Positioning by key applies to all file organizations except consecutive and unit record. To position by key the user specifies these parameters: DCB, KEY, KEYS=YES, and optionally KEYR=YES and N. If KEYR=YES the monitor returns the key of the record found, or if the requested key does not exist the next larger key. If N is also specified, the file is positioned by key and then forward or backward by the number of records specified by N.
The MSPRECORD service positions the file so that the next record read will be the record with the specified key, if a record with the specified key exists.
The alternate return is taken with an error reported (ESNOKEY), if a record with the specified key does not exist; the file remains positioned to read the record with the next higher key.
NOTE: For keyed and indexed labeled tape files opened with ACS=SEQUEN, the file is searched in the forward direction. The search is terminated if a key of equal value is found or if end-of-file is reached.
CESS-01 MODULE 6-2 Page 142
Tape Commands, Options, and Calls
The user may request reLative positioning by specifying KEYS=NO and N as the number of records to skip from the current position. The number of records to skip may be a positive number to move forward or a negative number to move backward. At the time the MSPRECORD is caLLed, current position is considered to be (1) the next record to be read if the previous operation was a read, (2) end-of-file if the previous operation was a write for a consecutive disk fiLe or tape file, (3) the next record if the previous operation was a write for other disk files, and (4) the record which would be read next if the previous operation was a call to MSPRECORD or MSPFIL. If the N parameter specifies a value which would cause positioning beyond the limits of the file, the
alternate return is taken; the file remains positioned before the first record or after the last record depending on the value of N.
NOTE: If the same FPT is used to position by key at times and relatively by number of records at othe~ times, N must be cleared before positioning by key.
After the relative positioning operation, the number of records actually skipped is returned in the ARS field of the DCB.
M$REW· REWIND
For labeled and managed tape files, MSREW positions to the beginning-of-file (just the same as MSPFIL with BOF=YES). For free tapes, MSREW rewinds to beginning-of-tape (BOT). If the user calls MSREW with a closed DCB, the DCB is opened automatically using the information currently in the DCB. If no DCB is specified, the serial number parameter specifies which tape volume to rewind. The volume must currently belong to the user and cannot be open.
M$PFIL· POSITION FILE
The MSPFIL service causes positioning of the medium to the beginning or the end of the current file. For labeled and managed tape files, the position is set before the first record or beyond the last record in the file. Free tapes are positioned beyond the next file mark in either the forward or reverse direction. If the user calls MSPFIL with a closed DCB, the DCB is opened automatically using the information currently in the DCB.
CE55-01 MODULE 6-2 Page 143
Tape Commands, Options, and Calls
M$WEOF - WRITE END-OF-FILE
The MSWEOF service is appropriate for only certain devices that require special end-of-file procedures. The MSWEOF service causes a file mark to be written on device (free or managed free) tape. (For managed tape, the current buffer is truncated before the file mark is written.) If the user calls
MSWEOF with a closed DCB, the DCB is opened automatically using the information currently in the DCB.
M$REM - REMOVE OR RELEASE VOLUME
The MSREM service permits a tape volume to be dismounted and optionally permits its respective resource to be released by its volume number. MSREM also rewinds the tape.
There is no DCB associated with an MSREM call. The specified tape volume must belong to the user and cannot currently be open.
M$TRUNC • TRUNCATE BUFFERS
The MSTRUNC service releases any blocking (POOL) buffers associated with a DCB after completion of any outstanding I/O operations. The MSTRUNC service applies to consecutive, keyed, indexed, relative, and unit record files on labeled tape; labeled tapes in V format; and labeled and managed tapes in D, S, and F formats. For any subsequent read or write operations for the DCB, the system assigns blocking buffers automatically as needed.
CE55-01 MODULE 6-2 Page 144
Tape Commands, Options, and Calls