Logical records versus buffers

Application programs can control whether VTAM® respects logical record boundaries when fulfilling a RECEIVE macroinstruction. This is done by means of the FILL keyword operand on the APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC and QUALIFY=ISPEC macroinstructions. For the APPCCMD CONTROL=RECEIVE, QUALIFY=ANY and QUALIFY=IANY macroinstructions, the choice is determined on an earlier macroinstruction by means of the CONMODE parameter. (This is discussed in Continuation modes for receiving normal information.)

The FILL keyword specifies whether the application program is to receive data in terms of the logical-record format of the data. This keyword, which corresponds to the FILL=LL|BUFFER parameter described in LU 6.2 architecture, is labeled RPL6FILL in the RPL extension.

The following values are valid for this parameter:

FILL=BUFF: Specifies that the application program is to receive data independently of its logical-record format, up to the length specified by the AREALEN field of the RPL. This corresponds to FILL=BUFFER on the RECEIVE_AND_WAIT verb described in LU 6.2 architecture. Note that for APPCCMD CONTROL=RECEIVE, QUALIFY=ISPEC, the data received may be less than the length specified on AREALEN.
FILL=LL: Specifies that the application program is to receive one logical record, or whatever portion of the logical record is available, up to the length specified by the AREALEN field of the RPL. This corresponds to FILL=LL on the RECEIVE_AND_WAIT verb described in LU 6.2 architecture. Note that for APPCCMD CONTROL=RECEIVE, QUALIFY=ISPEC, the data received may be less than the length specified by the AREALEN field and not complete a logical record.

By specifying FILL=LL on the APPCCMD CONTROL=RECEIVE macroinstruction, the application program can receive a logical record even if the total amount of data is less than the AREALEN specified on the RPL for the RECEIVE. If FILL=BUFF is specified, the macroinstruction is usually not completed until enough data is received to fill the application's entire buffer. In such cases, it is entirely up to the application program to detect the boundaries of logical records. When FILL=LL is specified, data in excess of a logical record is stored by VTAM and is available to use in fulfilling the next RECEIVE. Table 1 illustrates the use of FILL and its impact on how much data is received.

Table 1. Examples of the FILL parameter
Example	Macroinstruction	Results
A 120-byte logical record arrives for the application program, and VTAM receives it. The application program has a 100-byte buffer.	APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=LL	The application program receives the full 100 bytes that its buffer holds. VTAM continues to store the remaining 20 bytes of the logical record. The DATA_INCOMPLETE indicator is set on in the What-Received field in the RPL extension.
APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	One hundred bytes are put in the application's RECEIVE buffer, and VTAM continues to store the remainder. The DATA indicator in the What-Received field is set on.	APPCCMD CONTROL=RECEIVE QUALIFY=ISPEC AREA=buffer address, AREALEN=100, FILL=LL
The application program receives the full 100 bytes that its buffer holds. VTAM continues to store the remaining 20 bytes of the logical record. The DATA_INCOMPLETE indicator is set on in the What-Received field in the RPL extension.	APPCCMD CONTROL=RECEIVE, QUALIFY=ISPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	One hundred bytes are put in the application's RECEIVE buffer, and VTAM continues to store the remainder. The DATA indicator in the What-Received field is set on.
The program issues RECEIVE after the 20 remaining bytes from the first example have been stored by VTAM, and no other data has been received by VTAM for the application program.	APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=LL	The 20 bytes are received by the application program, and the DATA_COMPLETE indicator is turned on in the What-Received field of the RPL extension. RECLEN holds a value of X'14'.
APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	The macroinstruction does not receive the 20 bytes of data yet, unless this is the last logical record the partner application program is sending prior to a confirmation request, deallocation request, or attempt to enter RECEIVE state. VTAM normally waits until another 80 bytes of data arrive to complete the RECEIVE. When the macroinstruction does complete, the DATA bit in the What-Received field will be set on.	APPCCMD CONTROL=RECEIVE QUALIFY=ISPEC AREA=buffer address, AREALEN=100, FILL=LL
The 20 bytes are received by the application program, and the DATA_COMPLETE indicator is turned on in the What-Received field of the RPL extension. RECLEN holds a value of X'14'.	APPCCMD CONTROL=RECEIVE, QUALIFY=ISPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	The 20 bytes are received by the application program, and the DATA indicator is turned on in the What-Received field of the RPL extension. RECLEN holds a value of X'14'.
VTAM receives 100 bytes for the application program—the first 50 finishing a logical record and the next 50 making up a complete logical record. The application program has specified a buffer of 100 bytes.	APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=LL	The application program receives the first 50 bytes and the other 50 continue to be stored by VTAM. The DATA_COMPLETE indicator bit is set on.
APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	The application program receives the entire 100 bytes. The DATA indicator bit is set on.	APPCCMD CONTROL=RECEIVE QUALIFY=ISPEC AREA=buffer address, AREALEN=100, FILL=LL
The application program receives the first 50 bytes and the other 50 continue to be stored by VTAM. The DATA_COMPLETE indicator bit is set on.	APPCCMD CONTROL=RECEIVE, QUALIFY=ISPEC, AREA=buffer address, AREALEN=100, FILL=BUFF	The application program receives the entire 100 bytes. The DATA indicator bit is set on.