RPL—Generate a request parameter list at assembly time

Use the RPL macro to generate a request parameter list. Values for RPL macro subparameters can be specified as absolute numeric expressions, character strings, codes, and expressions that generate valid relocatable A-type address constants.

The format of the RPL macro is:

[label]

RPL

label: specifies 1 to 8 characters that provide a symbolic address for the generated request parameter list. You can use label in the request macros to give the address of the list. You can use label in the NXTRPL parameter of the RPL macro, when you are chaining request parameter lists, to indicate the next list.
ACB=address: specifies the address of the access method control block identifying the data set to which access is requested. If you used the ACB macro to generate the control block, you may specify the label of that macro for the address. If the ACB parameter is not coded, you must specify the address before issuing the request.
AM=VSAM: specifies the access method using the 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 your request is to process records 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 (of 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 that contains the search argument for direct retrieval, skip-sequential retrieval, and positioning. For a 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 or relative record number. 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. ARG is also used with WRTBFR and MRKBFR. Using WRTBFR and MRKBFR to share resources is described in z/OS DFSMS Using Data Sets.
ECB=address: specifies the address of an event control block (ECB) you may supply. VSAM indicates in the ECB whether a request is complete or not. For more details see the Event Control Block Fields section in z/OS DFSMSdfp Advanced Services. You can use the ECB to determine that an asynchronous request is complete before issuing a CHECK macro. (If you issue a CHECK before a request is complete, you give up control and must wait for completion.) The ECB 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 specified as a number from 1 through 255. It is required when the search argument is a generic key. 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 is ignored for z/OS UNIX files.
MSGAREA=address: specifies the address of an area you may, optionally, supply for VSAM to send you a message in case of a physical error. The format of a physical error message is given in Reason code (physical errors).
MSGLEN=abs expression: specifies the size, in bytes, of the message area indicated in the MSGAREA parameter. If MSGAREA is specified, MSGLEN is required. The minimum size of a message is 128 bytes. If you provide less than 128 bytes, no message is returned to your program.
NXTRPL=address: specifies the address of the next request parameter list in a chain. Omit this parameter from the macro that generates the 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. This parameter is not supported 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]
[,NWAITX|WAITX]
[,LOC|MVE]
[,CR|NRI]
[,RBA|XRBA]): specifies the subparameters governing 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 can be specified. Some requests do not require a 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.
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 will wait 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. This parameter is ignored for z/OS UNIX files.

