See Code disclaimer information for information pertaining to code examples.
This example shows how to set key values for a keyed interface.
For information and the examples, see the following:
The interface for the Add Exit Program API is a keyed interface. One of the parameters for the Add Exit Program API is the exit program attributes parameter. The exit program attributes are provided to the API by means of a variable-length record. Typically, APIs that use a variable-length record interface use either a 3- or 4-field record. The Add Exit Program API makes use of a 4-field variable-length record (4). The exit program attributes parameter for the API is defined as follows:
(3)
| Type | Field |
|---|---|
| BINARY(4) | Number of variable-length records |
(4)
| Type | Field |
|---|---|
| BINARY(4) | Length of variable-length record |
| BINARY(4) | Exit program attribute key |
| BINARY(4) | Length of data |
| CHAR(*) | Data |
The number of variable-length records field (3) is the first 4 bytes, and this field tells the API how many variable-length records have been specified. The fields defined in (4) are repeated (contiguously) immediately following the number of variable-length records for each record that is sent to the API. The API gets to each variable-length record by using the length of variable-length record field to get to the next record, up to and including the number of records specified.
The variable-length record structures are defined in the qus.h header file (this C-language header file is included by the qusrgfa1.h header file). The 4-field variable-length record is defined as:
typedef _Packed struct Qus_Vlen_Rec_4 {
int Length_Vlen_Record;
int Control_Key;
int Length_Data;
/*char Data[];*/ /* Varying length field */
} Qus_Vlen_Rec_4_t;
Because the data field is a varying-length field, it needs to be defined in a new structure.
The Add Exit Program API has several exit program attributes that can be set. The following table shows the valid exit program attribute keys for the key field area of the variable-length record.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(27) | Qualified message file name and message identifier for exit program description |
| 2 | CHAR(50) | Exit program text description |
| 3 | BINARY(4) | Exit program data CCSID |
| 4 | CHAR(1) | Replace |
This example specifies only two attribute keys (replace_rec and CCSID_rec fields) and lets the remaining attribute keys be set by the API to the default value. When working with variable-length structures, each variable-length record must start on a 4-byte boundary alignment. (The 4-byte boundary alignment requirement is only true for the registration facility APIs, not all keyed APIs.) The following new structure becomes the exit program attributes parameter on the call to the Add Exit Program API:
typedef struct {
int num_rec;
Qus_Vlen_Rec_4_t replace_rec;
char replace;
char Reserved[3];
Qus_Vlen_Rec_4_t CCSID_rec;
int CCSID;
} addep_attributes;
The num_rec field is set to the value of 2 because the example specifies two variable-length records. The replace_rec field contains the length of the variable-length record (value of 16), the key (value of 4), and the length of the data (value of 1). The replace field contains the data for the replace key. The Reserved field reserves 3 bytes to force the next record to start on a 4-byte boundary alignment. The 3 bytes that are reserved are counted as part of the length for the replace variable-length record. The next record then follows the first record.
