GETD returns data from items in a workmod. The values of the CLASS and SECTION parameters determine which item is returned. If SECTION is omitted, all sections are returned as a single unit. This service can only be performed on a bound workmod.
The syntax of the GETD call is:
[symbol] | IEWBIND | FUNC=GETD [,VERSION=version] |
The CURSOR value identifies an index into the requested data beginning with 0 for the first data item. Each of the buffer formats defined in Binder API buffer formatscontains an entry length field in its header. Multiplying the cursor value by the entry length provides a byte offset into the data. Note that CUI, LIB, PMAR, and text data is always treated as having entry length 1. The CURSOR value is both an input and output parameter. On input to the service, the cursor specifies the first item to return. On exit from the service, it is updated to an appropriate value for continued sequential retrieval if not all data has yet been retrieved. For text data, this may or may not be the next byte after the last one returned, because pad bytes between sections and uninitialized data areas within sections may have been skipped. Any data skipped should be treated by the calling application as containing the fill character (normally X'00').
On the next GETD request, the binder begins processing where the last request left off.
If you interrupt a series of successive GETD calls, you should reset the value of the cursor before continuing. Otherwise, the cursor value might be invalid and the results of a GETD request are unpredictable.
If a section name is not passed on a GETD API invocation for a text class and the target is an overlay module, the cursor is interpreted as an offset into the module and laid out sequentially in segment order, using the alignment as specified in the object modules.
The common binder API reason codes are shown in Table 1.
Return Code | Reason Code | Explanation |
---|---|---|
00 | 00000000 | Normal completion. |
04 | 83000800 | Normal completion. Some data might have been returned in the buffer, and an end-of-data condition was encountered. There is no message associated with this condition. |
04 | 83000801 | The requested item did not exist or is empty. No data has been returned. |
08 | 83000750 | The buffer is not large enough for one record. No data is returned. |
08 | 83000813 | The buffer version is not compatible with the module content. No data is returned. |
08 | 83002349 | Not all adcons were successfully relocated. This condition could occur because relocation addresses for all the segments were not passed, or because the adcon length was insufficient to contain the address. |
12 | 83002379 | Binder encountered a bad cursor for class B_PARTINIT and processing has been stopped. |
12 | 83000102 | Workmod was in an unbound state. GETD request could not be processed. |
12 | 83002375 | The class was not a text class. |
If your program does not use the IEWBIND macro, place the address of the GETD parameter list in general purpose register 1.
PARMLIST | DS | 0F | |
DC | A(GETD) | Function code | |
DC | A(RETCODE) | Return code | |
DC | A(RSNCODE) | Reason code | |
DC | A(WORKMOD) | Workmod token | |
DC | A(CLASS) | Class name | |
DC | A(SECTION) | Section name | |
DC | A(BUFFER) | Data buffer | |
DC | A(CURSOR) | Starting position | |
DC | A(COUNT+X'80000000') | Data count and end-of-list indicator | |
DC | A(RELOC) | Relocation address | |
GETD | DC | H'61' | GETD function code |
DC | H'version' | Interface version number | |