PUTD stores data into a new or existing workmod item. If the item already exists, the data overlays existing data in the item, or is added at the end. If the item does not yet exist, a new one is created using the specified class and section names.
The syntax of the PUTD call is:
[symbol] | IEWBIND | FUNC=PUTD [,VERSION=version] |
If CURSOR= is omitted or CURSOR= -1, the buffered data is appended to the existing item. If INTENT=ACCESS, only B_IDR- and B_SYM-class items can be appended. CURSOR is valid only if AREA has been specified.
CLASS can contain any valid data class except B_IDRB, and SECTION should contain the name of the CSECT being created or updated. If INTENT=ACCESS, ESD and RLD data cannot be modified, nor TEXT extended.
CURSOR allows the caller to replace part of an existing item. It contains the offset, relative to the start of the item, where the buffered data is to be inserted. If CURSOR = is omitted or CURSOR contains -1, the buffered data is added to the end of the item. If CURSOR contains zero, the data is stored starting at the first byte or record.
The BUFFER must be in the standard format for the data class being stored. See Binder API buffer formats for additional information on standard buffer formats.
The binder moves the specified number of bytes or records from the buffer into workmod. Data is reformatted, if necessary, to conform to the internal format of the data in workmod.
PUTD operates in either INPUT or EDIT mode. INPUT mode is used when adding new sections to the workmod (INTENT must be BIND), and begins with the first PUTD call specifying NEWSECT=YES and continues until ENDDATA=YES is received. While in INPUT mode, there are certain restrictions on acceptable program management binder functions. The only functions allowed against a workmod in INPUT mode (those for which an input workmod token matches that of the workmod in INPUT mode) are PUTD with NEWSECT = YES, RESETW, or DELETEW. RESETW, DELETEW, and ENDD causes the operation to be prematurely terminated.
In INPUT mode, sections being added are held in a temporary workmod until ENDDATA=YES is received, when all of the new sections are validated as a unit and added to the target workmod. If any of the new sections fail validation, the entire group is discarded; otherwise, sections are added to the permanent workmod according to normal merge rules. If the new section already exists, it does not replace the existing one. If a deferred ALTERW request is pending, it is applied to all sections in the temporary workmod before merging them into the permanent workmod.
EDIT mode is used to update existing data items, or to add new items to an existing section. EDIT mode begins with the first PUTD call specifying NEWSECT=NO (the default) and continues until ENDDATA=YES is received. In EDIT mode, each PUTD call is completely processed before returning to the caller. Some validation is performed on ESD and RLD type data as it is received, to prevent consistency or integrity problems in the target module. This includes all of the same checks listed above for input mode, except the last.
If INTENT=ACCESS, certain restrictions apply. B_ESD and B_RLD items cannot be created or modified. TEXT items cannot be created or have their lengths extended.
If INTENT=BIND, SECTION must contain blanks or a user-assigned name consisting only of characters between X'41' and X'FE' (or X'0E' or X'0F'). A section name of all blanks should be used for private code or blank common. Special names, which always begin with a character invalid for user-assigned names, are created by the program management binder and can only be used by the caller when modifying an existing item. Such modification requires INTENT=ACCESS. Private code special names created by the program management binder can not be used in the PUTD call for section name with INTENT=BIND.
Only one private code or blank common section (not both) can be handled during one PUTD call series (a series being terminated by an end-of-data indication). Section names used in the SECTION field of the call parameter list must be the same as the ESD_NAME field in the supplied ESD input record.
The common binder API reason codes are shown in Table 1.
Return Code | Reason Code | Explanation |
---|---|---|
00 | 00000000 | Normal completion. Data inserted in workmod. |
04 | 83000801 | No data was passed. Module has not been changed. |
08 | 83000815 | Errors (such as invalid names) found in records contained in PUTD data buffers. Some data might have been dropped. |
12 | 83000101 | Buffer not large enough to contain the designated number of bytes or records. Request rejected. |
12 | 83000802 | NEWSECT was set to 'Yes', but workmod intent is ACCESS. Request rejected. |
12 | 83000803 | Workmod intent is ACCESS, but the target section does not exist. Request rejected. |
12 | 83000804 | PUTD cannot be used to modify ESD or RLD data (even in an existing section) in a workmod specified with INTENT=ACCESS. Request rejected. |
12 | 83000805 | PUTD cannot be used to extend the length of text data in a workmod specified with INTENT=ACCESS. Request rejected. |
12 | 83000806 | PUTD cannot be used to modify sections generated by the binder. Request rejected. |
12 | 83000807 | Incorrect parameter specification. The call attempted to modify an existing item with NEWSECT=YES, or it specified NEWSECT=NO while the binder was still in input mode. Request rejected. |
12 | 83000808 | PUTD cannot be used to modify the IDRB record. Request rejected. |
12 | 83000811 | One or more errors was detected in the module just completed. The CSECT(s) was not added to the workmod. |
12 | 83000814 | One or more errors were detected in the data records in the buffer just passed to the program management binder. The records were not added to workmod. |
PARMLIST | DS | 0F | |
DC | A(PUTD) | 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) | Standard data buffer | |
DC | A(CURSOR) | Starting position | |
To append data, set cursor value to (-1). | |||
DC | A(COUNT) | Data count | |
DC | A(NEWSECT) | New section flag | |
DC | A(ENDDATA+X'80000000') | End-of-data flag | |
PUTD | DC | H'65' | PUTD function code |
DC | H'version' | Interface version number | |
NEWSECT | DC | CL1'Y' | New
section flag 'Y' = Yes |
ENDDATA | DC | CL1'Y' | End-of-data flag 'Y' = Yes |