BLOCKMAP Macro

BLOCKMAP is an XEDIT macro used to map the data areas within DSECTs. These DSECTS can be either IBM supplied or user created so long as they are in ASSEMBLER source format. This macro accepts the data definitions and control statements as input and creates a formatted control block. This formatted control block includes the original input, a map of the data areas defined in the DSECT, and a map of the flags or code-defining EQUates. The formatted control block is a pictorial representation of the DSECT data areas formed by a series of comments, statements, and the original DSECT definition.

Note: The output from the BLOCKMAP macro is z/VM product implementation information for diagnosis and must not be used for programming purposes.

A major portion of any program's internal structure is used for creating and altering control blocks, and for passing information in the form of control blocks or data structures. An important element in the documentation is the support of this function. BLOCKMAP automates this documentation support by

Accepting, as input, the data definition and control statements that define a control block
Producing a map of all flag or code defining equates (EQUs) included in the control block, or of another control block referenced within the current one.

Note: BLOCKMAP and BLOCKDEF no longer support CP control blocks.

BLOCKMAP Conventions

The BLOCKMAP input conventions ensure that control blocks are readable and consistent. A control block is written in System/370 Assembler Language. Because BLOCKMAP creates a map of the control block, only one DSECT is allowed per copy file. A copy file is the file in which the control block is defined and is the term that will be used throughout this guide. The effectiveness of BLOCKMAP depends on adherence to these conventions. A description of these conventions is provided in the following sections.

Field Naming: For notational convenience, control block field names have prefixes specified by 1 to 5 characters. The field names have the same prefix as the prefix on the DSECT label. BLOCKMAP will attempt to use the full name when drawing the control block map. For 1-byte fields, the maximum length is 6 characters. If the name is longer than this, BLOCKMAP will replace the prefix characters with a colon (:). If the resulting name is still too long for the field, BLOCKMAP will use the hexadecimal offset in parentheses as the name. The hexadecimal offset is the offset of the field from the beginning of the control block. In the case of field overflow (a field definition that occupies two lines of the control block image), the field name will appear in both the leading field as well as in the continuation field. The leading field name will have a dash (–) appended to it, while the continuation field name will be prefixed by a dash. If either the leading or continuation fields are 1 byte in length, the total length, including the dash, cannot exceed the 6 characters allowed for the field.

Definition of Reserved Fields: Reserved fields are denoted by a data operand (DS/DC) with no associated field name. Reserved fields are denoted in the control block pictorial as a group of slashes (/), while defined fields contain the field name in the pictorial. Two consecutive undefined fields will be depicted as two undefined fields in the control block pictorial and will not be logically combined to form a single field.

Control Block Structure/ORG Processing: The entire main body of the control block must be defined first. This main definition may have one or more ORG statements that may provide for additional detail for a larger field in the main picture or a complete redefinition of a field based on some device specification. Resetting the location counter to its original value, when the ORG statement is specified without operands, is not supported.

When an ORG statement is encountered, main picture processing is terminated. The data definition statements processed to that point will be appended after the commented statements forming the control block picture. The complete commented control block picture is the main body definition. BLOCKMAP will then enter redefinition mode. Each ORG followed by its data definition(s) will create a new picture for those fields. Redefinitions must not exceed the bounds of the main body definition. The target of an ORG statement must be a previously defined field and cannot be the label on the DSECT statement, another ORG statement, or an EQU statement.

As part of the redefinition picture, the following title line is built:

****     REDEFINITION -  .........

Any comments that appear on the ORG statement up to column 63 will be appended to the title line.

Redefinition Mode and Unnamed Fields: The treatment of unnamed reserved fields is handled differently in redefinition mode. At times, an unnamed field is encountered and the operands describing that field are syntactically equivalent to those appearing at the same displacement in a previous definition. In this case, the picture field generated will contain the name of the previous definition field and will not be depicted as being reserved. REACH-BACK will attempt to define an unnamed field based on the target field of the ORG statement. If this attempt fails, REACH-BACK uses the field name in the main body definition as the field name in the unnamed redefined field.

