|
Use the ACB macro to generate an access method control block at
assembly time.
The format of the ACB macro follows.
The format of
the ACB macro.Label |
Operand |
Parameters |
---|
[label]
|
ACB
|
[AM=VSAM] [,BSTRNO=abs expression] [,BUFND=abs expression] [,BUFNI=abs expression] [,BUFSP=abs expression] [,DDNAME=character string] [,EXLST=address] [,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] [,RLSREAD={NRI|CR|CRE|NORD}] [,PASSWD=address] [,RMODE31={ALL|BUFF|CB|NONE}] [,SHRPOOL={0|abs expression}] [,STRNO=abs expression] [,SUBSYSNM=address] [,CTRLACB={YES|NO}]
|
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 UNIX files. This is the case when an
application program uses the VSAM interface to access a 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 65535. 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. The maximum number of buffers that is allowed
is currently 255 (254 data buffers and 1 insert buffer). 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 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 65535. 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. The maximum number
of buffers allowed is currently 255 (254 data buffers and 1 insert
buffer).
This parameter is only applicable to MACRF=NSR.
This parameter has no effect for 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 was 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, in the preceding text.
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
- Minimum storage that is required to process the data set with
its specified processing options
A valid BUFSP amount takes precedence over
the amount BUFND and BUFNI call for. If the BUFSP amount is greater
than the amount 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 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 applicable only
to MACRF=NSR; it is ignored when MACRF=RLS is specified.
This
parameter has no effect for 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.
If
you code CTRLACB=YES, do not code DDNAME. Otherwise, the DDNAME value
must come from some source.
- 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 can specify subparameters in any order. You can
specify both ADR and KEY to process a key-sequenced data set (KSDS).
You can 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. MACRF optionsOption |
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 and DFSMStvs do 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®®,
a component of the z/OS Security Server, or a functionally equivalent
program instead of VSAM passwords.
For VSAM RLS and
DFSMStvs, CNV is invalid. This parameter is invalid for UNIX files and
if it is specified, 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 VSAM RLS or DFSMStvs. |
CFX |
OPEN fixes control blocks and I/O
buffers, and they remain fixed until the ACB is closed. For
VSAM RLS and DFSMStvs, CFX is ignored and NFX is assumed. This subparameter
has no effect for UNIX files.
|
NFX |
OPEN fixes control blocks and I/O
buffers, and they remain fixed until the ACB is closed. For VSAM RLS
and DFSMStvs, NFX is assumed. |
DDN |
Subtask shared control
block connection is based on common ddnames. For VSAM RLS and DFSMStvs,
DDN is ignored. This subparameter has no effect for UNIX files. |
DSN |
Subtask shared control
block connection is based on common data set names. For VSAM RLS and
DFSMStvs, DSN is ignored. This subparameter has no effect for UNIX files. |
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 VSAM RLS and
DFSMStvs, DFR is ignored and direct request modified buffers are immediately
written to disk and the CF (coupling facility). This subparameter
has no effect for UNIX files. |
NDF |
Writes are not deferred for direct
PUTs. For VSAM RLS and DFSMStvs, 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 VSAM RLS and DFSMStvs, ICI is
invalid. This parameter is invalid for UNIX files and if specified,
results in an open failure.
|
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. For VSAM RLS and DFSMStvs, LEW is ignored. |
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. For VSAM RLS and
DFSMStvs, NLW is ignored. |
NIS |
Normal insert strategy. This subparameter
has no effect for 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 UNIX files. |
NRM |
The object to be processed is the
one named in the specified ddname. For VSAM RLS and DFSMStvs, NRM
does not allow the direct open of an alternate index. |
AIX |
The object to be processed
is the alternate index of the path specified by ddname, rather than
the base cluster through the alternate index. For VSAM RLS and DFSMStvs,
the AIX® subparameter is invalid. This subparameter
has no effect for 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 can 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 UNIX files and if it is specified, results
in an open failure. |
GSR |
Global shared resources;
all address spaces can have local and global resources pools, and
each task in an address space with a local resource pool can use either
the local resource pool or the global resource pool. This parameter
is invalid for UNIX files and if it is specified, results in an open
failure. This parameter is invalid for compressed format data sets. |
RLS |
While a data set can be accessed
using both VSAM RLS and DFSMStvs simultaneously, it is not possible
to access a data set simultaneously with both VSAM RLS or DFSMStvs
protocols and NSR/LSR/GSR protocols. VSAM enforces this restriction.
VSAM RLS and DFSMStvs imply 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. Both VSAM RLS and DFSMStvs
do not support the following data set features:- Linear data sets
- ADR access to a KSDS
- CNV access to any data set organization
- Data sets defined with imbedded indexes
This parameter is invalid for UNIX files and if
it is specified, results in an open failure.
|
NUB |
Management of I/O buffers is left
up to VSAM. For VSAM RLS and DFSMStvs, 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 VSAM RLS and DFSMStvs, UBF is invalid. |
- MAREA=address
- Specifies the address of an optional OPEN/CLOSE or TYPE=T option
(CLOSE macro) message area.MAREA is ignored for VSAM RLS and DFSMStvs.
- 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. 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 that are opened for RLS processing must be SMS-managed data sets
that are cataloged and have password processing set to be ignored.
This parameter has no effect for UNIX files.
- RLSREAD={NRI|CR|CRE|NORD}
- Specifies the read integrity option that applies
to GET requests that are issued against this ACB. This parameter overrides
the read integrity option that is specified in the RLS JCL parameter.
You can override the RLSREAD parameter for a specific GET request
by specifying the read integrety option in the RPL OPTCD parameter.
For DFSMStvs, you can specify CRE. If you use CRE for
DFSMStvs access, specify CRE in the JCL or the ACB. Those requests
that do not require CRE can be overridden by the value that is specified
in the RPL.
- 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.
- CRE
- Specifies consistent read explicit. It can only be specified
with MACRF=RLS. When it is specified, DFSMStvs access is used. This
locking allows the application to inhibit update or erase of the record
by other transactions or applications until commit or backout.
- 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 or DFSMStvs,
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
values specified by the RMODE31 parameter have an effect on VSAM only
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.
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
in 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 that 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 UNIX files. If you specify a value greater than 1, OPEN fails.
- SUBSYSNM=address
- For VSAM RLS and DFSMStvs, specifies
the address of the subsystem name (mapped by IFGSYSNM and unique to
the Parallel Sysplex®). This parameter
specifies a commit protocol application, which supports online transaction
processing subsystems. When SUBSYSNM is specified, you must specify
LUWID for all RPL requests against the ACB. The subsystem name is
valid only for RLS or DFSMStvs processing; otherwise, it is ignored.
SUBSYSNM is used by CICS® to
specify a unique name for the CICS region.
This name and the RPL LUWID are used by RLS to form the lock owner
name for record locks obtained for CICS transactions.
- CTRLACB={YES
|NO}
- For RLS, specifies whether the opened
ACB is to be used as a control ACB.
This
facility is used by commit protocol applications (for example, CICS)
for certain record management requests and in support of an RLS sphere
quiesce. - YES
- Specifies that the ACB is to be used as a control ACB. The ACB
cannot specify a DDNAME, but SUBSYSNM must be specified. The control
ACB is also required to have an associated EXLST that specifies a
QUIESCE exit. For applications that use DFSMStvs, YES should not be
specified.
- NO
- Specifies the ACB is not to be used as a control ACB.
The default is NO.
CTRLACB is ignored if RLS processing is not specified.
|