BUFFLST operating considerations

SEND OPTCD=BUFFLST allows FM data to be sent from a number of discontiguous buffers; this can result in more efficient use of application program storage areas. The RPLAREA field points to a buffer list, which is a contiguous set of 16-byte control blocks called buffer-list entries. Each buffer-list entry points to a buffer that contains part of the data to be sent.

Figure 1. Buffer-list operation

The diagram shows buffer-list operation. When SEND OPTCD=BUFFLST is issued, RUs in a chain if LMPEO is used; otherwise, a single RU. If LMPEO is used to split data into RUs, the RU boundaries do not usually correspond to the buffer boundaries. There might be more or fewer RUs than the buffer list-entries.

Note: If LMPEO is used to split data into RUs, the RU boundaries do not usually correspond to the buffer boundaries. There may be more or fewer RUs than the buffer-list entries.

If the message to be sent using OPTCD=BUFFLST is not an FM data request or a set of FM data requests, SEND is rejected with (RTNCD,FDB2)=(X'14',X'77').

The RPL RECLEN field specifies the length (in bytes) of the buffer list. If RECLEN does not specify a nonzero multiple of 16, SEND is rejected with (RTNCD,FDB2)=(X'14',X'79'). Each buffer-list entry is mapped in the ISTBLENT DSECT described in Control block formats and DSECTs.

If OPTCD=(BUFFLST,LMPEO), then each buffer-list entry contains LMPEO control flags which govern whether the buffers associated with adjacent buffer-list entries should be grouped together as a single RU, or whether the data is eligible to be split into multiple RUs. See Buffer-list LMPEO states for a description of how LMPEO control flags are used to govern RU boundary settings. See also Table 1 for information about using combinations of the BUFFLST, LMPEO, and USERRH options. The format of the buffer list follows. A buffer list consists of one or more contiguous buffer list entries aligned on a fullword boundary.

Figure 2. Buffer-list entry format

The diagram shows buffer-list entry format. Each buffer-list entry contains 1-byte of flags, 3-bytes RH, 4-bytes reserved, 4-bytes Data Pointer, and 4-bytes Data Length.

Table 1. Buffer-list entry format
Word	Contents
1	Byte 0 Flag Byte. The first two flags are LMPEO control flags. They are used only if OPTCD=LMPEO is specified. Otherwise, they must be set to 0. ¹ Bit 0 The Begin RU flag (BLEBEGRU) in the ISTBLENT DSECT. If on, it indicates that the data in the associated buffer begins an RU. VTAM® does not split this data into multiple RUs. Bit 1 The End RU flag (BLEENDRU) in the ISTBLENT DSECT. If on, it indicates that the data in the associated buffer ends an RU. Bits 2–7 Reserved. Bits must be set to 0. Bytes 1-3 Request header. If either OPTCD=NUSERRH or this buffer-list entry does not contain a user RH (it is not the first entry of a buffer group), these bytes are reserved and must be set to 0.
2	Reserved. Must be set to 0.
3	Pointer to the beginning of the data buffer.
4	Length of the data in the buffer. If 0 is specified, the third word is ignored. However, the flags in byte 0 of the first word are processed and can change the LMPEO states. For RUs whose boundaries are specified by the application program (using the Begin RU and End RU flags), the total RU length must not be larger than 65 535 bytes. If the LMPEO option is used to split the data into RUs, a length greater than 65 535 may be specified.
Note: These flags are discussed in detail, see (Begin RU, End RU)=(1,1), (Begin RU, End RU)=(1,0), (Begin RU, End RU)=(0,1), and (Begin RU, End RU)=(0,0).