The following UPAM functions are available for tape files:
Creation of tape files
UPAM creates tape files that do not extend over more than one tape. The user is responsible for programming access to logical records in these files.
Reading of SAM files with standard blocks
The file attributes are defined in the FCB (e.g. BLKSIZE, RECSIZE, REC-FORM) or by the BUFFER-LENGTH, RECORD-SIZE, RECORD-FORMAT operands in the ADD-FILE-LINK command by OPEN processing (see section "Sequence of OPEN processing"). This enables the user to program access to logical records.
Chained I/O
Not possible for tape files.
Eventing mechanism
The user job is notified when a UPAM I/O operation terminates and a contingency process starts.
Notes
The following points apply to the use of UPAM with tape files:
The file must reside on a single tape.
Every read/write operation processes exactly one physical block.
In the case of a file with the format BLKCTRL=PAMKEY or BLOCK-CONTROL-INFO=*PAMKEY (explicit or implicit), this must be a 2064-byte standard block: the first 16 bytes contain the PAM key and the remaining 2048 bytes contain the user data. Only STD or 2048 may be specified for the LEN operand of the PAM macro.
In the case of a file with the format BLKCTRL=DATA / NO (which is equivalent to BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK / *NO in the ADD-FILE-LINK command), BLKSIZE (or BUFFER-LENGTH) can be specified in bytes, in which case the value must be a multiple of 2048. The LEN value in the PAM macro must not be greater than the BLKSIZE value. Blocks of the length specified by LEN and containing either only user data (with BLKCTRL=NO) or a 12-byte block control field plus the (LEN – 12) bytes of user data (with BLKCTRL=DATA) are written to the tape. These blocks can be read by means of the UPAM function RD, in which case the value for LENRD in the read call must lie within the range:
LENWR <= LENRD <= BLKSIZE (LENWR: value for LEN when writing to the file)
In this context, the following special feature applies to files with FCBTYPE=ISAM or ACCESS-METHOD=*ISAM: regardless of the value specified for BLKSIZE, UPAM always works with a block size of 2048 bytes. This is because, for ISAM, each 2K block has a block control field and thus constitutes a separate entity. In this case, the LEN value must not be more than 2048.The following errors may arise in the context of a UPAM access to a tape file with BLKCTRL=PAMKEY and blocks which deviate from standard blocks (2064 bytes):
hardware error (error code = 927)
the data may be stored in the buffer incorrectly
the PAM key may be corrupted.
Tape files may not be accessed by several jobs at once, or by one job several times (this is due directly to the properties of the magnetic tapes). This means:
a tape file must not be opened with SHARUPD=YES/WEAK
a tape file which is already open cannot be opened again, even when both OPEN operations are in INPUT mode
a tape file must not be opened with an FCB operand whose PAMREQS value is greater than one.
It is possible to read a tape file with UPAM using random access. However, the time outlay involved can be considerable.
It is possible to write PAM blocks as of a specific point in an existing tape file. The last newly written block automatically becomes the last block in the file, even if the existing file contained more blocks. The file can then only be read up to this block. If a block nearer the start of the file is then read and the file is then closed, the most recently read block becomes the last block in the tape file.
Programming notes
Whenever UPAM induces a program termination, it supplies registers 0, 1 and 15 with the following contents, which can be easily identified and evaluated in memory dumps:
Register | Contents |
|---|---|
0 | Address at which the termination occurred |
1 | Address of the element in the UPAM operand list chain in which the error was detected |
15 | UPAM error code |
If register 1 contains an invalid address when the PAM macro is called for the first time, this address will be contained in register 0 when the dump is taken. Register 1 will then contain the value 0. I.e. the error occurred before the first element in the operand list chain was located.
UPAM uses the following EXLST exits:
EXLST exit | Brief description |
|---|---|
ERRADDR | Hardware fault or abnormal I/O termination. |
USERERR | Invalid use of a macro in the program or attempt to read a PAM page not belonging to the file (EOF). |
Fields ID1LWB (PARMOD=24) and ID1LWBPT (PARMOD=31) in the FCB are used to store the address of the last block on which a WT operation was carried out successfully by UPAM. The leftmost byte of field ID1LWB is used as an indicator byte.
If the last UPAM operation on the file was a successful WT, then the indicator byte in ID1LWB is set to X'00' and the three least significant bytes of ID1LWB/ID1LWBPT contain the address of the block affected by the WT operation. This occurs regardless of whether or not the operation which initiated the WT was successfully completed.
If the last UPAM operation on that file did not initiate a WT, the indicator byte in ID1LWB is set to X'FF'. The contents of the remaining three bytes in ID1LWB or ID1LWBPT are of no significance.
UPAM treats magnetic tape cartridges just like normal magnetic tapes.