Variable Length Fields: A variable length field must be the last item in the definition. It is denoted by a replication factor of zero and the control phrase START OF VARIABLE LENGTH DATA in the comment area. The field must be named. Redefinition blocks can have a variable length field only if one was specified in the main definition. The field is drawn in the picture with a series of colons, and no ending address is given.

Operators Supported: BLOCKMAP supports the following operators. Unrecognized statements are passed through, but ignored.

DSECT: Only one accepted per copy file.
DS, DC: Define a block in the picture.
EJECT: See Picture Segmentation Option.
ORG: See Control Block Structure/ORG Processing.
CCW, CCW0, CCW1: Define a doubleword block in the picture.

Data Type Operands Supported: BLOCKMAP is designed to support only a subset of the possible data operand coding conventions. Specifically, only the following data type operands are accepted:

D: Doubleword
F: Fullword
H: Halfword
X: Hexadecimal byte
A: Address constant
V: External address constant
C: Character byte

The alignment implicit to the above operands will be enforced. This means that these operands must be on a boundary divisible by its implicit data length. An exception to this requirement is the presence of a length modifier that negates implicit length alignment. Automatic alignment, and, therefore, undefined holes within the control block, will not be performed. Replication factors on any of the above data types will be accepted. A replication factor of zero will cause the field name to be ignored by BLOCKMAP in the control block picture. However, the operand will be checked for proper alignment. Explicit length modifiers are accepted on data type operands A, C, and X. A replication factor greater than 1 is not accepted in combination with a length modifier for the A type operand; it is permissible for the C and X type operands. C and X type operands that have both a replication factor and a length modifier will be formatted as one contiguous entity. Its length will be equal to the product of the replication factor and length modifier. For example, 2XL2 will be pictorially represented as XL4. Only one data definition operand per statement will be processed. For example, A(0),A(0) will be interpreted as if only one address constant were specified.

Bit and Code Definition Tables: Bit definition tables can be built for all flag byte definitions in the control block, and code definition tables for value equates. The actual bit or code definitions can be contained in this control block, or defined in an external copy file, either formatted or not. When the bit or code equates are in the current file, table formatting is invoked by one of the following phrases in a comment line:

BITS  DEFINED IN fieldname
CODES DEFINED IN fieldname

When the bit or code equates are in an external file, the control phrases have the following format:

BITS DEFINED FOR local-fieldname BY file name fieldname
CODES DEFINED FOR local-fieldname BY file name fieldname

In the external file the bits or codes may be defined by the local form or another format. The local form implies that the actual space for the byte is contained in the structure. The other format is used for global definition copy files that do not themselves define any space.

* fieldname BIT DEFINITION
* fieldname CODE DEFINITION

Bit-defining equates have the following format and can be intermixed within the byte definition:

bitname  EQU    X'xx'                  description
bitname  EQU    bitname1+bitname2...   description

Code-defining equates have one of the following formats; decimal and hex codes cannot be intermixed, nor can 1- and 2-byte fields.

codename  EQU    X'xx'      description
codename  EQU    X'xxxx'    description
codename  EQU    n          description

where x is a hexadecimal number and n is a decimal number.

The first such statement found that fits the above model starts the definition table. Table processing is terminated by one of the following statements:

A statement other than a comment, that does not match the format for the table; for example, a DS, ORG, or inappropriate EQU
A comment statement containing another definition control phrase
The comment statement * END OF DEFINITION
End-of-file.

Note: If codes are defined in an external file, the last line of the external code file must be a comment. If codes/bits are defined in an external file, a comment line must follow the last field that is defined. BLOCKMAP needs this comment starting in column 1 to execute properly.

The field being described must have been defined before the first EQU statement for it. The field name may have any of the following special characters appended to it; they will be ignored.

. (period)
, (comma)
- (hyphen)
= (equal sign)
: (colon)
; (semicolon)

The hexadecimal displacement of the field in the control block is noted in the title line or lines, which replace the invoking comment

****    BITS DEFINED IN fieldname (AT HEX DISPLACEMENT: addr)
****    CODES DEFINED IN fieldname (AT HEX DISPLACEMENT: addr)

or, for an externally defined set of values:

