The GET macro retrieves (reads) the next record. Various modes are available and are specified in the DCB macro.

In the locate mode, the GET macro instruction locates the next sequential record or record segment to be processed. The system returns the address of the record or segment in register 1. If you are reading undefined-length records (RECFM=U) and you are not using the large block interface (LBI), the system places the length of the record or segment in the logical record length (DCBLRECL) field of the data control block. The DCBLRECL field is not changed when GET is used in XLRI processing. You can process the record in the input buffer or move the record to a work area.

If you are using the large block interface (OPEN set DCBESLBI on) for undefined-length records, the actual length of the record block that was read is in a 4-byte length-read field. Find the length-read field as follows:

1. After return from the GET macro, and before issuing any other macros against this DCB, obtain the address in DCBIOBA, which is the word at offset X'44' in the DCB.
2. Subtract 4 from the address to obtain the address of the 4-byte length-read field.

In move mode, the GET macro moves the next sequential record to your work area. This work area must be large enough to contain the largest logical record of the data set and its record-descriptor word (variable-length records). The system returns the address of the work area in register 1. The record length is placed in the DCBLRECL field. You can use move mode only with simple buffering.

In data mode, which is available only for variable-length spanned records, the GET macro moves only the data portion of the next sequential record to your work area. You cannot use the TYPE=P parameter with data mode.

The GET 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 16MB line. Most types of data sets support 31-bit mode.

QSAM allows data areas to be located above the 16 MB line. To take advantage of providing data areas above the 16MB line for QSAM macros, the issuer of the GET 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 GET macro must then execute in 31-bit addressing mode. To specify that OPEN is to get buffers above the 16 MB 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 GET macro is:

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

specifies the address of the data control block for the opened input data set being retrieved.

pdab address—RX-Type Address, (2-12), or (1)

specifies the address of the parallel data access block for the opened input data sets from which a record is retrieved. When pdab address is used, TYPE=P must be coded.

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

specifies the address of an area into which the system is to move the record (move or data mode). The move, locate, or data mode can be used with QSAM, but 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 GET in 31-bit mode. If you requested that OPEN get buffers above the 16MB line, the GET must be issued in 31-bit mode. If the area address is omitted in the move or data mode, the system assumes that register 0 contains the area address. The following describes the operation of the three modes:

Locate Mode: If locate mode is specified in the data control block, the area address must be omitted. The system returns the address of the beginning buffer segment containing the record in register 1. If the data set is open for RDBACK, register 1 points to the last byte of the record. This address remains valid until you issue the next GET, FEOV, RELSE, or CLOSE macro for the DCB. Reasons why the address might become invalid include the system may be reading new data into the old buffer or the system may have freed the buffer.

When retrieving variable-length spanned records, and the logical record interface (LRI) or extended logical record interface (XLRI) is not used, the records are obtained one segment at a time. The problem program must retrieve additional segments by issuing subsequent GET macros, except when a logical record interface is requested (by specifying BFTEK=A in the DCB macro, by issuing a BUILDRCD macro, or by specifying DCBLRECL=0K or nnnnnK in the DCB macro). In this case, the control program retrieves all record segments and assembles the segments into a complete logical record. The system returns the address of this record area in register 1.

When the maximum logical record length is greater than 32756 bytes, LRECL=X must be specified in the data control block, and the problem program must assemble the segments into a complete logical record. LRECL=X or segment mode processing is not allowed for ISO/ANSI spanned records, RECFM=DS or RECFM=DBS.

Move Mode: If move mode is specified in the data control block, the area address specifies the beginning address of an area in the problem program into which the system moves the record. If the data set is open for RDBACK, the area address specifies the ending address of an area in the problem program.

If move mode is specified in the data control block, do not code BFTEK=A.

For variable-length spanned records, the system constructs the record-descriptor word in the first 4 bytes of the area and assembles one or more segments into the data portion of the logical record area; the segment descriptor words are removed. When XLRI mode is used, the record descriptor word (RDW) in the record area is a fullword value.

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 the area in the problem program into which the system moves the data portion of the logical record. A record-descriptor word is not constructed when data mode is used. TYPE=P cannot be used with data mode.

Extended Logical Record Interface (XLRI): When the GET macro is used in XLRI mode, the address returned in register 1 points to a fullword record length value. The 3 low-order bytes of the fullword indicate the length of the complete logical record plus 4 bytes for the fullword.

XLRI mode requires a record area to assemble a complete logical record from the segments that are read.

If a record area is not automatically obtained by OPEN processing, you can construct a record by using the BUILDRCD macro before issuing the OPEN. The DCB LRECL field indicates the length of the area in 'K' units (1024 bytes) required to contain the longest logical record of the data set.

Restriction: If spanned records extend across volumes, errors might occur when using the GET macro if a volume that begins with a middle or last record segment is mounted first, or if an FEOV macro is issued followed by a GET macro. QSAM cannot begin reading from the middle of the record. (This applies to move mode, data mode, and locate mode if logical record interface is specified.)

TYPE=P

TYPE=P and pdab address are used to retrieve a record from a queue of input data sets that have been opened. The open and close routines add and delete DCB addresses in the queue. The DCB from which a record is retrieved can be located from information in the PDAB. For this purpose, the formatting macro, PDABD, should be used. When pdab address is used, TYPE=P must be coded. The TYPE=P parameter is not supported for 31-bit callers. Unpredictable results may occur.