GENCB—Generate a request parameter list at execution time

The format of the GENCB macro used to generate a request parameter list is:

[label]

GENCB

The subparameters of the GENCB macro can be expressed as absolute numeric expressions, as character strings, as codes, as expressions that generate valid relocatable A-type address constants, in register notation, as S-type address constants, and as indirect S-type address constants. Subparameters with GENCB, MODCB, SHOWCB, and TESTCB, further defines these operand expressions.

The parameters of the GENCB macro to generate a request parameter list are optional sometimes, but required in others. It is not necessary to omit parameters that are not required for a request; they are ignored. Thus, if you switch from direct to sequential retrieval with a request parameter list, you do not have to zero out the address of the field containing the search argument (ARG=address).

label

specifies 1 to 8 characters that provide a symbolic address for the GENCB macro. For addressing lists generated by GENCB, see the COPIES parameter.

BLK=RPL

specifies you are generating a request parameter list.

ACB=address

specifies the address of the access method control block that identifies the data set to which access will be requested. If you omit this parameter, you must issue MODCB to specify the address of the access method control block before you issue a request. MODCB is described in MODCB—Modify an access method control block.

AM=VSAM

specifies that the access method using this control block is VSAM.

AREA=address

specifies the address of a work area to and from which VSAM moves a data record if you request it to do so (with the RPL parameter OPTCD=MVE). If you request that records be processed in the I/O buffer (OPTCD=LOC), VSAM puts into this work area the address of a data record within the I/O buffer.

AREALEN=abs expression

specifies the length, in bytes, of the work area whose address is specified by the AREA parameter. Its minimum for OPTCD=MVE is the size of a data record (or the largest data record, for a data set with records of variable length). For OPTCD=LOC, the area should be 4 bytes to contain the address of a data record within the I/O buffer.

ARG=address

specifies the address of a field containing the search argument for direct retrieval, skip-sequential retrieval, and positioning. For a fixed-length or variable-length RRDS, the ARG field must be 4 bytes long. For direct or skip-sequential processing, this field contains your search argument, a relative record number. For sequential processing (OPTCD=(KEY,SEQ)), the 4 bytes are required for VSAM to return the feedback RRN. For keyed access (OPTCD=KEY), the search argument is a full or generic key. For addressed access (OPTCD=ADR), the search argument is an RBA. If you specify a generic key (OPTCD=GEN), you must also specify in the KEYLEN parameter how many of the bytes of the full key you are using for the generic key.

COPIES=abs expression

specifies the number of copies of the request parameter list to generate. GENCB generates as many copies as you specify (default is 1) when your program is executed.

The copies of a request parameter list can be used to:

Chain lists together to gain access to many records with one request
Define many requests to gain access to many parts of a data set concurrently.

All copies generated are identical; you must use MODCB to tailor them to specific requests. MODCB is described in MODCB—Modify an access method control block.

ECB=address

specifies the address of an event control block (ECB) that you may supply. VSAM indicates in the ECB whether a request is complete or not (using standard completion codes, which are described in z/OS MVS System Codes). You can use the ECB to determine that an asynchronous request is complete before issuing a CHECK macro. This parameter is always optional.

KEYLEN=abs expression

specifies the length, in bytes, of the generic key (OPTCD=GEN) you are using for a search argument (given in the field addressed by the ARG parameter). This parameter is required with a search argument that is a generic key. The number can be 1 through 255. For full-key searches, VSAM knows the key length, which is taken from the catalog definition of the data set when you open the data set. This parameter has no effect for z/OS UNIX files.

LENGTH=abs expression

specifies the length, in bytes, of the area, if any, that you are supplying for VSAM to generate the request parameter lists. (See the WAREA parameter.) The LENGTH value cannot exceed 65535 (X'FFFF').

You can find out how long a request parameter list is with the SHOWCB macro, described in SHOWCB—Display fields of a request parameter list.

