Use the RUNCHAIN subcommand to process a chain of control blocks.
You can specify the links to follow and a mask to apply to the links.
You can also limit the length of the chain to prevent infinite loops.
With z/OS® Release 3 and higher,
you can also specify that attributes and data within a chain of data
areas is to determine their order of processing by the RUNCHAIN subcommand.
RUNCHAIN displays each control block and creates entries for each
control block in the symbol table that is part of the source description
for your current source. You can specify a control block name for
each symbol.
You can specify additional subcommand, CLIST, or REXX exec processing with the EXEC
parameter. For each control block in the chain, RUNCHAIN will display
the storage, set the value of X to the address of the control block,
and then process the EXEC parameter for that control block.
You can also process multiple levels of control block chains by
specifying another RUNCHAIN subcommand on the EXEC parameter.
- Related subcommands
- DROPSYM
- EQUATE
- LISTSYM
- RUNCPOOL
- RUNARRAY
- Syntax
{ RUNCHAIN | RUNC }
[ data-descr | ADDRESS(X) ]
[ AMASK(mask) ]
[ CHAIN [(nnn|999)] ]
[ DROP | NODROP ]
[ EXEC((clist|rexx-exec|subcommand)) ]
[ LINK(range[LENGTH(integer)])] [ MASK(mask) ]
[ NAME(prefix) ]
[ NULL [(value|0)] ]
[ SORTBY(sort-key [ ASCENDING | DESCENDING ] ...) ]
-------- SETDEF-Defined Parameters -------------------------
Note: You can override the following SETDEF parameters.
See SETDEF subcommand — set defaults.
[ DISPLAY[(display-options)] ]
[ NODISPLAY[(display-options)] ]
[ FLAG(severity) ]
[ PRINT | NOPRINT ]
[ TERMINAL | NOTERMINAL ]
[ TEST | NOTEST ]
[ VERIFY | NOVERIFY ]
- Parameters
- data-descr or ADDRESS(X)
- Specifies the data description parameter, which consists of five
parts:
- An address (required when data-descr is explicitly
specified on the subcommand)
- Address processing parameters (optional)
- An attribute parameter (optional)
- Array parameters (optional)
- A remark parameter (optional)
Data description parameter explains the use and syntax
of the data description parameter. However, the following exceptions
apply to RUNCHAIN only:
- The address is not a positional parameter. You must use
the ADDRESS parameter to specify an address.
- If you omit the ADDRESS parameter, the default for the RUNCHAIN
subcommand is ADDRESS(X), the most recently accessed address.
- AMASK(mask)
- Specifies an unsigned integer mask that RUNCHAIN is to AND to
the link field before using that field as the address of the next
block in the chain. IPCS accepts 64-bit values and interprets all
values entered as having 64-bit precision. If the chain originates
below 224, the default is X'00FFFFFF'. If the
chain originates above 224, the default is X'7FFFFFFF'.
If the chain originates above the bar, the default is X'FFFFFFFF_FFFFFFFF'.
- CHAIN[(nnn|999)]
- Specifies the maximum number of blocks the subcommand is to process.
The number can be a maximum of 16,777,215 and can be specified in
decimal, hexadecimal (X'xxx...'), or binary (B'bbb...').
If
you omit this parameter, the default is CHAIN(999).
- DROP or NODROP
- Specifies the DROP or NODROP attribute for the names RUNCHAIN
places in the symbol table. RUNCHAIN places the names of the control
blocks it finds in the symbol table when you specify the NAME parameter.
DROP
specifies the DROP attribute. This attribute allows the symbols to
be deleted from the symbol table by a DROPSYM subcommand.
NODROP
specifies the NODROP attribute. This attribute prevents the symbols
from being deleted from the symbol table by a DROPSYM subcommand,
unless DROPSYM contains a PURGE parameter.
- EXEC((clist|rexx-exec|subcommand))
- Specifies that a CLIST, a REXX exec, or an IPCS subcommand is to be appended
to the RUNCHAIN subcommand invocation. The appended CLIST, REXX exec, or
subcommand runs for each control block in the chain. Parameters or
keywords can accompany the CLIST, REXX exec, or IPCS subcommand. The symbol X
will point to the current control block on the chain before each EXEC
invocation.
The EXEC parameter also accepts another RUNCHAIN invocation
to process multiple levels of control blocks. See the BLSCRNC2 CLIST
in SYS1.SBLSCLI0 for an example.
The RUNCHAIN subcommand generates
a return code that consists of its own return code plus the return
code from the CLIST, REXX exec,
or IPCS subcommand designated on the EXEC parameter. If the CLIST, REXX exec, or
IPCS subcommand returns with a serious condition, RUNCHAIN processing
ends with the current control block.
- LINK(range[LENGTH(integer)])
- Defines a range of offsets that contain a 1-8 byte pointer from
one block in the chain to the next.
LINK(0:3) 4-byte pointer at the origin of the block
LINK(8:15) 8-byte pointer at displacement 8 in the block
LINK(8:4) Error. Descending range
Range consists
of one or two an unsigned integers. The end of the range may be omitted
or can be designated using LENGTH(integer). For compatibility with
earlier releases, RUNCHAIN treats this as a description of a 4-byte
pointer.
The link pointer is always extended to 8-bytes before
masking, nullity checking, and use for access to the next block on
the chain.
If you omit this parameter, the default is LINK(0).
- MASK[(mask)]
- Specifies an unsigned integer mask that RUNCHAIN is to AND to
the link field before comparing it to the value specified with the
NULL parameter. IPCS accepts 64-bit values and interprets all values
entered as having 64-bit precision.
The length of the mask must
be eight bytes. If it is less than eight bytes, the subcommand right-justifies
it and pads it on the left with zeros. If it exceeds eight bytes,
the subcommand rejects it.
You can specify the mask in decimal,
hexadecimal (X‘xxx...’), or binary (B‘bbb...’). If you specify it
in decimal or binary, the value is converted to its hexadecimal equivalent
and padded if needed.
If you omit this parameter, the default
for all chains is MASKX'FFFFFFFF_FFFFFFFF'.
- NAME(prefix)
- Specifies the prefix RUNCHAIN uses to generate names for each
control block it finds. The subcommand places the generated names
in the symbol table. The generated name can be 1 to 31 alphanumeric
characters and the first character must be a letter or the characters
“$”, “@”, or “#”.
RUNCHAIN appends a sequence number to the prefix
to produce a unique control block name. The sequence number starts
at 1 and is limited by the value specified with the CHAIN parameter.
The
prefix for any control block may not exceed 30 characters.
If
you omit this parameter, RUNCHAIN does not generate names for the
control blocks it finds.
- NULL[(value|0)]
- Specifies the unsigned integer doubleword value that indicates
the end of the chain. IPCS accepts 64-bit values and interprets all
values entered as having 64-bit precision.
For each control block
on the chain, RUNCHAIN:
- Locates the link field at the offset specified in the LINK parameter.
- ANDs the mask with the contents of the link field.
- Compares the result of the AND with the NULL value.
- When the result of the comparison is equal, chaining ends.
- When the result of the comparison is not equal, chaining continues.
- SORTBY(sort-key [ASCENDING|DESCENDING)...]
- Controls the order of processing for chain elements.
- sort-by
- A list of sort-keys directs RUNCHAIN to make two passes over the
chain. The first pass internally enumerates the blocks on the chain
and collects up to 256 bytes of aggregate sort key data.
If any
data described as a sort key cannot be retrieved, the chain is logically
terminated at the preceding block during the first pass.
Each
sort-key may be designated in one of the following ways:
- signed-integer[:signed-integer]
- Designates a range of offsets from the origin of the block. A
string or unsigned binary number at those locations is used as a
sort key. If the end of the range is not specified, four bytes are
selected.
- ADDRESS
- DIMENSION
- LENGTH
- MULTIPLE
- These keywords designate an unsigned attribute of the block. Each
of these attributes uses 8 bytes of the 256 available.
- ENTRY
- POSITION
- These keywords designate a signed attribute of the block. A signed
comparison between thers attributes is performed. Each of these attributes
uses 8 bytes of the 256 available.
- DATATYPE
- The DATATYPE keyword designates the type of block, for example,
STRUCTURE(UCBDASD) versus STRUCTURE(UCBTAPE). Each of these attributes
uses 34 bytes (see Data Area BLSRDATT) of the 256 available.
- ASCENDING
- DESCENDING
- These keywords designate the sort order for the preceding key.
Ascending sort order is the default.
- Return codes
See Standard subcommand return codes for
a description of the return codes produced by the RUNCHAIN subcommand.
The
RUNCHAIN subcommand generates a return code that consists of its own
return code plus the return code from a CLIST, REXX exec, or IPCS subcommand if
designated by the EXEC parameter. If the CLIST, REXX exec, or IPCS subcommand returns
with a serious condition, RUNCHAIN processing ends with the current
control block.
- Example: The
BLSCRNCH CLIST runs the chain of task control blocks (TCB) for an
address space. It displays the following information:
- The current TCB
- The TCBs that are lower on the priority chain in that address
space
- The currently dispatched RB for each of the TCBs
This CLIST, written for SVC dumps, uses the RUNCHAIN subcommand
as follows:
PROC 0 TCB(21C.%)
RUNCHAIN ADDRESS(&TCB) STRUCTURE(TCB) /* Process TCBs */+
LINK(X'74') /* Connected by field TCBTCB */+
VERIFY DISPLAY /* Maximum display for each TCB */+
EXEC((LIST X+0% STRUCTURE(RB) DISPLAY))/* Show RB for TCB*/
The logic of this CLIST is as follows:
- PROC 0 TCB(21C.%)
- This line indicates that the default path to the first TCB is
the fullword pointer at location X‘21C’.
- RUNCHAIN ADDRESS(&TCB) STRUCTURE(TCB)
- This line processes the first TCB that can be found by using the
default path or an alternate path to a TCB, described when the CLIST
is invoked. IPCS validates the TCB and creates a storage map entry
for it. The STRUCTURE attribute parameter identifies that a TCB is
being processed.
Note: If SDUMP writes the dump, IPCS does not require
address processing parameters. IPCS establishes the dumped ASID as
the default address space.
- LINK(X'74')
- This line establishes addressability to the TCBTCB field at offset X'74' for
each TCB, thereby providing the address of the next TCB on the chain
to be processed.
- VERIFY DISPLAY
- This line lists all TCBs found on the chain and displays the maximum
amount of information for each TCB. The VERIFY and DISPLAY parameters
each override the defaults established by the SETDEF subcommand for
the corresponding parameter.
- EXEC((LIST X+0% STRUCTURE(RB) DISPLAY))
- This line updates the current TCB that is currently being processed,
establishes addressability to the TCBRBP field at offset X'0' within
the current TCB, and accesses the RB related to the current TCB.