Preprocessor

The preprocessor assignment statement gives a value to a specified preprocessor variable.

The format of the assignment statement is:

%target = expression;

For arithmetic operations, only decimal integer arithmetic of precision (10,0) is performed. Each operand and all results are converted, if necessary, to a fixed decimal value of precision (10,0). Fractional digits are truncated.

The %Null statement performs no action.

The format of the %Null statement is:

%;

The most common use for the %Null statement is as the target statement of a %THEN or %ELSE clause in an %IF statement. For example:

%IF
   ERROR() > 0;
%THEN
   %GOTO FIXIT;
%ELSE
   %;

The %ACTIVATE statement makes preprocessor variable and procedure identifiers eligible for replacement. If the compiler encounters the named identifier after executing a %ACTIVATE statement, it initiates variable replacement.

The format of the %ACTIVATE statement is:

% { ACTIVATE }
  { ACT      }
element
[ RESCAN   ]
[ NORESCAN ]
,...;

An identifier is activated by either a %ACTIVATE statement or a %DECLARE statement. When an activated identifier is encountered by the compiler, in unquoted nonpreprocessor statements, the variable name or procedure reference is replaced by its value. Replacement continues throughout the rest of the source program unless replacement is stopped with the %DEACTIVATE statement.

You can activate several variables with a single statement. For example:

%DECLARE (A,B,C) FIXED;
%ACTIVATE (A,B), C NORESCAN;

Because RESCAN is the default action, this statement activates A and B with the RESCAN option. C is activated, but is not rescanned.

If an identifier that is not a preprocessor variable or procedure is the target of a %ACTIVATE statement, a warning message is issued and the identifier is implicitly declared as a preprocessor variable with the FIXED attribute. Thereafter, the identifier variable is eligible for replacement when activated.

For example:

DECLARE (A,B,C) FIXED;
%DECLARE (A,B) FIXED;
%ACTIVATE (A,B);

%A = 1;
%B = (A + A);

C = A + B;
PUT SKIP LIST (C);    /* C = 3 */

In this example, the activated preprocessor variables A and B are assigned values by the preprocessor. Notice that variables A and B are also declared as nonpreprocessor variables; this establishes them as variables within the nonpreprocessor program.

In the following example, the variable B is deactivated by the %DEACTIVATE statement.

   ⋮
%DEACTIVATE B;
B = 900;
C = A + B;
PUT SKIP LIST (C);    /* C = 901 */
END;

Because the preprocessor variable B is deactivated, the preprocessor assignment statement %B = (A + A) is not in effect and the value of B is taken from the run-time assignment of B = 900. However, the value of A remains 1.

The %DEACTIVATE statement makes preprocessor variable and procedure identifiers ineligible for replacement. After a variable or procedure has been deactivated, it will not be replaced during preprocessing. Replacement of a deactivated variable or procedure occurs again only after it is reactivated with the %ACTIVATE statement.

The format of the %DEACTIVATE statement is:

% { DEACTIVATE }
  { DEACT      }
element,...;

For example:

TESTF:PROCEDURE OPTIONS (MAIN);
      DECLARE Y FIXED DECIMAL;
      Y = 10;                  /* initial value: Y = 10 */
      %DECLARE Y FIXED;
      %Y = 3;                  /* replacement value: Y = 3 */
      PUT SKIP LIST(Y);        /* output: Y = 3 */
      %DEACTIVATE Y;
      PUT SKIP LIST(Y);        /* output: Y = 10 */
      END;

In this example, %Y, when activated, replaces all the occurrences of the variable Y by the value assigned to %Y, until %Y is deactivated by the %DEACTIVATE statement. The identifier %Y is implicitly activated when it is declared as a preprocessor identifier.

It is possible to deactivate several variables with a single statement. For example:

%DEACTIVATE (A,B,C,D,E,F);

