UPAM offers the following functions for disk files:
Creation of disk files; users themselves must program access to records (e.g. sequential access or associative access using hashing techniques).
Reading of SAM and ISAM files (OPEN=INPUT) and their transfer to other volumes (e.g. from disk to tape); the file attributes, e.g. BLKSIZE, RECSIZE, RECFORM, are stored in the associated FCB. This enables the user to program access to records.
UPAM cannot open SAM or ISAM files in UPDATE mode.
Because of the complex relationships between index blocks and data blocks, ISAM files cannot be effectively processed using UPAM. UPAM can, however, be used for the block-oriented transfer of ISAM files to tape.
Shared-update processing: a number of parallel jobs can process a PAM file concurrently. The OPEN modes permitted in the shared-update processing of a PAM FILE (mono system) are described in detail in the “UPAM” chapter of the “Introductory Guide to DMS” [1].
PAM macros in list form (up to 255, not necessarily all referring to the same file) can be handled with a single UPAM I/O request, i.e. only one SVC is required. The chaining of PAM macros (just like chained I/O) serves to optimize the runtime performance of user programs.
Eventing mechanism: the user job is notified when a UPAM I/O operation terminates and a contingency process starts.
For files with DRV (Dual Recording by Volume; see the “DRV” manual [15]): user information is output on the current status (e.g. loss of a copy of a disk). This information is requested by UPAM when an I/O operation is performed, and stored in the FCB (field ID1DRVST). However, this field is not updated unless the DRV status is modified.
When using UPAM for a disk file without a PAM key (BLKCTRL=DATA or BLKCTRL=NO), the following points should be borne in mind:
the file must have standard blocks (BLKSIZE=(STD,n))
if the file is not an ISAM file (FCBTYPE=SAM or FCBTYPE=PAM), the secondary allocation must be at least as large as the defined block size (BLKSIZE).
Chained I/O
Chained I/O permits the simultaneous input/output of up to 255 logically consecutive PAM pages in one file 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 "TU eventing: eventdriven 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 (EOF) processing” above).
A LOCK or UNLOCK operation applied to a file opened as SHARUPD=NO or SHARUPD= WEAK is treated as a no-op, i.e. the only action taken is to update the pointer to indicate the last page processed. The LEN operand is interpreted in this case.
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 on the processing of disk files with UPAM
Blocks are not transferred to the user buffer until an explicit action macro is issued. As this causes a delay, asynchronous I/O operations have to be terminated by means of the WTaction 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 0 | Address at which the termination occurred. |
Register 1 | Address of the element in the UPAM operand list chain in which the error was detected. |
Register 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:
ERRADDR USERERR | Hardware fault or abnormal I/O termination. Invalid use of a macro in the program or attempt to read a PAM page not belonging to the file (EOF). |
EOFADDR PGLOCK | Attempt to read a dummy file. 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, taking the following points into account (see also the KEYFLD operand of the PAM macro, "PAM - Perform UPAM actions"):
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):
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 or ID1WBPT 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 operation, 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.