Macro type: type S (E form/L form); see "Macro types"
All user requests for BTAM are handled using this macro. In the operand descriptions, the abbreviation “MTC” is used for “magnetic tape cartridge”.
Format
Operation | Operands |
|
[,PARMOD = 24 / 31 ] MF = L |
|
Operand descriptions
fcbaddr
Address of the FCB associated with the file to be processed.
RDWT
Reads the tape forwards and waits until the operation is completed before returning control to the user program (default function).
CHK
Checks whether the previous I/O operation has been completed. If not, control is transferred to the address specified in LOC. Otherwise, the operation is equivalent to WT.
MINF
Fetches information about the medium during the processing of optical disks. In BS2000, optical disks are operated via an MTC emulation. The area to which the information is to be written and its length (currently 128 bytes) must be specified via the LOC and LEN operands. The layout of the output information is described with the NDWMINF macro.
POS
Permissible only with PARMOD=31; positions the tape (see "Operation codes").
RBID
Permissible only with PARMOD=31; determines the tape position (see "Operation codes" ).
RD
Reads the tape in a forward direction.
RDBF
For tape cartridges, permissible only with PARMOD=31; transfers data block-by-block from the save area of the MTC buffer to the user area (see "Operation codes").
REV
Reads the tape backwards (towards BOT).
REVWT
Reads the tape backwards and waits until the operation has been completed before returning control to the user program.
RNT
Reads without data transfer; a message is issued if the length is shorter than expected.
RNTL
Reads without data transfer; no message is issued if the length is shorter than expected.
RT
Reads with data transfer; a message is issued if the length is shorter than expected.
RTL
Reads with data transfer; no message is issued if the length is shorter than expected.
SYNC
Permissible only with PARMOD=31; determines the tape position and synchronizes (see "Operation codes").
WRT
Writes to a magnetic tape.
WRTWT
Writes to a magnetic tape, waiting until the operation has been completed before returning control to the user program.
WT
Waits until the previous I/O operation has been completed. Control is not returned to the user program until the operation has been completed or the necessary error recovery functions have been performed.
ERG
Generates an interblock gap; if repeated, the tape is erased.
The operation triggered by ERG is physically a write operation. However, instead of a bit pattern, an “interblock gap” pattern is generated. The length of this pattern is defined by the user (although for some magnetic tape types, the length is preset).
BSF
Rewinds (backspaces) the tape by one tape mark.
BSR
Rewinds (backspaces) the tape by one block.
FSF
Forward-spaces the tape by one tape mark.
FSR
Forward-spaces the tape by one block.
REW
Rewinds the tape to the BOT marker.
RUN
Rewinds and unloads the tape; subsequently, only CLOSE is possible.
WTM
Writes a tape mark.
LEN = length
Specifies the length of the individual blocks or, for chained I/O (CHAINIO operand in FILE/FCB), the length of the transport unit.
If LEN is not specified, the length of a transport unit is the product of the block size and the chaining factor, where the block size is defined by BLKSIZE if RECFORM=F is specified, and by the contents of the register specified for RECSIZE if RECFORM=U applies.
Without chaining, the system takes the specifications only from the RECSIZE operand when writing with RECFORM=U; otherwise, they are taken from the BLKSIZE operand. If RECFORM=U is specified, a length specification entered via the LEN operand may be such that the last block within a transport unit is shorter than the previous blocks. If RECFORM=F is specified, the given length should be a multiple of the BLKSIZE specified (but the job will not be rejected if this is not the case).
The length to be read is always taken from the current length specification and only from this. After a successful READ, the actual block size is returned in the RECSIZE register.If specified in conjunction with operation code RDBF, LEN specifies the length of the blocks to be saved from the buffer. If RECFORM=U/V applies, the current block length is stored in the RECSIZE register.
LOC
Specifies the area from which data is to be read or to which data is to be written.
Default value:
IOAREA1
for the first input or output
when switching from LOC=relexp to an IOAREA
if IOAREA2 was used last
if IOAREA2 is not defined
IOAREA2, if IOAREA1 was used last
= relexp
Address of an area in the macro.The LOC operand must be specified in the form LOC=relexp if a CHK operation is required. It specifies the address to which control is to be passed if the operation being checked has not yet been completed. The addressed area must not coincide with IOAREA1/2.
= 1
Points to the address IOAREA1 in the FCB.
= 2
Points to the address IOAREA2 in the FCB. The used I/O area is indicated in the TU FCB:in field ID1BLWB of the 31-bit TU FCB, or
in field ID1LWB of the 24-bit TU FCB.
POS:address of the specified tape position (9 bytes)
RBID:address at which the specified tape position (9 bytes) is output
RDBF:address of the area into which the saved block is to be placed
SYNC:address at which the specified tape position (9 byes) is output
MF
The formats of the MF operand are described in detail in the appendix, "Macro types".
PARMOD
Specifies the generation mode for the macro.
Default value: | the value preset for the generation mode by means of the GPARMOD macro or by the assembler. |
= 24
The macro is expanded in accordance with the format for the 24-bit interface. The object code is thus executable only in 24-bit addressing mode.
= 31
The macro is generated as addressing mode-independent.
REQNO = number
Number <= 8; the number of the input/output request or of the associated macro. Several asynchronous read or write operations, identified by different numbers, can be started. Each of these read/write operations must be terminated by the WT operand (together with the relevant number). The maximum number of concurrent I/O operations is specified in the BTAMRQS operand of the FCB.
Operation codes
POS – Position the tape
This is useful for restarting, e.g. after a write error with loss of data: the user can specify the block number (2 bytes) which he/she obtained from an earlier RBID operation at the address defined by LOC and the tape is then positioned to the corresponding block.
RBID – Determine current tape position (block number)
Each block on a tape, including the tape marks, can be identified by means of its position on the tape.
In the case of conventional magnetic tapes, the tape position is returned to the user as a pair of values (TM and record counters). This information is returned to the user after an RBID instruction (or SYNC instruction, see "BTAM - Process tape files (type S)") at the address defined by means of the LOC operand (see the operand description) or, if LOC is not specified, in one of the I/O areas defined in the FCB. The position information (first 8 bytes) depends on the processing status and returns the information listed in the table on "BTAM - Process tape files (type S)" in field ID1ECB of the FCB in the case of an error.
The 9th byte specifies how the position information is to be interpreted.
2**7 = 1: | TM and record counters |
2**6 = 1: | block ID |
2**0 = 1: | no valid position specified |
Before an RBID instruction is issued, all outstanding asynchronous read/write operations (in MAV mode) must be terminated with a WAIT. In the case of synchronous file processing, BTAM executes the WAIT automatically.
For magnetic tape cartridges, the tape position is defined as a “block number” (or block ID).
Information returned
Event | Information | Meaning | Action |
Successful execution | Block number | Indicates the position of the next block to be written to or read out of the MTC buffer | ---- |
Unsuccessful execution | Block number | The tape position has been saved; | Reposition using POS |
Block number undefined | The tape position could not be saved | Reposition to checkpoint or program is aborted | |
Block number undefined | The tape position could not be saved | Program is aborted | |
Block number | I/O error; the block number is the one that existed after error handling | ---- | |
Block number undefined | I/O error with “loss of position” | Reposition to checkpoint or program is aborted |
RDBF – for MTC only – after an unrecoverable write error, read data from the save area of the MTC buffer into a user area.
When writing is buffered, it is possible for errors to occur for data blocks for which the user has already received a positive acknowledgment. DMS attempts to save the data already passed to the MTC buffer and the tape position so that the user can carry out normal error handling. (S)he can retrieve the block causing the error and subsequent blocks (which have been acknowledged but not yet written to tape) from the save area of the buffer and process them again, for example by sending them to a different volume.
Before the file is closed (CLOSE) or a tape swap is initiated by FEOV, the user must use the POS function to position the tape after the last block which was written successfully. The blocks are read on the principle “last in, first out” and the number of blocks stored in the buffer is kept in field ID1BLANZ in the TU FCB. A separate RDBF instruction must be issued for each block, in which case the input area is specified as for normal read operations: the address is given by the LOC operand in the BTAM macro or by IOAREA in the FCB and the length in the LEN operand or in the FCB, in the same way as for reading from tape. The blocks are transferred with the specified length. If RECFORM=V/U is specified for the file, the actual length of the saved block is indicated in the register specified by means of RECSIZE in the FILE or FCB macro.
SYNC – Synchronize and set marker points
The data contained in the MTC buffer is written to tape. For synchronous processing (not MAV mode), BTAM initiates any outstanding WAIT. For asynchronous processing (MAV mode), the user must ensure that any outstanding WAITs are executed before the SYNC instruction is issued. The SYNC call implicitly includes an RBID call, i.e. the current tape position is returned to the user in the I/O area. The user can utilize this fact to set checkpoints, e.g. for handling subsequent errors: he/she can then restart at one of these points and continue processing.
Programming notes
The BTAM macro destroys the contents of registers 0, 1, 14 and 15.
Misuse of FSF or FSR can cause the tape to run to end-of-volume, in which case it must be rewound by the operator (offline).
Whenever a branch to BTAM is unsuccessful, control is passed to the address specified in the EXIT operand of the FCB. An appropriate hexadecimal error code is stored in the FCB.
If the user specifies fixed-length blocks (format F) but reads blocks of a different length, control is passed to the ERRADDR exit in the EXLST macro.
If the record length exceeds the specified length, an “abnormal termination” bit is set in the Executive flag byte, and the “record-length error” bit is set in the sense byte, provided no RTL or RNTL operation with the simultaneous use of chaining and/or MAV mode is involved (in which case the user is not informed). If the block is shorter than the specified length, however, the “abnormal termination” bit is set, but no error byte is returned (the residual count is stored in sense bytes 2 and 3; see the NDWERINF macro, "NDWERINF - Evaluate status bytes"). No notification is provided to the user if an RTL or RNTL operation is involved.If the user specifies variable-length blocks (format U or V) or uses the operation codes RTL or RNTL, but reads blocks of a greater length than specified, control is passed to the ERRADDR exit in the EXLST macro, provided chaining and MAV mode are not used. The ERRADR exit is always activated for RT and RNT operations. In all other cases, no information is returned to the user for the U/V format.
The various cases and situations in which the user is notified are summarized in the table below:
Operation RECFORM=F
Block < spec. lengthRECFORM=F
Block > spec. lengthRECFORM=U/V
Block < spec. lengthRECFORM=U/V
Block > spec. lengthRD(WT) yes yes no conditional *) R(N)T yes yes yes yes R(W)TL no conditional *) no conditional *) *) yes if chaining and MAV mode are not used
The user need not specify wait operations explicitly, provided that he/she is not working in MAV mode. BTAM automatically outputs a WAIT before each new operation. However, if an error occurs during this WAIT operation, error code X'0C77' is output. The new operation is not executed.
Note that this implicit WAIT is only meaningful when working with multiple I/O areas. Since the data in the output area must essentially be retained when writing until the completion of a WAIT, and since the input area is correctly filled when reading only after completion of a WAIT, users who work with only one I/O area must ensure that a WAIT is issued as soon as they wish to reuse this single area.
BTAM does not use the EOFADDR exit of the EXLST macro (end of file). If a tape mark is read by a RD, RDWT, RNT, RNTL, RT, RTL, REV or REVWT, control is transferred to the ERRADDR address.The program can evaluate the 5 status bytes in the FCB (SDB, FB1, FB2, FB3, AMB) after the WAIT. Control is also transferred to the ERRADDR address if an attempt is made to reverse-read a tape that is positioned at the beginning of the tape.In the case of the REV and REVWT operations, the address for the first byte into which data is read is defined by:
LOC + LEN - 1
The SAM macro FEOV can be used for a file opened by BTAM. If end-of-file (on the current tape) is encountered, BTAM branches to the otherwise unused exit EOFADDR.
CHAINIO with tape cartridges: the transport unit should not be larger than the buffer size, and the buffer size should be an integral multiple of BLKSIZE. In the case of an error, the indicated number of blocks in the buffer (TU FCB: ID1BLANZ) always refers to individual blocks, not to transport units. The RDBF operations also process only individual blocks.
MAV mode with tape cartridges: the value specified for BTAMREQS in the FCB can be smaller than for tapes, since the user I/O areas become free again more rapidly in the case of tape cartridges.
In the event of an error, it is possible that the entire contents of the MTC buffer cannot be written to the cartridge. The user can access the blocks transferred by the operating system from the MTC buffer to a save area, which is equivalent to reading a tape in the reverse direction. After this, the user should attempt to position the MTC after the last block which was written correctly.
The user must ensure that the tape is positioned correctly (by means of POS) before further write operations are started (particularly before writing the EOV/EOF labels). Otherwise, data on the tape may be overwritten. An RBID operation after error DC7C returns the tape position after the last block which was written correctly.
The tape can be closed correctly by writing the end labels if it is first read backwards for a few blocks or positioned backwards (if the user does not need the data already written).
If, due to a write error, some blocks were not written from the MTC buffer to tape, but are still saved in the save area of the buffer, the user must first execute an RDBF or RBID operation in order to tell the system that he/she does not want to discard this data; otherwise, it will not be available later. RDBF and RBID may be issued in any sequence; the contents of the buffer are retained as long as the user starts no other operations, with the exception of any outstanding WAITs. The user may issue these before issuing the RBID and/or RDBF instructions (and must issue them before the RBID); naturally, all of these WAITs will result in error code DC7C.
If the user does not position the tape after the DC7C error message, the tape position becomes “UNDEFINED” and this state can be cleared only by positioning the tape (or with REW and UNL).
Before checkpoints are written by means of the SYNC instruction, all previously initiated I/O operations must be terminated by means of WAIT.
If a calling sequence in which a “write” operation follows a “reverse read” is used when in MAV mode, all outstanding WAITS must be issued before the “write” operation.
A characteristic feature of tape cartridge devices is that errors which occur during output operations are reported only when the buffer contents are transferred to tape. The user may thus be informed that an error has occurred only when (s)he starts another request. Consequently, the user may receive the message “end of tape” before the message indicating that an error has occurred. The “end-of-tape” message means that the user should not start any more write operations, in order to ensure that all data still in the buffer and the end labels will fit on the current tape. In the case of tape cartridges, this “end-of-tape” message does not result from detection of an end-of-volume label on the tape; rather it is generated during the transfer of data into the buffer, contingent on the amount of data already in the buffer and other criteria.
When the FEOV or CLOSE macro is issued for a BTAM file which was opened in INOUT mode, the file is treated as an output file if a WRITE-and-WAIT operation was requested for it during processing (WRT, WRTWT, WTM). If no WRITE-and-WAIT operation was requested, the file is treated as an input file.
BTAM issues the error code X'0C95' if:
an invalid device type is specified
the operation code is invalid
one of the registers 0, 1, 13, 14 or 15 is specified in the FCB RECSIZE operand
the value of the LEN operand in the BTAM macro is less than or equal to 0 or, if LOC=relexp is not specified, greater than BLKSIZE (in which case IOAREA1/2 will be used, which is the same size as BLKSIZE)
a read operation is requested for a file opened in OUTPUT mode
the REQNO specification in MAV mode exceeds the maximum permissible value
a WAIT macro has not been issued before a read/write call for the same REQNO, when in MAV mode
a BTAM call is specified after RUN (only CLOSE is possible) or after an unsuccessful FEOV operation
BTAM calls are issued for a file which has not been opened for BTAM (except in EXLST routines for label handling)
When extending a tape file, a direct switch from “write” to “read” should be avoided. Discrepancies in deletion overlaps can lead to problems on certain magnetic tape devices.
The following sequence of operations always guarantees error-free execution:BTAM macro
Meaning
BSR, FSR, ...
Position tape before block n
RD
Read (save) block n
BSR
Reposition tape before block n
WRT
Write block n back to the tape
WRT/WRTM
Write block n+1 (or tape mark)
- An incorrect block length is not indicated in some cases, e.g. when reading data with chaining specified (see "BTAM - Process tape files (type S)").
The chain for the input of CCWs continues to run. However, the areas to which the individual blocks are transferred are incremented at the customary rate for blocks of normal size; in other words there will be gaps in the input/output areas in those cases where blocks of shorter length occur. - Information relating to the buffers used is provided in the TUFCB field ID1LWB when PARMOD=24, and in the field ID1BLWB when PARMOD=31, when a WAIT is executed in the following manner (asynchronous processing): for an input operation, a note is made of the buffer affected by the last WAIT operation without an error message. For output operations, the buffer indicated is the one which was used for the last output (which may not necessarily have terminated).
For synchronous processing, the following applies: for PARMOD=24, the value specified in the FCB field ID1LWB refers to the buffer which was last used, and for which a successful WAIT was issued; if PARMOD=31 applies, the FCB field ID1BLWB is used. - When the block and transport unit sizes are defined by the user, the following point should be borne in mind: Each I/O operation initiated by the device driver involves defining block and transport unit sizes for the pages affected. In the case of chained input/output, these definitions are effected for every CCW of the chain. For memory management reasons, however, this is only possible for up to 63 definitions per page; that is, if a job is issued in such a way that more than 63 CCWs referring to the same page may be created (e.g. when using small block sizes and large transport unit lengths), a CSTAT error may be the result.
- In the case of tapes with standard labels, BTAM checks whether a planned write operation is actually allowed by the current tape position. If not, the request is rejected with USERERR and error code 0C9D.
Return codes
Five FCB sense bytes (SDB, FB1, FB2, FB3 and AMB) are loaded in the TU FCB. In addition, the following information is issued in field ID1LRCRB:
Byte 1: | X'04' End-of-tape/beginning-of-tape encountered |
Byte 2: | Request number (required, since EXIT ERRADR can be issued only once |
Bytes 3/4: | Block number within a chained input/output job during which an error |
A DSECT (DLRC macro) is supplied to interrogate the values set in the first byte of the ID1LRCLB field.
With operations in asynchronous mode (REQNO operand), any further input/output jobs which have already been accepted are no longer started if an error occurs during input/output. Instead, these jobs are terminated logically after a WAIT command has been issued by the user. When this is the case, the block number in bytes 3 and 4 of field ID1LRCLB and the error information for the errored I/O operation both have a value of 1, and the value in the RECSIZE register (for RECFORM=U) is 0.
The user can issue a CLOSE macro at any time, even before all outstanding WAITS have been issued. All outstanding input/output requests which may not yet have been completed at this point in time are then terminated logically. However, this does not necessarily mean that all these requests have been honored.