Table 1. OPTCD Options
Option	Meaning
ADR	Addressed access to a key-sequenced or an entry-sequenced data set: RBAs are used as search arguments and sequential access is done by entry sequence. RLS does not support access to a KSDS.
CNV	Control interval access. Control interval access is not allowed for compressed data sets. RLS does not support CNV access. This parameter is ignored for z/OS UNIX files and if it is specified results in an error on a subsequent GET, PUT, or POINT.
KEY	Keyed access to a RRDS or KSDS. Keys or relative record numbers are used as search arguments and sequential access is done by key or relative record number sequence.
DIR	Direct access to a RRDS, KSDS, or ESDS.
SEQ	Sequential access to a RRDS, KSDS, or ESDS.
SKP	Skip sequential access.
ARD	User's argument determines the record to be located, retrieved, or stored.
LRD	Last record in the data set is to be located (POINT) or retrieved (GET direct); requires OPTCD=BWD.
FWD	Processing to proceed in a forward direction.
BWD	Processing to proceed in a backward direction; for keyed (KEY) or addressed (ADR) sequential (SEQ) or direct (DIR) requests; valid for POINT, GET, PUT, and ERASE operations; establish positioning by a POINT with OPTCD=BWD or by a GET direct with OPTCD=(NSP,BWD). When OPTCD=BWD is specified, subparameters KGE and GEN are ignored; subparameters KEQ and FKS are assumed. This parameter is ignored for z/OS UNIX files and if it is specified results in an error on a subsequent GET, PUT, or POINT.
ASY	Asynchronous access; VSAM returns to the processing program after scheduling a request so the program can do other processing while the request is being carried out.
SYN	Synchronous access; VSAM returns to the processing program after completing a request.
NSP	With OPTCD=DIR only, VSAM is to remember its position (for subsequent sequential access); that is, the position is not to be forgotten unless an ENDREQ macro is issued.
NUP	A data record being retrieved will not be updated or deleted; a record being stored is a new record; VSAM does not remember its position for direct requests into a work area.
UPD	A data record being retrieved may be updated or deleted; a record being udpated or deleted was previously retrieved with OPTCD=UPD; VSAM remembers its position for sequential and direct GET requests. A GET with update (UPD) must use the same RPL on the following PUT, ERASE or ENDREQ. When PUT, ERASE or ENDREQ is issued after a DIRUPD GET request, VSAM releases exclusive control. This parameter is not supported for z/OS UNIX files, and if it is specified, results in an error on a subsequent GET, PUT, or POINT.
KEQ	For GET with OPTCD=(KEY,DIR) or (KEY,SKP) and for POINT with OPTCD=KEY, the key (full or generic) that you provide for a search argument must equal the key or relative record number of a record. For a RRDS, KEQ is assumed except for POINT.
KGE	For the same cases as KEQ, if the key (full or generic) that you provide for a search argument does not equal that of a record, the request applies to the record that has the next higher key. If using POINT with a RRDS, KGE positions to the specified relative record number whether the slot is empty or not. If the relative record number is greater than the highest existing record, EOD is returned. A subsequent PUT will insert the record at this position.
FKS	A full key is provided as a search argument.
GEN	A generic key is provided as a search argument; give the length in the KEYLEN parameter. Generic keys are not supported for a variable-length RRDS.
NWAITX	Never take the UPAD or RLSWAIT exit.
WAITX	If OPTCD=SYN and the ACB's MACRF=LSR GSR and UPAD exit routing is specified, VSAM takes the UPAD exit at points when VSAM would normally issue a WAIT. For RLS, take the RLSWAIT exit which is active for this request.
LOC	For retrieval, VSAM leaves the data record in the I/O buffer for processing, unless the data set is compressed, in which case VSAM moves the record to a work area; not valid for PUT or ERASE; valid for GET with OPTCD=UPD. However, to update the record, you must build a new version of the record in a work area and modify the request parameter list OPTCD from LOC to MVE before issuing a PUT. For keyed-sequential retrieval, modifying key fields in the I/O buffer may cause incorrect results for subsequent GET requests until the I/O record is reread. Not valid for requests with spanned records. For z/OS UNIX files, LOC mode is supported but requires extra overhead to get storage in the user space and move the record.
MVE	For retrieval, VSAM moves the data record to a work area for processing, and for storage, VSAM moves it from the work area to the I/O buffer.
CR	For RLS GET and POINT only, CR (consistent read integrity) specifies that a shared lock is to be obtained and released as part of GET processing. CR specifies the application wants this request to be serialized with update/erase of this record by other applications or transactions. RLS obtains a share lock on the record. For RLS POINT, the shared lock remains held on successful completion of the POINT CR request. For RLS GET, after moving a copy of the record to the area pointed to by the RPL AREA parameter, the shared lock is released. If neither NRI, or CR is specified, the NRI/CR option is determined in the following order: RLSREAD specification on the ACB, if any, RLS JCL specification, if any, NRI is assumed. If there are multiple specifications in the RPL, CR takes precedence over NRI.
NRI	For RLS GET NUP and POINT only, NRI (no read integrity) specifies no locking on a GET(non-update). Since a lock is not obtained on the record, another application or transaction may currently hold an exclusive lock on the record. For a recoverable sphere, the returned record may be an uncommitted change which may be later backed out (this form of processing is sometimes referred to as "dirty read"). The opposite form of read processing is provided by the CR option where if another application/transaction holds an exclusive lock on the record, the reader waits for release of the exclusive lock and thus does NOT read an uncommitted change. If neither NRI or CR is specified, the NRI/CR option is determined in the following order: RLSREAD specification on the ACB, if any, RLS JCL specification, if any, NRI is assumed. If there are multiple specifications in the RPL, CR takes precedence over NRI. Inserting or updating a base cluster record can result in a concurrent NRI read to the record by an alternate index path, causing you to receive a false error (return code 8, reason code 144 in Table 1). RLS obtains a record lock and retries the request to be sure this is not a false condition.
RBA	For addressed accessing (OPTCD=ADR), the ARG field contains the address of a 4-byte RBA. RBA is the default. Extended addressing is not to be used for this request.
XRBA	For addressed accessing (OPTCD=ADR), the ARG field contains the address of an 8-byte RBA search argument. While you can specify RBA while using XRBA, the following considerations apply to accessing by RBA values: For a GET extended addressing request, you must specify an OPTCD which includes DIR, ADR, and XRBA. For a POINT extended addressingrequest, you must specify an OPTCD which includes ADR and XRBA. For a MRKBFR extended addressingrequest, you must specify an OPTCD which includes XRBA. The ARG field has the address of a 16 byte field containing the beginning and ending 8 byte RBAs of the range. For a SCHBFR extended addressingrequest, you must specify an OPTCD which includes XRBA. The ARG field has the address of a 16 byte field containing the beginning and ending 8 byte RBAs of the range. For a WRTBFR TYPE=DRBA extended addressingrequest, you must specify an OPTCD which includes XRBA. The ARG field has the address of an 8 byte field containing the 8 byte RBA to be located and written. If the data being referenced by RBA for an extended addressing KSDS is less than 4GB, you do not have to code this parameter. For data with RBA greater than 4GB the RPL must specify extended addressing (XRBA) and an 8-byte RBA is required. Also, to retrieve an 8-byte RBA using SHOWCB for the RPL, XRBA must be used instead. XRBA specification can be used for any data set (whether or not it is extended addressable).

RECLEN=abs expression: specifies the length, in bytes, of a data record being stored. This parameter is required for a PUT request.
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.
TRANSID=abs expression: specifies a number that relates modified buffers in a buffer pool. Used in shared resource applications and described in z/OS DFSMS Using Data Sets. This parameter is ignored for z/OS UNIX files.