|
The format of the GENCB macro used to generate a request parameter
list follows.
The format of
the GENCB macro used to generate a request parameter list.Label |
Operand |
Parameters |
---|
[label]
|
GENCB
|
BLK=RPL [,ACB=address] [,AM=VSAM] [,AREA=address] [,AREALEN=abs expression] [,ARG=address] [,COPIES=abs expression] [,LUWID=address][,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|CRE] [,NRI|CR|CRE [,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 that 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 z/OS MVS System Codes describes).
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 UNIX files.
- LUWID=luwid
- For &rls only, logical unit of work identifier.
The LUWID together with the SUBSYSNM (specified when the ACB is OPENed)
forms the ownership for record locks. CICS® uses
the LUWID parameter to pass a CICS transaction
identifier to RLS. A non-CICS application does not specify the LUWID
parameter. VSAM assigns a single LUWID for all requests issued by
a non-CICS application.
- 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 z/OS DFSMS Macro Instructions for Data Sets.
- 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.
- 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 topic Understanding 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 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])
- [,UPD[,KL|NOKL]]
- [,CR|CRE|NRI]
- [,CR|CRE|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 VSAM RLS or DFSMStvs only, specifies the time in seconds
that your program is to wait to obtain a lock on a VSAM record when
a lock on the record is already held by another program.
A
nonzero value for TIMEOUT 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 UNIX files.
For RLS or DFSMStvs, this parameter is ignored. LUWID
replaces this function.
- 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.
|