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 sections1
RequestAPP APPOBJAPPSELAPPVAL APPFLDAPPDAT
GETRequired OptionalOptionalOptional OptionalNot used
PUT RequiredRequiredRequired RequiredRequiredRequired
DELRequiredRequired RequiredRequiredNot used Not used
CREATERequired RequiredRequiredRequired Required2Required2
Note:
  1. APP must be the first section in a buffer. There is no restriction on the order of other section types.
  2. 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 1. Example of a send buffer layout for a GET request

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).

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.