LOC=BELOW|ANY

BELOW: specifies that storage for the RPL be obtained from virtual storage below 16 megabytes.
ANY: specifies that storage be obtained from virtual storage above 16 megabytes if possible.

The LOC parameter is different from other GENCB parameters. If you code it on the list form, the execute form always overrides it. If you want LOC=ANY when using the list and execute forms, you must code it on the execute form. For more information, refer to GENCB—List form and GENCB—Execute form.

MSGAREA=address

specifies the address of an area you are supplying for VSAM to send you a message if a physical error occurs. The format of a physical error message is given under Reason code (physical errors) in the chapter VSAM macro return and reason codes.

MSGLEN=abs expression

specifies the size, in bytes, of the message area indicated in the MSGAREA parameter. The size of a message is 128 bytes. If you provide less than 128 bytes, no message is returned to your program. This parameter is required when MSGAREA is coded.

NXTRPL=address

specifies the address of the next request parameter list in a chain. Omit this parameter from the macro that generates the only or last list in the chain. When you issue a request defined by a chain of request parameter lists, indicate in the request macro the address of the first parameter list in the chain. A single request macro can be defined by multiple request parameter lists. For example, a GET can cause VSAM to retrieve two or more records. This parameter has no effect for z/OS UNIX files, and if it is specified with a non-zero value, results in an error on a subsequent GET, PUT, or POINT.

OPTCD=([ADR|CNV|KEY]

[,DIR|SEQ|SKP]

[,ARD|LRD]

[,FWD|BWD]

[,ASY|SYN]

[,NSP|NUP|UPD]

[,KEQ|KGE]

[,FKS|GEN]

[,LOC|MVE])

[,CR|NRI]

[,RBA|XRBA])

specifies the subparameters that govern the request defined by the request parameter list. Each group of subparameters has a default; subparameters are shown in Table 1 with defaults underlined. Only one subparameter from each group is effective for a request. Some requests do not require an subparameter from all of the groups to be specified. The groups that are not required are ignored. Thus, you can use the same request parameter list for a combination of requests (GET, PUT, POINT, for example) without zeroing out the inapplicable subparameters each time you go from one request to another.

RECLEN=abs expression

specifies the length, in bytes, of a data record being stored. If the records you are storing are all the same length, you do not need to change RECLEN after you set it. This parameter is required for PUT requests. For GET requests, VSAM puts the length of the record retrieved in this field in the request parameter list. It will be there if you update and store the record.

TIMEOUT=number

For RLS only, specifies the time in seconds that your program is willing to wait to obtain a lock on a VSAM record when a lock on the record is already held by another program.

A non-zero value for TIMEOUT (or if TIMEOUT is not specified) specifies the time (in seconds) this program waits for the other program(s) to release the lock.

A value of zero specifies TIMEOUT processing is NOT to be performed by VSAM for this request. That is, if the record lock required by the request is held by another program, the program waits until the other program releases the lock regardless of how long that might be.

TRANSID=abs expression

specifies a number that relates modified buffers in a buffer pool. Use in shared resource applications and a description are in z/OS DFSMS Using Data Sets. This parameter has no effect for z/OS UNIX files.

WAREA=address

specifies the address of an area in which the request parameter lists are generated.

If you did not specify an area in which the request parameter list is to be generated, VSAM obtains virtual storage space for the area (as specified by the LOC=keyword). Subpool 0 will be requested under the user's key and state. Users executing in key 0 and supervisor state will actually be assigned subpool 252. VSAM returns the address of the area in which the request parameter lists are generated in register 1, and the length of the area in register 0. You can find the length of each list by dividing the length of the area by the number of copies. You can then calculate the address of each list by using the length of each list as an offset.

If you are generating control blocks by issuing several GENCBs, specifying an area (WAREA and LENGTH parameters) for them allows you to address all of them with one base register and to avoid repetitive requests for virtual storage.