Chapter 9. CAL Defined Sequences

9.1.1. Editing

Assembler editing is disabled at definition time. The body of the definition (see Section 9.1.2) is saved before micros and concatenation marks are edited.

If editing is enabled, editing of the definition occurs during assembly each time it is called. The ENDDUP, ENDM, END, INCLUDE, and LOCAL pseudo instructions and prototype statements should not contain micros or concatenation characters because they may not be recognized at definition time.

When a sequence is defined, editing is disabled and cannot be explicitly enabled. When a sequence is called, the assembler performs the following operations:

• Checks all parameter substitutions marked at definition time

• Edits the statement if editing is enabled

• Processes the statement

By disabling editing at definition time (default) and specifying the INCLUDE pseudo instruction with embedded underscores, a saving in program overhead is achieved. Because editing is disabled at definition time, concatenation does not occur until the macro is called. If editing is enabled when the macro is called, the file is included at that time. This technique is demonstrated in the following example:

MACRO INC . . . IN_CLUDE MYFILE ; INCLUDE pseudo instruction with an embedded . ; underscore . . ENDM

Embedding underscores in an INCLUDE pseudo instruction becomes desirable when the INCLUDE pseudo instruction identifies large files. Because files are included when the macro is called and not at definition time, embedding underscores in the INCLUDE pseudo instruction can reduce the overhead required for a program.

9.1.2. Definition Format

MACRO, OPDEF, DUP, and ECHO pseudo instructions use the same definition format. The format consists of a header, body, and end.

The header consists of a MACRO, OPDEF, DUP, or ECHO pseudo instruction, a prototype statement for a MACRO or OPDEF definition, and, optionally, LOCAL pseudo instructions. For a macro, the prototype statement provides a macro functional definition and a list of formal parameters. For an opdef, the prototype statement supplies the syntax and the formal parameters.

LOCAL pseudo instructions identify parameter names that the assembler must make unique to the assembly each time the definition sequence is placed in a program segment. Asterisk comments can be placed in the header and do not affect the way the assembler scans the header. Asterisk comments are dropped from the definition. To force asterisk comments into a definition, see Section 6.10.5.

The body of the definition begins with the first statement following the header. The body can consist of a series of CAL instructions other than an END pseudo instruction. The body of a definition can be empty, or it can include other definitions and calls. A definition used within another definition is not recognized, however, until the definition in which it is contained is called; therefore, an inner definition cannot be called before the outer definition is called for the first time.

A comment statement identified by an asterisk in column l is ignored in the definition header and the definition body. Such comments are not saved as a part of the definition sequence. Comment fields on other statements in the body of a definition are saved.

An ENDM pseudo instruction with the proper name in the label field ends a macro or opdef definition. A statement count or an ENDDUP pseudo instruction with the proper name in the label field ends a dup definition. An ENDDUP pseudo instruction with the proper name in the label field ends an echo definition.

9.1.3. Formal Parameters

Formal parameters are defined in the definition header and recognized in the definition body. Four types of formal parameters are recognized as follows:

• Positional

• Keyword

• Echo

• Local

The characters that identify positional, keyword, echo, and local parameters must all have unique names within a given definition. Positional, keyword, and echo parameters are also case-sensitive. To be recognized, you must specify these parameters in the body of the definition exactly as specified in the definition header. Parameter names must meet the requirements for identifiers as described in Section 6.3.

You can embed a formal parameter name within the definition body; however, embedded parameters must satisfy the following requirements:

• The first character of an embedded parameter must begin with a legal initial-identifier-character.

• An embedded parameter cannot be preceded by an initial-identifier-character (for example, PARAM is a legally embedded parameter within the ABC_PARAM_DEF string because it is preceded by an underscore character). PARAM is not a legally embedded character within the string ABCPARAMDEF because it is preceded by an initial-identifier-character (C).

• An embedded parameter must not be followed by an identifier-character.

  In the following example, the embedded parameter is legal because it is followed by an element separator (blank character):

  PARAM678

  In the following example, the embedded parameter is illegal because it is followed by the identifier-character 9:

  PARAM6789

• Embedded parameters must contain 8 or less characters. PARAM6789 is illegal because it contains 9 characters. The character that follows an embedded parameter (9) cannot be an identifier-character.

• If and only if the new format is specified, an embedded parameter must occur before the first comment character (;) of each statement within the body.

• An embedded parameter must have a matching formal parameter name in the definition header.

• Formal parameter names should not be END, ENDM, ENDDUP, LOCAL, or INCLUDE pseudo instructions. If any of these are used as parameter names, substitution of actual arguments occurs when these names are contained in any inner definition reference.

  Note: If the file is included at expansion time, arguments are not substituted for formal parameters into statements within included files.

9.1.4. Instruction Calls

Each time a definition sequence of code is called, an entry is added to a list of currently active defined sequences within the assembler. The most recent entry indicates the current source of statements to be assembled. When a definition is called within a definition sequence that is being assembled, another entry is made to the list of defined sequences, and assembly continues with the new definition sequence belonging to the inner, or nested, call.

At the end of a definition sequence, the most recent list entry is removed and assembly continues with the previous list entry. When the list of defined sequences is exhausted, assembly continues with statements from the source file.

An inner nested call can be recursive; that is, it can reference the same definition that is referenced by an outer call. The depth of nested calls permitted by CAL is limited only by the amount of memory available.

The sequence field in the right margin of the listing shows the definition name and nesting depth for defined sequences being assembled. Nesting depth numbers begin in column 89 and can be one of the following: :1, :2, :3, :4, :5, :6, :7, :8, :9, :*.

If the nesting depth is greater than 9, the assembler keeps track of the current nesting level; an asterisk represents nesting depths of 10 or more. Nesting depth numbers are restricted to two characters so that only the two rightmost character positions are overwritten.

If the sequence field (columns 73 through 90) of the source file is not empty, the assembler copies the existing field for a call into every statement expanded by the call reserving columns 89 and 90 for the nesting level. For example, if the sequence field for MCALL was LQ5992A.112, the sequence field for a statement expanded from MCALL would read as follows:

LQ5992A.1l2 :l

Additional nested calls within MCALL would change the nesting level, but the sequence field would be unchanged during MCALL. For example:

LQ5992A.112 :2 LQ5992A.l12 :2 LQ5992A.112 :2 LQ5992A.112 :3 LQ5992A.112 :* LQ5992A.112 :l

If the sequence field (columns 73 through 90) of the source file is empty, the assembler inserts the name of the definition, as follows:

In all cases, the first two columns of the sequence field contain asterisks (**) to indicate that the assembler has generated the sequence field. Columns 89 and 90 of the sequence field are reserved for the nesting level. If, for example, the sequence field is missing for MCALL, it would read as follows:

** MCALL :1

Additional nested calls within MCALL would change the nesting level, but the sequence field number would be unchanged for the duration of MCALL.

The following example illustrates how the assembler tracks the nesting sequence:

*MCALL :1 *MCALL :2 *MCALL :2 *MCALL :2 *MCALL :3 ** MCALL :* ** MCALL :1

9.1.5. Interaction with the INCLUDE Pseudo Instruction

The INCLUDE pseudo instruction operates with defined sequences, as follows: