The following UPAM functions are available 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 and transfer of SAM and ISAM files
(OPEN INPUT) reading of SAM and ISAM files and their transfer to other volumes (e.g. from disk to tape): the file attributes are defined in the FCB (e.g. BLKSIZE, RECSIZE, RECFORM) or in the ADD-FILE-LINK command (BUFFER-LENGTH, RECORD-SIZE, RECORD-FORMAT). 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.
Chained I/O
Up to 255 logically consecutive PAM pages of a file can be input or output by means of a single PAM macro. The maximum value depends on the disk attributes (see SHOW-MASTER-CATALOG-ENTRY, I/O length).
PAM macros in list form
Up to 255 PAM macros (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.
DRV
For files with DRV (Dual Recording by Volume; see the “DRV” manual [14 (Related publications)]), 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.
Shared-update processing (multi-user mode)
A number of parallel jobs can process a PAM file concurrently.
Disk file without a PAM key
A file without a PAM key is defined by means of the operands BLKCTRL=NO / DATA in the FILE/FCB macro or with the operands BLOCK-CONTROL-INFO=*NO / *WITHIN-DATA-BLOCK in the ADD-FILE-LINK command. The following points should be kept in mind:
The file must have standard blocks (BLKSIZE=(STD,n) or BUFFER-LENGTH=*STD(SIZE=n))
If the file is not an ISAM file (FCBTYPE=SAM/PAM or ACCESS-METHOD=*SAM/*UPAM), the secondary allocation must be at least as large as the defined block size (BLKSIZE or BUFFER-LENGTH).
The following applies to the UPAM access method:
If SHARUPD=*WEAK is specified, a file can be opened in read mode even if it has been opened in write mode by another system in the multi-system environment. However, a file extension (secondary allocation) initiated by the other system at a point in time after the file is opened locally will be ignored. Any file sections generated at this later time cannot be read by the local user.
Illegal combinations result in an OPEN error.
If a PAM file is to be processed simultaneously by a number of different jobs, the operand SHARUPD=YES or SHARED-UPDATE=*YES must be specified for each job in the FCB macro or in the ADD-FILE-LINK command, respectively.
In UPAM, there is no implicit locking/unlocking of PAM pages. The user must explicitly request and release every lock himself/herself. The only exception is the CLOSE macro: before the file is closed, any PAM pages still locked in the file by this job are unlocked.Locking a PAM page does not prevent other jobs from reading it or writing to it. It merely prevents it from being locked once more by another job. Therefore, all jobs participating in shared-update mode should observe the following processing sequence:
Sperren (LOCK) -> Read(RD) -> Write(WRT) -> (UNLOCK)The entries in parentheses indicate the operands of the PAM macro.
The user should not attempt to request other resources for exclusive use while he/she has PAM pages locked, since this could lead to a deadlock situation (EXLST exit DLOCK).
One job must not have more than 255 PAM pages locked at the same time.
The same PAM page can only be locked once within a given UPAM operand list chain.
UPAM examines the FCB field ID1TOUT (value of the PAMTOUT operand) whenever a lock is requested. Thus the user program can amend this value as and when required, as long as the file remains open. If several locks are requested when PAM macros are chained together, the PAMTOUT value in the FCB referenced by the first lock request applies to all the locks requested in this “chain”.
If a lock is not available immediately, the job is queued for the length of time specified in the ID1TOUT field. If the requested lock is still not available after this time, the DLOCK or PGLOCK exit of the EXLST macro is taken, depending upon whether or not there are PAM pages locked by the job when the timeout occurs.
Any LOCK or UNLOCK operation applied to a file previously opened with SHARUPD=*NO or SHARUPD=*WEAK is treated as a no-op; all that happens is that the file pointer is updated.
If a PGLOCK is encountered, the program can continue normally, e.g. make a new attempt to lock the page after a waiting time. A DLOCK means that a multiple lock has at least been attempted, if not imposed, causing the program to become unstable. As long as it is in this unstable state, any attempt to lock a PAM page before all current locks are released will lead to abnormal termination of the program. Only when all current locks have been released, either in or after the routine for the DLOCK exit, will the program become stable again and be able to request locks in the usual way.
UPAM can also be used to access SAM node files. For write access (OPEN OUTIN), the additional bit SAM_NODE_FILE_ENABLE must be set in the FCB. By default, UPAM, when reading from SAM node files, recieves SAM blocks of the same structure as from public space. Likewise, UPAM has to write data blocks with the SAM structure.It is, however, possible to work without converting the data from UFD to the SAM block format: The so-called RAW access enables a direct access to the data of the node file. The RAW access is activated by setting the UPAM_RAW_ACCESS indicator in the FCB before OPEN processing. Dynamic switching between block-based processing and RAW processing is not possible.
If data are written to somewhere other than the end of the file, it is important in both cases (block-oriented with conversion or in RAW mode without conversion) to ensure that the writing (user) data are of the exact same length as the data to be overwritten. Disregarding this may lead to loss of data. It is also important to note that, when accessing data in RAW mode, UPAM addresses the data in multiples of 2 kB and therefore generally without considering the start and end of the record as well as the record length. The application is responsible for the correct processing of the data.