The %DECLARE statement establishes an identifier as a preprocessor variable, specifies the data type of the variable, and activates the identifier for replacement. %DECLARE can occur anywhere in a PL/I source program.

The format of the %DECLARE statement is:

% { DECLARE } element
  { DCL     }
[ FIXED     ] ,...;
[ CHARACTER ]
[ BIT       ]

When a variable is declared in a preprocessor statement, it is activated for replacement and rescanning. The scope of a preprocessor variable is all of the text following the declaration of the variable, unless the variable is declared inside a preprocessor procedure. Using %DECLARE inside of a preprocessor procedure has the effect of declaring a local variable.

For example:

%DECLARE HOUR FIXED;

In this example, HOUR is declared as a preprocessor variable identifier with the FIXED attribute. The compiler supplies the default values that make this declaration the equivalent of the following:

DECLARE HOUR FIXED DECIMAL (10,0) INITIAL (0);

Factored declarations are permitted and follow the same usage rules as nonpreprocessor declarations. For example:

%DECLARE (A,B) CHARACTER, C BIT;

Both A and B are declared with the CHARACTER attribute. The compiler supplies default values that make this declaration the equivalent of the following:

%DECLARE (A,B) CHARACTER VARYING(32500) INITIAL(''),
         C BIT(31)INITIAL((31)'0'B);

The %DICTIONARY statement causes VAX Common Data Dictionary (CDD) data definitions to be incorporated into the current PL/I source file during compilation. The statement can occur anywhere in a PL/I source file. For information on using PL/I with CDD, see Appendix E in the Endless PL/I for OpenVMS User Manual.

The format of the %DICTIONARY statement is:

%DICTIONARY cdd-path;

For example, assume that you have a record with the following path name:

CDD$TOP.SALES.JONES.SALARY

You can then specify a relative path name as follows:

%DICTIONARY 'SALARY';

Or you can specify an absolute path name as follows:

%DICTIONARY '_CDD$TOP.SALES.JONES.SALARY';

The compiler extracts the record definition from the CDD and inserts the PL/I structure declaration corresponding to the record description in the PL/I program.

If the %DICTIONARY statement is not embedded in a PL/I language statement, then the resulting structure is declared with the logical level 1 and the BASED storage attribute is furnished. The logical member levels are incremented from 2. For example:

DECLARE PRICE FIXED BINARY(31);
%DICTIONARY 'ACCOUNTS';

This would result in a declaration of the following form:

DECLARE PRICE FIXED BINARY(31);
DECLARE 1 ACCOUNTS BASED,
          2 NUMBER,
            3 LEDGER CHARACTER(3),
            3 SUBACCOUNT CHARACTER(5),
          2 DATE CHARACTER(12),
             .
             .
             .

Notice that in the above example, ACCOUNTS is a relative dictionary path name.

If the %DICTIONARY statement is embedded in a PL/I language statement, as in a structure declaration, then the resulting structure is declared with no logical level and no storage attribute. Logical member numbers are supplied and incremented from 100. For example:

DECLARE 1 COMMON_INTERFACES STATIC EXTERNAL,
          %DICTIONARY 'ACCOUNTS';   ,
          %DICTIONARY 'ADDRESSES';  ;

Notice the syntax in the above %DICTIONARY example. The %DICTIONARY statement is terminated with the preprocessor terminator semicolon before the normal PL/I line punctuation. The normal PL/I punctuation must also be included so that the final structure declaration will contain proper PL/I punctuation. The previous declaration would result in a declaration of the following form:

DECLARE 1 COMMON_INTERFACES STATIC EXTERNAL,
          100 ACCOUNTS,
              101 NUMBER,
                  102 LEDGER CHARACTER(3),
                  102 SUBACCOUNT CHARACTER (5),
              101 DATE CHARACTER(12),
                 .
                 .
                 .
          100 ADDRESSES,
             .
             .
             .