****    BITS DEFINED FOR local-fieldname BY file name fieldname
****    (AT HEX DISPLACEMENT: addr)
****    CODES DEFINED FOR local-fieldname BY file name fieldname
****    (AT HEX DISPLACEMENT: addr)

This title card will replace the BITS DEFINED statement encountered in the input stream. This implies that any additional characters following the field name on the input statement will be ignored. For those flags that are defined against more than 1 byte, multiple DEFINED IN/FOR statements should be used (one for each byte for which the definition applies). These keyword statements must appear before the first EQU model statement but may be separated from each other by intervening comment statements.

As shown in the model of bit-defining EQUs above, a bit name can be defined to have a value equal to the summation of some number of previously defined bit names. The scope of reference for these previously defined bit names is the current flag byte definition only. Bit names defined for other flag bytes cannot be referenced outside of the scope of their flag byte definition. Code definition EQU statements cannot reference labels.

The description portion of the statement can be continued to subsequent statements either by use of the continuation column or by the use of subsequent comment statements. All comment statements that follow an EQU model statement (except for one that contains a control phrase) will be treated as a description continuation.

BLOCKMAP Invocation

BLOCKMAP is an XEDIT macro that is invoked while editing a file containing the control block to be mapped. BLOCKMAP can be issued anywhere in the file, regardless of the current line orientation. Also, any number of files can be active in the XEDIT when BLOCKMAP is invoked.

In order for BLOCKMAP to run, some additional control statements are required. These control statements are found as special tags in the control block prolog. BLOCKMAP looks for a one-line description of the control block following the prolog tag DESCRIPTIVE NAME:. The remaining line is assumed to be the text to be used while building the control block structure. If this tag is not found, a blank line appears in the output. BLOCKMAP looks for the prefix length tag as the switch to indicate that the file should be mapped. The tag must appear as PREFIX_LEN =n, where n is the number of characters that prefix every field in the control block. This prefix is stripped off field names that may be just too long to fit in their storage declaration picture.

BLOCKMAP has many formatting capabilities. For brevity, not all examples are illustrated. A discussion of the formatting capabilities will precede each example of formatting.

Processing: Processing of the input file starts when the first DSECT statement is found. The control block name is the field name of the DSECT. Only one DSECT record per input file is accepted; all others will be ignored with the data following them being considered to be part of the original DSECT definition.

Upon successful completion of BLOCKMAP processing, the screen will be left in edit mode for the work file. It is your responsibility to save or file this work file if it is to be retained. If an error occurs during BLOCKMAP processing, an appropriate error message will be issued. The input file will be oriented such that the current line will be the line that caused the error. The work file created, if any, will be left intact, although it may contain incorrect images because of incomplete processing. There is no need to erase or quit this file before reinvoking BLOCKMAP.

Various Field Pictures: Control block fields are depicted in boxes with a length of 1 doubleword. When required, the doubleword field is segmented to form fullwords, half words, or bytes. The control block picture has the hexadecimal displacement of the doubleword boundary for any box space that starts a new field definition. All control blocks will also have their ending address printed. This address will be printed in the remaining space of an unused doubleword definition or on the line immediately following the last definition.

Fields that cross a doubleword boundary are represented as spanned records. A box space is continued on the next line by using hyphens (-) as continuation characters. Large fields that use spanned records and share a common boundary will have that boundary removed.

The DS or DC field name is centered within the box it defines. A reserved field box will be filled with slashes (/). The field name of a spanned record will appear in both boxes. A field larger than two doublewords will use the standard doubleword box with break symbols (=) instead of vertical lines (|) for the box sides to represent more than one doubleword. This eliminates a huge blank box for fields many doublewords long. The field name of a field larger than a doubleword that shares a common boundary and does not have a break character sequence will be centered in the largest field of the definition.

An abbreviated field name will be used when the name of a byte field is greater than 6 characters. A colon (:) will be substituted for the prefix. If the abbreviated field name of a byte field is larger than 6 characters, the hexadecimal displacement will be placed in the field.

Redefinition Pictures: Any redefinition of fields must occur after the entire control block has been defined. When an ORG is encountered, main picture processing ends. Each ORG followed by its data definition will cause a new picture to be drawn. A title line,

