GETE returns data from ESD items. GETE must be used on a bound workmod. Four optional parameters allow you to specify selection criteria for the ESD items to be returned: section name, ESD record type, offset in the section or module, and symbol name. Only ESD records that meet all of the selection criteria will be returned. Multiple selection criteria can be specified to retrieve exactly the records you need.
The syntax of the GETE call is:
| [symbol] | IEWBIND | FUNC=GETE [,VERSION=version] |
The default value is all sections. If this parameter is specified, only the indicated section is searched.
If neither OFFSET nor SYMBOL is provided, processing begins at the start of the item.
The CURSOR value identifies an index into the requested ESD data beginning with 0 for the first ESD. The ESD buffer formats defined in Binder API buffer formats contain an entry length field in their headers. Multiplying the cursor value by the entry length provides a byte offset into the data. CURSOR is an input and output parameter. On input to the service, the cursor specifies the first record to return. On exit from the service, it is updated to the index of the next sequential ESD if not all data has yet been retrieved.
The binder will typically return multiple entries in a single call, depending on the size of the buffer. Data is reformatted, if necessary, to conform to the version identified in the caller's buffer. The COUNT parameter is set to the number of records actually returned in the buffer.
The ESD buffer formats defined in Binder API buffer formats contain a record length field in their headers giving the length of each ESD record. This provides a way for the caller to index through the returned records or to access a specific record in the returned data buffer.
In some cases where OFFSET is specified and the parameter list is version 6 or less, return code 0 and reason code 0 will be returned on an end-of-data condition. The version 7 API call will always return return code 4 and reason code 83000800 on an end-of-data condition, while the COUNT may be non-zero indicating that data was returned.
The common binder API reason codes are shown in Table 1.
| Return Code | Reason Code | Explanation |
|---|---|---|
| 00 | 00000000 | Normal completion. |
| 04 | 83000705 | The specified symbol could not be located in the workmod. No data is returned in the buffer. |
| 04 | 83000800 | An end-of-data condition was detected. Some data might have been returned in buffer. There is no message associated with this condition. |
| 04 | 83000801 | The requested item was not found in the workmod, or was empty, or no records met the specified criteria. No data returned. |
| 04 | 83000812 | The specified offset was negative or beyond the end of the designated item or module. No data is returned in the buffer. |
| 12 | 83000101 | OFFSET and SYMBOL have both been specified. Request rejected. |
| 12 | 83000102 | Workmod is unbound. GETE request rejected. |
If your program does not use the IEWBIND macro, place the address of the GETE parameter list in general purpose register 1.
| PARMLIST | DS | 0F | |
| DC | A(GETE) | Function code | |
| DC | A(RETCODE) | Return code | |
| DC | A(RSNCODE) | Reason code | |
| DC | A(WORKMOD) | Workmod token | |
| DC | A(SECTION) | Section name | |
| DC | A(RECTYPE) | ESD record type(s) | |
| DC | A(OFFSET) | Offset in module or section. If not a selection criterion, set to -1. | |
| DC | A(SYMBOL) | Symbol name | |
| DC | A(BUFFER) | Data buffer | |
| DC | A(CURSOR) | Starting position | |
| DC | A(COUNT) | Data count | |
| DC | A(CLASS) | Text class | |
| GETE | DC | H'62' | GETE function code |
| DC | H'version' | Interface version number | |
| RECTYPE | DC | H'7',CL7'(SD,CM)' | Sample varying string |