INPUT | read sequentially towards the end of the file; the file must exist. |
OUTPUT | create a new file sequentially or overwrite an existing file. |
EXTEND | extend file. |
UPDATE | for disk files in locate mode only: update records; the record to be updated must be retrieved by means of GET; the length of the record must not be changed during processing; the updated record is replaced by means of PUTX. |
REVERSE | read sequentially towards the beginning of the file; the file must exist; tape files which extend over more than one volume can only be read volume by volume with the aid of the VSEQ operand (see "FILE - Define file attributes / control file processing"); no automatic tape swap. |
The following table shows which OPEN modes are possible for which SAM action macros.
Action macro | OPEN type | OPEN type | OPEN type | OPEN type | OPEN type |
GET | x | x | x | ||
PUT | x | x | |||
PUTX | x | ||||
RELSE | x | x | x | x | x |
SETL | x | x | x | x | x |
If files are opened as output files (OPEN OUTPUT/EXTEND), SAM interprets each PUT or SETL macro as an end-of-file (EOF) indicator. The last PUT or SETL macro prior to a CLOSE macro for a file thus automatically indicates EOF to the system. If the user wishes to delete all records after a specific record in a file, he/she can use the SETL macro to position to the desired point in the file, and then issue a CLOSE macro to close the file.
For direct access, a retrieval address is made available to the user. The format of this retrieval address is described in detail in the “SAM” chapter of the “Introductory Guide to DMS” [1]. When a record is written, its retrieval address is made available in the FCB. If the user wishes, he/she can create a new file from this retrieval address data to serve as a basis for subsequent non-sequential processing of this file. The retrieval address is also made available in the FCB after execution of a GET macro. In this case too, therefore, even if the user did not create the file, he/she can still create a secondary file from the retrieval addresses in order to perform subsequent non-sequential processing of the file.
If, in move mode with two output buffers, physical end-of-volume is detected when a data block is written to a tape file, the other buffer (which contains only one record) is written to the other tape. A tape swap is not executed until this has been done.
If a file is to be created in locate mode (OPEN OUTPUT/EXTEND), the start address of the first record to be written is returned to the user, after OPEN, in the register specified in the operand IOREG in the FCB macro. After execution of the PUT macro, this register contains the address for the next higher record.
In the case of a file with variable-length records (RECFORM=V), the user also always receives the number of free bytes in the current block. This information is passed in the register he/she specified in the VARBLD operand of the FCB macro.
Primary and secondary allocations (disk files)
When a SAM file is created or overwritten (OPEN OUTPUT) or extended (OPEN EXTEND), both the primary and secondary allocations must be at least the same as the block size.
If a file for which RECFORM=F or RECFORM=V is specified is to be created or extended in move mode (OPEN OUTPUT/EXTEND) and is to have more than one record per data block, then the following conditions apply:
The primary allocation must be at least twice as long as the data block (primary allocation >= 2 * BLKSIZE). Otherwise control will be passed to the EXLST exit NOSPACE (insufficient storage space).
The secondary allocation defined by SAM is implemented as of the first record of the last block that can still be written in the assigned area. If the secondary allocation cannot be implemented, control passes to the EXLST exit NOSPACE (provided it is available in the program), thereby giving the user the opportunity to write the remaining records of the last block.
Effects of the LABEL operand (tape files)
NO / NSTD | Specification of the BUFOFF operand will lead to an OPEN error with CODE=ISO/OWN and BLKSIZE=STD. |
(STD,0) | Specification of the BUFOFF operand and CODE=ISO/OWN will lead to an OPEN error. |
(STD,1) | Specification of the BUFOFF operand and the entry CODE=ISO/OWN will lead to an OPEN error. |
(STD,2) | Standard blocks are converted into nonstandard blocks (BLKCTRL=DATA/NO) and V-records are converted to D-records; |
(STD,3) | Standard blocks are converted into nonstandard blocks (BLKCTRL=DATA/NO) and V-records are converted to D-records; |
STD / | Specification of the BUFOFF operand will lead to an OPEN error. |
1) Length specified in decimal form in the case of D-records.
The combination of the specifications for the operands CODE, RECSIZE and RECFORM result in the following values for LABEL if the file to be created is the first file on a tape:
CODE | Block format | RECFORM | LABEL value (implicit) |
EBCDIC | PAMKEY | - | (STD,1) |
EBCDIC | DATA/NO | U | (STD,2) |
EBCDIC | DATA/NO | F/V | (STD,3), V-records -> D-records |
ISO/OWN | PAMKEY | - | OPEN error |
ISO/OWN | DATA/NO | U | (STD,2) |
ISO/OWN | DATA/NO | F | (STD,3) |
ISO/OWN | DATA/NO | V | V-records -> D-records (STD,3) OPEN error if BLKSIZE > 9999 |
Table 3: Effeccts of the CODE BLKSIZE, RECFORM operands on the LABLE operand
The combination BUFOFF and RECFORM=U or BLKCTRL=DATA is not permitted.
In the case of LABEL=(STD,1), it is not possible to write a file with CODE=EBCDIC, with nonstandard blocks and D-records. However, it is possible to read such a file.
An OPEN error will occur if the standard label level requested via the LABEL operand does not match that specified in the VOL1 label.
If LABEL=STD is specified or the LABEL operand is omitted, the label level is determined as shown in Table 55. If the resulting label level is higher than that in the VOL1 label, the label level defined in the VOL1 label is used. If the resulting label level is lower than that in the VOL1 label, or if the VOL1 label specifies LABEL=(STD,0), and if CODE=ISO/OWN is specified, an OPEN error will result.
SAM file record formats
The SAM access method permits the record formats: F (fixed record length), V (variable record length) and U (undefined record length).
When format U is used, SAM reads or writes only one record per data block (buffer). For example, the definition RECFORM=U in combination with BLKSIZE=STD, BLKCTRL=PAMKEY and a current record length of 48 bytes would mean that 2000 bytes in each PAM page would be “wasted”.
If the full capacity of a standard block is not used (e.g. after the action macro RELSE, SETL, FEOV or CLOSE), the remaining bytes in the block are unchanged, which means that their contents are undefined.
The size of the record must not exceed the block size (see the BLKSIZE operand in the FILE/FCB macro).
Further information on record format can be found in the section dealing with access methods in the “Introductory Guide to DMS” [1].
FCB retrieval address
When creating a SAM file, DMS places a retrieval address in the FCB. This address can be used for positioning by means of SETL. It consists of block numbers and record numbers. The block number always refers to a logical data block (not to a PAM page), while the record number indicates the position of the record within the indicated block. For multivolume files, it should be noted that the block number is maintained only within each volume.
In the 31-bit TU FCB, i.e. for XS programming, the retrieval address is split into two fields, each one word long: the field ID1BLK# contains the block number within the file and the field ID1REC# contains the record number within this block. Both fields are incremented automatically by the system. Whenever a data transfer operation is initiated, the record counter is automatically reset.
For non-XS programming, the retrieval address is kept in field ID1RPTR of the 24-bit TU FCB in the form “bbbbbbrr”, where “bbbbbb” is the number of the data block in the file and “rr” is the number of the record within the block. The record counter is not automatically incremented by the system; the user must do this in his program if he/she wants to use the retrieval address. However, the record counter is automatically reset whenever a data transfer operation is initiated.
For tape files, it should be noted that the retrieval address is returned only for files with standard blocks, which means that SETL R (see the SETL macro, "SETL - Position file pointer") cannot be used for files with nonstandard blocks.
Structure of the retrieval address:
ID1BLK# (1 word) | ID1REC# (1 word) |
Block number | Record number |
Table 4: Structure of the retrieval address XS interface
ID1RPTR1 byte 1-3 | ID1RPTR1 byte 4 |
Block number | Record number |
Table 5: Structure of the retrieval address Non-XS interface
1 1 word
The first record in a file thus has the following retrieval address:
in the 31-bit TU FCB in the 24-bit TU FCB | 00000001 in field ID1BLK# and 00000001 in field ID1REC# 00000101 in field ID1RPTR |
The following has to be noted for processing SAM node files:
If a data block is closed with RELSE during a write process on a SAM node file before it has been filled completely, the retrieval addresses are only valid from that moment on for as long as the file is open.
CLOSE and re-OPEN results in a different distribution of the data sets of the node file on the SAM blocks, which are transferred to the access method for processing; this means the previous retrieval addresses do not match the file anymore!
This behavior of SAM node files (Net-Storage) is incompatible with the processing of SAM files on conventional public space, where the block and record structure remains unchanged even after CLOSE and OPEN. Because of this, the application must set the indicator SAM_NODE_FILE_ENABLE in the file control block (FCB) before it opens the file, to indicate that it is capable of processing SAM node files correctly.
Retrieval address values for SETL B and SETL E, depending on the OPEN type:
OPEN type | SETL B | SETL B | SETL B | SETL E | SETL E | SETL E |
INPUT, UPDATE | - | - | - | max. | 1 | max. 1 |
OUTPUT | 1 | 0 | 1 0 | error | error | error |
EXTEND | 1 | 0 | 1 0 | error | error | error |
REVERSE | - | - | - | - | - | - |
where:
- max | Field contents unchanged. Highest block number. |
Field IDRPTR contains both the block and record counters.
The action macros return the retrieval address as follows:
GET
if a data transfer is necessary for the requested record, the block counter contains the logical block number and the record counter is reset. For 31-bit FCB, the record counter is updated by each action macro.
PUT
if the PUT macro results in a data transfer, the block counter is updated and the record counter is reset. The block counter thus contains the number of the new data block which will receive the record. For 31-bit FCB, the record counter is updated by each action macro.
RELSE
if a file is being created or extended (OPEN OUTPUT/EXTEND), the block counter contains the number of the block which will receive the following record and the record counter is set to zero.
FEOV
after a tape swap, the block and record counters are reset for the new tape by the system.
Example
File attributes: | BLKCTRL=PAMKEY, BLKSIZE=(STD,2), RECFORM=F, RECSIZE=512 |
Retrieval address | Retrieval address | Retrieval address | |
Record 10 | 00000002 | 00000002 | 00000202 |
Record 20 | 00000003 | 00000004 | 00000304 |