 |
The data control block for a basic partitioned access method (BPAM)
data set is constructed during assembly of the problem program. You
must code the DSORG and MACRF parameters in the DCB macro, but the
other DCB parameters can be supplied from other sources. Each of the
BPAM DCB parameter descriptions contains a heading, "Source".
The information under this heading describes the sources that can
supply the parameter to the data control block. Each reference to
a DCB OPEN exit routine applies also to a JFCBE exit routine. The
DCB fields that you can test or set are described in Non-VSAM control blocks.
You can assemble the DCB macro into a program that resides
above the 16 MB line, but the program must move it below the line
before using it. Except for the DCBE, all areas that the DCB refers
to, such as EXLST and EODAD, must be below the 16 MB line.
The format of the DCB macro for BPAM is:
[label]
|
DCB
|
[BFALN={F|D}]
[,BLKSIZE=absexp]
[,BUFCB=relexp]
[,BUFL=absexp]
[,BUFNO=absexp]
[,DCBE=relexp] 1
[,DDNAME=symbol] 1
,DSORG={PO|POU}
[,EODAD=relexp]
[,EXLST=relexp]
[,KEYLEN=absexp]
[,LRECL=absexp]
,MACRF={(R|W|R,W)} 1
[,NCP=absexp]
[,OPTCD={C|W[C]}
[,RECFM={{U[T][A|M]}
{V[B[T]|T][A|M]}
{F[B[T]|T][A|M]}}]
[,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.
Note: 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=POU. Refer to z/OS DFSMS Using Data Sets for
further information.
When you create or process a partitioned
data set or PDSE, you can specify the following parameters in the
DCB macro: - BFALN={F|D}
- specifies the boundary alignment for each buffer in the buffer
pool when the buffer pool is constructed automatically or by a GETPOOL
macro. If BFALN is omitted, the system provides doubleword alignment
for each buffer. You can specify the following characters in BFALN:
- F
- specifies that each buffer is aligned on a fullword boundary that
is not also a doubleword boundary.
- D
- specifies that each buffer is aligned on a doubleword boundary.
If the BUILD macro is used to construct the
buffer pool or if the problem program controls all buffering, the
problem program must provide an 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.
- BLKSIZE=absexp (maximum value KEYLEN
+ BLKSIZE is 32760)
- specifies the length, in bytes, of each data block for fixed-length
unblocked records. Or, it specifies the maximum length, in bytes,
for any other record format. If keys are used, the length of the key
is not included in the value specified for BLKSIZE.
You
can request to use the BLKSIZE keyword on a DCBE macro. This is the
large block interface (LBI). If the system allows the LBI, the system
modifies the BLKSIZE field in the DCB and your program should not
use it.
The actual block size you can specify depends
on the record format and type of direct access storage devices being
used. The block size can be up to 32760 but you will get more data
on each track if you write shorter blocks. 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.
For
fixed-length records, the value specified in BLKSIZE should be a multiple
of the value specified for the logical record length (LRECL).
For
fixed-length unblocked records, LRECL must equal BLKSIZE (if LRECL
is specified).
For variable-length records, the value specified
in BLKSIZE must include the maximum logical record length (up to 32756
bytes) plus 4 bytes for the block descriptor word (BDW).
For undefined-length records, the value specified for BLKSIZE
can be altered by the problem program when the actual length becomes
known to the problem program. The value can be inserted into the DCBBLKSI
field of the data control block, or DCBEBLKSI field of the DCBE, or
specified in the length parameter of a READ
or WRITE macro.
Processing PDSEs: The
system reblocks PDSE records into its own internal format when the
data set is written, and reconstructs the blocks using the block size
from the DCB when the data set is read. For fixed-length blocked records,
the value specified in BLKSIZE must be a multiple of the value
in LRECL (if LRECL is specified). The LRECL value must be available
to OPEN when the PDSE is open for output.
When reading a PDSE
directory using fixed-length blocked records, you can specify a BLKSIZE
of 256 or greater (the LRECL is ignored).
System-Determined
Block Size: IBM® recommends
that you not specify block size unless the record format is U. This
makes your program less dependent on the physical characteristics
of the device although a PDSE block size has little to do with device
characteristics. If the block size is not specified when the data
set is allocated, and the LRECL and RECFM are known, the system derives
an optimum block size for the data set. This system-determined block
size is retained in the data set label. When the data set is opened
for output, OPEN checks the block size in the data set label. If it
is a system-determined block size, and the LRECL or RECFM have changed
from those specified in the data set label, OPEN redetermines an optimum
block size for the data set.
Source: BLKSIZE
can be supplied in the DCB or DCBE macro, in the DCB subparameter
of a DD statement, by the problem program before completion of the
data control block exit routine, by the data set label of an existing
data set, or by the system determining a value for a new data set.
The system does not copy BLKSIZE when you code the JCL keyword LIKE.
It derives the BLKSIZE from RECFM and LRECL which can be copied. For
more information on LIKE, see z/OS MVS JCL Reference
and z/OS MVS JCL User's Guide.
.
- BUFCB=relexp
- specifies the address of the buffer pool control block that you
have constructed by a BUILD macro.
If the buffer pool is constructed
automatically or by a GETPOOL macro, you can omit the BUFCB parameter
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 the BUFCB parameter. A buffer pool control block
resides below the 16MB line.
Source: BUFCB can be supplied
in the DCB macro or by the problem program before issuing a GETBUF
macro.
- BUFL=absexp (maximum value is 32760)
- specifies the length, in bytes, of each buffer in the
buffer pool when the buffer pool is acquired automatically. If BUFL
is omitted and you request OPEN to build a buffer pool, the system
acquires buffers with a length equal to the sum of the values specified
in KEYLEN and BLKSIZE. If the problem program requires longer buffers
(up to 32760 bytes), specify BUFL.
If the problem program controls
all buffering, BUFL is not required.
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, it specifies the number of buffers to be acquired automatically
by the system.
If the problem program controls all buffering or
if the buffer pool is constructed by a GETPOOL macro, omit BUFNO.
The default value is zero. If the blocksize is less than
32768 and BUFNO is either specified as zero to allowed to default
to zero the system does not acquire buffers automatically. If the
blocksize is 32768 or greater and BUFNO is either specified as zero
or allowed to default to zero then the system will acquire two buffers
or the number of buffers specified by MULTSDN, whichever is greater.
If the system acquires buffers for BPAM, they reside below the 16MB
line. You may obtain each buffer by issuing a GETBUF macro.
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 16 MB 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 that refers to the DCBE.
The DCBE is not required with BPAM unless
the data set requires a DCBE option or if you choose to use DCBE options.
If
a DCB points to a DCBE, the flags DCBH0 and DCBH1 are both set on.
The pointer to the DCBE is stored at offset +0 in the DCB (and replaces
the field DCBRELAD). If a DCBE exists, data that would be stored at
DCBRELAD is stored in the DCBE (DCBERELA). If a DCBE does not exist,
DCBRELAD continues to be located 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 that is 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 by the problem program before an OPEN macro is issued to
open the data set.
- DSORG={PO|POU}
- specifies the data set organization and whether the data set contains
any location-dependent information that would make it unmovable.
You
can specify:
- PO
- specifies a partitioned data set organization.
- POU
- specifies a partitioned data set organization and that the data
set contains location-dependent information that makes it unmovable.
If BSAM or QSAM is used to add or retrieve a
single member of a partitioned data set, specify DSORG=PS or DSORG=PSU
in the BSAM or QSAM DCB. To retrieve a single member of a PDSE, specify
DSORG=PS in the BSAM or QSAM DCB. The name of the member being processed
in this manner is supplied in the DD statement.
Restrictions are
as follows:
- Unmovable data sets cannot be SMS-managed. There are
exceptions, however, in cases where the checkpoint/restart function
has set the unmovable attribute for data sets that are already system-managed.
This setting prevents data sets that were open when a checkpoint
was taken by the application from being moved until you no longer
want to perform a restart on that application.
- PDSEs cannot be unmovable data sets.
Source: DSORG parameter must be specified in the
DCB macro.
- EODAD=relexp
- specifies the address of the routine given control
when the end of the input member is reached. Control is given to this
routine when a CHECK macro is issued and the end of the member is
reached. If the end of the member is reached but no EODAD address
was supplied in the DCB or DCBE, the task is abnormally terminated.
The EODAD routine (whether it is specified in the DCBE or DCB) receives
control in the addressing mode in which the CHECK macro was issued.
For additional information on the EODAD routine, see z/OS DFSMS Using Data Sets.
This end-of-data routine entry point specified in the DCB must reside
below the line. If you wish the entry point to reside above the line,
use the EODAD parameter of the DCBE macro. See the EODAD parameter
description for the DCBE macro, DCBE—(BDAM, BSAM, QSAM, BPAM, and EXCP).
Source: EODAD can be supplied in the DCB macro or by the
problem program before the end of the member is reached.
- EXLST=relexp
- specifies the address of the DCB exit list. The EXLST
parameter is required if the problem program uses the data control
block OPEN exit routine 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 the key associated with each
data block in the direct access storage device data set. If the key
length is not supplied from any source by the end of the data control
block exit routine, a key length of zero (no keys) is assumed.
A nonzero
key length is allowed for input from a PDSE, but is not allowed for
output to a PDSE. You can use keys for reading PDSE members, but not
for writing PDSE members.
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 the data set label of an existing data set. 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 is 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.
- LRECL=absexp (maximum value is 32760)
- specifies
the length, in bytes, for fixed-length records. Or, it specifies the
maximum length, in bytes, for variable-length and undefined-length
records. The value specified in LRECL cannot exceed the value specified
in BLKSIZE.
For PDSEs containing fixed-length blocked records,
you must specify LRECL when opened for output. For other types of
data sets, you can omit LRECL for BSAM; the system uses the value
specified in BLKSIZE. If you want the system to determine the optimum
block size for the data set, you must code LRECL. If the LRECL value
is coded, it is coded as follows:
Unblocked fixed-length
records: the value specified in LRECL must be equal to the value
specified in BLKSIZE.
Blocked fixed-length records:
the value specified in LRECL must be evenly divisible into the value
specified in BLKSIZE. However, except for PDSEs, the LRECL parameter
is not checked for validity.
Variable-length records:
the value specified in LRECL must include the maximum data length
(up to 32752 bytes) plus 4 bytes for the record-descriptor word (RDW).
Undefined-length
records: omit LRECL; the actual length is supplied dynamically
in a READ/WRITE macro. When an undefined-length record is read, the
actual length of the record is returned by the system in the DCBLRECL
field of the data control block if your program is not using the large
block interface (LBI).
Source: LRECL 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.
Record length
can be derived from the data class associated with the data set. Record
length can also be derived from the JCL keyword LIKE. For undefined-length
records, if LRECL 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.
- MACRF={(R|W|R,W)}
- specifies the type of macros (READ, WRITE, and NOTE/POINT) that
are used to process the data set. You can specify the following characters
for BPAM:
- R
- specifies that READ macros are to be used. This subparameter automatically
allows you to use both the NOTE and POINT macros with the data set.
R is required if the OPEN option is INPUT or UPDAT. It has no effect
if the OPEN option is OUTPUT or EXTEND.
- W
- specifies that WRITE macros are to be used. This subparameter
automatically allows you to use both the NOTE and POINT macros with
the data set. W is required if the OPEN option is OUTPUT or EXTEND.
It has no effect if the OPEN option is INPUT. W may be specified if
the OPEN option is UPDAT.
All BPAM READ and WRITE macros issued must
be tested for completion using a CHECK macro. MACRF does not require
any coding to specify that a CHECK macro is to be used.
Source: MACRF
must be specified in the DCB macro.
- NCP=absexp (maximum value is 255)
- specifies
the maximum number of READ and WRITE macros that are issued before
the first CHECK macro is issued to test completion of the I/O operation.
In an address space that is constrained for storage below the line,
requesting too large a number may result in abnormal termination of
the program. If NCP is omitted, 1 is assumed unless you coded the
MULTSDN parameter on the DCBE macro.
To request the
system to default a value for NCP other than 1, you must supply a
DCBE and set MULTSDN to nonzero. The system will update DCBNCP with
the system-defaulted NCP (SDN) before the DCB OPEN exit is given control.
This allows you to give the system indicators without being dependent
on device information such as blocks per track. If you change parameters
in the OPEN exit which would cause recalculation of system-determined
block size, or you change block size, the SDN will be re-derived after
the OPEN exit and stored in the DCBNCP.
Source: NCP
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 open exit routine.
- OPTCD={[C][J][W]}
- specifies optional services that are performed by the system.
- C
- specifies that chained scheduling is used. BPAM ignores this obsolete
option.
- J
- specifies that the first data byte in the output data line is
a 3800 table reference character. This table reference character selects
a particular character arrangement table for the printing of the data
line and can be used singly or with ISO/ANSI or machine control characters.
OPEN saves this indication in the data set label and it is available
to programs that read the data. For a partitioned data set, the OPTCD
value applies to all members.
- W
- specifies that the system is to perform a validity check for each
block written.
OPTCD=W is ignored for PDSEs.
Source: OPTCD
can be supplied in the DCB macro, in the DCB subparameter of a DD
statement, or by the problem program before an OPEN macro is issued
to open the data set. However, all optional services must be requested
from the same source.
- RECFM={{U[T][A|M]}
- {V[B[T]|T][A|M]}
- {F[B[T]|T][A|M]}}
- specifies the record format and characteristics of the data set
being allocated or processed. All the record formats
shown above can be specified, but in those record formats that show
blocked records, the problem program must perform the blocking and
deblocking of logical records. BPAM recognizes only data blocks. You
can specify:
- A
- specifies that the records in the data set contain ISO/ANSI control
characters. For a description of control characters, see Control characters.
- B
- specifies that the data set contains blocked records.
- F
- specifies that the data set contains fixed-length records.
- M
- specifies that the records in the data set contain machine code
control characters. For a description of control characters, see Control characters.
- T
- specifies
that track overflow is used with the data set. Track overflow allows
a record to be written partially on one track of a direct access storage
device and the remainder of the record to be 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, by 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 (SYNAD) routine to be given control
when an uncorrectable input/output error occurs. The entry point of
this SYNAD routine must reside below the line. If you wish the entry
point to reside above the line, use the SYNAD parameter of the DCBE
macro. You can also use the technique shown in Figure 1. 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 system detects I/O errors asynchronously. It calls
your SYNAD routine synchronously (hence the name SYNAD) when you issue
a CHECK macro for the failed block. If SYNAD is omitted in the DCB
and DCBE, the task is abnormally terminated when you issue a CHECK
and an uncorrectable input/output error occurred.
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. If control is returned in this manner, the system returns
control to the problem program and proceeds as though no error had
been found.
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.
|
z/OS DFSMS Macro Instructions for Data Sets
Copyright IBM Corporation 1990, 2014