|
The data control block for a basic direct access method (BDAM)
data set is constructed during assembly of the problem program. You
must code DSORG and MACRF in the DCB macro, but the other parameters
can be supplied to the DCB from the DD statement or an existing data
set label (DSCB). If more than one of these sources specifies information
for a particular field, the order of priority is the DCB macro, DD
statement, and data set label. Each BDAM DCB parameter description
contains a heading, "Source". The information under this heading
describes the sources that can supply the parameter.
Each reference to a DCB OPEN exit routine applies also to a JFCBE
exit routine.
You can assemble the DCB macro into a program that resides
above the 16MB line, but the program must move it below the line before
using it. All areas that the DCB refers to, such as EXLST and SYNAD,
must be below the 16MB line.
The format of the DCB macro for BDAM is:
[label]
|
DCB
|
[BFALN={F|D}] [,BFTEK=R] [,BLKSIZE=absexp] [,BUFCB=relexp] [,BUFL=absexp] [,BUFNO=absexp] [,DCBE=relexp] [,DDNAME=symbol] 1 ,DSORG={DA|DAU} [,EXLST=relexp] [,KEYLEN=absexp] [,LIMCT=absexp] ,MACRF={{(R{K[I]|I}[X][S][C])} {(W{A[K][I]|K[I]|I}[C])} {(R{K[I]|I}[X] [S][C] ,W{A[K][I]|K [I]|I}[C])}} [,OPTCD={[R|A][E][F][W]}] [,RECFM={U|V[S|BS]|F[T]}] [,SYNAD=relexp]
|
Note: - This parameter must be supplied before an OPEN macro
is issued for this DCB; it cannot be supplied in the open exit routine.
Recommendation: When creating a DCB to open a data set allocated
to an SMS-managed volume, do not specify values that would change
the data set to a type which cannot be SMS-managed, such as DSORG=DAU.
BDAM supports the following DCB parameters: - BFALN={F|D}
- specifies the boundary alignment for each buffer in the buffer
pool. You can specify the BFALN parameter when (1) BSAM is being used
to allocate a direct data set and buffers are acquired automatically,
(2) when an existing BDAM data set is being processed and dynamic
buffering is requested, or (3) when the GETPOOL macro is used to construct
the buffer pool. If BFALN is omitted, the system provides doubleword
alignment for each buffer. You can specify:
- F
- specifies that each buffer is on a fullword boundary that is not
also a doubleword boundary.
- D
- specifies that each buffer is on a doubleword boundary.
If you use the BUILD macro to construct the
buffer pool, or if the problem program controls all buffering, the
problem program must provide the area for the buffers and control
buffer alignment.
Source: BFALN can be supplied in
the DCB macro, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine.
If both BFALN and BFTEK are specified, they must be supplied from
the same source.
- BFTEK=R
- specifies that the
data set is allocated for or contains variable-length spanned records.
You can code BFTEK=R only when the record format is specified as RECFM=VS.
When variable-length spanned records are written, the data length
can exceed the total capacity of a single track on the direct access
storage device being used, or it can exceed the remaining capacity
on a given track. The system divides the data block into segments
(if necessary), writes the first segment on a track, and writes the
remaining segments on the following track(s).
When a variable-length
spanned record is read, the system reads each segment and assembles
a complete data block in the buffer designated in the area
address of a READ macro.
Variable-length spanned
records can also be read using BSAM. When BSAM is used to read a BDAM
variable-length spanned record, the record is read one segment at
a time, and the problem program must assemble the segments into a
complete data block. This operation is described in the section for
the BSAM DCB macro.
Source: BFTEK can be supplied in
the DCB macro, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine.
If both BFTEK and BFALN are specified, they must be supplied from
the same source.
- BLKSIZE=absexp (maximum value is
32760)
- specifies the length, in bytes, of each data block for fixed-length
records. Or, specifies the maximum length, in bytes, of each data
block for variable-length or undefined-length records. If keys are
used, the length of the key is not included in the value specified
for BLKSIZE.
The actual value that you can specify in BLKSIZE
depends on the record format and the type of direct access storage
devices being used. If variable-length spanned records are used, the
value specified in BLKSIZE can be up to the maximum. For all other
record formats (F, V, VBS, and U), the maximum value that can be specified
in BLKSIZE is determined by the track capacity of a single track on
the direct access storage device being used. Device capacity for direct
access storage devices is described in Selecting logical record lengths and block sizes for specific devices.
For additional information about space allocation, see z/OS DFSMS Using Data Sets.
Source: BLKSIZE
can be supplied in the DCB macro, in the DCB subparameter of a DD
statement, by the problem program before completion of the data control
block exit routine, or by the data set label of an existing data set.
Block size can also be derived from the JCL keyword LIKE. See z/OS MVS JCL Reference and z/OS MVS JCL User's Guide for
more information on LIKE.
- BUFCB=relexp
- specifies
the address of the buffer pool control block in a buffer pool constructed
by a BUILD macro. The buffer pool must reside below the 16MB line.
If the buffer pool is constructed automatically, dynamically,
or by a GETPOOL macro, you do not need to use BUFCB because the system
places the address of the buffer pool control block into the data
control block. Also, if the problem program is to control all buffering,
omit BUFCB.
Source: BUFCB can be supplied in the DCB
macro or by the problem program before completion of the data control
block exit routine. If the problem program is to control all buffering
(and BUFNO is not supplied by any source), then BUFCB can be supplied
any time before it is needed. You do not have to have a buffer pool.
- BUFL=absexp (maximum value KEYLEN
+ BLKSIZE is 32760)
- specifies
the length, in bytes, of each buffer in the buffer pool when the buffers
are acquired automatically (create BDAM) or dynamically (existing
BDAM).
When buffers are acquired automatically (create BDAM),
the BUFL parameter is optional. If specified, the value must be at
least as large as the sum of the values specified for KEYLEN and BLKSIZE.
If BUFL is omitted, the system builds buffers with a length equal
to the sum of the values specified in KEYLEN and BLKSIZE.
You
must specify BUFL when processing an existing direct data set with
dynamic buffering. Its value must be at least as large as the value
specified for BLKSIZE when the READ or WRITE macro specifies a key
address, or the value specified in BUFL must be at least as large
as the sum of the values specified in KEYLEN and BLKSIZE if the READ
and WRITE macros specify 'S' for the key
address.
You can omit BUFL if the buffer pool is constructed
by a BUILD or GETPOOL macro, or if the problem program controls all
buffering.
Source: BUFL can be supplied in the DCB
macro, in the DCB subparameter of a DD statement, or by the problem
program before completion of the data control block exit routine.
- BUFNO=absexp (maximum value is 255)
- specifies the number of buffers to
be constructed by a BUILD macro, or the number of buffers and segment
work areas to be acquired automatically by the system.
If the
buffer pool is constructed by a BUILD macro or if buffers are acquired
automatically when BSAM is used to allocate a direct data set, you
must specify the number of buffers in BUFNO.
If dynamic buffering
is requested when an existing direct data set is being processed,
BUFNO is optional; if omitted, the system acquires two buffers.
If
variable-length spanned records are being processed and dynamic buffering
is requested, the system also acquires a segment work area for each
buffer. If
dynamic buffering is not requested, the system acquires the number
of segment work areas specified in BUFNO. If BUFNO is omitted when
variable-length spanned records are being processed and dynamic buffering
is not requested, the system acquires two segment work areas.
If
the buffer pool is constructed by a GETPOOL macro or if the problem
program controls all buffering, you can omit BUFNO unless you need
it to acquire additional segment work areas for variable-length spanned
records.
Source: BUFNO can be supplied in the DCB macro,
in the DCB subparameter of a DD statement, or by the problem program
before completion of the data control block exit routine.
- DCBE=relexp
- specifies the address of a DCB Extension (DCBE). The
DCBE may reside above the 16MB line. You may assemble a DCB and DCBE
in a program that resides above the line if the DCB is copied below
the line before opening the copy.
If the DCBE is specified, it
must be specified before issuing the OPEN macro. Like the DCB, the
DCBE must exist until the data set is closed. Otherwise, there may
be unpredictable results.
Only one open DCB at a
time can refer to a particular DCBE. After a DCB is successfully closed,
you can open a different DCB referring to the DCBE.
The
DCBE is not required with BDAM unless the data set requires a DCBE
option or if you choose to use DCBE options.
If a DCBE exists,
the flags DCBH0 and DCBH1 are both set on. The pointer to the DCBE
is stored at offset +0 in the DCB.
Source: You
can supply the DCBE address in the DCB macro or before issuing an
OPEN macro to open the data set.
- DDNAME=symbol
- specifies the name used to identify the job control language data
definition (DD) statement that defines the data set being allocated
or processed.
Source: DDNAME can be supplied in the DCB
macro or can be moved into the DCB by the problem program before an
OPEN macro is issued to open the data set.
- DSORG={DA|DAU}
- specifies the data set organization and whether
the data set contains any location-dependent information that would
make it unmovable. For example, if actual device addresses are used
to process a BDAM data set, the data set can be unmovable. You can
specify:
- DA
- specifies a direct organization data set.
- DAU
- specifies a direct organization data set containing location-dependent
information that would make it unmovable.
Restriction:
A DSORG=DAU data set cannot
be SMS-managed.
When a direct data set is allocated, the basic
sequential access method (BSAM) is used. You must code DSORG in the
DCB macro as DSORG=PS or PSU when the data set is allocated, and code
the DCB subparameter in the corresponding DD statement as DSORG=DA
or DAU. This creates a data set with a data set label identifying
it as a direct data set.
Source: DSORG must be specified
in the DCB macro. See the preceding comment about creating a direct
data set.
- EXLST=relexp
- specifies the address of the DCB exit list. The EXLST parameter
is required if the problem program processes user labels during the
open or close routine, if the data control block exit routine is used
for additional processing, or if the DCB ABEND exit is used for abend
condition analysis.
The
exit list must reside below the line. For the functions, format, and
requirements of exit list processing, see z/OS DFSMS Using Data Sets.
Exit routines can reside above the 16 MB line if you use the technique
described in Figure 1.
Source: EXLST
can be supplied in the DCB macro or by the problem program before
the relevant function is needed.
- KEYLEN=absexp (maximum value is
255)
- specifies the length, in bytes, of all keys used in the data set.
When keys are used, a key is associated with each data block in the
data set. If the key length is not supplied by any source, no input
or output requests that require a key can be specified in a READ or
WRITE macro.
Source: KEYLEN can be supplied in the DCB
macro, in the DCB subparameter of a DD statement, by the problem program
before the completion of the data control block exit routine, or by
an existing data set label. If KEYLEN=0 is specified in the DCB macro,
a special indicator is set in RECFM so that KEYLEN cannot be supplied
from the DCB subparameter of a DD statement or data set label of an
existing data set. KEYLEN=0 can be coded only in the DCB macro and
will be ignored if specified in the DD statement.
Key length
can be derived from the data class associated with the data set. Key
length can also be derived from the JCL keyword LIKE. However, if
KEYLEN is specified in the DCB macro, it overrides the value derived
from data class or LIKE. For more information, see z/OS MVS JCL Reference.
- LIMCT=absexp
- specifies the number of blocks or tracks to be searched when the
extended search option (OPTCD=E) is requested.
When the extended
search option is requested and relative block addressing is used,
the records must be fixed-length record format. The system converts the number of blocks
specified in LIMCT into the number of tracks required to contain the
blocks, then proceeds in the manner described below for relative track
addressing.
When the extended search option is requested and
relative track addressing is used (or the number of blocks has been
converted to the number of tracks), the system searches for two things:
(1) the block specified in a READ or WRITE macro (type DK), or (2)
available space where it can add a block (WRITE macro, type DA). The
search is as follows:
- The search begins at the track specified by the block
address of a READ or WRITE macro.
- The search continues until the search is satisfied, the number
of tracks specified in LIMCT have been searched, or the entire data
set has been searched. If the search is not satisfied when the last
track of the data set is reached, the system continues the search
by starting at the first track of the data set if the EOF marker is
on the last track allocated to the data set. (This operation allows
the number specified in LIMCT to exceed the size of the data set,
causing the entire data set to be searched.) You can ensure that the
EOF marker is on the last allocated track by determining the size
of the data set and allocating space in blocks, or by allocating space
in tracks and including the RLSE subparameter in the SPACE parameter
of the DD statement (RLSE specifies that all unused tracks be returned
to the system).
The problem program can change the DCBLIMCT field in the
data control block at any time, but, if the extended search option
is used, the DCBLIMCT field must not be zero when a READ or WRITE
macro is issued.
If the extended search
option is not requested, the system ignores LIMCT, and the search
for a data block is limited to a single track.
Source: LIMCT
can be supplied in the DCB macro, the DCB subparameter of a DD statement,
or by the problem program before the count is required by a READ or
WRITE macro.
- MACRF={{(R{K[I]|I}[X][S][C])}
- {(W{A[K][I]|K [I]|I}[C])}
- {(R{K[I]|I}[X] [S][C],W{A[K][I] |K[I]|I}[C])}}
- specifies the type of macros (READ, WRITE, CHECK, and WAIT) that
are used to process the data set. MACRF also specifies
the type of search argument and BDAM functions that are used with
the data set. When BSAM is used to create a direct data set, the BSAM
parameter MACRF=WL is specified. This special parameter invokes the
BSAM routine that can create a BDAM data set. You can specify the
following characters for BDAM:
- A
- specifies that data blocks are added to the data set.
- C
- specifies that the CHECK macro is used to test for completion
of read and write operations. If C is not
specified, WAIT macros must be used to test for completion of read
and write operations.
- I
- specifies that the search argument is the block identification
portion of the data block. If relative addressing is used, the system
converts the relative address to an actual address (MBBCCHHR) before
the search.
- K
- specifies that the search argument is the key portion of the
data block. The location of the key to be used as a search argument
is specified in a READ or WRITE macro.
- R
- specifies that READ macros are used. READ macros can be issued
when the data set is opened for INPUT, OUTPUT, or UPDAT. R is required
if the OPEN option is INPUT or UPDAT. It has no effect if the OPEN
option is OUTPUT or EXTEND.
- S
- specifies that dynamic buffering is requested by specifying 'S' in
the area address parameter of a READ or WRITE macro.
- W
- specifies that WRITE macros are used. WRITE macros can be issued
only when the data set is opened for OUTPUT or UPDAT. W is required
if the OPEN option is OUTPUT. It has no effect if the OPEN option
is INPUT.
- X
- specifies
that READ macros request exclusive control of a data block. When
exclusive control is requested, the data block must be released by
a subsequent WRITE or RELEX macro.
Source: MACRF must be supplied in the
DCB macro.
- OPTCD={[R|A][E][F ][W]}
- specifies the optional
services used with the direct data set. These options are related
to the type of addressing used, the extended search option, block
position feedback, and write-validity checking. You can code the following
characters in any order, in any combination, and without commas between
characters:
- A
- specifies that actual device addresses (MBBCCHHR) are provided
to the system when READ or WRITE macros are issued.
- E
- specifies that the extended search option is used to locate data
blocks or available space where a data block can be added. When the
extended search option is specified, the number of blocks or tracks
to be searched must be specified in LIMCT. The extended search option
is ignored if actual addressing (OPTCD=A) is also specified. The extended
search option requires that the data set have keys and that the search
be made by key (by specifying DK in the READ or WRITE macro or DA
in the WRITE macro).
- F
- specifies that the block position feedback that is requested by
a READ or WRITE macro is to be in the same form originally presented
to the system in the READ or WRITE macro. If the F parameter
is omitted, the system provides feedback, when requested, as an 8-byte
actual device address. (Feedback is always provided if exclusive control
is requested.)
- R
- specifies that relative block addresses (as 3-byte binary numbers)
are provided to the system when a READ or WRITE macro is issued.
- W
- specifies
that the system is to perform a validity check for each record written.
Tip: You can specify relative track addressing
by omitting both A and R from
OPTCD. If
you want to specify relative track addressing after your data set
has been accessed using another addressing scheme (OPTCD=A or OPTCD=R),
you should either specify a valid OPTCD subparameter (E,
F, or W) in the DCB macro
or DD statement when you reopen your data set, or zero out the OPTCD=A
or OPTCD=R bits in the data control block exit routine. Note that
the first method prevents the open routines from merging any of the
other OPTCD bits from the format-1 DSCB in the DCB. Both methods update
the OPTCD bits in the DSCB if the open is for OUTPUT, OUTIN, or UPDAT.
Source: OPTCD
can be supplied in the DCB macro, in the DCB subparameter of a DD
statement, or by the problem program before completion of the DCB
open exit routine.
- RECFM={U|V[S|BS]|F[T]}
- specifies the record format and characteristics of the data set
being allocated or processed. You can specify the following characters.
(If the optional characters are coded, they must be coded in the order
shown above).
- B
- specifies
that the data set contains blocked records. The record format RECFM=VBS
is the only combination in which B can be
specified. RECFM=VBS does not cause the system to process spanned
records. The problem program must block and segment the records. RECFM=VBS
is treated as a variable-length record by BDAM.
- F
- specifies that the data set contains fixed-length records.
- S
- specifies that the data set contains variable-length spanned records
when it is coded as RECFM=VS. When RECFM=VBS is coded, the records
are treated as variable-length records, and the problem program must
block and segment the records.
- T
- specifies
that track overflow is used with the data set. Track overflow allows
a record to be partially written on one track and the remainder is
written on the following track (if required).
Note: This
is an obsolete option. The system ignores it.
- U
- specifies that the data
set contains undefined-length records.
- V
- specifies that the data set contains variable-length records.
Source: RECFM can be supplied in the
DCB macro, in the DCB subparameter of a DD statement, the problem
program before completion of the data control block exit routine,
or by the data set label of an existing data set.
Record
format can be derived from the data class associated with the data
set. Record format can also be derived from the JCL keyword LIKE.
However, if RECFM is specified in the DCB macro, it overrides the
value derived from data class or LIKE. For more information, see z/OS MVS JCL Reference.
- SYNAD=relexp
- specifies
the address of the error analysis routine to be given control when
an uncorrectable input/output error occurs. The entry point of this
SYNAD routine must reside below the line. The entry point of this
SYNAD routine must reside below the line. The contents of the registers
when the error analysis routine is given control are described in z/OS DFSMS Using Data Sets.
Additional status information available to the SYNAD routine is described
in Status information following an input/output operation.
The error analysis routine
must not use the save area pointed to by register 13. The system does
not restore registers when it regains control from the error analysis
routine. The error analysis routine can issue a RETURN macro that
uses the address in register 14 to return control to the system. When
control is returned in this manner, the system returns control to
the problem program and proceeds as though no error had been found.
When a direct data set is being created, a return from the error analysis
routine to the system causes abnormal end of the task.
When
you issue a CHECK macro, the SYNAD routine receives control if an
I/O error occurred. If SYNAD is omitted, the task is abnormally terminated
if you issue a CHECK macro and it finds an uncorrectable I/O error.
SYNAD
receives control in the addressing mode in which the CHECK macro was
issued. On return from a SYNADAF or SYNADRLS macro issued in the SYNAD
routine, the high order byte of register 15 will be unpredictable.
Therefore, callers of SYNADAF or SYNADRLS in 31-bit addressing mode
must either not use register 15 as a base register or restore the
high order bytes on return from SYNADAF or SYNADRLS.
Source: SYNAD
can be supplied in the DCB macro or by the problem program. The problem
program can also change the error routine address at any time.
|