GENCB—Generate an access method control block at execution time

The format of the GENCB macro used to generate an access method control block is:

[label]

GENCB

BLK=ACB
[,AM=VSAM]
[,BSTRNO=abs expression]
[,BUFND=abs expression]
[,BUFNI=abs expression]
[,BUFSP=abs expression]
[,COPIES=abs expression]
[,DDNAME=character string]
[,EXLST= address]
[,LENGTH=abs expression]
[,LOC=BELOW|ANY]
[,MACRF=([ADR][,CNV] [,KEY]
  [,CFX|NFX]
  [,DDN|DSN]
  [,DFR|NDF]
  [,DIR][,SEQ][,SKP]
  [,ICI|NCI]
  [,IN][,OUT]
  [,LEW|NLW]
  [,NIS|SIS]
  [,NRM|AIX]
  [,NRS|RST]
  [,NSR|LSR|GSR|RLS]
  [,NUB|UBF])]
[,MAREA=address]
[,MLEN=abs expression]
[,PASSWD=address]
[,RMODE31={ALL|BUFF|CB|NONE}]
[,SHRPOOL={0|abs expression}]
[,STRNO=abs expression]
[,RLSREAD={NRI|CR|NORD}]
[,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.

label

specifies 1 to 8 characters that provide a symbolic address for the GENCB macro.

BLK=ACB

specifies that you are generating an access method control block.

AM=VSAM

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

BSTRNO=abs expression

specifies the number of strings initially allocated for access to the base cluster of a path. BSTRNO must be a number between 0 and 255. The default is STRNO. BSTRNO is ignored if the object being opened is not a path. If the number specified for BSTRNO is insufficient, VSAM dynamically extends the number of strings as needed for the access to the base cluster. BSTRNO can also influence performance. The VSAM control blocks for the set of strings specified by BSTRNO are allocated on contiguous virtual storage, whereas this is not guaranteed for the strings allocated by dynamic extension.

For RLS, BSTRNO is ignored. This parameter has no effect for z/OS UNIX files.

BUFND=abs expression

specifies the number of I/O buffers VSAM uses for transmitting data between virtual and auxiliary storage. A buffer is the size of a control interval in the data component. BUFND must be a number between 0 and 32767. The minimum number you may specify is 1 plus the number specified for STRNO (if you omit STRNO, BUFND must be at least 2, because the default for STRNO is 1). The number can be supplied through the JCL DD AMP parameter and through the macro. The default is the minimum number required. A larger number for BUFND can improve the performance of sequential access.

For RLS, BUFND is ignored. This parameter has no effect for z/OS UNIX files.

BUFNI=abs expression

specifies the number of I/O buffers VSAM uses for transmitting index entries between virtual and auxiliary storage for keyed access. A buffer is the size of a control interval in the index. BUFNI must be a number between 0 and 32767. The minimum number is the number specified for STRNO (if you omit STRNO, BUFNI must be at least 1, because the default for STRNO is 1). You can supply the number through the JCL DD AMP parameter and through the macro. The default is the minimum number required. A larger number for BUFNI can improve the performance of keyed-direct retrieval.

For RLS, BUFNI is ignored. This parameter has no effect for z/OS UNIX files.

BUFSP=abs expression

specifies the maximum number of bytes of virtual storage used for the data and index I/O buffers. VSAM gets the storage in your program's address space. If you specify less than the amount of space specified in the BUFFERSPACE parameter of the DEFINE command when the data set was defined, VSAM overrides your BUFSP specification upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by definition, is the least amount of virtual storage that is ever provided for I/O buffers.) You can supply BUFSP through the JCL DD AMP parameter and through the macro. If you do not specify BUFSP in either place, the amount of storage used for buffer allocation is the largest of:

The amount specified in the catalog (BUFFERSPACE),
The amount determined from BUFND and BUFNI, or
The minimum storage required to process the data set with its specified processing options.

If BUFSP is specified and the amount is smaller than the minimum amount of storage required to process the data set, VSAM cannot open the data set.

A valid BUFSP amount takes precedence over the amount called for by BUFND and BUFNI. If the BUFSP amount is greater than the amount called for by BUFND and BUFNI, the extra space is allocated as follows:

When MACRF indicates direct access only, additional index buffers are allocated.
When MACRF indicates sequential access, one additional index buffer and as many data buffers as possible are allocated.

If the BUFSP amount is less than the amount called for by BUFND and BUFNI, the number of data and index buffers is decreased as follows:

When MACRF indicates direct access only, the number of data buffers is decreased to not less than the minimum number. Then, if required, the number of index buffers is decreased until the amount called for by BUFND and BUFNI complies with the BUFSP amount.
When MACRF indicates sequential access, the number of index buffers is decreased to not less than 1 more than the minimum number. Then, if required, the number of data buffers is decreased to not less than the minimum number. If still required, 1 more is subtracted from the number of index buffers.
Neither the number of data buffers nor the number of index buffers is decreased to less than the minimum number.

If the index does not exist or is not being opened, only BUFND, and not BUFNI, enters into these calculations.

For RLS, BUFSP is ignored. This parameter has no effect for z/OS UNIX files.

COPIES=abs expression

specifies the number of copies of the access method control block VSAM generates. All the copies are identical. Use MODCB to tailor the individual copies for particular data sets and processing. MODCB is described in MODCB—Modify an access method control block.

DDNAME=character string

specifies 1 to 8 characters that identify the data set you want to process by specifying the JCL DD statement for the data set. You may omit DDNAME and provide it through the MODCB macro before opening the data set. MODCB is described in MODCB—Modify an access method control block.

EXLST=address

specifies the address of a list of addresses of exit routines you are providing. The list is established by the EXLST or GENCB macro. If you use the EXLST macro, you can specify its label here as the address of the exit list. If you use GENCB, you can specify the address returned by GENCB in register 1. Omitting this parameter indicates that you have no exit routines. VSAM user exit routines are described in z/OS DFSMS Using Data Sets.

LENGTH=abs expression

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

LOC={BELOW|ANY}

BELOW: specifies that VSAM is to construct an ACB in an area of virtual storage below 16 megabytes at execution time. This is the default.
ANY: specifies that VSAM is to construct an ACB in an area of virtual storage above 16 megabytes, if possible, at execution time.

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.

MACRF=([ADR][,CNV][,KEY]

[,CFX|NFX]

[,DDN|DSN]

[,DFR|NDF]

[,DIR][,SEQ][,SKP]

[,ICI|NCI]

[,IN][,OUT]

[,LEW|NLW]

[,NIS|SIS]

[,NRM|AIX]

[,NRS|RST]

[,NSR|LSR|GSR|RLS]

[,NUB|UBF])

specifies the kinds of processing you will do with the data set. The subparameters must be significant for the data set. For example, if you specify keyed access for an entry-sequenced data set, you cannot open the data set. You must specify all the types of access you are going to use, whether you use them concurrently or by switching from one to the other. The subparameters are shown in Table 1. They are arranged in groups, and each group has a default value (shown by underlining). You may specify subparameters in any order. You may specify both ADR and KEY to process a key-sequenced data set. You may specify both DIR and SEQ; with keyed access, you may specify SKP as well. If you specify OUT and want merely to retrieve some records and also update, delete, or insert others, you need not also specify IN.

MAREA=address

specifies the address of an optional OPEN/CLOSE or TYPE=T option (CLOSE macro) message area. See OPEN/CLOSE message area for multiple reason or attention messages.

MAREA is ignored for RLS processing.

MLEN=abs expression

specifies the length of an optional OPEN/CLOSE or TYPE=T option (CLOSE macro) message area.

MLEN is ignored for RLS processing.

PASSWD=address

specifies the address of a field that contains the highest-level password required for the types of access indicated by the MACRF parameter. The first byte of the field contains the length (in binary) of the password (maximum of 8 bytes). Zero indicates that no password is supplied. If the data set is password protected and you do not supply a required password in the access method control block, VSAM may give the console operator the opportunity to supply it when you open the data set. This parameter has no effect for z/OS UNIX files.

RLSREAD={NRI|CR|NORD}

RLSREAD (for RLS), specifies the read integrity options that apply to GET requests issued against this ACB. This parameter overrides the read integrity options specified in the RLS JCL parameter. Read integrity options can also be specified on the GET request, when they override the RLSREAD specification.

NRI: specifies no read integrity.
CR: specifies consistent read integrity.
NORD: species the read integrity option used is determined either by the RLS JCL specification or by options specified on the GET request.

For non-RLS, this parameter is ignored.

RMODE31={ALL|BUFF|CB|NONE}

specifies where VSAM OPEN is to obtain virtual storage (above or below 16 megabytes) for control blocks and I/O buffers.

The values specified by the RMODE31 parameter only have an effect on VSAM at the setting just before an OPEN is issued. At all other times, changing these values has no effect on the residency of the control blocks and I/O buffers.

The virtual storage location of the ACB is independent of the RMODE31 parameter. An ACB may reside either above or below 16 megabytes.

RMODE31 is ignored for RLS processing.

ALL: specifies both VSAM control blocks and I/O buffers are obtained above 16 megabytes.
BUFF: specifies only VSAM I/O buffers are obtained above 16 megabytes.
CB: specifies only VSAM control blocks are obtained above 16 megabytes.
NONE: specifies both VSAM control blocks and I/O buffers are obtained below 16 megabytes. This is the default.

SHRPOOL={abs expression|0}

specifies the identification number of the resource pool used for LSR processing. SHRPOOL must be a number between 0 and 255. The default is SHRPOOL=0. For RLS, SHRPOOL is ignored. This parameter has no effect for z/OS UNIX files.

STRNO=abs expression

specifies the number of requests requiring concurrent data set positioning VSAM is prepared to handle. A request is defined by a given request parameter list or chain of request parameter lists. STRNO must be a number between 1 and 255. See RPL—Generate a request parameter list at assembly time and GENCB—Generate a request parameter list at execution time for information on request parameter lists. For RLS, STRNO is ignored and strings are dynamically acquired up to a limit of 1024. STRNO > 1 is not supported for z/OS UNIX files and, if specified with a value greater than 1, results in an open failure.

WAREA=address

specifies the address of an area in which to generate the access method control blocks.

The area must begin on a fullword boundary.

This parameter is paired with the LENGTH parameter. You must supply the LENGTH parameter if you specify an area address.

If you do not specify an area in which the access method control block 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 containing the control blocks in register 1 and the length of the area in register 0. You can determine the length of each control block by dividing the length of the area by the number of copies. The address of each control block can then be calculated by this offset from the address in register 1. You can find the length of an access method control block with the SHOWCB macro.

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.