The CDD supports data types that are not native to PL/I. If a data definition contains an unsupported data type, PL/I makes the unsupported data type accessible by declaring it as data type BIT_FIELD or data type BYTE_FIELD. PL/I does not attempt to approximate a data type that is not supported by PL/I. For example, an F_FLOATING_COMPLEX number is declared BYTE_FIELD(8), not (2)FLOAT(24).

Note, however, that use of these two data types is limited. Data declared with the BIT_FIELD or BYTE_FIELD data type can be manipulated only with the PL/I built-in functions ADDR, INT, POSINT, SIZE, and UNSPEC. A variable declared with either of these data types can be passed as a parameter provided the parameter is declared as ANY. Thus, references to data declared as BIT_FIELD or BYTE_FIELD are limited to contexts in which the interpretation of a data type is not applied to the reference.

PL/I ignores CDD features that are not supported by PL/I, but issues error messages when the features conflict with PL/I.

When you extract a record definition from the CDD, you can choose to include this translated record in the program listing by using the /LIST/SHOW=DICTIONARY qualifiers in the PLI command line. Even if you choose not to list the extracted record, the names, data types, and offsets of the CDD record definition are displayed in the program listing allocation map.

CDD data definitions can contain explanatory text in the CDDL DESCRIPTION IS clause. This text is included in the PL/I listing comments, if /LIST/SHOW=DICTIONARY is specified. For example, you could use CDDL comments to indicate the data type of each structure and member. The punctuation for CDDL comments is the same as for other PL/I programs: the slash-asterisk (/*) and the asterisk-slash (*/).

The %DO statement begins a preprocessor DO-group, a sequence of statements terminating with the %END statement. The preprocessor DO-group must be a simple DO-group and is noniterative, but it can be usefully combined with an %IF statement.

The format of the %DO statement is:

You can include both preprocessor and nonpreprocessor text in a preprocessor DO-group. For example:

%DECLARE T CHARACTER;          /* declare T */
%ACTIVATE T NORESCAN;          /* activate T for replacement */
   ⋮
%IF VARIANT() = 'NONE';
   %THEN
   %DO;
   %T = '''unknown variant'''; /* assign string to T */
   %WARN T;                    /* output unknown variant
                                  warning at compile time */
   INIT_MESSAGE = INIT_MESSAGE||' with '||T; /* assign
                               value of T to nonpreprocessor
                                    variable */
   %END;

This preprocessor DO-group performs several steps. First, a string constant is assigned to T. Then the value of T is used in a preprocessor user-generated diagnostic message. This message is issued at compile time to warn the programmer that the program is compiled with an unknown variant. Finally, the value of T is concatenated with a nonpreprocessor string constant. INIT_MESSAGE, including the value of T, is part of the run-time image.

The %END statement terminates a preprocessor procedure or DO-group.

The format of the %END statement is:

%END;

Preprocessing then continues with the next executable preprocessor statement.

The %ERROR statement provides a diagnostic error message during program compilation.

The format of the %ERROR statement is:

%ERROR preprocessor-expression;

%PLIG-E-USERDIAG, preprocessor-expression

The %FATAL statement provides a diagnostic fatal message during program compilation.

The format of the %FATAL statement is:

%FATAL preprocessor-expression;

%PLIG-F-USERDIAG, preprocessor-expression

The %GOTO statement causes the preprocessor to interrupt its sequential processing of source text and continue processing at the point specified in the %GOTO statement. A %GOTO is useful for avoiding large segments of text in the source program.

The format of the %GOTO statement is:

%GOTO label-reference;

Nonlocal %GOTOs are not permitted. In other words, if a %GOTO is used within a preprocessor procedure, control must not be passed out of the containing procedure. Also, a %GOTO must not transfer control into a preprocessor procedure.

The following example illustrates transfers (forward and backward) and the use of %GOTO:

%TEXT:PROCEDURE RETURNS(CHARACTER);
         ⋮
%CHANG_TEXT: DO;
   ⋮
%IF WARN() = 5
    %THEN
         %GOTO CHANG_TEXT;

    %ELSE
         %GOTO INSERT_TEXT;
             ⋮


%INSERT_TEXT: DO;
   ⋮
%END;

Depending on the status of the %IF statement in this example, program compilation takes one of two courses. Control is transferred either forward to the statement labeled INSERT_TEXT or backward to the statement labeled CHANG_TEXT. The compiled program will then include one of the two blocks, but not both. Notice also in this example that the preprocessor built-in function WARN is used to determine preprocessor action, which makes the program self-diagnostic.

If program text is not compiled because the %GOTO statement transferred control over it, the compiler still checks the basic syntax of all statements. Therefore, comment delimiters and parentheses must balance, apostrophes must be paired correctly, and all statements must end with a semicolon.

The %IF statement controls the flow of program compilation according to the scalar bit value of a preprocessor expression. The %IF statement tests the preprocessor expression and performs the specified action if the result of the test is true.

The format of the %IF statement is:

%IF test-expression %THEN action [%ELSE action];

The %IF statement evaluates the preprocessor test expression. If the expression is true, the action specified following the keyword %THEN is compiled. Otherwise, the action, if any, following the %ELSE keyword is compiled. In either case, compilation resumes at the first executable statement following the termination of the %IF statement, unless a %GOTO in one of the action clauses causes compilation to resume elsewhere.

If an action is not compiled because the alternative action was compiled instead, the compiler still checks the basic syntax of all statements. Therefore, comment delimiters and parentheses must balance, apostrophes must be paired correctly, and all statements must end with a semicolon.

The %INCLUDE statement incorporates text from other files into the current source file during compilation. It can occur anywhere in a PL/I source file; it need not be part of a procedure.

The format of the %INCLUDE statement is:

%INCLUDE { 'file-spec'                 };
         { module-name                 }
         { 'library-name(module-name)' }

%INCLUDE 'SUM.PLI';

%INCLUDE SYSTEM_PROCEDURES;

%INCLUDE 'PROJECT_LIBRARY(MY_MODULE)';

The %INFORM statement specifies a user-written diagnostic informational message to be displayed during program compilation.

The format of the %INFORM statement is:

%INFORM preprocessor-expression;

%PLIG-I-USERDIAG, preprocessor-expression

The %LIST_xxx statement (where xxx is either ALL, DICTIONARY, INCLUDE, MACHINE, or SOURCE) enables the selective listing display of INCLUDE file contents, extracted Common Data Dictionary (CDD) record descriptions, machine code, and source code. The %LIST_xxx statement has a number of forms, each of which enables listing control for specific portions of the source text.

The format of the %LIST_xxx statements are:

{ %LIST_ALL;        }
{ %LIST_DICTIONARY; }
{ %LIST_INCLUDE;    }
{ %LIST_MACHINE;    }
{ %LIST_SOURCE;     }

You must compile the program with the appropriate value specified for the /SHOW qualifier before the above statements can be effective.

The %LIST_xxx form of each statement enables the appearance of the specified information starting with the listing line following the %LIST_xxx statement. If you previously specified %NOLIST_xxx, the %LIST_xxx statement has the effect of reenabling the display.

The text displayed with each form of the %LIST_xxx statement is summarized as follows:

To disable a %LIST_xxx statement, specify %NOLIST_xxx at the appropriate line in the source text.

%LIST_xxx statements cannot be nested.

The %NOLIST_xxx statement (where xxx is either ALL, DICTIONARY, INCLUDE, MACHINE, or SOURCE) disables the selective listing display of INCLUDE file contents, extracted Common Data Dictionary (CDD) record descriptions, machine code, and source code. The %NOLIST_xxx statement has a number of forms; each disables listing control for specific portions of the source text.

The format of the %NOLIST_xxx statements are:

{ %NOLIST_ALL;        }
{ %NOLIST_DICTIONARY; }
{ %NOLIST_INCLUDE;    }
{ %NOLIST_MACHINE;    }
{ %NOLIST_SOURCE;     }

You must compile the program with the /SHOW qualifier before any of these statements can be effective.

The %NOLIST_xxx form of each statement disables the appearance of the specified information starting with the listing line following the %NOLIST_xxx statement. If you previously specified %LIST_xxx, the %NOLIST_xxx statement has the effect of disabling the display.

The following summarizes the text suppressed with each form of the %NOLIST_xxx statement:

To cancel the effect of any of the %NOLIST_xxx statements, specify %LIST_xxx (see Section 10.2.15, “%LIST_xxx”) at the appropriate line in the source text.

The %PAGE statement provides listing pagination without inserting form-feed characters into the source text.

The format of the %PAGE statement is:

%PAGE;

The first source record following the record that contains the %PAGE statement is printed on the first line of the next page of the source listing.

A preprocessor procedure is a sequence of preprocessor statements headed by a %PROCEDURE statement and terminated by a %END statement. A preprocessor procedure executes only at compile time. Invocation is similar to a function reference and occurs in two ways:

The format of the %PROCEDURE statement is:

%label:PROCEDURE [(parameter-identifier,...)]
[STATEMENT]
RETURNS ( { CHARACTER } );
          { FIXED     }
          { BIT       }
     ⋮
[%]RETURN (preprocessor-expression);
     ⋮
[%]END;

The %PROCEDURE statement defines the beginning of a preprocessor procedure block and specifies the parameters, if any, of the procedure. Because the preprocessor procedure is always invoked as a function, the %PROCEDURE statement must also specify (via the RETURNS option) the data type attributes of the value that is returned to the point of invocation.

For example:

%A_VAR = A_PROC();

In this statement, the preprocessor procedure A_PROC is invoked and evaluated, and the result is returned and assigned to the preprocessor variable A_VAR.

As with other PL/I procedures, a parenthesized parameter list specifies the parameters that the preprocessor procedure expects when it is invoked. Each preprocessor parameter specifies the name of a variable declared in the preprocessor procedure. The preprocessor parameters must correspond one-to-one with arguments specified for the preprocessor procedure when it is invoked, except when the STATEMENT option is used.

The value to be returned to the invoking source code is converted to the data type specified in the RETURNS option. The return value replaces the preprocessor procedure reference in the invoking source code. Preprocessor procedures cannot return values through their parameter list. The return value must be capable of being converted to one of the data types CHARACTER, FIXED, or BIT. The maximum precision of the value returned by the %RETURNS statement is BIT(31), CHARACTER(32500), or FIXED(10).

Preprocessor procedures cannot be nested. The scope of a preprocessor procedure is the procedure itself; that is, variables, labels, and any %GOTO statements used inside of the procedure must be local.

A preprocessor procedure is invoked by the appearance of its entry-name and list of arguments. If the reference occurs in a nonpreprocessor statement, the entry name must be active before the preprocessor procedure is invoked. If the entry name is activated with the RESCAN option, the value of the preprocessor procedure is rescanned for further possible preprocessor variable replacement and procedure invocation. You can invoke preprocessor procedures recursively.

When a preprocessor procedure (with or without the STATEMENT option) is invoked from a preprocessor statement, each argument is treated as an expression and the result of executing the preprocessor procedure is returned to the statement containing the invocation.

When a preprocessor procedure is invoked from nonpreprocessor source text, the arguments are interpreted as character strings and are delimited by the appearance of a comma or a right parenthesis occuring outside of balanced parentheses. For example, the positional argument list (Q(E,D), XYZ) has two arguments; the strings 'Q(E,D)' and 'XYZ'.

%A1: PROCEDURE RETURNS(FIXED);
     DECLARE (A,B,C) FIXED;
        A = 2;
        B = 10;
        C = A + B;
        RETURN(C);
     END;

