Kednos PL/I for OpenVMS Systems
User Manual

The /SHOW qualifier must be used in combination with the /LIST qualifier to be effective. The /LIST qualifier specifies that a source listing is to be made, and the /SHOW qualifier gives you control over which portions of the source listing you want to see.

You can also control the content of the source listing by using preprocessor statements to suppress preprocessor portions in the program text. For example, if you previously specified /SHOW=INCLUDE, you can suspend included files from the listing with the %NOLIST_INCLUDE statement in your program.

By default, the /SHOW qualifier yields a listing with two items (P and * ) noted

Kednos PL/I for OpenVMS VAX

in the column to the right of the line numbers.

Kednos PL/I for OpenVMS Alpha

at the beginning of the line, followed by the line numbers.

If you specify /LIST/SHOW=ALL, the compiler includes the full complement of character notations.

When you specify any option with the /SHOW qualifier, the settings for other options are not changed. Table 2-6 summarizes the character notations that can appear in the listing.

Table 2-6 Character Notations That Can Appear in a Listing

Character	Qualifiers	Meaning
| (vertical bar)	/LIST	Indicates a line that contains a comment only.
* (asterisk)	/LIST	Indicates program text that was not used at compile time.
" (quotation mark)	/LIST/SHOW=EXPANSION	Indicates a continuation of a previous line wrapped at the right margin, to show the complete final replacement value of a preprocessor expansion.
+ (plus sign)	/LIST/SHOW=TRACE	Indicates the flow of preprocessor procedure evaluation and out-of-sequence source processing resulting from %GOTO.
D	/LIST/SHOW=DICTIONARY	Indicates CDD text included by a %DICTIONARY statement.
E	/LIST/SHOW=EXPANSION	Indicates the final replacement value of a preprocessor variable or procedure.
I	/LIST/SHOW=INCLUDE	Indicates text included by a %INCLUDE statement.
P	/LIST	Indicates lines contained within a preprocessor procedure.
T	/LIST/SHOW=TRACE	Indicates each step of preprocessor replacement and rescanning.

/VARIANT

/VARIANT="alphanum_string" (default)

If /VARIANT is not specified, or if /VARIANT is specified without a value, /VARIANT ="" is assumed.

/WARNINGS (default)

/WARNINGS=(option list)

/NOWARNINGS

By default, the compiler prints all diagnostic messages during compilation. If you specify /NOWARNINGS to override this default, the compiler does not print informational and warning messages, including user-generated warning messages. It does, however, continue to display all error and fatal diagnostic messages.

The /WARNINGS qualifier has two options:

• NOINFORMATIONALS causes the compiler to suppress informational messages.
• NOWARNINGS causes the compiler to suppress warning messages.

Note that the informational message SUMMARY cannot be suppressed with /NOWARNINGS or /WARNINGS=NOINFORMATIONALS.

File Qualifier

/LIBRARY

Indicates that the associated input file is a library containing text modules that may be included in the compilation of one or more of the specified input files.

The specification of a library file must be preceded by a plus sign. If the file specification does not contain a file type, PL/I assumes the default file type of .TLB.

The PL/I preprocessor permits you to alter a source program at compile time. Preprocessor statements can be mixed with nonpreprocessor statements in the source program, but preprocessor statements are executed only at compile time. The resulting source program is then used for further compilation.

The preprocessor performs two types of preprocessing:

• It interprets preprocessor statements and evaluates preprocessor expressions.
• It replaces the values of preprocessor variables and procedures.

Preprocessor statements allow you to include text from alternative sources (INCLUDE libraries and the VAX Common Data Dictionary), control the course of compilation (%DO, %GOTO, %PROCEDURE, and %IF), enter user-generated diagnostic messages, and selectively control listings and formats. The preprocessor statements are described in full in the Kednos PL/I for OpenVMS Systems Reference Manual.

2.3.3.1 Preprocessor Compilation Control

At compile time, preprocessor variables, procedures, and variable expressions are evaluated in the order in which they appear in the source text, and the new values are substituted in the source program in the same order. Thus, the course of compilation becomes conditional, and the resulting executable program may exhibit a variety of unique features. Note that preprocessor variables and procedures must be declared and activated before replacement occurs.

For example:

%DECLARE HOUR FIXED; %HOUR = SUBSTR(TIME(),1,2); %IF HOUR > 7 & HOUR < 18 %THEN %FATAL 'Please compile this outside of prime time'; %DECLARE T CHARACTER; %ACTIVATE T NORESCAN; %T = '''Compiled on '||DATE()||''''; DECLARE INIT_MESSAGE CHARACTER(40) VARYING INITIAL(T); %IF VARIANT() = '' | VARIANT() = 'NORMAL' %THEN %INFORM 'NORMAL'; %ELSE %IF VARIANT() = 'SPECIAL'; %THEN %INFORM 'SPECIAL'; %ELSE %IF VARIANT() = 'NONE'; %THEN %; %ELSE %DO; %T = '''unknown variant'''; %WARN T; INIT_MESSAGE = INIT_MESSAGE||' with '||T; %END; %END; PUT LIST (INIT_MESSAGE);

This example illustrates several aspects of the preprocessor. First, this program must be compiled outside of prime time. Second, depending upon the value of VARIANT, the program is compiled with a different variant.

Notice the number of single quote marks around the string constant assigned to T. Single quotes are sufficient if the value of T is used only in a preprocessor user-generated diagnostic message. That is, the value of T is concatenated with nonpreprocessor text and assigned to INIT_MESSAGE, because during preprocessing single quotes are stripped from string constants. To ensure that the run-time program also has quotes around the string, additional quotes are needed.

2.3.3.2 Preprocessor Procedures

The %PROCEDURE statement defines the beginning of a preprocessor procedure block and specifies the parameters, if any, of the procedure. A preprocessor procedure executes only at compile time. Invocation is similar to a function reference and occurs in two ways:

• Preprocessor statements can invoke preprocessor procedures. In addition, preprocessor statements from within preprocessor procedures can invoke other preprocessor procedures.
• Statements from the source program can invoke preprocessor procedures.

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. Preprocessor procedures can be invoked recursively.

Since the preprocessor procedure is always invoked as a function, the %PROCEDURE statement must also specify (through the RETURNS option) the data type attributes of the value that is returned to the point of invocation.

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), and FIXED(10).

Preprocessor procedures can have one of two distinctly different types of argument lists: positional or keyword. Positional argument lists (ending with a right parenthesis) use parameters sequentially, as in a parenthesized list. Positional argument lists can be used in any preprocessor procedure. Keyword argument lists (ending with a semicolon) use parameters in any order, as long as each keyword matches the name of a parameter. Therefore, the order in which you list them does not affect the correct matching of parameters and arguments. Keyword argument lists can only be used when the preprocessor procedure contains the STATEMENT option and is invoked from a nonpreprocessor statement.

A keyword argument list ends with a semicolon rather than the right parenthesis. In this way, the STATEMENT option permits you to use a preprocessor procedure as if it were a statement. Consequently, preprocessor procedures using the STATEMENT option permit you to extend the PL/I language by simulating features that may not otherwise be available.

Preprocessor Statements

All preprocessor statements are preceded by a percent sign (%) and are terminated by a semicolon (;). All text that appears within these delimiters is considered part of the preprocessor statement and is executed at compile time. For example:

%DECLARE HOUR FIXED; /* declaration of a preprocessor single variable */ %DECLARE (A,B) CHARACTER; /* a factored preprocessor declaration */ %HOUR = SUBSTR(TIME(),1,2); /* preprocessor assignment statement using two built-in functions */

Notice that a percent sign (%) is required only at the beginning of the statement. Preprocessor built-in functions are contained within preprocessor statements and consequently do not require a percent sign. However, when you include Common Data Dictionary record definitions, you may need to include the usual PL/I punctuation.

Labels are permitted on preprocessor statements and, like other PL/I labels, are used as the targets of program control statements. A preprocessor label must be an unsubscripted label constant and must be preceded by a percent sign. As with other preprocessor statements, the percent sign alerts the compiler that until the line is terminated with a semicolon, all subsequent text is preprocessor text. Therefore, no other percent signs are required on that line.

Labels for preprocessor procedures are necessary for the procedure to be invoked. On a preprocessor procedure, the leading percent sign is only required on the label; statements within the procedure do not require leading percent signs.

The format for a preprocessor label is as follows:

%label: preprocessor-statement;

For a table summarizing the preprocessor statements and for individual descriptions of the statements, see the Kednos PL/I for OpenVMS Systems Reference Manual.

Preprocessor Built-In Functions

A number of PL/I preprocessor built-in functions are available for use at compile time. With few exceptions, they have the same effect as run-time PL/I built-in functions with the same name. For a table summarizing the preprocessor built-in functions and for individual descriptions of the functions, see the Kednos PL/I for OpenVMS Systems Reference Manual.

2.3.4 Compiler Error Messages

One of the functions of the PL/I compiler is to identify syntax errors and violations of language rules in the source program. If the compiler locates any errors, it writes messages to your default output device; thus, if you enter the PLI command interactively, the messages are displayed on your terminal. If the PLI command is executed in a batch job, the messages appear in the batch job log file.

Each compilation with diagnostic messages terminates with a diagnostic summary that indicates the number of error, warning, and informational messages generated by the compiler. The diagnostic summary has the following format:

%PLIG-I-SUMMARY Completed with n error(s), n warning(s), n informational messages.

If the compiler creates a listing file, it also writes the messages to the listing. Messages typically follow the statement that caused the error.

When it appears on the screen, a message from the compiler has the following format:

%PLIG-s-ident, message-text At line number n device:[directory]file.ext;x.

The Kednos PL/I for OpenVMS Alpha compiler generally displays the line containing the error also, with a carat (...<wedge symbol>) underneath pointing to the error.

%PLIG

Is the facility, or program, name of the compiler. (G denotes the General-Purpose Subset.) This portion indicates that the message is being issued by PL/I.

s

Specifies the severity of the error. Following are the letters that represent the possible severities:

F	Fatal. The compiler stops executing, does not continue the compilation, and does not produce an object module. You must correct the error before you can compile the program.
E	Error. The compiler continues, but does not produce an object module. You must correct the error before you can successfully compile the program.
W	Warning. The compiler produces an object module. It attempts to correct the error in the statement, but you should verify that the compiler's action is acceptable. Otherwise, your program may produce unexpected results.
I	Information. This message usually appears with other messages to inform you of specific actions taken by the compiler. Informational messages also indicate nonstandard constructs and items that are syntactically correct, but that may contain programming errors. No action is necessary on your part.

ident

Is the message identification. This gives a descriptive abbreviation of the message text.

message-text

Is the compiler's message. In many cases, the message text consists of more than one line of output. The messages generally provide enough information for you to determine the cause of an error and correct it.

At line number n

Specifies the source file line number of the statement that caused the error. This is the line number assigned to a statement by the compiler. (It is not necessarily the same as the line number, if any, assigned by a text editing program.) Line numbers appear in a listing file.

device:[directory]file.ext;x.

Indicates the file specification.

The compiler produces messages with warning severity if it encounters the following:

• Syntax errors (such as a missing END statement) that the compiler attempts to fix
• Language elements (such as undeclared variables) that are not part of the PL/I General-Purpose Subset but do belong to full PL/I
• Legal PL/I General-Purpose Subset usage (such as assignment of a bit-string value to a fixed-point binary variable) that nonetheless may represent a programming error or produce unexpected results

Most diagnostic messages are self-explanatory; Appendix A lists the diagnostic messages and gives additional explanations.

To examine any diagnostic messages that occurred during the compilation, print the listing file and search for each occurrence of %PLIG.

Section 2.3.5 shows and explains examples of of Kednos PL/I for OpenVMS VAX compiler listings, and Section 2.3.6 performs the equivalent function for Kednos PL/I for OpenVMS Alpha compiler listings.

2.3.5 Kednos PL/I for OpenVMS VAX Compiler Listing

The Kednos PL/I for OpenVMS VAX compiler listing displays the following information:

• Effects of the options in the /SHOW qualifier
• The machine code generated by PL/I
• Effects of the /CROSS_REFERENCE qualifier
• Effects of the /OBJECT qualifier

Example 2-1 illustrates the default listing (specified with the /LIST qualifier) and describes the information provided in the listing.

Example 2-2 illustrates a storage map of the program listed in Example 2-1. The Kednos PL/I for OpenVMS VAX compiler generates a storage map if you specify /LIST/SHOW=MAP on the PLI command; it also generates a cross-reference listing if you specify /CROSS_REFERENCE.

Example 2-3 illustrates the statistical summary generated if the /LIST/SHOW=STATISTICS qualifier is specified.

Example 2-4 illustrates a portion of a listing of a program compiled with the /LIST/OBJ/MACHINE_CODE qualifiers.

Example 2-5 illustrates the effects of /SHOW=(TRACE,EXPANSION), which shows preprocessor activity in the program listing.

Example 2-1 Default Compiler Listing for VAX Systems

FLOWERS (1) (2) 16-Nov-2003 11:37:00 Kednos PL/I V3.8-001 (3) Page 1 01 (4) 16-Nov-2003 11:35:49 LI$:[MALCOLM]FLOWERS.PLI;18 (1) (5) 1 | /* This procedure obtains data about state flowers from STATEDATA.DAT */ 2 3 4 FLOWERS: PROCEDURE OPTIONS(MAIN); 5 1 (6) 6 1 DECLARE EOF BIT(1) STATIC INIT('0'B); 7 1 8 1 %INCLUDE 'STATE.TXT'; 23 1 24 1 ON KEY(STATE_FILE) BEGIN; 25 2 PUT SKIP LIST('Error on key',ONKEY(),'error no.',ONCODE()); 26 2 STOP; 27 2 END; 28 1 29 1 MODE: BEGIN; 30 2 DECLARE RUN BIT(1); 31 2 GET LIST(RUN) OPTIONS(PROMPT('List by state? ')); 32 2 IF RUN THEN GOTO LIST_BY_STATE; 33 2 GET LIST(RUN) OPTIONS(PROMPT('List by flower? ')); 34 2 IF RUN THEN GOTO LIST_BY_FLOWER; 35 2 ELSE BEGIN; 36 3 DECLARE INPUT_FLOWER CHARACTER(30) VARYING; 37 3 GET LIST(INPUT_FLOWER) OPTIONS(PROMPT('Flower? ')); 38 3 OPEN FILE(STATE_FILE) KEYED ENV( 39 3 INDEX_NUMBER(1), 40 3 SHARED_READ); 41 3 READ FILE(STATE_FILE) SET (STATE_PTR) KEY(INPUT_FLOWER); 42 3 PUT SKIP EDIT('The flower of',STATE.NAME,'is the',FLOWER) 43 3 (3(a)); 44 3 END; 45 2 END; 46 1 RETURN; 47 1 LIST_BY_STATE: 48 1 ON ENDFILE(STATE_FILE) EOF = '1'B; 49 1 OPEN FILE(STATE_FILE) SEQUENTIAL ENV( 50 1 INDEX_NUMBER(0), 51 1 SHARED_READ); 52 1 READ FILE(STATE_FILE) SET (STATE_PTR); 53 1 DO WHILE (^EOF); 54 2 PUT SKIP LIST(STATE.NAME,'flower is ',FLOWER); 55 2 READ FILE(STATE_FILE) SET (STATE_PTR); 56 2 END; 57 1 CLOSE FILE(STATE_FILE); 58 1 RETURN; 59 1 LIST_BY_FLOWER: 60 1 ON ENDFILE(STATE_FILE) EOF = '1'B; 61 1 OPEN FILE(STATE_FILE) SEQUENTIAL ENV( 62 1 INDEX_NUMBER(1), 63 1 SHARED_READ); 64 1 READ FILE(STATE_FILE) SET (STATE_PTR); 65 1 DO WHILE (^EOF); 66 2 PUT SKIP LIST(STATE.NAME,'flower is ',FLOWER); 67 2 READ FILE(STATE_FILE) SET (STATE_PTR); 68 2 END; 69 1 CLOSE FILE(STATE_FILE); 70 1 RETURN; 71 1 END; COMMAND LINE ------- ---- PLI/LIST FLOWERS (7)

The following notes are keyed to Example 2-1:

1. The name of the first level-1 procedure in the source program and its identification. If the main procedure did not specify OPTIONS(IDENT), the compiler uses 01 for the identification.
2. The date and time of compilation, and the version of the compiler that was used to compile the program.
3. The page number of the listing file, and the page number of the source file.
4. The date and time that the file containing the source program was created, and its full file specification (to a maximum of 44 characters).
5. Compiler-generated line numbers. The compiler assigns a number to each line in the source program, including comment lines and lines read from INCLUDE files.
   Note that these line numbers do not necessarily correspond to the line numbers, if any, assigned to the file by an editor that is line-number oriented.
   A vertical bar (|) character indicates a line that contains only a comment.
6. The nesting level, or depth, of each statement. The outermost procedure is always level 1. Additional level numbers are assigned to statements within internal procedures, begin blocks, and DO-groups.
7. The PLI command line as it was entered for compilation.

If the program is compiled with the qualifier /LIST/SHOW=INCLUDE, the %INCLUDE statements are followed by the contents of the INCLUDE files, with line numbers. Notice that INCLUDE files are indicated by an 'I' in the column to the right of the line numbers.

6 1 DECLARE EOF BIT(1) STATIC INIT('0'B); 7 1 8 1 %INCLUDE 'STATE.TXT'; 9 I 1 declare 1 state based (state_prt), 10 I 1 2 name character (20), /* Primary key */ 11 I 1 2 population fixed binary(31),/* 3rd alternate key */ 12 I 1 2 capital, 13 I 1 3 name character (20), 14 I 1 3 population fixed binary(31), 15 I 1 2 largest_cities(2), 16 I 1 3 name character(30), 17 I 1 3 population fixed binary(31), 18 I 1 2 symbols, 19 I 1 3 flower character (30), /* secondary - 1st alternate - key */ 20 I 1 3 bird character (30), /* tertiary - 2nd alternate - key */ 21 I 1 state_ptr pointer, 22 I 1 state_file file; 23 1 24 1 ON KEY(STATE_FILE) BEGIN; 25 2 PUT SKIP LIST('Error on key',ONKEY(),'error no.',ONCODE()); 26 2 STOP; 27 2 END; 28 1

Example 2-2 illustrates the storage map page of the program listing. This page is generated if /LIST/SHOW=MAP is specified on the PLI command.

Example 2-2 Compiler Storage Map for VAX Systems

FLOWERS 12-Nov-2003 11:36:16 Kednos PL/I V3.8-001 Page 2 01 16-Nov-2003 11:35:49 LI$:[MALCOLM]FLOWERS.PLI;17 (1) +-------------+ | Storage Map | +-------------+ External Entry Points and Variables Declared Outside Procedures (1) -------------------------------------------------------------- Identifier Name Storage Size Line Attributes ---------- ---- ------- ---- ---- ---------- FLOWERS 4 ENTRY, EXTERNAL Procedure FLOWERS on line 3 --------------------------- Identifier Name (2) Storage Size Line Attributes ---------- ---- ------- ---- ---- ---------- BIRD 30 BY 22 OFFSET FROM BASE IS 146 BY, MEMBER OF STRUCTURE SYMBOLS CHARACTER(30), UNALIGNED CAPITAL 24 BY 22 OFFSET FROM BASE IS 24 BY, MEMBER OF STRUCTURE STATE,STRUCTURE EOF static 1 BI 6 BIT(1), UNALIGNED, INITIAL, INTERNAL FLOWER 30 BY 22 OFFSET FROM BASE IS 116 BY, MEMBER OF STRUCTURE SYMBOLS CHARACTER(30), UNALIGNED, LARGEST_CITIES 68 BY 22 OFFSET FROM BASE IS 48 BY, MEMBER OF STRUCTURE STATE, STRUCTURE DIMENSION . . . Begin Block on line 29 ---------------------- Identifier Name Storage Size Line Attributes ---------- ---- ------- ---- ---- ---------- RUN automatic 1 BI 30 BIT(1), UNALIGNED Begin Block on line 35 ---------------------- Identifier Name Storage Size Line Attributes ---------- ---- ------- ---- ---- ---------- INPUT_FLOWER automatic 32 BY 36 CHARACTER(30), VARYING, UNALIGNED

Psect Name (3) Allocation Attributes ----- ---- ---------- ---------- $CODE 1221 by position-independent, relocatable, share, execute, read $DATA 1 by position-independent, relocatable, read, write $ADDRESS_DATA 0 by position-independent, relocatable, read SYSIN 450 by position-independent, overlay, relocatable, global, read, write SYSPRINT 450 by position-independent, overlay, relocatable, global, read, write STATE_FILE 451 by position-independent, overlay, relocatable, global, read, write Procedure Definition Map (4) --------- ---------- --- Line Name ---- ---- 5 FLOWERS 26 BEGIN 31 BEGIN 37 BEGIN COMMAND LINE (5) ------- ---- PLI/LIST/SHOW=MAP FLOWERS

The following notes are keyed to Example 2-2: