ACB—Generate an access method control block at assembly time

Use the ACB macro to generate an access method control block at assembly time.

The format of the ACB macro is:

Values for ACB macro subparameters can be specified as absolute numeric expressions, character strings, codes, and expressions that generate valid relocatable A-type address constants.
label
specifies 1 to 8 characters that provide a symbolic address for the access method control block that is assembled. If you omit the DDNAME parameter, label serves as the ddname.
AM=VSAM
specifies that the access method using this control block is VSAM.
BSTRNO=abs expression
specifies the number of strings that are 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 that is specified for BSTRNO is insufficient, VSAM dynamically extends the number of strings as needed for access to the base cluster.

BSTRNO can influence performance. The VSAM control blocks for the set of strings that is specified by BSTRNO are allocated in contiguous virtual storage. This is not guaranteed for the strings allocated by dynamic extension.

This parameter is only applicable to MACRF=NSR.

This parameter has no effect for z/OS UNIX files. This is the case when an application program uses the VSAM interface to access an z/OS UNIX file.

BUFND=abs expression
specifies the number of I/O buffers that VSAM is to use 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 that you can specify is 1 plus the number that is 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 that is required. The minimum buffer specification does not provide optimum sequential processing performance. Generally, the more data buffers that are specified, the better the performance.

Additional data buffers benefit direct inserts or updates during control area splits and benefit spanned record accessing. See z/OS DFSMS Using Data Sets for more information on optimizing performance and system-managed buffering.

This parameter is applicable only to MACRF=NSR; it is ignored when MACRF=RLS is specified.

This parameter has no effect for z/OS UNIX files.

BUFNI=abs expression
specifies the number of I/O buffers that VSAM is to use for transmitting the contents of 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 that is 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 that is required.

Additional index buffers improve performance by providing for the residency of some or all of the high-level index, thereby minimizing the number of high-level index records retrieved from DASD for key-direct processing. For more information on optimizing performance, see z/OS DFSMS Using Data Sets.

The default is the minimum number that is required.

This parameter is only applicable to MACRF=NSR.

This parameter has no effect for z/OS UNIX files.

BUFSP=abs expression
specifies the maximum number of bytes of virtual storage to be 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 that was specified in the BUFFERSPACE parameter of the DEFINE command when the data set was defined, VSAM overrides your BUFSP specification upward to the value that is specified in BUFFERSPACE. (BUFFERSPACE, by definition, is the least amount of virtual storage that is ever provided for I/O buffers.) However, if BUFSP is specified and the amount specified is much too small — smaller than the minimum amount of buffer storage required to process the data set — VSAM cannot open the data set. The minimum amount is described under BUFND and BUFNI, above.
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 that is used for buffer allocation is the largest of the following amounts:
  • Amount that is specified in the catalog (BUFFERSPACE)
  • Amount that is determined from BUFND and BUFNI or
  • Minimum storage that is required to process the data set with its specified processing options
A valid BUFSP amount takes precedence over the amount that is called for by BUFND and BUFNI. If the BUFSP amount is greater than the amount that is called for by BUFND and BUFNI, the extra space is allocated under the following conditions:
  • 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 that is called for by BUFND and BUFNI, the number of data and index buffers is decreased under the following conditions:
  • When MACRF indicates direct access only, the number of data buffers is decreased to not fewer than the minimum number. Then, if required, the number of index buffers is decreased until the amount that is 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 fewer than 1 more than the minimum number. Then, if required, the number of data buffers is decreased to not fewer 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 fewer than the minimum number.

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

The BUFFERSPACE must not exceed 16776704.

This parameter is only applicable to MACRF=NSR.

This parameter has no effect for z/OS UNIX files.

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 label or 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 that you are providing. The list must be 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 or the label of an area you supplied to GENCB for the exit list.

To use the exit list, you must code this EXLST parameter. Omitting this parameter means that you have no exit routines. Exit routines are described in z/OS DFSMS Using Data Sets.

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 (ESDS), 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. Table 1 gives the subparameters. Each group of subparameters 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 (KSDS). 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.
Table 1. MACRF Options
Option Meaning
ADR Addressed access to a key-sequenced or entry-sequenced data set; RBAs are used as search arguments and sequential access is by entry sequence. VSAM RLS does not support ADR access to a KSDS.
CNV Access is to the entire contents of a control interval rather than to an individual data record. If the data set is password protected, you must supply the address of the control or higher-level password in the ACB PASSWD parameter.

Recommendation: Use RACF® or a functionally equivalent program instead of VSAM passwords.

