|
The format of the GENCB macro used to generate a request parameter
list is:
[label]
|
GENCB
|
BLK=RPL [,ACB=address] [,AM=VSAM] [,AREA=address] [,AREALEN=abs expression] [,ARG=address] [,COPIES=abs expression] [,TIMEOUT=number] [,ECB=address] [,KEYLEN=abs expression] [,LENGTH=abs expression] [,LOC=BELOW|ANY] [,MSGAREA=address] [,MSGLEN=abs expression] [,NXTRPL=address] [,OPTCD=([ADR|CNV|KEY] [,DIR|SEQ|SKP] [,ARD|LRD] [,FWD|BWD] [,ASY|SYN] [,NSP|NUP|UPD] [,KEQ|KGE] [,FKS|GEN] [,LOC|MVE] [,NRI|CR] [,RBA|XRBA])] [,RECLEN=abs expression] [,TRANSID=abs expression] [,WAREA=address]
|
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.
|