Macro type: type S
All user requests to DMS for UPAM actions are issued using this macro.
Format
Operation | Operands |
|
|
Operand descriptions
fcbaddr
Specifies the address of the FCB associated with the file.
CHAIN = relexp
This operand specifies the symbolic address of the next element in a chain of PAM macros in list form. Such a chain must not contain more than 255 elements.
Default value: | the list is regarded as the last element in a chain. |
CHK
Checks whether the specified I/O request has been completed. If so, the program resumes; if not, control is transferred to the address specified by the LOC operand in the user program.
FECB = relexp
Symbolic address of a file event control block (see "TU eventing: event-driven processing"). This operand may be specified only for the operations RD, LRD and WRT.
HP
Points to a specific PAM page, as follows:
in non-chained I/O, the PAM page to be transferred (or locked)
in chained I/O (for disk files or for tape files with nonstandard blocks (NK files)), the first in a series of PAM pages to be transferred (or locked).
Default value: | HP = +1 (i.e. sequential processing). |
Note
For PAM and SAM files without PAM keys (operand BLKCTRL=DATA or BLKCTRL=NO), the following restrictions result from the fact that only logical blocks (and not the individual 2K blocks) can be accessed in such files:
For the operations LRD, LRDWT, RD, RDWT, RDEQU, WRT, WRTWT, WRTWU, LOCK and UNLOCK, HP must point to the beginning of a logical block,
i.e. HP = n * BLKSIZE + 1 (n >= 0).
If this is not the case, the PAM call will be rejected.For the operations SETL and SETLPP, HP must point to the end of a logical block, i.e. HP = n * BLKSIZE + 1 (n >= 0).
If this is not the case, the PAM call will be rejected. (For SETL operations, the file pointer is thus ready to access the next logical block.)
More detailed information is given in the "Programming notes".
= number
The absolute logical block number of the PAM page (LHP) within the file.
= +number
= -number
A relative logical block number (= relative to the file pointer). The corresponding absolute logical block number is calculated by adding the file pointer and the specified relative block number.
KEYFLD = relexp
This is evaluated only for files with PAM keys (operand BLKCTRL=PAMKEY). It is ignored for files with BLKCTRL=DATA or BLKCTRL=NO.
In the case of non-chained I/O, this operand specifies the address of a 16-byte area into which the PAM key is placed during reading or from which it is taken during writing.
In the case of chained I/O with separate processing of all associated PAM keys (operand MKEY=YES), this operand must specify the address of a sufficiently large area (number of PAM pages to be transferred times 16 bytes). If just the PAM key of the first PAM page is to be processed (MKEY=NO), the specified area need only be 16 bytes long. In this case the KEYFLD operand can be omitted, and the default value will come into effect.
The KEYFLD operand is ignored for the operations WT, CHK, SETL and SYNC.
Default value (for files with BLKCTRL=PAMKEY):
address of the ID1KEY1 field in the FCB (for all read and write operations except RDWT, LRDWT and RDEQU);
address of the ID1KEY2 field in the FCB (for RDWT,LRDWT and RDEQU).
For further information, see the "Programming notes".
LEN
Specifies the length of the data transferred in a PAM call.
Default value: | LEN=STD |
The LEN operand is ignored for the operations WT, CHK and SETL.
For its relationship with BLKSIZE, see the description of the UPAM FCB macro ("UPAM - User Primary Access Method").
For further information, see the "Programming notes".
= STD
Data is transferred with the length of a standard block (corresponds to 2048 bytes).
= (STD,n)
Data is transferred with the length of n standard blocks (of 2048 bytes each). n is an integer in the range 1 <= n <= 16.This operand value may be specified only for the 31-bit interface of the macro.
= length
The length in bytes of the data to be transferred (1 <= length <= 32768). A distinction must be made between the following cases:
1 <= length <= 2048: no chained processing; each PAM macro transfers a block with a length of 2048 bytes from/to the buffer, i.e. reads or writes one block.
2049 <= length <= 32768: chained processing.
For disk and tape files with PAM keys, the number of PAM blocks transferred with one PAM call is determined as follows:
If length is an integral multiple of 2048 (length = n * 2048, n <= 16), the quotient n = length/2048 is the number of PAM blocks to be transferred.
If length is not an integral multiple of 2048, the quotient is rounded up to the next higher integer. With certain hardware configurations, this can result in intermediate buffering and a corresponding decline in performance.
During CLOSE processing, in the case of files with BLKCTRL=PAMKEY the position of the last valid byte is always stored in the last-byte pointer of the last PAM block, and in the case of files with BLKCTRL=NO or DATA in the last-byte pointer of the last logical block of the file.
In the case of node files only data equivalent to the length length is transferred at the end of the file. A node file thus ends on a byte boundary in the event of subsequent CLOSE processing.
For a write operation, data is transferred with this length length; for a read operation, only the specified number of bytes are valid.
For PAM or SAM disk files without PAM keys, the length of a logical block is taken into account when the file pointer is calculated. However, the number of 2048-byte blocks written is never more than necessary to satisfy the LEN specification.
LOC
Points to the I/O buffer in main memory (this does not apply to CHK, see “relexp” below). The buffer must be large enough to hold at least as many PAM pages as specified by the value of LEN. The buffer address can be freely aligned on a byte boundary. If the buffer size is <= 4096 bytes (1 (main memory) page), it should be contained within one page and be aligned on a word boundary. If the buffer size is greater than 4096, it should be aligned on a page boundary. If the buffer alignment is not carried out in this manner, intermediate buffering may be required with certain hardware, and this is likely to have a detrimental effect on performance.
Default value:
IOAREA2 address in the FCB if a PAM call has already been executed for this FCB and IOAREA1 was specified in the last PAM call;
IOAREA1 address in the FCB in all other cases.
The LOC operand is ignored for the operations WT, LOCK, UNLOCK, SETL, SETLPP and SYNC.
= 1
This means that the buffer address is located in FCB field IOAREA1.
This specification is not permitted if IOAREA1=NO was specified in the OPEN macro. The (default) facility for switching buffers may be used only if neither IOAREA1=NO nor IOAREA2=NO was specified in OPEN.
= 2
This means that the buffer address is located in FCB field IOAREA2.
This specification is not permitted if IOAREA2=NO was specified in the OPEN macro. The (default) facility for switching buffers may be used only if neither IOAREA1=NO nor IOAREA2=NO was specified in OPEN.
= relexp
This specifies the buffer address or, in the case of a CHK operation, the continuation address if a checked I/O request has not been completed.
LOC=relexp is mandatory for a CHK operation; in other words, LOC must specify an address at which the task is to be continued if the checked I/O operation has not yet terminated.
LOCK
For disk files only:
Requests locks to be set on one or more PAM blocks (see also the operands HP and LEN). Locking a block means that other PAM calls with LOCK or LRD/LRDWT for this block will be rejected.
LRD
For disk files only:
Same as LOCK; if the lock is effected, processing continues as for RD.
LRDWT
For disk files only:
Same as LOCK and LRD; if the lock is effected, processing continues as for RDWT.
MKEY
For disk files only:
This operand is significant only for files with a PAM key (operand BLKCTRL=PAMKEY) and for chained I/O (see also the KEYFLD operand).
Default value: MKEY=NO
= NO
Only the PAM key of the first in a series of PAM pages is expected/provided by the user.
= YES
PAM keys are expected by the user for each PAM page read or provided by the user for each PAM page written.
PARMOD
Specifies the generation mode for the macro.
Default value: | the value predefined for the generation mode by means of the GPARMOD macro or preset by the assembler. |
= 24
The macro is expanded in accordance with the 24-bit interface format. The object code can only run in 24-bit addressing mode.
= 31
The macro is generated as addressing mode-independent.
POST = postcode
If UPAM TU eventing is used in conjunction with PARMOD=31, the user may enter a post code here; otherwise any entry in POST is ignored.
When I/O is complete, the post code can be retrieved in accordance with the SOLSIG definition:
from the two rightmost bytes of the RPOSTAD field
from the two rightmost bytes of the register specified in RPOSTAD
from the two rightmost bytes of register 3 in the contingency process initiated by the UPAM event (for more details see the description of the SOLSIG macro in the “Executive Macros” manual [2]).
RD
Initiates the reading of a data block from the file into main memory; the job continues immediately after the read operation has been initiated.
RDEQU
Same as RDWT except that, for disk files with Dual Recording by Volume (DRV, see the “DRV” [15] manual), the copy is also updated.
This operand value may be specified only for the 31-bit interface of the macro.
RDWT
Same as RD, except that the job does not continue until the read operation has been completed.
REQNO = number
For disk files only:
Specifies the number of the I/O request assigned to this operation. If this operand is specified, the FECB operand must be omitted.
Default value: | REQNO=1 |
SETL
Causes the file pointer to be set to the specified PAM page.
SETLPP
Only for disk files:
Causes the last-page (end-of-file) pointer to be set to the specified PAM page; the PAM page must already belong to the file. This operation is not permitted for input files (OPEN=INPUT) or for files which have been opened with SHARUPD=WEAK/YES. Node files are truncated after SETLPP.
SYNC
Waits for termination of the I/O operation and clears the control buffer for tape cartridge files; for files which are not on a magnetic tape cartridge, SYNC is equivalent to WAIT.This operand value may be specified only for the 31-bit interface of the macro.
UNLOCK
For disk files only:
Unlocks locked PAM blocks (see also the operands HP and LEN).
WRT
Initiates the writing of a data block from main memory into the file; the job is continued immediately after the write operation has been initiated.
WRTWT
Same as WRT, except that the job does not continue until the write operation has been completed.
WRTWU
Same as WRTWT; the PAM page just written is unlocked immediately after completion of the I/O operation.
WT
This operation causes the program to wait for the end of a particular request. The program continues upon completion of this request.
Programming notes
The PAM macro overwrites the contents of registers 0, 1, 14 and 15.
The first PAM page of a PAM file is designated as number 1. When a PAM file is opened, the file pointer is set to an initial value of 0. The HP operand is ignored in WT, CHK and SYNC operations. WT and CHK refer to I/O requests, not to PAM pages.
With the exception of WT, CHK, SYNC and – for tape files- SETLPP operations, any operation not resulting in a branch to an error routine causes the file pointer to be set to the number of the PAM page currently being accessed. This is also true of locking/unlocking even where SHARUPD=NO is specified. When operations lead to an error routine instead of terminating normally, the value of the file pointer does not change.
For PAM and SAM files without PAM keys (operand BLKCTRL=DATA or BLKCTRL=NO), the file pointer then contains the number of the last 2-Kbyte block which was accessed in the logical block. (During calculation of the file pointer, the length is thus rounded up to the next higher multiple of BLKSIZE.)If, for a disk file, “n” denotes the number of PAM pages already allocated to a file and “k” is the value of the secondary allocation, the following rules must be observed:
PAM operation Meaning RD
RDEQU
RDWT
LRD
LRDWTHP = number, where 1 <= number <= n WRT
WRTWT
WRTWUHP = number, where 1 <= number <= n + k
As soon as a PAM page with LHP > n is written, a secondary allocation is made; the file size thus increases to n + k PAM pages. If several consecutive PAM pages are to be written using one PAM macro (chained I/O), sufficient space for all pages to be written must be available (at the latest) after the first secondary allocation, i.e. LHP <= n+k must be true for the last page.LOCK
UNLOCKHP = number, where number > 0
PAM pages which are not allocated at the moment can be locked or unlocked later – this locking/unlocking does not result in a secondary allocation.The value specified for REQNO must be less than or equal to the value defined in the PAMREQS operand in the FCB macro.
The REQNO operand is ignored for the LOCK, UNLOCK and SETL operations. In WT, CHK and SYNC operations, it serves to specify the I/O request for which the operation is to be carried out.
Only one asynchronous I/O operation can be assigned to each request number (REQNO). A waiting period for termination of the asynchronous I/O operation can be defined either explicitly by specifying its request number in a WT operation or implicitly by a second read or write operation for the same request number. If an error is detected during an implicit wait for the end of an I/O request, error code 997 is returned, and the request which caused the implicit WT is not carried out.
Request numbers (REQNOs) are system resources; improper use may impair the efficiency of the system.
If the user wishes to use the data buffer created by OPEN for I/O operations (operand LOC=1 or LOC=2), the value specified for the LEN operand must not be greater than BLKSIZE, since the buffer will otherwise be too small to hold the data.
For tape files, the value specified for LEN must be exactly equal to the length of a tape buffer. For files with BLKCTRL=PAMKEY, this is one PAM block (2048 bytes); this is equivalent to the specification LEN=STD or LEN=(STD,1) or LEN=2048 (16 bytes for the PAM key are added by the system).
For tape files without PAM keys (operand BLKCTRL=DATA or BLKCTRL=NO), a nonstandard block with the length specified in LEN is written; when reading, an attempt is made to read a block with the length specified in LEN. For PAM or SAM files without PAM keys, the value specified for LEN must not be greater than BLKSIZE; for ISAM files without PAM keys, it must not be greater than 2048 or (STD,1).
If, when reading from a tape file without a PAM key, the value specified for LEN is less than the block length of the file, the read operation is terminated with an error. In order to avoid such errors, one should always read a tape file without a PAM key with LEN=BLKSIZE, i.e. with the maximum permissible value for LEN. For files with BLKCTRL=DATA, the length of the valid data can then be determined from the block control field.
In the case of a write operation (WRT, WRTWT, WRTWU) to a file with BLKCTRL=DATA, UPAM treats the first 12 bytes as the block control field and overwrites them with the block control information.
For files with BLKCTRL=DATA and operations which require an input/output operation, the value for LEN must be selected such that the block control field is entirely contained in the data buffer. This is the case if the following conditions are fulfilled:
For PAM and SAM disk files:
LEN = n*BLKSIZE or LEN > n*BLKLSIZE + 12 (n = number of data blocks)For ISAM disk files:
LEN = n*2048 or LEN > n*2048 + 12 (n = number of data blocks)For tape files:
LEN > 12
Files with BLKCTRL=DATA are subject to the following restriction with regard to parallel processing:
when processing a PAM file with BLKCTRL=DATA, the IOAREAs must not be used in parallel for several I/O jobs, as this would mean that the contents of the block control field would be undefined.Illegal approach:
PAM WRT,FCB1,LOC=BUFFER PAM WRT,FCB2,LOC=BUFFER (Parallel I/Os for BUFFER) PAM WT,FCB1 PAM WT,FCB2
Permissible approach:
PAM WRTWT,FCB1,LOC=BUFFER (Consecutive I/O operations PAM WRTWT,FCB2,LOC=BUFFER for BUFFER)
For LOCK or UNLOCK operations, LEN=0 is treated like LEN=2048 (or LEN=n, where 1 <= n <= 2048). If any other value is specified for LEN, as many PAM blocks as would be written or read by an I/O operation with this LEN value are locked.
For PAM and SAM files without PAM keys (operand BLKCTRL=DATA or BLKCTRL=NO), only the first 2-Kbyte section of each affected logical block is actually locked internally, but this causes the entire logical block to be locked.The following points apply to files with a PAM key (BLKCTRL=PAMKEY):
If a WT operation is performed (explicitly or implicitly) for a successful read operation, the 16-byte PAM key assigned to the block read is moved to the field designated by the KEYFLD operand. A CHK operation initiated after the completion of an I/O operation has the same effect as a WT operation.
If, for a write operation, the user places any information in the last 8 bytes of the 16-byte field defined by the KEYFLD operand, the information is written to the file as part of the PAM key assigned to the PAM page to be written (this is not recommended). UPAM always sets up the first 8 bytes of the KEYFLD area before the write operation begins.
The KEYFLD operand is ignored in conjunction with the WT, CHK, UNLOCK, SETL and SETLPP operations.