PPFIB: PROCEDURE OPTIONS (MAIN);
       DECLARE Y CHAR(14) INITIAL('Fibonacci Test'); ❶
       %DECLARE Y FIXED; ❷
       %F: PROCEDURE(X) RETURNS (FIXED); ❸
           DECLARE X FIXED;
           IF (X <= 1)
              THEN RETURN(1);
              ELSE RETURN(F(X-1)+F(X-2));
           END;           /* End preprocessor procedure */
       %Y = F(10); ❹
       PUT SKIP LIST(Y);
       %Y = F(11); ❺
       PUT SKIP LIST(Y);
       %Y = F(12); ❻
       PUT SKIP LIST(Y);
       %DEACTIVATE Y; ❼
       PUT SKIP LIST(Y); ❽
       END;               /* End run-time procedure */

89
144
233
Fibonacci Test

%B: PROCEDURE (ALPHA, BETA, GAMMA) STATEMENT...;
    DECLARE (ALPHA, BETA, GAMMA) FIXED;
       ⋮
    END;

B(1,2,3);
B ALPHA(1) GAMMA(3) BETA(2);
B(1) GAMMA(3) BETA(2);
B (,2,3) ALPHA(1);

%APPEND: PROCEDURE (string,to) STATEMENT RETURNS(CHARACTER); ❶

    %DECLARE (string,to) CHARACTER; ❷
    %RETURN (
        'DO;'|| ❸
        'IF LENGTH('||string||')+LENGTH('||to||') > SIZE('||to||')-2'||
        ' THEN DO;'||
           'PUT SKIP LIST (''Buffer overflowed appending to '||to||''');'||
           'SIGNAL FINISH;'|| ❹
           'END;'||
        'ELSE '||to||' = '||to||'||'||string||';'||
        'END;'
              );
     %END;

The preprocessor %REPLACE statement specifies that an identifier is a constant of a given value. It can be used anywhere within a procedure or anywhere in a PL/I source file.

Beginning at the point at which a %REPLACE statement is encountered, PL/I replaces all occurrences of the specified identifier with the specified constant value, until the end of compilation.

The format of the %REPLACE statement is:

%REPLACE identifier BY constant-value;

Integer constants that are given values by %REPLACE statements are valid in constant expressions. For example:

%REPLACE PREFIX BY 8;

DECLARE BUFFER CHARACTER( 80 + PREFIX);

When the program containing these lines is compiled, the variable BUFFER is declared with a length of 88 characters.

The %RETURN statement terminates execution of the current preprocessor procedure.

The format of the %RETURN statement is:

[%]RETURN (preprocessor-expression);

When the value of the evaluated preprocessor expression is passed back to the point of invocation, control returns to the evaluation of the statement that contained the reference to the preprocessor procedure.

Within a preprocessor procedure, the leading percent sign (%) is optional.

Multiple %RETURN statements are permitted in preprocessor procedures. See Section 10.2.18, “%PROCEDURE” for examples of %RETURN.

The %SBTTL statement allows specification of an arbitrary compile-time string for the listing subtitle line. PL/I uses the procedure IDENT, or 01 if no IDENT was specified. If %SBTTL is used, the specified subtitle appears to the right of IDENT or 01. Subtitles do not appear on the first page of the listing file.

The format of the %SBTTL statement is:

%SBTTL preprocessor-expression

The %TITLE statement allows specification of an arbitrary compile-time string for the listing title line. If %TITLE is used, the specified title appears to the right of the customary title. (If no TITLE option is specified, PL/I uses the name of the first level-1 procedure in the source program as the title.)

The format of the %TITLE statement is:

%TITLE preprocessor-expression

The %WARN statement provides a diagnostic warning message during program compilation.

The format of the %WARN statement is:

%WARN preprocessor-expression;

%PLIG-W-USERDIAG, preprocessor-expression