For VSAM RLS and z/OS UNIX files, CNV is invalid. If it is specified for a z/OS UNIX file, it results in an OPEN failure.
KEY Keyed access to a relative record data set (RRDS) or key-sequenced data set. Keys or relative record numbers are used as search arguments and sequential access is by key or relative record number. KEY processing is not affected by RLS.
CFX If you use ICI, OPEN fixes control blocks and I/O buffers and they remain fixed until the ACB is closed. For RLS and z/OS UNIX files, this subparameter has no effect.
NFX OPEN does not fix control blocks or I/O buffers. VSAM fixes and unfixes pages dynamically as needed. For RLS and z/OS UNIX files, NFX is assumed.
DDN Subtask shared control block connection is based on common ddnames. For RLS and z/OS UNIX files, this subparameter has no effect.
DSN Subtask shared control block connection is based on common data set names. For RLS and z/OS UNIX files, this subparameter has no effect.
DFR With shared resources, writes for direct PUT requests are deferred until the WRTBFR macro is issued or until VSAM needs a buffer to satisfy a GET request. Deferring writes saves I/O requests in cases where subsequent requests can be satisfied by the data already in the buffer pool. For RLS, DFR is ignored and direct request modified buffers are immediately written to disk and the CF (coupling facility). This subparameter has no effect for z/OS UNIX files.
NDF Writes are not deferred for direct PUTs. For RLS, NDF is ignored and direct request modified buffers are immediately written to disk and the CF (coupling facility).
DIR Direct access to an RRDS, KSDS, or ESDS.
SEQ Sequential access to an RRDS, KSDS, or ESDS.
SKP Skip-sequential access to an RRDS or KSDS. Used only with keyed access in a forward direction.
ICI Processing is limited to improved control interval processing; access is faster because fewer processor instructions are executed. ICI processing is not allowed for extended format data sets.

For RLS and z/OS UNIX files, this subparameter has no effect.
NCI Processing other than improved control interval processing.
IN Retrieval of records of a RRDS, KSDS, or ESDS; (not allowed for an empty data set). If the data set is password protected, you must supply the address of the read or higher-level password in the ACB PASSWD parameter.
OUT Storage of new records in a RRDS, KSDS, or ESDS (not allowed with addressed access to a KSDS). Update of records in a RRDS, KSDS, or ESDS. Deletion of records from a RRDS or KSDS.

If the data set is password protected, you must supply the address of the update or higher-level password in the ACB PASSWD parameter.
LEW Using LSR, if an exclusive control conflict is encountered, VSAM defers the request until the resource becomes available.
NLW With this value specified, instead of deferring the request, VSAM returns the exclusive control return code 20 (X'14') to the application program. The application program is then able to determine the next action.
NIS Normal insert strategy. This subparameter has no effect for z/OS UNIX files.
SIS Sequential insert strategy (split control intervals and control areas at the insert point rather than at the midpoint when doing direct PUTs); although positioning is lost and writes are done after each direct PUT request, SIS allows more efficient space usage when direct inserts are clustered around certain keys. This subparameter has no effect for z/OS UNIX files.
NRM The object to be processed is the one named in the specified ddname.
AIX The object to be processed is the alternate index of the path specified by ddname, rather than the base cluster though the alternate index. For RLS, the AIX subparameter is invalid. This subparameter has no effect for z/OS UNIX files.
NRS Data set is not reusable.
RST Data set is reusable (high-used RBA is reset to 0 during OPEN). If the data set is password protected, you must supply the address of the update or higher-level password in the ACB PASSWD parameter.
NSR Nonshared resources.
LSR Local shared resources. Each address space may have up to 256 index resource pools and 256 data resource pools independent of other address spaces. Unless you are using the default, SHRPOOL=0, you must specify the SHRPOOL parameter to indicate which resource pool you are using. Specifying LSR causes a data set to use the local resource pool built by the BLDVRP macro. If an index resource pool exists at the time an OPEN macro is issued, the index for a KSDS is connected to the index resource pool. This parameter is invalid for z/OS UNIX files and if specified results in an open failure.
GSR Global shared resources; all address spaces may have local and global resources pools, where tasks in an address space with a local resource pool may use either the local resource pool or the global resource pool. This parameter is invalid for compressed format data sets. If specified for a z/OS UNIX file, it results in an open failure.
RLS RLS specifies that VSAM record level sharing protocols are used. RLS and NSR/LSR/GSR are mutually exclusive. RLS implies that VSAM uses cross system record level locking as opposed to CI locking, uses CF for buffer consistency, and manages a system wide local cache. When you specify this parameter, OPEN will fail for:
  • Linear data sets
  • ADR access to a KSDS
  • CNV access to any data set organization
  • Data sets defined with imbedded indexes
  • z/OS UNIX files.
