RUNCHAIN subcommand — process a chain of control blocks

• DROPSYM
• EQUATE
• LISTSYM
• RUNCPOOL
• RUNARRAY

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 2²⁴, the default is X'00FFFFFF'. If the chain originates above 2²⁴, 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.

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.

• 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*/