****     REDEFINITION -  .........

will be written before the picture is drawn.

The starting displacement for redefinitions is defined by the ORG operand. For redefinitions that do not start on doubleword boundaries, the control block picture will be indented the appropriate number of spaces needed to represent the degree of offset from a doubleword boundary. The left-hand edge will contain the doubleword boundary address upon which the control block definition falls. If the offset from this boundary is greater than a byte, the adjusted address (doubleword address offset) will also be included in the picture. This adjusted address is printed in the indentation space immediately to the left of the first box.

Figure 2 illustrates the redefinition of fields. The original input statements used to generate the picture are left in the example.

This figure illustrates the redefinition of fields. — Figure 2. Redefinition of Fields

Bit and Code Definition Tables: Figure 3 illustrates the bit and code definition facility used by BLOCKMAP. The bits and codes can be in the same file as the control block definition or in an external file. The control block in SAMPLE3 will have to look externally, in CODES COPY, for the bit and code definitions. For a detailed discussion of the bit and code definition conventions used by BLOCKMAP, refer to BLOCKMAP Conventions.

Figure 4. Bit and Code Definition (Part 2 of 2)

CODES DEFINED FOR SAMCODES BY CODES STANDARD
(AT HEX DISPLACEMENT: 1)

VALUE   NAME     X'VALUE  DESCRIPTION
_______ ________ _______  _____________________________

0       NULL     X'00'    ABSENCE OF MEANING
0       ZERO     X'00'    MEANS THE QUANTITY 'NONE'
         
           SPACE 1
           SPACE 2

CODES DEFINED IN SAMLCODE (AT HEX DISPLACEMENT: 2)

VALUE   NAME      DESCRIPTION
_______ ________  ______________________________________

X'0010' SAMINFO   INFORMATION PROVIDED
X'0020' SAMCOMP   FUNCTION COMPLETE
X'09F0' SAMERR09  USER INPUT ERROR

         SAMPLE 1
SAMINFO  EQU    X'0010'   INFORMATION PROVIDED
SAMCOMP  EQU    X'0020'   FUNCTION COMPLETE
SAMERR09 EQU    X'09F0'   USER INPUT ERROR
SAMOTHER EQU    X'40'     NOT TO BE INCLUDED IN CODES TABLE

General Page Formatting: BLOCKMAP attempts to format the control block, with respect to the organization of groups of data, on page boundaries. Control block pictures will be divided at points that do not contain spanned records. BLOCKMAP will also attempt to maximize the number of lines per page in deciding where to divide a control block. In addition, BLOCKMAP will attempt to keep redefinitions (ORGs) with their associated data definition statements on the same page.

Because of the infinite number of combinations, it may appear that in some cases the formatting performed by BLOCKMAP is not optimal. Therefore, it is suggested that you examine the output to determine the suitability of the formatting performed.

Picture Segmentation Option: For very large control blocks, it is often desirable to break up the commented portion into smaller units. This is accomplished by including commented EJECT statements in the input file as follows:

     blank
EJECT     ,          NEW PICTURE
     count,

When this form of the EJECT statement is encountered, the current image will be completed. The data definition statements processed to that point will be combined to form part of the formatted control block, followed by this EJECT statement. Processing will then continue with the next logical statement, and a new picture will be started. This facility provides for the breaking up of the main body of the control block without entering redefinition. This has significance in the function of reach-back for the processing of undefined fields when in redefinition mode. Use of this option is valid for both main picture processing mode and redefinition mode.

No Picture Option: You can override the normal picture segmentation invoked by an ORG statement by specifying the NO PICTURE option as follows:

ORG:  label NO PICTURE and other comments

If this option is encountered during main picture processing, the current picture is not terminated and will be continued with the next space defining statement. This option lets you perform the following without disrupting the picture:

Define space for operators not recognized by BLOCKMAP
ORG back to the beginning of the reserved space
Enter the unknown operators.

If the option is encountered on an ORG statement after the main picture is closed, the current redefinition picture is closed and processing continues without picture processing until another ORG statement is encountered.