API buffer layouts

There are two buffer types, send buffers and receive buffers. All buffers are in EBCDIC format and must be in contiguous storage. The buffers can contain these sections:

APP: Fixed section
APPFLD: Field section
APPDAT: Data section
APPOBJ: Object section
APPSEL: Selection section
APPVAL: Selection value section

The sections that a send buffer should contain depends on the request that you make. Contents of a Send Buffer shows the sections that you can include for each request:

Table 1. Contents of a Send Buffer
	Buffer sections¹
Request	APP	APPOBJ	APPSEL	APPVAL	APPFLD	APPDAT
GET	Required	Optional	Optional	Optional	Optional	Not used
PUT	Required	Required	Required	Required	Required	Required
DEL	Required	Required	Required	Required	Not used	Not used
CREATE	Required	Required	Required	Required	Required²	Required²

Note:

APP must be the first section in a buffer. There is no restriction on the order of other section types.
Not used for BACKUP_EVENT object.

Example of a send buffer layout for a GET request is an example of the layout of a send buffer for a GET request. The arrows show the buffer parts that each section type points to. APP and APPOBJ point to related sections using triplet fields, which specify the offset, the length, and the number of the section type. APPSEL uses offset and length fields to point to an APPVAL section. All offsets are relative to the start of the buffer (offset 0).

Figure showing an example of the layout of a send buffer for a GET request. The arrows show the buffer parts that each section type points to. APP and APPOBJ point to related sections using triplet fields, which specify the offset, the length, and the number of the section type. APPSEL uses offset and length fields to point to an APPVAL section. All offsets are relative to the start of the buffer (offset 0). — Figure 1. Example of a send buffer layout for a GET request

When a receive buffer is returned from HCL Workload Automation for Z, the buffer contains the entire send buffer. Some fields are updated by HCL Workload Automation for Z, for example, return codes and reason codes. For a GET request, data sections are also added if the requested information was found. One data section is added for each object instance found, and the data section triplet in APPOBJ is updated to point to the data.

If an error occurs during verification of the send buffer, HCL Workload Automation for Z returns a receive buffer that contains the whole of the send buffer unaltered, plus an additional APP section at the start of the buffer. This additional APP section is updated to indicate the error type.

Each buffer section is described here in more detail.