ISAM: | Macro type: | R for PARMOD=24 |
SAM: | Macro type: | R for PARMOD=24 |
Application area
The PUT function can be used when processing files with SAM or ISAM (record-oriented access methods). The file must have been opened with one of the following OPEN modes:
EXTEND | for SAM and ISAM |
Function
The PUT macro is used for sequential creation or extension of a file. It appends a record to the file.
For K-ISAM only:
The PUT macro can only be used to write records sequentially at the end of a file. If a file was opened in INOUT or OUTIN mode, PUT writes the record at the current end of the file. If the last macro issued for this file was not a PUT, the PUT performs a SETL to the end-of-file position before the record is written into the file.
ISAM:
The PAD factor (block padding) is taken into account during sequential creation or extension of a file. However, the effects for NK-ISAM and K-ISAM are different (For further details see "OPEN modes").
The PUT macro ensures that the key of any record added to the file is equal to or greater than the current highest key value. If the ascending sequence of the keys is broken, control is passed to one of the following two EXLST exits:
DUPEKY, if the key of the current record is equal to the key of the preceding record and DUPEKY=YES was not specified.
SEQCHK, if the key of the current record is less than the highest key of the exisiting file.
NK-ISAM:
If IOAREA1=NO is specified in the FCB for an NK-ISAM file, each PUT results in an SVC; the PAD value is ignored.
If IOAREA1 not equal to NO, the I/O area IOAREA1 is filled with records until:
the buffer is full, or
the limit specified by PAD in the FILE/FCB macro is exceeded, or
an ISAM action macro other than PUT is issued.
An SVC is then issued and a new block with the contents of the I/O area is appended to the file.
For shared-update processing, the complete area between the current highest key and the end of the file is locked after a PUT.
Locate mode:
In locate mode, DMS supplies the IOREG register (see FCB macro, IOREG operand, "FCB - Define file control block") with the address of the first free byte within the buffer. The user must then ensure that the record to be included in the output file is made available at this address.
The PUT macro checks the record and updates the address in IOREG for the next record. After the last record has been made available at the address specified in IOREG, it is not necessary to call the PUT macro again (otherwise a CLOSE error will result or a corrupted record will be added to the file).
SAM:
When processing Format V records in locate mode, DMS specifies the buffer capacity remaining after each PUT macro in the VARBLD register (see FCB macro, VARBLD operand, "FCB - Define file control block". The application program must ensure that the remaining buffer area can accommodate a complete record. If there is not enough space left, the RELSE macro must be called to close a block.
Move mode – tape processing:
If, in the case of tape processing, a PUT macro initiates a transfer of the preceding records, and if the end-of-tape mark is detected during this transfer operation, the current record is then written, alone and unblocked, into a block on the tape before the tape swap is initiated. As a result, the file may become one block larger each time the tape is swapped.
Format
Operation | Operands |
|
|
Operand descriptions
fcbaddr
Address of the FCB associated with the file to be processed.
(1)
The FCB address is stored in register 1.
area
Current address of the record to be transferred to the output buffer; The operand (if the IOREG operand is specified in the FCB) is ignored when processing files in locate mode.
(0)
The address of the record to be transferred to the output buffer is stored in register 0.
PARMOD
Specifies the generation mode for the macro.
Default value: | the value preset in the program by means of the GPARMOD macro or by the assembler. |
= 24
The macro is generated with the expansion for the 24-bit interface. The object code generated can run only in the 16-Mb address space (24-bit addressing).
= 31
The object code generated can run in the 2-Gb address space (24-bit or 31-bit addressing). The macro is generated such that it is independent of the addressing mode.
Programming notes
The PUT macro overwrites the contents of registers 0, 1, 14 and 15.
A PUT macro results in an SVC only when a buffer transfer is initiated. Consequently, the user cannot expect to receive control in an STXIT process each time a PUT macro is issued (when using the STXIT macro with SVC= or SVCLIST=; for more details see the “Executive Macros” manual [2]).