EXPAND Command

The EXPAND command causes the text of a specified declaration to be written out (expanded) if the identifier is an item such as a DEFINE, ARRAY, or FILE statement that has text associated with its declaration.

The identifier specified in the EXPAND command becomes the new work identifier. If no identifier is specified, the current work identifier is used.

Unless the EXPAND command is modified by the available options, the action taken is as follows:

  • The first time the work identifier is expanded, the text of the declaration is given.

  • Subsequent requests to expand the work identifier cause this text to be scanned for occurrences of other DEFINE statements. If such nested DEFINE statements are found, they are replaced by their text. This process can be repeated, one step at a time, until the text is completely expanded (that is, no more nested DEFINE statements are found), a new work identifier is specified, or the work identifier is nullified.

  • Once the expansion is complete, a message to that effect is displayed. Subsequent requests to expand the work identifier cause the final version to be displayed.

The expansion of a DEFINE statement is context-sensitive. A DEFINE statement can be used within a procedure or block more local than that in which it was declared. In this case, the inner procedure or block might have redeclared some of the identifiers used in the text of the DEFINE statement. Unless the identifier was specified using a qualification such as AT<sequence number>, which gives some indication of the context to be used, a context must be chosen. If the DEFINE statement is referenced, it is expanded in the context of its first reference. If the DEFINE statement is never referenced, it is expanded in the context of its declaration. In either case, a warning message is displayed.

You must load the symbol file to use this command.

Syntax 

── EXPAND ─┬──────────────────────────────────────────┬────────────────┤
           │ ┌◄─────────────────────────────────────┐ │
           └─┴─┬─/1\─ : ── FULL ──────────────────┬─┴─┘
               ├─/1\─ : ── PARAMETERS ────────────┤
               ├─/1\─ : ── BLOCKED ───────────────┤
               ├─/1\─ : ── PRINTER ───────────────┤
               ├─/1\─ : ── REMOTE ────────────────┤
               └─/1\─┬─<identifier specification>─┤
                     └─ AT ──<sequence number>────┘

Explanation

EXPAND

Expands the work identifier. The work identifier is the identifier used in the most recently entered LOCATE, REFERENCE, EXPAND, or SUMMARY command. If no identifier is specified and the work identifier is empty, an error occurs.

FULL

Causes the text to be completely expanded before it is displayed.

PARAMETERS

If the identifier being expanded is a DEFINE with parameters, and if it is being expanded in the context of a reference, then actual parameters are extracted from the text of that reference and substituted for the formal parameters in the expansion. Even if the expansion was complete before the actual parameters were inserted, the expansion reverts to the incomplete state because the actual parameters can contain identifiers that are DEFINE statements.

Note: If both the FULL option and the PARAMETERS option are specified, the actual parameters are inserted before the full expansion is performed. PARAMETERS works only if the DEFINE statement was referenced directly and not by another DEFINE statement.

BLOCKED

Causes the first expansion to be blocked, that is, to indent at the BEGIN statement and place statements on separate lines. By default, the first expansion is printed out exactly as it appears in the symbol file (including comments). Subsequent levels of expansion are blocked.

PRINTER

Sends output to the line printer by way of a file internally named LINE.

REMOTE

Sends output to the terminal. This option can be used when PRINTER has been specified so that output is sent to the terminal as well as the printer.

<identifier specification>

Specifies the identifier to be expanded.

AT <sequence number>

Expands the identifier in the context of the reference nearest the specified sequence number.

Examples

The following examples use the example INTERACTIVEXREF program contained at the end of this section. These examples feature each step of the expansion process in order to show the effect of entering several EXPAND commands in a row.

The following command establishes EQUATION as the work identifier and gives the text of the declaration: 

EXPAND EQUATION
      EQUATION  ::  DEFINE  ::  DECLARED @ 00002000
        EQUATION=R[ONEE] + R[TWOO] * R[THREE] - R[MORE] / R[ONEE];
      %

The first time the work identifier is expanded, the output is the expansion of all first-level defines, as follows: 

EXPAND
      *** WARNING: EXPANDING IN CONTEXT OF FIRST USE ***
          EQUATION=R[1]+R[2]*R[3]-R[FOURR]/R[1];
      %

The next EXPAND command causes the expansion of all second-level defines: 

EXPAND

       EQUATION=R[1]+R[2]*R[3]-R[4]/R[1];
       %

The next time the work identifier is expanded, the following message indicates that the work identifier is fully expanded: 

EXPAND
EXPANSION COMPLETE

Every time following the completed expansion of the work identifier, the final expansion is given as follows: 

EXPAND

EQUATION=R[1]+R[2]*R[3]-R[4]/R[1];

Considerations for Use

The room available for storing expansion text is limited. The first level of expansion is always completely printed out. Higher levels might be truncated if internal storage is insufficient.

For any given expansion, expansion of nested DEFINE statements is carried out in only one context. Also, text is displayed in complete syntax form, and declarations cannot be distinguished from other statements. As a consequence, higher-level expansions of DEFINE statements that contain declarations might be incorrect.

Prev  Up  Next
DECLARATIONS Command  Home  HELP Command