The PUT macro writes a record in a sequential data set, partitioned data set, PDSE or UNIX file. You can specify locate mode, move mode, and data mode in the DCB macro. In the locate mode, the PUT macro returns the address of an area in an output buffer in register 1. You should then construct, at this address, the next sequential record or record segment. In the move mode, the PUT macro moves a logical record into an output buffer. In the data mode, which is available only for variable-length spanned records, the PUT macro moves only the data portion of the record into one or more output buffers.

The access method blocks records as specified in the data control block before being placed in the data set. Blocking means collecting records into blocks. For undefined-length records without LBI, you set the DCBLRECL field to determine the length of the next record. Use the DCBD macro to map DCBLRECL. For undefined-length records with LBI, you set DCBEBLKSI before each PUT to determine the length of the next record. Use the IHADCBE macro to map DCBEBLKSI. For variable-length records, PUT uses the DCBLRECL field to locate a buffer segment of sufficient size (locate mode), but the length of the record actually constructed is verified before the record is written (the output block can be filled to the maximum if, before issuing the PUT macro, you set DCBLRECL equal to the length of the next record). For variable-length spanned records, the system segments the record according to the record length, buffer length, and amount of unused space remaining in the output buffer. The smallest segment created is 5 bytes, 4 for the segment descriptor word plus 1 byte of data.

The PUT macro may be issued in 24- or 31-bit addressing mode. When issued in 31-bit addressing mode, all addresses must be valid 31-bit addresses. This includes allowing the caller to issue QSAM macros in 31-bit addressing mode regardless of whether the buffers are above or below the 16 MB line. Most types of data sets support 31-bit mode.

QSAM allows data areas to be located above the 16MB line. To take advantage of providing data areas above the 16MB line for QSAM macros, the issuer of the PUT macro must then execute in 31-bit addressing mode. To take advantage of QSAM buffers above the line, you must specify for OPEN to obtain the buffers above the line and the issuer of the PUT macro must then execute in 31-bit addressing mode. To specify that OPEN is to get buffers above the 16MB line, code RMODE31=BUFF on the DCBE macro.

Refer to z/OS DFSMS Using Data Sets, for a complete description of CCSID conversion and default character conversion.

The format of the PUT macro is:

dcb address—RX-type address, (2-12), or (1)

specifies the address of the data control block for the data set opened for output.

area address—RX-type address, (2-12), or (0)

specifies the address of an area containing the record to be written (move or data mode). The move, locate, or data mode can be used with QSAM, but they must not be mixed in the specified data control block. When issued in 31-bit addressing mode, the input area address (move or data mode) must be clean 31-bit addresses. For move or data mode, if the input area address resides above the 16MB line, you must issue the PUT in 31-bit mode. If you requested that OPEN get buffers above the 16MB line, the PUT must be issued in 31-bit mode. If the area address is omitted in the move or data mode, the system assumes that register zero contains the area address. The following describes the operation of the three modes:

Locate Mode: If you specify locate mode, omit the area address. The system returns the address of the next available buffer in register 1. This is the buffer into which your program later places the next record.

When variable-length spanned records are processed without the extended logical record interface (XLRI), and a record area is provided for a logical record interface (LRI) (BFTEK=A has been specified in the data control block or a BUILDRCD macro has been issued), the address returned in register 1 points to an area large enough to contain the maximum record size (up to 32756 bytes). The system segments the record and writes all segments, providing proper control codes for each segment. If, for variable-length spanned records, a record area has not been provided, the actual length remaining in the buffer is returned in register 0. In this case, you must segment the records and process them in record segments. ISO/ANSI spanned records, RECFM=DS or RECFM=DBS, cannot be processed in segment mode. The record or segment is not written until another PUT macro is issued for the same data control block or an FEOV or CLOSE macro is issued.

When a PUT macro is used in the locate mode, the address of the buffer for the first record or segment is obtained by issuing a PUT macro after open. QSAM returns the address in register 1. Then, move data to this address. The buffer is not written to the data set until the next PUT macro is issued. If records are blocked, the data is not written to the data set until the PUT following the one that filled the buffer. Each PUT macro returns the address of the next buffer in register 1. After this address is given to you, QSAM always counts this address as a valid record. You should always place valid data at the address returned in register 1 before issuing another PUT or FEOV or CLOSE macro. Otherwise, residual data at that location is written to the data set. After issuing an FEOV macro (for multivolume data sets), you must reinitialize register 1 with the first buffer address for the next volume by issuing a PUT macro after return from FEOV.

Move Mode: If move mode is specified in the data control block, the area address specifies the address of the area containing the record to be written.The system moves the record to an output buffer before control is returned.

Data Mode: If data mode is specified in the data control block (data mode can be specified for variable-length spanned records only), the area address specifies the address of an area in the problem program that contains the data portion of the record to be written. The system moves the data portion of the record to an output buffer before control is returned. You must place the total data length in the DCBPRECL (not the DCBLRECL) field of the data control block before issuing the PUT macro. On return from the PUT, the value stored in DCBPRECL may have been modified by the system.

Extended Logical Record Interface (XLRI): When the PUT macro is used with the extended logical record interface, the address returned in register 1 points to an area used to build a 4-byte logical record length field (RDW) followed by a complete logical record. The logical record length byte count occupies the 3 low-order bytes of the record length field and must include the length of the field. The high-order byte must be zero. The DCB LRECL value indicates the length of the longest logical record of the data set in 'K' (1024-byte) units.