NUB Management of I/O buffers is left up to VSAM. For RLS, you must specify NUB.
UBF Management of I/O buffers is left up to the user. The work area specified by the RPL (or GENCB) AREA parameter is the I/O buffer. VSAM transmits the contents of a control interval directly between the work area and direct access storage. UBF is valid when OPTCD=MVE and MACRF=CNV are specified. When ICI is specified, UBF is assumed. For RLS, UBF is invalid.
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 for more information. MAREA is ignored for RLS.
MLEN=abs expression
specifies the length of an optional OPEN/CLOSE or TYPE=T option (CLOSE macro) message area. The default is 0. The maximum length is 32KB. See OPEN/CLOSE message area for multiple reason or attention messages for more information. MLEN is ignored for RLS.
PASSWD=address
specifies the address of a field containing the highest-level password required for the types of access indicated by the MACRF parameter. The first byte of the field pointed to 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 gives the console operator the opportunity to supply it when you open the data set.

Data sets which are opened for RLS processing must be SMS-managed data sets which have had password processing ignored.

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 that are issued against this ACB. This parameter overrides the read integrity options that are specified in the RLS JCL parameter. You can override the RLSREAD parameters for a specific GET request by specifying the read integrety options in the RPL OPTCD parameter.
NRI
specifies no read integrity. NRI is a performance option. When you specify NRI, VSAM does not obtain a lock on the record.
CR
specifies consistent read integrity. CR ensures that only records that have been committed are read.
NORD
specifies that the read integrity option that is used is determined either by the RLS JCL specification or by options that are specified on the GET request.

For access modes other than RLS, RLSREAD is ignored.

RMODE31=[ALL|BUFF|CB|NONE]
specifies where VSAM OPEN obtains virtual storage (above or below 16 megabytes) for control blocks and I/O buffers.

The rev="r105dq01">The values specified by the RMDE31 parameter have an effect only before issuing an OPEN. At all other times, changing these values has no effect on the residency of the control blocks and I/O buffers.

If MACRF=RLS is specified, RMODE31=ALL is assumed. For RLS and DFSMStvs, VSAM control blocks and buffers are located in a data space owned by the SMSVSAM server address space and are not directly addressable.

RMODE31= can also be specified on the JCL AMP parameter.
ALL
specifies that both VSAM control blocks and I/O buffers are obtained above 16 megabytes.
BUFF
specifies that only VSAM I/O buffers are obtained above 16 megabytes.
CB
specifies that only VSAM control blocks are obtained above 16 megabytes.
NONE
specifies that both I/O buffers and VSAM control blocks are built below 16 megabytes. This is the default.
SHRPOOL={abs expression|0}
specifies which LSR pool is connected to the ACB. This parameter is valid only when MACRF=LSR is also specified. SHRPOOL must be a number between 0 and 255. The default is 0.
STRNO=abs expression
specifies the number of requests requiring concurrent data set positioning VSAM is prepared to handle. STRNO must be a number between 1 and 255. The default is 1. A request is defined by a given request parameter list or chain of request parameter lists. The string number is equal to the number of requests issued concurrently for all the data sets sharing the resource pool. 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. When records are loaded into an empty data set, the STRNO value in the access method control block must be 1.
VSAM dynamically extends the number of strings as they are needed by concurrent requests for this ACB. This automatic extension can influence performance. The VSAM control blocks for the set of strings specified by STRNO are allocated on contiguous virtual storage, but this is not guaranteed for the strings allocated by dynamic extension. Dynamic string addition cannot be done when using the following options:
  • Load mode
  • ICI
  • LSR or GSR
For STRNO, you should specify the total number of request parameter lists or chains of request parameter lists that you are using to define requests. (VSAM needs to remember only one position for a chain of request parameter lists.) However, each position beyond the minimum number that VSAM needs to be able to remember requires additional virtual storage space for these parameters:
  • A minimum of one data I/O buffer and, for keyed access, one index I/O buffer (the size of an I/O buffer is the control interval size of a data set)
  • Internal control blocks and other areas
For RLS, STRNO is ignored. Strings are dynamically acquired up to a limit of 1024.

STRNO >1 is not supported for z/OS UNIX files. If you specify a value greater than 1, OPEN fails.

Parent topic: VSAM macro descriptions and examples