Use this general macro to perform the following actions:
- Create a new data event control block (DECB)
- Locate an existing DECB
- Swap a core block between a DECB and an entry control block (ECB) data
level
- Release an existing DECB that is no longer in use
- Determine if a given address references a valid DECB that is in
use.
Format
- label
- A symbolic name can be assigned to the macro statement.
- FUNC
- Specifies the requested DECB action. The following values are
allowed:
- CREATE
- Create a new DECB.
- LOCATE
- Locates a previously allocated DECB with a name matching the value
specified in the NAME parameter or locates the next DECB in the chain
specified by the CHAIN parameter.
- RELEASE
- Releases the DECB referenced in the DECB or NAME parameters (if the DECB
is not currently in use).
- SWAPBLK
- Exchanges core block and related information between a DECB and a
specified ECB data level.
- VALIDATE
- Determines if the DECB specified is a valid DECB.
- DECB=(reg)|label1
- For FUNC=CREATE and FUNC=LOCATE, specifies the label or general register
where the address of the DECB is to be returned. For all other actions,
specifies the label or general register containing the address of a valid DECB
for which the specified action is to be performed. For E-type programs,
allowable register values are R1-R7. For control programs (CPs),
allowable register values are R1-R7, R14, or R15.
- NAME=(reg)|label2
- The general register containing the address (or a label indicating the
address) of a 16-byte name associated with a DECB. For E-type programs,
allowable register values are R0-R7. For CPs, allowable register
values are R0-R7, R14, or R15.
- CHAIN
- Specifies the next DECB entry to be returned.
- INUSE
- Returns the next active DECB chained to the current DECB. The
register specified by the DECB parameter indicates the address of the current
DECB. If the register specified by the DECB parameter contains a value
of zero, it returns the first active DECB.
- ANY
- Returns the next allocated DECB without first verifying that the DECB is
active. The register specified by the DECB parameter indicates the
address of the current DECB. If the register specified by the DECB
parameter contains a value of zero, the first DECB will be returned without
verifying the active state of the DECB.
- WKREG=(reg)
- Specifies an available general register (R1-R7, R14, or R15) to be
used on the macro call. If no register is specified, the default
register is R14.
- LEVEL=level
- Specifies a valid ECB data level (D0-DF).
- ERROR=label3
- The label in which to branch if an error occurs during processing of the
macro. If ERROR is not specified and an error occurs, control will
return to the next sequential instruction (NSI). The caller then checks
the contents of the register specified on the RC parameter for the associated
return code.
- RC=(reg)
- Specifies the general register (R0-R7, R14, or R15) where the return
code is placed when the macro ends. For E-type programs, R15 must be
specified.
Entry Requirements
R9 must contain the address of the ECB being processed.
Return Conditions
- When called from an E-type program, the contents of R14 and R15 cannot be
predicted. The contents of all other registers are maintained.
- The register specified on the RC parameter contains the return code from
one of the following:
- DECBC_OK
- The request completed successfully.
- DECBC_DUPNAME
- The NAME parameter specified for FUNC=CREATE contains a DECB name that
already exists for this ECB.
- DECBC_NOTFOUND
- A DECB matching the input search criteria could not be found when
specifying FUNC=LOCATE.
- DECBC_NOTVALID
- The DECB specified for FUNC=VALIDATE did not reference a valid DECB
address or the DECB is no longer in use.
Programming Considerations
- The DECB is an alternative to standard ECB data level information.
Data level information is used to specify information about I/O request (core
block reference word (CBRW) and file address reference word (FARW))
fields. The DECB fields specify the same CBRW and FARW information
without requiring the use of a data level in the ECB. All the same
requirements and conditions that apply to the CBRW and FARW in the ECB also
pertain to the same field information in the DECB.
- The FARW in the DECB provides storage for an 8-byte file address.
The DECB layout is in the IDECB DSECT (see the IDECB DSECT for more
information about the fields in a DECB).
- FUNC=SWAPBLK is not intended to perform the same operation as the FLIPC
macro, which is for ECB data levels. When FUNC=SWAPBLK is specified,
only the CBRW information is exchanged between the specified DECB and ECB data
level.
- Macros that support the use of a DECB (such as FILEC, FINDC, and others)
will only accept a DECB address as a valid reference to the DECB. If an
application does not maintain the address of a particular DECB and instead
maintains the name of the DECB, the caller will first have to issue the DECBC
macro with the FUNC=LOCATE parameter to obtain the address of the desired
DECB. The resulting address of the DECB can then be passed to the
subsequent macro call.
- FUNC=LOCATE specified with the CHAIN parameter is intended for use by
system utilities that have a requirement to step through each DECB associated
with a particular ECB. This parameter must only be used when the
application is running in the ECB virtual memory (EVM).
- The letters I, i, TPF, TPF_, tpf, and tpf_ are reserved for future use by
IBM for DECB name spaces.
Examples
- The following example obtains a DECB and assigns it a name of
TESTDECB. The address of the newly created DECB is returned in register
7 (R7).
DECBC FUNC=CREATE,DECB=(R7),NAME=NEWDECB
NEWDECB DC CL16'TESTDECB'
- The following example exchanges the core block information from the DECB
whose address is represented in R5 and data level 3 of the ECB.
DECBC FUNC=SWAPBLK,DECB=(R5),LEVEL=D3
- The following example releases the DECB named DATABLK1.
DECBC FUNC=RELEASE,NAME=RELDECB
RELDECB DC CL16'DATABLK1'
- The following example locates the DECB named DATABLK2 and returns its
address in R3.
LA R1,DECBNAME
DECBC FUNC=LOCATE,DECB=(R3),NAME=(R1)
DECBNAME DC CL16'DATABLK2'