Chained I/O permits the simultaneous input/output of up to 255 logically consecutive PAM pages using a single PAM macro (not to be confused with the chaining of PAM macros in list form with the CHAIN operand). This reduces the number of I/O operations (and interrupts) and thus reduces processing time. On the downside, however, it increases main memory requirements and the paging rate.
UPAM uses chained I/O if the LEN operand of the PAM macro contains a value greater than STD or greater than 2048.
End-of-file (EOF) processing
If the end-of-file condition is encountered during a write operation, a secondary allocation is performed and the specified number of PAM pages are appended to the file.
If the end-of-file condition is detected during a read operation, UPAM merely transfers the PAM pages belonging to the file into the buffer.
UPAM notifies the calling job of end-of-file processing as follows:
If eventing is not used:
The user job receives control at the EXLST exit USERERR with error code X'0922' in field ID1ECB of the FCB. The number of PAM pages transferred is contained in field ID1NBPP of the FCB. The value X'00' in this field means that all the PAM pages to be read are located outside the file. A value greater than X'00' means that the user job must perform a wait operation, unless this was implicitly included in the read operation (i.e. in a RDWT operation).If eventing is used:
If all the PAM pages to be read are located outside the file, UPAM passes control to the user job at the EXLST exit USERERR with error code X'0922' in field ID1ECB of the FCB. If at least one of the PAM pages to be read belongs to the file, UPAM either resumes the basic task or initiates a contingency process (see section "TU eventing: event-driven processing"). Field IDECBNPA of the FECB (File Event Control Block, see "TU eventing: event-driven processing") now contains a value indicating the number of PAM pages transferred.X'00'
All PAM pages to be read were transferred to the buffer.
X'0n'
n = number of PAM pages belonging to the file that were transferred to the buffer.
Locking and unlocking of PAM pages
Only the first in a series of PAM pages to be locked/unlocked needs to be specified in a PAM macro; the number of pages to be locked/unlocked is derived from the value of the LEN operand. It should, however, be noted that after a lock or unlock operation, the file pointer points to the last PAM page that was locked/unlocked. This page may lie outside the file (see “End-of-file processing”, previous page).
A LOCK or UNLOCK operation applied to a file opened as SHARUPD=*NO or SHARUPD=*WEAK is a no-op: the only action taken is to update the pointer to indicate the last page processed, and the LEN operand is evaluated.
Processing of PAM keys
There are two possible ways of processing PAM keys:
The user reads/writes each individual key of a series of PAM pages: MKEY=YES operand in the PAM macro; the KEYFLD operand must contain the address of a sufficiently large area.
The user reads/writes only the first key of a series of PAM pages. During writing, succeeding blocks are assigned the same key as the first, with just the logical block number being incremented by 1 each time.
Notes
As blocks are not transferred to the user buffer until an explicit action macro is issued, this causes a delay. Consequently asynchronous I/O operations have to be terminated by means of the WT action macro. For TU eventing, the SOLSIG macro should be used (synchronously or asynchronously).
Any unsuccessful branch to the UPAM routines causes control to be passed to the routine specified in the EXIT operand of the FCB macro, or to the corresponding EXLST routine. An indicator is stored in the FCB.
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 issued for the first time, this address will be contained in register 0 when the dump is taken, and register 1 will contain zeros (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 |
|---|---|
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). |
EOFADDR | Attempt to read a dummy file. |
PGLOCK | Not all of the requested locks become available within the specified time, and the job currently has no blocks locked. |
DLOCK | The request to set up a lock is rejected and the job already has locks set. |
PAM pages which have been allocated to a file but have not yet been written by the file owner are identified by an internal file name code assigned by the system (CFID = Coded File ID, bytes 0-3 of the PAM key or block control field), which does not correspond to the current file name. The name comparison must be performed by the user. Thereby making sure (see also the KEYFLD operand of the PAM macro) that at OPEN time the current CFID is written to the first word of field ID1KEY1 in the FCB.
The following points apply solely to the processing of K-PAM files (BLKCTRL=PAMKEY or BLOCK-CONTROL-INFO=*PAMKEY):
After execution of a RDWT, LRDWT or RDEQU operation, the CFID of the block just read is located in the first word of FCB field ID1KEY2.
After execution of one of the operations WRT, WRTWT, WRTWU or WT, the CFID of the PAM page concerned is located in the first word of FCB field ID1KEY1. As the entry generated by OPEN will be overwritten, it should be saved prior to processing so that subsequent comparisons can be made.
After execution of an LRD or RD operation, the contents of fields ID1KEY1 and ID1KEY2 are not changed.
With event-driven processing, the CFID of the relevant PAM page is in the first word of FCB field ID1KEY1 after completion of an I/O operation.
The fields ID1LWB (PARMOD=24) and ID1LWBPT (PARMOD=31) in the FCB are used to store the address of the last block on which UPAM successfully performed an I/O operation. The leftmost byte of field ID1LWB is used as an indicator for an outstanding WT operation.
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.