Chapter 2
Developing PL/I Programs at the DCL Command Level
This chapter describes how to create, compile, link, and run an Endless PL/I program.
2.1. DCL Commands for Program Development
This section describes the DCL commands that are used to create, compile, link, and run a PL/I program on an OpenVMS system. Figure 2.1, “Steps in Developing Programs” shows the steps in creating a program.
The commands to perform the actions shown in Figure 2.1, “Steps in Developing Programs” are as follows:
EDIT/EDT AVERAGE.PLI
PLI AVERAGE
LINK AVERAGE
RUN AVERAGE
PLI is the default file type for PL/I source files. You do not have to specify the file type when you compile the source file.
If your source program compiles successfully, the compiler creates an object file with the file type OBJ. If the compiler detects errors, the system displays each error on your screen and then displays the DCL prompt.
The /LIST qualifier causes the compiler to produce a listing file, as follows:
$PLI/LIST AVERAGE
In this example, AVERAGE is the name of the program. Section 2.3.2, “PLI Command Qualifiers” lists the command qualifiers for the PLI command.
To create an executable image file from the successfully compiled program, invoke the OpenVMS Linker. The linker uses the object file as input to produce an executable image file as output.
Section 2.4.2, “LINK Command Qualifiers” lists and explains the command qualifiers for the LINK command.
To run your program after the executable image file has been created, use the DCL command RUN.
2.2. Creating a PL/I Program
To create and modify a PL/I program, invoke a text editor. The OpenVMS system supports the following text editors: EDT, the VSI Language-Sensitive Editor (LSE), and the VSI Text Processing Utility (DECTPU). LSE is a layered extension of DECTPU. The following sections describe briefly how to use these editors.
2.2.1. Using EDT
EDT is an interactive general-purpose text editor that offers three editing modes: keypad, nokeypad, and line. With keypad mode, you enter commands by using the numeric keypad that appears to the right of your main keyboard. With nokeypad mode, you enter commands on a command line, which EDT processes when you press the Return key. Line mode focuses on the line as the unit of text. With line mode, you enter commands at the line mode asterisk prompt (*).
Keypad mode and nokeypad mode continually display the contents of the file on your screen. When you begin your editing session, editing in line mode is the default. Unlike keypad and nokeypad mode, line mode displays only one line of text on your screen.
The following command line invokes the EDT editor and creates the file PROG_1.PLI:
$EDIT/EDT PROG_1.PLI
To change from line mode to keypad mode, enter the CHANGE command at the asterisk prompt. To return to line mode from keypad mode, press Ctrl/z. To change from line mode to nokeypad mode, enter the SET NOKEYPAD command and then enter the CHANGE command.
When you invoke EDT to create a file, a journal file is created automatically. You can use this journal file to recover your edits if the system fails during an editing session. To recover your edits, enter the EDIT/RECOVER command.
EDT provides an online HELP facility that you can access during an editing session. In line mode, you can enter the HELP command. EDT displays general information on EDT as well as detailed information on both line-mode editing and nokeypad-mode editing. In keypad mode, you can press the Help key or the PF2 key. EDT displays a keypad diagram on your screen and a list of keypad editing keys. For help on a specific keypad function, press the key you want help on.
For more information on EDT, see the OpenVMS EDT Reference Manual.
2.2.2. Using LSE
The Language-Sensitive Editor (LSE), a component of the software engineering tool kit called DECset, is a multilanguage, programmable editor designed to help develop and maintain source code. LSE is layered on DECTPU, and is available with the EVE and EDT interfaces. LSE provides language-specific templates for each language it supports, including PL/I; these templates help the programmer build syntactically correct programs efficiently.
LSE provides the following features:
Language-specific source code templates for fast entry of source code
Compilation, review, and correction of compile-time errors within a single edit session
Interactive edit capabilities during debugging
Ability to customize editing environments
Integrated access to the Source Code Analyzer (SCA) cross-referencing features (Endless PL/I V3.9 for OpenVMS VAX only)
Ability to access SCA or diagnostics file information
Support for a package facility to define your own subroutine call templates, with tokens and placeholders available for use by multiple LSE environments
Source code templates for calls to OpenVMS system services
Support for user-written diagnostic files, enhancing support for nonsupported and user-modified compilers
Besides PL/I, LSE supports many other products.
VAX ADA
DEC Ada
VAX BASIC
DEC BASIC
VAX BLISS
VAX C
DEC C
DEC C++
CDD/Plus
VAX COBOL
DEC COBOL
VAX DATATRIEVE
DEC DATATRIEVE
VAX DIBOL
VAX DOCUMENT
VAX FORTRAN
DEC Fortran
VAX MACRO
MACRO-64
DEC Pascal
VAX SCAN
2.2.3. Using DECTPU
The VSI OpenVMS Text Processing Utility (DECTPU) is a high-performance, programmable utility. DECTPU provides two editing interfaces: the Extensible VAX Editor (EVE) and the DECTPU EDT Keypad Emulator. You can also create your own interfaces.
Like EDT, DECTPU provides you with an online HELP facility that you can access during your editing session. When you invoke DECTPU to create a file, a journal file is created automatically. You can use this journal file to recover your edits if the system fails during an editing session. To recover your edits, include the /RECOVER qualifier on the command line that invokes the editor.
Unlike EDT, DECTPU provides multiple windows. This feature allows you to view two files on your screen at the same time.
The following sections describe how to use the EVE interface and the EDT Keypad Emulator interface.
2.2.3.1. The EVE Interface
EVE is an interactive text editor that allows you to execute common editing functions using the EVE keypad or to execute more advanced functions by entering commands on the EVE command line. The following command line invokes the EVE editor and creates the file PROG_1.PLI:
$EDIT/TPU PROG_1.PLI
You can define a global symbol for the EDIT/TPU command by placing a symbol definition in your LOGIN.COM file. For example:
$EVE == "EDIT/TPU"
After this command line is executed, you can type EVE at the DCL prompt followed by the name of the file you want to modify or create.
For more information on using the advanced features of EVE, see the Guide to VMS Text Processing.
2.2.3.2. The EDT Keypad Emulator Interface
The EDT Keypad Emulator interface provides all the keypad functions associated with EDT and uses the same keys to perform each function. It also provides a subset of the line editing commands of the EDT editor; however, it does not provide nokeypad editing. The following command line invokes the EDT Keypad Emulator:
$EDIT/TPU/SECTION=EDTSECINI.TPU$SECTION
You can define a global symbol for this command by placing a symbol definition in your LOGIN.COM file. For example:
$EDTEM == "EDIT/TPU/SECTION=EDTSECINI"
When this command line is executed, you can enter EDTEM at the DCL prompt followed by the name of the file you want to create or modify. For example:
$EDTEM PROG_1.PLI
For more detailed information on how to use the EDT Keypad Emulator, see the Guide to VMS Text Processing.
2.3. Compiling a PL/I Program
The compiler performs the following functions:
Detects errors in your source program
Displays each error on your screen or writes the errors to a file
Generates machine language instructions from the source statements
Groups these language instructions into an object module for the OpenVMS Linker
The following sections discuss the PLI command and its qualifiers.
2.3.1. PLI Command
To invoke the compiler, use the PLI command. The PLI command has the following format:
PLI[/qualifier...][file-spec[/qualifier...]],...
- /
qualifier Specifies an action to be performed by the compiler on all files or specific files listed. When a qualifier appears directly after the PLI command, it affects all files listed. However, when a qualifier appears after a file specification, it affects only the file that immediately precedes it. When files are concatenated, however, these rules do not apply.
file-specSpecifies an input source file that contains the program or module to be compiled. You are not required to specify a file type; the compiler adopts the default file type, PLI.
You can include more than one file specification on the same command line by separating the file specifications with either a comma (,) or a plus sign (+). If you separate the file specifications with commas, you can control which source files are affected by each qualifier. In the following example, the compiler creates an object file for each source file but creates only a listing file for the source files PROG_1 and PROG_3.
$PLI /LIST PROG_1, PROG_2/NOLIST, PROG_3
If you separate the file specifications with plus signs, the compiler concatenates each of the specified source files and creates one object file and one listing file. In the following example, only one object file is created, PROG_1.OBJ, and only one listing file is created, PROG_1.LIS. The two files are named after the first source file in the list but contain all three modules.
$PLI PROG_1 + PROG_2/LIST + PROG_3
Note that a qualifier intended for one file affects other files also if the intended file is part of a list of files separated by plus signs.
You can specify a library file in a PLI command. To do this, you must precede the specification with a plus sign and use the /LIBRARY qualifier. For example:
$PLI APPLIC+DATAB/LIBRARY
This PLI command compiles the source program APPLIC.PLI and uses the library DATAB.TLB to locate any INCLUDE files that are referenced in the following format:
%INCLUDE text-module-name;The module name must not be enclosed in apostrophes.
When you specify more than one library, PL/I searches the libraries in the order specified each time it processes a %INCLUDE statement that specifies a text module name; for example:
$PLI APPLIC+DATAB/LIBRARY -$_+NAMES/LIBRARY+GLOBALSYMS/LIBRARY
When PL/I processes a %INCLUDE statement in the source file APPLIC.PLI, it searches for modules referenced in the libraries DATAB.TLB, NAMES.TLB, and GLOBALSYMS.TLB, in that order.
When you use a command that requests multiple compilations, you must specify a library for each compilation in which it is needed; for example:
$PLI METRIC+DATAB/LIBRARY,APPLIC+DATAB/LIBRARY
In this example, PL/I compiles METRIC.PLI and APPLIC.PLI separately and uses the library DATAB.TLB for each compilation.
The order of appearance of the library file specification within a concatenated list of files is irrelevant. The following, for example, are equivalent:
$PLI ALPHA+MYLIB/LIBRARY+BETA$PLI ALPHA+BETA+MYLIB/LIBRARY
You can define one of your private INCLUDE file libraries as a default library for the PL/I compiler to search. The compiler searches the default library after it searches libraries specified on the PLI command.
To define a default library, define an equivalence for the logical name PLI$LIBRARY, as follows:
$DEFINE PLI$LIBRARY DATAB
While this assignment is in effect, the compiler automatically searches the library DATAB.TLB for any INCLUDE modules that it cannot locate in libraries explicitly specified on the PLI command.
You can define the logical name PLI$LIBRARY in the process, group, or system logical name table. If the name is defined in more than one table, the PL/I compiler uses the equivalence for the first match it finds in the normal order of search (that is, the process, then group, then system table). Thus, if PLI$LIBRARY is defined in both the process and group logical name tables, the process logical name table assignment overrides the group logical name table assignment.
When it cannot find INCLUDE modules in libraries specified on the PLI command or in the default library defined by PLI$LIBRARY, PL/I searches the library identified by the following name:
SYS$LIBRARY:PLI$STARLET.TLB
SYS$LIBRARY is normally defined by the system manager to identify the device and directory containing system libraries. PLI$STARLET.TLB is a library of INCLUDE modules supplied by PL/I. It contains declarations for the entry points for OpenVMS system services, local symbol definitions required for use with them, and variables to test their return status values. For more information on libraries, see the VMS Librarian Utility Manual.
2.3.2. PLI Command Qualifiers
This section describes the qualifiers available with the PLI command. Command qualifiers request processing choices by the compiler. You can specify qualifiers to the PLI command after the command or after a file specification. See Section 2.3.1, “PLI Command” for information on using file specifications with qualifiers.
Table 2.1, “Command Qualifiers” summarizes the qualifiers and indicates the differences between their use with the Endless PL/I V3.9 for OpenVMS VAX and Endless PL/I V5.0 for OpenVMS Alpha compilers.
| Qualifier | Default |
Endless PL/I V3.9 for OpenVMS VAX and Endless PL/I V5.0 for OpenVMS Alpha Differences |
|---|---|---|
| /ALIGN[=option] | /NOALIGN | Qualifier options differ |
/ANALYSIS_DATA[=file-spec] | /NOANALYSIS_DATA | VAX only |
| /CHECK | /NOCHECK | None |
| /CROSS_REFERENCE | /NOCROSS_REFERENCE | None |
| /DATA[=option] | /DATA=NATIVE | AXP only |
| /DEBUG[=option] | /DEBUG=TRACEBACK | Qualifier options differ |
| /[NO]DESIGN[=option] | /NODESIGN | VAX only |
/[NO]DIAGNOSTICS[=file-spec] | /NODIAGNOSTICS | VAX only |
| /ERROR_LIMIT[=n] | /ERROR_LIMIT=100 | None |
| /FIXED_BINARY[=p] | /FIXED_BINARY=31 | None |
| /FLOAT[=option] | /FLOAT=D_FLOAT | AXP only |
| /G_FLOAT | /NOG_FLOAT | None |
| /GRANULARITY[=option] | /GRANULARITY=QUADWORD | AXP only |
/[NO]LIST[=file-spec] |
/NOLIST (interactive) /LIST (batch) | None |
| /MACHINE_CODE[=option] |
/MACHINE_CODE= INTERSPERSED (VAX) AFTER (AXP) | Qualifier options and defaults differ |
/[NO]OBJECT[=file-spec] | /OBJECT | None |
| /[NO]OPTIMIZE[=option] | /OPTIMIZE=ALL | Qualifier options differ |
| /SHOW[=option,...] | /SHOW=NOINCLUDE | Qualifier options differ |
|
/VARIANT[= ["]alphanum_string["] |
/VARIANT="" | None |
| /WARNINGS | /WARNINGS[=(option,...)] | None |
Certain pairs of command qualifiers, as follows, are mutually exclusive and therefore should not be used together in the same command line:
/FLOAT and /G_FLOAT
/DATA and /ALIGN
/DATA and /FIXED_BINARY
The remainder of this section explains each qualifier and its options individually.
- /ALIGN[=
option], /NOALIGN (default) Controls alignment of data within structures and aligned bit strings. If you specify /ALIGN on a VAX system, data is aligned on the natural byte boundary of the specified data type, as shown in Table 2.2, “Natural Data Alignment”. If you specify /NOALIGN, the default, data is aligned on the next available byte boundary.
Two options are provided for Endless PL/I V5.0 for OpenVMS Alpha only: packed and natural.
If you specify /ALIGN=natural, data is aligned on the natural byte boundary of the specified data type, as shown in Table 2.2, “Natural Data Alignment”. If you specify /ALIGN=packed, data is aligned on the next available byte boundary. If you specify /ALIGN with no keyword, the default is /ALIGN=natural.
Table 2.2. Natural Data AlignmentData Type Data Size Alignment fixed bin (p) p <=7byte fixed bin (p) 7 < p <= 15word fixed bin (p) p > 15longword fixed dec (p,q) word float bin (p) p <=24longword float bin (p) 24 < p <= 53quadword float bin (p) p >53octaword float dec (p) p <=7longword float dec (p) 7 < p <= 15quadword float dec (p) p > 15octaword char N/A byte char aligned N/A byte char varying N/A word bit N/A bit bit aligned N/A longword pointer varies longword area N/A longword label varies quadword entry varies quadword file varies longword structure varies max of members picture N/A byte offset varies longword - /ANALYSIS_DATA[=
file-spec](OpenVMS VAX), /NOANALYSIS_DATA (default) Controls whether the compiler generates a file of source code analysis information. The default file name is the file name of the primary source file; the default file type is ANA.
- /CHECK, /NOCHECK (
default) Controls the checking of array subscripts and of positional references in arguments to the SUBSTR built-in function. If you specify /CHECK, the compiler checks for the following conditions:
Whether each reference to the SUBSTR built-in function or pseudovariable lies within the string's current length
Whether each reference to an array specifies subscripts that are within the bounds declared for the array
Whether all string lengths are nonnegative and whether all array extents are positive
The default is /NOCHECK. /CHECK is useful primarily during initial program debugging; it results in the generation of additional code and, consequently, a slower program.
Specifying /CHECK is equivalent to specifying /CHECK=ALL or the attribute /CHECK=BOUNDS. Likewise, /NOCHECK is the equivalent of specifying /CHECK=NONE or the attribute /CHECK=NOBOUNDS.
- /CROSS_REFERENCE, /NOCROSS_REFERENCE (
default) Specifies whether the compiler is to generate, in the listing file, alphabetical cross-references for variable names. If you specify /CROSS_REFERENCE, the compiler lists all variable names, including all members of structures as separate entities in an alphabetical cross-reference listing. The cross-reference entry for each structure member also lists the name of the structure that contains the member. The listing contains the line numbers of the lines on which all variables are referenced.
Note that you must specify /SHOW=MAP with /CROSS_REFERENCE. The full specification is as follows:
$PLI/LIST/SHOW=MAP/CROSS_REFERENCE file.PLIBy default, the compiler does not include cross-references in the listing.
- /DATA[=
option] (OpenVMS Alpha) Specifies the integer size and whether alignment is enabled. You can select the following options:
NATIVE Sets the integer size to 32 and enables /ALIGNMENT; equivalent to ALPHA_AXP32 and MIPS. VAX Sets the integer size to 32 and enables /NOALIGNMENT. ALPHA_AXP32 Sets the integer size to 32 and enables /ALIGNMENT. MIPS Sets the integer size to 32 and enables /ALIGNMENT. - /DEBUG[=
option], /DEBUG=TRACEBACK (default) Requests that information be included in the object module for use with the OpenVMS Debugger.
It is strongly recommended that you use the /NOOPTIMIZE qualifier when you use the /DEBUG qualifier. Optimization can cause confusing results during a debugging session.
When /DEBUG is specified, the compiler generates small routines that are used only by the debugger. When the program is linked with /NODEBUG, these routines will still be included in the program but will not be used. For this reason it is recommended that final versions of programs be recompiled with /NODEBUG (which is the default).
You can select the following options:
- /DESIGN[=
option](OpenVMS VAX), /NODESIGN (default) Controls whether the compiler processes the source file as a detailed design, in conjunction with the VSI DECset Program Design Facility (PDF). The /DESIGN qualifier requires that the /ANALYSIS_DATA qualifier also be specified.
If you specify the /DESIGN qualifier, the compiler modifies its parsing and semantics according to the optional keywords you supply. The design information is added to the SCA Analysis Data File (.ANA).
You can select from the following options:
[NO]COMMENTS COMMENTS, the default, directs the compiler to search inside comment fields for program design information. Specifying the option NOCOMMENTS omits this searching. [NO]PLACEHOLDERS PLACEHOLDERS, the default, directs the compiler to treat LSE placeholders in proper contexts within the program as valid syntax. Specifying NOPLACEHOLDERS causes the compiler to treat all LSE placeholders as invalid syntax. The options are mutually independent. Specifying /DESIGN without naming an option is equivalent to /DESIGN=(COMMENTS,PLACEHOLDERS). You can exclude both options by specifying /NODESIGN or by omitting the qualifier. To select one option and exclude the other, you must specify /DESIGN=NOCOMMENTS or /DESIGN=NOPLACEHOLDERS.
- /DIAGNOSTICS[=
file-spec] (OpenVMS VAX), /NODIAGNOSTICS (default) Controls whether the compiler produces a diagnostics file, which contains compiler messages and diagnostic information.
The file type .DIA is the default file type for a diagnostics file. The diagnostics file is used by VSI layered products such as LSE.
- /ERROR_LIMIT[=
n], /NOERROR_LIMIT Permits you to specify the number of errors acceptable during program compilation. For example, if you specify /ERROR_LIMIT=5, then compilation terminates with the sixth error. By default, compilation terminates when the number of errors exceeds 100, but /NOERROR_LIMIT raises the default number to 1000. The maximum number of error messages permitted by the system is 32,767.
All error messages (excluding warning messages) are counted toward the error limit. A fatal error message immediately terminates the compilation.
- /FIXED_BINARY[=
p] This qualifier sets the default precision of fixed-binary variables. You can specify either 15 or 31 as the value of p. If you omit this qualifier or specify it without a precision value, the default precision of fixed-binary variables is 31. Normally, /FIXED_BINARY=15 is specified when compiling for a system whose memory words are 16 bits long.
- /FLOAT[=
option] (OpenVMS Alpha) For Alpha computers, specifies the default representation of floating-point variables. Precision depends upon whether the variable is binary or decimal. See the Endless PL/I for OpenVMS Reference Manual for more information.
For floating-point variables with a precision in the range 1 through 24, the default format is F. Use /FLOAT=IEEE_FLOAT to specify S_FLOAT as the format. For floating-point variables with a precision in the range 25 to 53, the default format is D. Use /FLOAT=IEEE_FLOAT to specify T_FLOAT as the format, or use /FLOAT=G_FLOAT to specify G_FLOAT as the format.
Note
The qualifiers /FLOAT and /G_FLOAT are mutually exclusive and should not be used in the same command line.
- /G_FLOAT, /NOG_FLOAT (
default) For systems equipped with the appropriate hardware option, specifies the default representation of floating-point variables, depending upon whether the variable is binary or decimal.
By default, the compiler uses D (double-precision) floating point. Specify /G_FLOAT to override this default and to request the compiler to use the (G-floating-point) type for these variables.
Note
The qualifiers /FLOAT and /G_FLOAT are mutually exclusive and should not be used in the same command line.
The default and maximum precisions for all floating-point formats are summarized in the Endless PL/I for OpenVMS Reference Manual.
- /GRANULARITY[=
option] (OpenVMS Alpha) Specifies the smallest unit of data that can be cached in a register. The following options are available:
byte
longword
quadword
For example, quadword granularity would mean that the Alpha system would cache quadword values in registers. The default granularity is quadword.
- /LIST[=
file-spec] (batchdefault), /NOLIST (interactivedefault) Controls whether a listing file is produced.
When /LIST is in effect, the compiler gives a listing file the same file name as the source file and a file type of .LIS.
If you specify a file specification with /LIST, the compiler uses that file specification to override the default values applied.
- /MACHINE_CODE[=
option], /NOMACHINE_CODE (default) Controls whether the listing file produced by the compiler includes a listing of the machine code generated during the compilation.
You can select the following options:
AFTER (OpenVMS Alpha) Puts machine code after the source code (the default if /MACHINE_CODE is specified on an OpenVMS Alpha system) BEFORE Puts machine code before the source code INTERSPERSED (OpenVMS VAX) Intersperses source and machine code (the default if /MACHINE_CODE is specified on a VAX machine) No machine code is generated if /NOOBJECT is specified; thus, if /NOOBJECT/MACHINE_CODE are specified together, no machine code listing is generated.
- /OBJECT[=
file-spec] (default), /NOOBJECT Controls whether the compiler produces object modules. By default, the compiler produces an object module with the same file name as the source file and a file type of OBJ.
Specify /NOOBJECT when you want to compile a program only to obtain a listing or when you want the compiler only to check the source program for errors and display diagnostic messages. The compiler can compile code more rapidly if it does not need to create an object module.
- /OPTIMIZE[=(
option,...)], /NOOPTIMIZE Controls the optimization performed by the compiler.
On a VAX system, you can select one or more of the options listed in Table 2.3, “Compiler Optimization Options for VAX Systems”. By default, all possible optimizations are performed. If you specify /OPTIMIZE with any options, the other options are not affected. For example, /OPTIMIZE=NOPEEPHOLE disables the PEEPHOLE option but leaves all other options enabled. Note that if you specify NOCOMMON_SUBEXPRESSION with the /OPTIMIZE qualifier to the PLI command, NORESULT_INCORPORATION is implied.
Table 2.3. Compiler Optimization Options for VAX SystemsOn an OpenVMS Alpha system, you can specify a value for the options listed in Table 2.4, “Compiler Optimization Options for OpenVMS Alpha Systems”.
Table 2.4. Compiler Optimization Options for OpenVMS Alpha SystemsOption Description LEVEL=n Specifies the level of optimization based on a value from 0 to 5. Zero (0) specifies no optimization and is equivalent to /NOOPTIMIZE. The default value for LEVEL is 4. UNROLL=n Specifies the number of times to unroll loops, based on a value from 1 to 16. If the /UNROLL option is not specified, a default unroll amount of 4 is used. LEVEL must be specified as 3 or greater to enable loop unrolling. INLINE=NONE Suppresses all inlining INLINE=MANUAL Inlines the calls you explicitly request to be inlined INLINE=AUTOMATIC Inlines the calls in the MANUAL category and any additional calls that improve performance INLINE=ALL Optimizes every call that is possible to inline while still generating correct code. Each subsequent level of optimization includes the optimizations from all lower levels. The levels of optimization are as follows:
0 - No optimizations performed. The only code transformations performed are block reordering, and intermediate language and final peepholes.
1 - Optimizations performed that do not seriously affect readability or debugging. This includes common subexpression and register history, and user-directed inlining.
2 - Optimizations performed that do not increase code size. This includes code motion, strength reduction, induction variables, test replacement, split lifetime analysis, and intermediate language and final scheduling.
3 - All optimizations performed except automatic inlining, including while-repeat transformations, loop unrolling, and final code replication.
4 - Full optimization, including automatic inlining. This is the default optimization level.
5 - Full optimization, as in level 4, but with more aggressive inlining. This allows you to indicate that speed is more important than size.
- /SHOW[=(
option,...)] Sets or cancels specific compilation listing options. You can select or cancel any of the options listed in Table 2.5, “Compiler Listing Options”.
Table 2.5. Compiler Listing OptionsThe following options are enabled by default:
NOINCLUDE
NOMAP
NODICTIONARY
SOURCE
TERMINAL
HEADER
NOSTATISTICS
NOTRACE
NOEXPANSION
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
Endless PL/I V3.9 for OpenVMS VAX
in the column to the right of the line numbers.
Endless PL/I V5.0 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, “Character Notations That Can Appear in a Listing” summarizes the character notations that can appear in the listing.
Table 2.6. Character Notations That Can Appear in a ListingCharacter 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) Permits specification of compilation variants. The value specified for /VARIANT is available at compile time with the VARIANT preprocessor built-in function.
If /VARIANT is not specified, or if /VARIANT is specified without a value, /VARIANT ="" is assumed.
- /WARNINGS (
default), /WARNINGS=(optionlist), /NOWARNINGS Controls whether the compiler prints diagnostic warning and informational messages.
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.
- /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.
2.3.3. PL/I Preprocessor
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 Endless PL/I for OpenVMS 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 Endless PL/I for OpenVMS 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 Endless PL/I for OpenVMS 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-textAtlinenumberndevice:[directory]file.ext;x.
The Endless PL/I V5.0 for OpenVMS Alpha compiler generally displays the line containing the error also, with a carat (...wedge) 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.
sSpecifies the severity of the error. Following are the letters that represent the possible severities:
identIs the message identification. This gives a descriptive abbreviation of the message text.
message-textIs 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, PL/I Messages 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, “Endless PL/I V3.9 for OpenVMS VAX Compiler Listing” shows and explains examples of Endless PL/I V3.9 for OpenVMS VAX compiler listings, and Section 2.3.6, “Endless PL/I V5.0 for OpenVMS Alpha Compiler Listing” performs the equivalent function for Endless PL/I V5.0 for OpenVMS Alpha compiler listings.
2.3.5. Endless PL/I V3.9 for OpenVMS VAX Compiler Listing
The Endless PL/I V3.9 for OpenVMS VAX compiler listing displays the following information:
Example 2.1, “Default Compiler Listing for VAX Systems” illustrates the default listing (specified with the /LIST qualifier) and describes the information provided in the listing.
Example 2.2, “Compiler Storage Map for VAX Systems” illustrates a storage map of the program listed in Example 2.1, “Default Compiler Listing for VAX Systems”. The Endless PL/I V3.9 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, “Compiler Performance Statistics for VAX Systems” illustrates the statistical summary generated if the /LIST/SHOW=STATISTICS qualifier is specified.
Example 2.4, “Machine Code Listing for VAX Systems” illustrates a portion of a listing of a program compiled with the /LIST/OBJ/MACHINE_CODE qualifiers.
Example 2.5, “Preprocessor Compiler Listing for VAX Systems” illustrates the effects of /SHOW=(TRACE,EXPANSION), which shows preprocessor activity in the program listing.
FLOWERS ❶ ❷ 16-Nov-2003 11:37:00 Kednos PL/I V3.8-001 ❸ Page 1
01 ❹ 16-Nov-2003 11:35:49 LI$:[MALCOLM]FLOWERS.PLI;18 (1)
❺
1 | /* This procedure obtains data about state flowers from STATEDATA.DAT */
2
3
4 FLOWERS: PROCEDURE OPTIONS(MAIN);
5 1 ❻
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 ❼The following notes are keyed to Example 2.1, “Default Compiler Listing for VAX Systems”:
- ❶
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.
- ❷
The date and time of compilation, and the version of the compiler that was used to compile the program.
- ❸
The page number of the listing file, and the page number of the source file.
- ❹
The date and time that the file containing the source program was created, and its full file specification (to a maximum of 44 characters).
- ❺
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.
- ❻
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.
- ❼
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 1Example 2.2, “Compiler Storage Map for VAX Systems” illustrates the storage map page of the program listing. This page is generated if /LIST/SHOW=MAP is specified on the PLI command.
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 ❶
--------------------------------------------------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
FLOWERS 4 ENTRY, EXTERNAL
Procedure FLOWERS on line 3
---------------------------
Identifier Name ❷ 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, UNALIGNEDPsect Name ❸ 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 ❹ --------- ---------- --- Line Name ---- ---- 5 FLOWERS 26 BEGIN 31 BEGIN 37 BEGIN COMMAND LINE ❺ ------- ---- PLI/LIST/SHOW=MAP FLOWERS
The following notes are keyed to Example 2.2, “Compiler Storage Map for VAX Systems”:
- ❶
The compiler lists the names of all external entry points in the module and their attributes.
- ❷
For each procedure in the source program, the compiler lists each declared name, giving
The user-specified identifier of the name.
The storage class to which the name belongs.
The amount of storage allocated for the name, where bi indicates that the size is given in bits and by indicates that the size is given in bytes.
The line number on which the declaration of the name appears. Note that if a declaration continues on more than one line (for example, in a structure declaration), the line number is always the number of the line on which the DECLARE statement is terminated.
The data type attributes of the name. If the name represents a member of a structure, the attributes are preceded by the offset of the structure member from the base of the structure.
- ❸
The Program Section (Psect) Synopsis lists the program sections created by the compiler and their attributes.
- ❹
The Procedure Definition Map lists each procedure and begin block in the program, giving the line number on which the block is defined.
- ❺
The Command Line shows the PLI command string that was processed, including input files, qualifiers, and library files.
When PLI/LIST/SHOW=MAP/CROSS_REFERENCE is specified, each name that is referenced is followed by a list of the numbers of all lines that contain references to that name. For example:
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
BIRD 30 BY 22 OFFSET FROM BASE IS 146 BY, MEMBER OF STRUCTURE
SYMBOLS CHARACTER(30), UNALIGNED
No references.
CAPITAL 24 BY 22 OFFSET FROM BASE IS 24 BY, MEMBER OF STRUCTURE
STATE, STRUCTURE
No references.
EOF static 1 BI 6 BIT(1), UNALIGNED, INITIAL, INTERNAL
Reference lines: 48, 53, 56, 60, 65, 68
FLOWER 30 BY 22 OFFSET FROM BASE IS 116 BY, MEMBER OF STRUCTURE
SYMBOLS CHARACTER(30), UNALIGNED,
Reference lines: 43, 54, 66
Begin Block on line 29
----------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
RUN automatic 1 BI 30 BIT(1), UNALIGNED
Reference lines: 31, 32, 33, 34
Begin Block on line 35
----------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
INPUT_FLOWER automatic 32 BY 36 CHARACTER(30), VARYING, UNALIGNED
Reference lines: 37, 41Example 2.3, “Compiler Performance Statistics for VAX Systems” illustrates the statistical summary that PL/I includes in the listing if you specify /LIST/SHOW=STATISTICS qualifier.
FLOWERS 22-Nov-2003 09:59:16 Kednos PL/I V3.8-001 Page 3
01 16-Nov-2003 11:35:49 LI$:[MALCOLM]FLOWERS.PLI;18 (1)
+------------------------+
| Performance Indicators |
+------------------------+
❶ ❷
phase buf i/o dir i/o pageflt virtmem workset cputim
----- ------- ------- ------- ------- ------- ------
pass 1 totals 4 34 116 0 1350 78
declare totals 0 0 4 0 1500 6
pass 2 totals 0 0 64 0 1800 41
live analysis 0 0 29 0 2048 7
reorder invariants 0 0 30 0 2048 3
eliminate redundancy 0 0 12 0 2048 9
optimizer totals 0 0 98 0 2048 32
allocator totals 1 3 28 0 2048 13
generate code list 0 0 26 0 2048 35
register allocation 0 0 0 0 2048 6
peephole optimization 0 0 3 0 2048 13
branch/jump resolution 0 0 0 0 2048 2
write object module 0 0 2 0 2048 8
code generator totals 0 0 34 0 2048 66
total compilation 8 45 827 432 2048 300
71 lines compiled
compilation rate was 1420 lines per minuteThe following notes are keyed to Example 2.3, “Compiler Performance Statistics for VAX Systems”:
If you specify /LIST/OBJECT/MACHINE_CODE when you compile a PL/I program, the compiler includes the generated assembly language code and object code in the listing. Example 2.4, “Machine Code Listing for VAX Systems” illustrates this listing.
FLOWERS 22-Nov-2003 10:00:37 Kednos PL/I V3.8-001 Page 1
01 16-Nov-2003 11:35:49 LI$:[MALCOLM]FLOWERS.PLI;18 (1)
1 | /* This procedure obtains data about state flowers from STATEDATA.DAT */
2
3
4 FLOWERS: PROCEDURE OPTIONS(MAIN);
0073 FLOWERS:
C00C 0073 .entry FLOWERS,^m<dv,iv,r2,r3>
5E 10 C2 0075 subl2 #10,sp
00000000* EF 16 0078 jsb PLI$OPTIONSMAIN
5C 00000000 EF 9E 007E movab STATE_FILE,ap
52 00000000 EF 9E 0085 movab $DATA,r2
53 5E D0 008C movl sp,r3
5 1
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; ❶
5E 53 14 C3 008F subl3 #14,r3,sp ❷
53 5E D0 0093 movl sp,r3
0C AE 6C 9E 0096 movab (ap),0C(sp)
04 AE 001E8024 8F D0 009A movl #1E8024,04(sp)
08 AE 0D AF 9E 00A2 movab sym.1,08(sp)
6E F4 AD D0 00A7 movl -0C(fp),(sp)
F4 AD 5E D0 00AB movl sp,-0C(fp)
0092 31 00AF brw sym.4
00B2 sym.1:
C000 00B2 .entry vcg.code,^m<dv,iv>
25 2 PUT SKIP LIST('Error on key',ONKEY(),'error no.',ONCODE());
51 5D D0 00B4 movl fp,r1
02 AF 6C FA 00B7 callg (ap),sym.2
7D 11 00BB brb sym.3
00BD sym.2:
C87C 00BD .entry vcg.code,^m<dv,iv,r2,r3,r4,r5,r6,r11>
5E FEF8 CE 9E 00BF movab -0108(sp),sp
5C 00000000 EF 9E 00C4 movab SYSPRINT,ap
50 7C 00CB clrq r0
FE AD 01 B0 00CD movw #1,-02(fp)
52 FE AD 9E 00D1 movab -02(fp),r2
53 7C 00D5 clrq r3
00000000* EF 16 00D7 jsb PLI$PUTFILE_R6
50 81 AF 9E 00DD movab $CODE+61,r0
51 0C 3C 00E1 movzwl #C,r1
00000000* EF 16 00E4 jsb PLI$PUTLCHAR_R6
FF7E CD 9F 00EA pushab -0082(fp)
7E 80 8F 9A 00EE movzbl #80,-(sp)
00000000* EF 02 FB 00F2 calls #2,PLI$ONKEY
52 FF7E CD B0 00F9 movw -0082(fp),r2
50 FF7E CD 9E 00FE movab -0082(fp),r0
51 52 3C 0103 movzwl r2,r1
00000000* EF 16 0106 jsb PLI$PUTLVCHA_R6
50 FF48 CF 9E 010C movab $CODE+58,r0
51 09 3C 0111 movzwl #9,r1
00000000* EF 16 0114 jsb PLI$PUTLCHAR_R6The following notes are keyed to Example 2.4, “Machine Code Listing for VAX Systems”:
- ❶
The machine code is generated in line with the PL/I source statements. Thus, you can see the code that is generated by each statement following the statement itself.
- ❷
The listing shows, in hexadecimal, the object module location of each generated statement directly to the left of the machine code. To the left of the object location is the object code generated by the Endless PL/I V3.9 for OpenVMS VAX compiler.
If you specify /LIST/SHOW=(INCLUDE,EXPANSION,TRACE) when you compile a program that uses the embedded preprocessor, the compiler includes additional preprocessor information in the listing. Example 2.5, “Preprocessor Compiler Listing for VAX Systems” illustrates some of the notations that can appear in the column to the right of the line numbers in the listing. Except as indicated, the notations seen here are enabled by default.
WR_SCHEDULE 12-Nov-2003 16:00:27 Kednos PL/I V3.8-001 Page 1
01 12-Nov-2003 15:57:14 APLD$:[MALCOLM]SCHEDULE.PLI;1 (1)
1 WR_SCHEDULE: PROCEDURE OPTIONS (MAIN);
2 1 DECLARE I FIXED BINARY(15);
3 1 %DECLARE (DOWN_PAGE,ACROSS_PAGE) CHAR;
4 1
5 1 %ACROSS_PAGE = 'PAGE(ACROSS)';
6 1 %DOWN_PAGE = 'PAGE(DOWN)';
7 1 %IF VARIANT() = 'DAYS' %THEN %INCLUDE 'DAYS.PLI';
❶ 8 |I 1 /* THE INCLUDE FILE 'DAYS.PLI' CREATES AN ARRAY STRUCTURE DAYS AND */
9 |I 1 /* INITIALIZES IT WITH THE DAYS OF THE WEEK. */
10 I 1
11 I 1 %DO;
12 I 1
13 I 1 %DECLARE SCHEDULE CHAR,NUM_ITEMS FIXED;
14 I 1 %SCHEDULE = 'DAYS';
❷ 15 I 1 %NUM_ITEMS = 7;
16 I 1
17 I 1 DECLARE DAYS(7) CHAR(10) INIT(
18 I 1 'MONDAY','TUESDAY','WEDNESDAY','THURSDAY','FRIDAY',
19 I 1 'SATURDAY','SUNDAY');
20 I 1 %END;
❸ 21 * 1 %ELSE %IF VARIANT() = 'MONTHS' %THEN %INCLUDE 'MONTHS.PLI';
22 1
23 * 1 %WRITE: PROCEDURE(SCHEDULE,PAGE) STATEMENT RETURNS(CHAR);
24 P 1 DECLARE (SCHEDULE,PAGE,F_SPEC) CHAR;
25 1
26 1 IF PAGE = 'DOWN'
27 P 1 THEN DO;
❹ 28 P 1 F_SPEC = ' DO I = 1 TO NUM_ITEMS)) (A(10),SKIP);';
29 P 1 RETURN ('PUT SKIP EDIT(('||SCHEDULE||'(I)'||F_SPEC);
30 P 1 END;
31 1 ELSE IF PAGE = 'ACROSS'
32 P 1 THEN RETURN ('PUT SKIP LIST ('||SCHEDULE||');');
33 P 1 END;
34 1
35 1 WRITE(SCHEDULE) DOWN_PAGE;
❺ T WRITE(DAYS) DOWN_PAGE;
T WRITE(DAYS) PAGE(DOWN);
T PUT SKIP EDIT((DAYS(I) DO I = 1 TO 7)) (A(10),SKIP);
❻ E PUT SKIP EDIT((DAYS(I) DO I = 1 TO 7)) (A(10),SKIP);
36 1 WRITE(SCHEDULE) ACROSS_PAGE;
T WRITE(DAYS) ACROSS_PAGE;
T WRITE(DAYS) PAGE(ACROSS);
E PUT SKIP LIST (DAYS);
37 1 END;
COMMAND LINE
------- ----
PLI/LIST/SHOW=(INCLUDE,EXPAN,TRACE)/VARIANT=DAYS SCHEDULEThe following notes are keyed to Example 2.5, “Preprocessor Compiler Listing for VAX Systems”:
- ❶
The operand symbol (|) denotes a line of source text that contains comment text.
- ❷
The I indicates text from an INCLUDE file. /SHOW=INCLUDE enables this indicator.
- ❸
The asterisk (*) indicates unused preprocessor text.
- ❹
The P indicates lines contained within a preprocessor procedure.
- ❺
The T indicates each instance of preprocessor variable value replacement. /SHOW=TRACE enables this indicator.
- ❻
The E indicates the final replacement value for the preprocessor variable. /SHOW=EXPANSION enables this indicator.
2.3.6. Endless PL/I V5.0 for OpenVMS Alpha Compiler Listing
The Endless PL/I V5.0 for OpenVMS Alpha compiler listing displays the following information:
Example 2.6, “Default Compiler Listing for OpenVMS Alpha Systems” illustrates the default listing (specified with the /LIST qualifier) and describes the information provided in the listing.
Example 2.7, “Compiler Storage Map for OpenVMS Alpha Systems” illustrates a storage map of the program listed in Example 2.6, “Default Compiler Listing for OpenVMS Alpha Systems”. The Endless PL/I V5.0 for OpenVMS Alpha 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.8, “Compiler Performance Statistics for OpenVMS Alpha Systems” illustrates the statistical summary generated if the /LIST/SHOW=STATISTICS qualifier is specified.
Example 2.9, “Machine Code Listing for OpenVMS Alpha Systems” illustrates a portion of a listing of a program compiled with the /LIST/OBJ/MACHINE_CODE qualifiers.
Example 2.10, “Preprocessor Compiler Listing for OpenVMS Alpha Systems” illustrates the effects of /SHOW=(TRACE,EXPANSION), which shows preprocessor activity in the program listing.
FLOWERS ❶ Source Listing ❷ 19-Nov-2003 10:26:27 Kednos PL/I V4.4-001 ❸ Page 1
01 ❹ 19-Nov-2003 10:25:07 DISK$DISK4:[MAZORA.DECPLI.LZ]FLOWERS.PLI;1
| ❺ 1 /* This procedure obtains data about state flowers from STATEDATA.DAT */
2
3
❻ 4 FLOWERS: PROCEDURE OPTIONS(MAIN);
1 5
1 6 DECLARE EOF BIT(1) STATIC INIT('0'B);
1 7
1 8 %INCLUDE 'STATE.TXT';
1 23
1 24 ON KEY(STATE_FILE) BEGIN;
1 25 PUT SKIP LIST('Error on key',ONKEY(),'error no.',ONCODE());
1 26 STOP;
1 27 END;
1 28
1 29 MODE: BEGIN;
1 30 DECLARE RUN BIT(1);
1 31 GET LIST(RUN) OPTIONS(PROMPT('List by state? '));
1 32 IF RUN THEN GOTO LIST_BY_STATE;
1 33 GET LIST(RUN) OPTIONS(PROMPT('List by flower? '));
1 34 IF RUN THEN GOTO LIST_BY_FLOWER;
1 35 ELSE BEGIN;
1 36 DECLARE INPUT_FLOWER CHARACTER(30) VARYING;
1 37 GET LIST(INPUT_FLOWER) OPTIONS(PROMPT('Flower? '));
1 38 OPEN FILE(STATE_FILE) KEYED ENV(
1 39 INDEX_NUMBER(1),
1 40 SHARED_READ);
1 41 READ FILE(STATE_FILE) SET (STATE_PTR) KEY(INPUT_FLOWER);
1 42 PUT SKIP EDIT('The flower of',STATE.NAME,'is the',FLOWER)
1 43 (3(a));
1 44 END;
1 45 END;
1 46 RETURN;
1 47 LIST_BY_STATE:
1 48 ON ENDFILE(STATE_FILE) EOF = '1'B;
1 49 OPEN FILE(STATE_FILE) SEQUENTIAL ENV(
1 50 INDEX_NUMBER(0),
1 51 SHARED_READ);
1 52 READ FILE(STATE_FILE) SET (STATE_PTR);
1 53 DO WHILE (^EOF);
1 54 PUT SKIP LIST(STATE.NAME,'flower is ',FLOWER);
1 55 READ FILE(STATE_FILE) SET (STATE_PTR);
1 56 END;
1 57 CLOSE FILE(STATE_FILE);
1 58 RETURN;
1 59 LIST_BY_FLOWER:
1 60 ON ENDFILE(STATE_FILE) EOF = '1'B;
1 61 OPEN FILE(STATE_FILE) SEQUENTIAL ENV(
1 62 INDEX_NUMBER(1),
1 63 SHARED_READ);
1 64 READ FILE(STATE_FILE) SET (STATE_PTR);
1 65 DO WHILE (^EOF);
1 66 PUT SKIP LIST(STATE.NAME,'flower is ',FLOWER);
1 67 READ FILE(STATE_FILE) SET (STATE_PTR);
1 68 END;
1 69 CLOSE FILE(STATE_FILE);
1 70 RETURN;
1 71 END;
COMMAND LINE
------- ----
PLI/LIST FLOWERS ❼The following notes are keyed to Example 2.6, “Default Compiler Listing for OpenVMS Alpha Systems”:
- ❶
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.
- ❷
The date and time of compilation, and the version of the compiler that was used to compile the program.
- ❸
The page number of the listing file, and the page number of the source file.
- ❹
The date and time that the file containing the source program was created, and its full file specification (to a maximum of 44 characters).
- ❺
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.
- ❻
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.
- ❼
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.
1 6 DECLARE EOF BIT(1) STATIC INIT('0'B);
1 7
1 8 %INCLUDE 'STATE.TXT';
I 1 9 declare 1 state based (state_ptr),
I 1 10 2 name character (20), /* Primary key */
I 1 11 2 population fixed binary(31),/* 3rd alternate key */
I 1 12 2 capital,
I 1 13 3 name character (20),
I 1 14 3 population fixed binary(31),
I 1 15 2 largest_cities(2),
I 1 16 3 name character(30),
I 1 17 3 population fixed binary(31),
I 1 18 2 symbols,
I 1 19 3 flower character (30), /* secondary - 1st alternate - key */
I 1 20 3 bird character (30), /* tertiary - 2nd alternate - key */
I 1 21 state_ptr pointer,
I 1 22 state_file file;
1 23
1 24 ON KEY(STATE_FILE) BEGIN;
1 25 PUT SKIP LIST('Error on key',ONKEY(),'error no.',ONCODE());
1 26 STOP;
1 27 END;
1 28FLOWERS Source Listing 19-Nov-2003 10:44:46 Kednos PL/I V4.4-001 Page 2
01 19-Nov-2003 10:25:07 DISK$DISK4:[MAZORA.DECPLI.LZ]FLOWERS.PLI;1
+-------------+
| Storage Map |
+-------------+
External Entry Points and Variables Declared Outside Procedures ❶
---------------------------------------------------------------
Identifier Name ❷ Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
FLOWERS 4 ENTRY, EXTERNAL
Procedure FLOWERS on line 4
---------------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
BIRD 30 BY 20 OFFSET FROM BASE IS 146 BY, MEMBER OF STRUCTURE SYMBOLS,
CHARACTER(30) UNALIGNED, NONVARYING
CAPITAL 24 BY 12 OFFSET FROM BASE IS 24 BY, MEMBER OF STRUCTURE STATE,
STRUCTURE
EOF static 1 BI 6 BIT(1), UNALIGNED, INTERNAL, INITIAL, NONVARYING
FLOWER 30 BY 19 OFFSET FROM BASE IS 116 BY, MEMBER OF STRUCTURE SYMBOLS,
CHARACTER(30) UNALIGNED, NONVARYING
LARGEST_CITIES 68 BY 15 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, NONVARYING
Begin Block on line 35
----------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
INPUT_FLOWER automatic 32 BY 36 CHARACTER(30), VARYING, UNALIGNED
Procedure Definition Map ❸
--------- ---------- ---
Line Name
---- ----
4 FLOWERS
24 BEGIN
29 BEGIN
35 BEGIN
COMMAND LINE ❹
------- ----
PLI/LIST/SHOW=MAP FLOWERSThe following notes are keyed to Example 2.7, “Compiler Storage Map for OpenVMS Alpha Systems”:
- ❶
The compiler lists the names of all external entry points in the module and their attributes.
- ❷
For each procedure in the source program, the compiler lists each declared name, giving
The user-specified identifier of the name.
The storage class to which the name belongs.
The amount of storage allocated for the name, where bi indicates that the size is given in bits and by indicates that the size is given in bytes.
The line number on which the declaration of the name appears. Note that if a declaration continues on more than one line (for example, in a structure declaration), the line number is always the number of the line on which the DECLARE statement is terminated.
The data type attributes of the name. If the name represents a member of a structure, the attributes are preceded by the offset of the structure member from the base of the structure.
- ❸
The Procedure Definition Map lists each procedure and begin block in the program, giving the line number on which the block is defined.
- ❹
The Command Line shows the PLI command string that was processed, including input files, qualifiers, and library files.
When you specify PLI/LIST/SHOW=MAP/CROSS_REFERENCE, each name that you reference is followed by a list of the numbers of all lines that contain references to that name. For example:
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
BIRD 30 BY 22 OFFSET FROM BASE IS 146 BY, MEMBER OF STRUCTURE
SYMBOLS CHARACTER(30), UNALIGNED
No references.
CAPITAL 24 BY 22 OFFSET FROM BASE IS 24 BY, MEMBER OF STRUCTURE
STATE, STRUCTURE
No references.
EOF static 1 BI 6 BIT(1), UNALIGNED, INITIAL, INTERNAL
Reference lines: 48, 53, 56, 60, 65, 68
FLOWER 30 BY 22 OFFSET FROM BASE IS 116 BY, MEMBER OF STRUCTURE
SYMBOLS CHARACTER(30), UNALIGNED,
Reference lines: 43, 54, 66
Begin Block on line 29
----------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
RUN automatic 1 BI 30 BIT(1), UNALIGNED
Reference lines: 31, 32, 33, 34
Begin Block on line 35
----------------------
Identifier Name Storage Size Line Attributes
---------- ---- ------- ---- ---- ----------
INPUT_FLOWER automatic 32 BY 36 CHARACTER(30), VARYING, UNALIGNED
Reference lines: 37, 41FLOWERS Compilation statistics 19-Nov-2003 10:56:56 Kednos PL/I V4.4-001 Page 3
01 19-Nov-2003 10:25:07 DISK$DISK4:[MAZORA.DECPLI.LZ]FLOWERS.PLI;1
COMPILER INTERNAL TIMING
Phase ❶ CPU ❷ Elapsed Page I/O
seconds seconds faults count
pass 1 totals 0.08 1.63 52 5
declare totals 0.01 0.62 3 0
pass 2 totals 0.09 1.34 15 0
translation totals 0.04 2.62 58 0
Optimization 0.19 0.76 5 0
Dominator tree construction 0.00 0.00 0 0
Loop dominator insertion 0.00 0.00 0 0
Lifetime analysis 0.00 0.00 0 0
IDEF computation 0.01 0.00 0 0
DATAFLOW computation 0.06 0.19 1 0
Strength reduction 0.02 0.00 0 0
Loop unroll/Loop optimization 0.00 0.00 0 0
Test replacement 0.01 0.00 0 0
Profitability determination 0.02 0.29 2 0
Profitability reordering 0.00 0.00 0 0
Use propagation 0.00 0.00 0 0
Split lifetime analysis 0.02 0.03 0 0
Code Generation 0.36 2.66 47 0
Context analysis 0.16 1.80 17 0
Register History 0.03 0.25 2 0
Temporary allocation 0.05 0.35 3 0
Code emission 0.07 0.23 18 0
Final 0.13 0.12 0 0
Peepholing 0.03 0.01 0 0
Object scheduling 0.08 0.11 0 0
Branch/jump resolution 0.01 0.00 0 0
Object module generation 0.00 0.67 1 10
Compiler totals 0.98 15.49 253 20
COMPILATION STATISTICS
CPU time: 0.98 seconds
Elapsed time: 15.49 seconds
Pagefaults: 253
I/O Count: 20
Source lines: 71
4346 lines per CPU minute.The following notes are keyed to Example 2.8, “Compiler Performance Statistics for OpenVMS Alpha Systems”:
If you specify /LIST/OBJECT/MACHINE_CODE when you compile a PL/I program, the compiler includes the generated assembly language code and object code in the listing. Example 2.9, “Machine Code Listing for OpenVMS Alpha Systems” illustrates this listing.
FLOWERS Machine Code Listing 19-Nov-2003 10:59:36 Kednos PL/I V4.4-001 Page 2
01 FLOWERS 19-Nov-2003 10:25:07 DISK$WORK4:[MAZORA.DECPLI.LZ]FLOWERS.PLI;1
.PSECT $CODE$, OCTA, PIC, CON, REL, LCL, SHR,-
EXE, NORD, NOWRT
0000 FLOWERS::
23DEFF10 0000 LDA SP, -240(SP) ; SP, -240(SP) ❶
47FF0419 0004 CLR R25 ; R25
B7FE00A0 0008 STQ R31, 160(SP) ; R31, 160(SP)
B77E0000 000C STQ R27, (SP) ; R27, (SP)
B75E00B8 0010 STQ R26, 184(SP) ; R26, 184(SP)
B45E00C0 0014 STQ R2, 192(SP) ; R2, 192(SP)
B47E00C8 0018 STQ R3, 200(SP) ; R3, 200(SP)
B49E00D0 001C STQ R4, 208(SP) ; R4, 208(SP)
B4BE00D8 0020 STQ R5, 216(SP) ; R5, 216(SP)
B7BE00E0 0024 STQ FP, 224(SP) ; FP, 224(SP)
63FF0000 0028 TRAPB ;
47FE041D 002C MOV SP, FP ; SP, FP
47FB0402 0030 MOV R27, R2 ; R27, R2
23DEFF80 0034 LDA SP, -128(SP) ; SP, -128(SP)
A742FFC8 0038 LDQ R26, -56(R2) ; R26, -56(R2)
A762FFD0 003C LDQ R27, -48(R2) ; R27, -48(R2)
6B5A4000 0040 JSR R26, DPLI$HND_OPTIONS_MAIN ; R26, R26
263F001F 0044 LDAH R17, 31(R31) ; R17, 31(R31)
22318024 0048 LDA R17, -32732(R17) ; R17, -32732(R17)
A402FEE8 004C LDQ R0, -280(R2) ; R0, -280(R2)
B3FD0090 0050 STL R31, 144(FP) ; R31, 144(FP)
221D0010 0054 LDA R16, 16(FP) ; R16, 16(FP)
B23D0098 0058 STL R17, 152(FP) ; R17, 152(FP)
.
.
.
Routine Size: 1616 bytes, Routine Base: $CODE$ + 0000The following note is keyed to Example 2.9, “Machine Code Listing for OpenVMS Alpha Systems”:
- ❶
The listing shows, in hexadecimal, the object module location of each generated statement directly to the left of the machine code. To the left of the object location is the object code generated by the Endless PL/I V5.0 for OpenVMS Alpha compiler.
WR_SCHEDULE 13-Nov-2003 17:16:36 Kednos PL/I 4.4-001 Page 1
01 24-Nov-2003 10:23:43 USER6:[MAZORA.DECPLI.LZ]SCHEDULE.PLI;2
1 1 WR_SCHEDULE:PROCEDURE OPTIONS (MAIN);
1 2 DECLARE I FIXED BINARY(15);
1 3 %DECLARE (DOWN_PAGE,ACROSS_PAGE) CHAR;
1 4
1 5 %ACROSS_PAGE = 'PAGE(ACROSS)';
1 6 %DOWN_PAGE = 'PAGE(DOWN)';
1 7 %IF VARIANT() = 'DAYS' %THEN %INCLUDE 'DAYS.PLI';
❶ |I 1 8 /* THE INCLUDE FILE 'DAYS.PLI' CREATES AN ARRAY STRUCTUREDAYS AND */
|I 1 9 /* INITIALIZES IT WITH THE DAYS OF THE WEEK.
*/
I 1 10
❷ I 1 11 %DO;
I 1 12
I 1 13 %DECLARE SCHEDULE CHAR,NUM_ITEMS FIXED;
I 1 14 %SCHEDULE = 'DAYS';
I 1 15 %NUM_ITEMS = 7;
I 1 16
I 1 17 DECLARE DAYS(7) CHAR(10) INIT(
I 1 18 'MONDAY','TUESDAY','WEDNESDAY','THURSDAY','FRIDAY',
I 1 19 'SATURDAY','SUNDAY');
I 1 20 %END;
❸ * 1 21 %ELSE %IF VARIANT() = 'MONTHS' %THEN %INCLUDE 'MONTHS.PLI';
1 22
* 1 23 %WRITE: PROCEDURE(SCHEDULE,PAGE) STATEMENT RETURNS(CHAR);
❹ P 1 24 DECLARE (SCHEDULE,PAGE,F_SPEC_CHAR;
1 25
1 26 IF PAGE = 'DOWN'
P 1 27 THEN DO;
P 1 28 F_SPEC = ' DO I = 1 TO NUM_ITEMS)) (A(10),SKIP);';
P 1 29 RETURN ('PUT SKIP EDIT(('||SCHEDULE||'(I)'||F_SPEC);
P 1 30 END;
1 31 ELSE IF PAGE = 'ACROSS'
P 1 32 THEN RETURN ('PUT SKIP LIST ('||SCHEDULE||');');
P 1 33 END;
1 34
1 35 WRITE(SCHEDULE) DOWN_PAGE;
❺ T WRITE(DAYS) DOWN_PAGE;
T WRITE(DAYS) PAGE(DOWN);
+ %WRITE: PROCEDURE(SCHEDULE,PAGE) STATEMENT RETURNS(CHAR);
+ DECLARE (SCHEDULE,PAGE,F_SPEC) CHAR;
+
+ IF PAGE = 'DOWN'
+ THEN DO;
+ F_SPEC = ' DO I = 1 TO NUM_ITEMS)) (A(10),SKIP);';
+ RETURN ('PUT SKIP EDIT(('||SCHEDULE||'(I)'||F_SPEC);
T PUT SKIP EDIT((DAYS(I) DO I = 1 TO NUM_ITEMS)) (A(10),SKIP);
T PUT SKIP EDIT((DAYS(I) DO I = 1 TO 7)) (A(10),SKIP);
❻ E PUT SKIP EDIT((DAYS(I) DO I = 1 TO 7)) (A(10),SKIP);
1 36 WRITE(SCHEDULE) ACROSS_PAGE;
T WRITE(DAYS) ACROSS_PAGE;
T WRITE(DAYS) PAGE(ACROSS);
+ %WRITE: PROCEDURE(SCHEDULE,PAGE) STATEMENT RETURNS(CHAR);
+ DECLARE (SCHEDULE,PAGE,F_SPEC) CHAR;
+
+ IF PAGE = 'DOWN'
+ THEN DO;
+ ELSE IF PAGE = 'ACROSS'
+ THEN RETURN ('PUT SKIP LIST ('||SCHEDULE||');');
T PUT SKIP LIST (DAYS);
E PUT SKIP LIST (DAYS);
1 37 END;
COMMAND LINE
------- ----
PLI/LIST/SHOW=(INCLUDE,EXPAN,TRACE)/VARIANT=DAYS SCHEDULE.PLIThe following notes are keyed to Example 2.10, “Preprocessor Compiler Listing for OpenVMS Alpha Systems”:
- ❶
The operand symbol (|) denotes a line of source text that contains comment text.
- ❷
The I indicates text from an INCLUDE file. /SHOW=INCLUDE enables this indicator.
- ❸
The asterisk (*) indicates unused preprocessor text.
- ❹
The P indicates lines contained within a preprocessor procedure.
- ❺
The T indicates each instance of preprocessor variable value replacement. /SHOW=TRACE enables this indicator.
- ❻
The E indicates the final replacement value for the preprocessor variable. /SHOW=EXPANSION enables this indicator.
2.4. Linking a PL/I Program
Once you have compiled a PL/I source program or module, use the DCL command LINK to combine your object modules into one executable image, which can then be executed by the OpenVMS system. A source program or module cannot run on the OpenVMS system until it is linked.
When you execute the LINK command, the OpenVMS Linker performs the following functions:
Resolves local and global symbolic references in the object code
Assigns values to the global symbolic references
Signals an error message for any unresolved symbolic reference
Allocates virtual memory space for the executable image
When linking on development systems, you may want to use the /DEBUG qualifier. The /DEBUG qualifier appends to the image all the symbol and line-number information appended to the object modules, plus information on global symbols, and causes the image to run under debugger control when it is executed.
The LINK command produces an executable image by default. However, you can also use the LINK command to obtain shareable images and system images. Section 2.4.2, “LINK Command Qualifiers” describes LINK command qualifiers.
For a complete discussion of the OpenVMS Linker, see the OpenVMS Linker Utility Manual.
2.4.1. LINK Command
The LINK command has the following format:
LINK[/command-qualifier]... {file-spec[/file-qualifier...]},...
- /
command-qualifier... Specifies output file options.
file-specSpecifies the input files to be linked.
- /
file-qualifier... Specifies input file options.
If you specify more than one input file, you must separate the input file specifications with a plus sign (+) or a comma (,).
By default, the linker creates an output file with the name of the first input file specified and the file type EXE. Therefore, when you link more than one file, it is good practice to list the file containing the main program first so that the name of your output file will have the same name as that of your main program module.
The following command line links the object files MAINPROG.OBJ, SUBPROG1.OBJ, and SUBPROG2.OBJ to produce one executable image called MAINPROG.EXE.
$LINK MAINPROG.OBJ, SUBPROG1.OBJ, SUBPROG2.OBJ
2.4.2. LINK Command Qualifiers
The LINK command qualifiers can be used to modify the linker's output, as well as to invoke the debugging and traceback facilities. Linker output consists of an image file and an optional map file.
The following list summarizes some of the most commonly used LINK command qualifiers. A brief description of each qualifier follows this list. For a complete list of LINK qualifiers, see the OpenVMS Linker Utility Manual.
| Command Qualifiers | Default |
|---|---|
/[NO]EXECUTABLE[=file-spec]
| /EXECUTABLE=name.EXE |
/[NO]SHAREABLE[=file-spec]
| /NOSHAREABLE |
/BRIEF
| |
/[NO]CROSS_REFERENCE
| /NOCROSS_REFERENCE |
/FULL
| |
/[NO]MAP
| /NOMAP (interactive) |
/[NO]DEBUG
| /NODEBUG |
/[NO]TRACEBACK
| /TRACEBACK |
- /EXECUTABLE [=
file-spec], /NOEXECUTABLE Causes the linker to produce or to suppress the production of an executable image.
- /SHAREABLE [=
file-spec], /NOSHAREABLE (default) Causes the linker to create or not create a shareable image.
- /BRIEF
Causes the linker to produce a summary of the image's characteristics and a list of contributing modules.
- /CROSS_REFERENCE, /NOCROSS_REFERENCE (
default) Causes the linker to produce cross-reference information for global symbols or to suppress its creation.
- /FULL
Causes the linker to produce a summary of the image's characteristics, a list of contributing modules, listings of global symbols by name and by value, and a summary of characteristics of image sections in the linked image.
- /MAP, /NOMAP (
interactivedefault) Causes the linker to generate or not generate a map file.
- /DEBUG, /NODEBUG (
default) Causes the linker to include or not include the OpenVMS Debugger in the executable image and generate or not generate a symbol table.
- /TRACEBACK (
default), /NOTRACEBACK Causes the linker to generate symbolic traceback information when error messages are produced or to suppress its generation.
2.4.3. Linker Input Files
You can specify the object modules to be included in an executable image in any of the following ways:
Specify input file specifications for the object modules.
If no file type is specified, the linker searches for an object file with the file type OBJ.
Specify one or more object module library files.
You can specify either the name of an object module library with the /LIBRARY qualifier or the names of object modules contained in an object module library with the /INCLUDE qualifier. The uses of object module libraries are described in Section 2.4.5, “Object Module Libraries”.
Specify an options file.
An options file can contain additional file specifications for the LINK command, as well as special linker options. You must use the /OPTIONS qualifier to specify an options file. For more information on options files, see the OpenVMS Linker Utility Manual.
The linker uses the following default file types for input files.
| File Type | File |
|---|---|
| OBJ | Object module |
| OLB | Library |
| OPT | Options file |
2.4.4. Linker Output Files
When you issue the LINK command interactively and do not specify any qualifiers, the linker creates only an executable image file. By default, the resulting image file has the same file name as the first object module, and a file type of EXE.
In a batch job, the linker creates both an executable image file and storage map file by default. The default file type for map files is MAP.
To specify an alternative name for a map file or image file or to specify an alternative output directory or device, you can include a file specification on the /MAP or /EXECUTABLE qualifier. In the following example, the LINK command creates the image file [PROJECT.EXE]UPDATE.EXE and the map file [PROJECT.MAP]UPDATE.MAP:
$LINK UPDATE/EXECUTABLE=[PROJECT.EXE]/MAP=[PROJECT.MAP]
2.4.5. Object Module Libraries
You can make program modules accessible to other users by storing them in an object module library. To link modules contained in an object module library, use the /INCLUDE qualifier and specify the modules you want to link. In the following example, the LINK command directs the linker to link the subprogram modules EGGPLANT, TOMATO, BROCCOLI, and ONION with the main program module GARDEN:
$LINK GARDEN,VEGGIES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)
An object module library can also contain a symbol table with the names of each global symbol in the library, and the name of the module in which they are defined. You specify the name of the object module library containing symbol definitions with the /LIBRARY qualifier. When you use the /LIBRARY qualifier during a linking operation, the linker searches the specified library for all unresolved references found in the included modules during compilation.
In the following example, the linker uses the library RACQUETS to resolve undefined symbols in BADMINTON, TENNIS, and RACQUETBALL.
$LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY
You can define an object module library to be your default library by using the DCL command DEFINE. The linker searches default user libraries for unresolved references after it searches modules and libraries specified in the LINK command. For more information about the DEFINE command, see the OpenVMS DCL Dictionary.
For more information about object module libraries, see the OpenVMS Linker Utility Manual.
2.4.6. Linker Error Messages
If the linker detects any errors while linking object modules, it displays messages indicating the cause and severity of the error. If any error or fatal error conditions occur (that is, errors with severities of E or F), the linker does not produce an image file.
The messages produced by the linker are descriptive, and you do not usually need additional information to determine the specific error. Some common errors that occur during linking are as follows:
An object module has compilation errors.
This occurs when you attempt to link a module that produced warning or error messages during compilation. You can usually link compiled modules for which the compiler generated messages, but you should verify that the modules will actually produce the output you expect.
The input file has a file type other than OBJ and no file type was specified on the command line.
If you do not specify a file type, the linker searches for a file that has a file type of OBJ by default. If the file is not an object file and you do not identify it with the appropriate file type, the linker signals an error message and does not produce an image file.
You tried to link a nonexistent module.
The linker signals an error message if you misspell a module name on the command line or if the compilation contains fatal diagnostics.
A reference to a symbol name remains unresolved.
An error occurs when you omit required module or library names from the command line and the linker cannot locate the definition for a specified global symbol reference. In the following example, a main program module OCEAN.OBJ calls the subprogram modules REEF.OBJ, SHELLS.OBJ, and SEAWEED.OBJ, and the following LINK command is executed:
$LINK OCEAN, REEF, SHELLSBecause SEAWEED is not linked, the linker signals the following error messages:
%LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, module "OCEAN" references undefined symbol "SEAWEED" %LINK-W-DIAGISUED, completed but with diagnostics
If an error occurs when you link modules, you can often correct the error by reissuing the command string and specifying the correct modules or libraries. If an error indicates that a program module cannot be located, you may be linking the program with the wrong PL/I Run-Time Library.
For a complete list of linker messages, from both the Endless PL/I V3.9 for OpenVMS VAX and Endless PL/I V5.0 for OpenVMS Alpha compilers, see OpenVMS System Messages and Recovery Procedures Reference Manual.
2.5. Running a PL/I Program
Once you have linked your program, you can use the DCL command RUN to execute it. The RUN command has the following format:
RUN [/[NO]DEBUG] file-spec [/[NO]DEBUG]- /[NO]DEBUG
Is an optional qualifier. Specify the /DEBUG qualifier to invoke the debugger if the image was not linked with it. You cannot use /DEBUG on images linked with the /NOTRACEBACK qualifier. If the image was linked with the /DEBUG qualifier and you do not want the debugger to prompt you, use the /NODEBUG qualifier. The default action depends on whether the file was linked with the /DEBUG qualifier.
file-specSpecifies the file you want to run.
The following example executes the image SAMPLE.EXE without invoking the debugger:
$RUN SAMPLE/NODEBUG
See Chapter 3, Using the OpenVMS Debugger for more information on debugging programs.
During execution, an image can generate a fatal error called an exception condition. When an exception condition occurs, the system displays an error message. Run-time errors can also be issued by the operating system or by certain utilities, such as the OpenVMS Sort Utility.
For example, if an integer divide-by-zero condition occurs and if no ON-unit for this condition exists in any active procedure block, the following run-time messages appear:
%PLI-F-ERROR, PL/I ERROR condition signaled -SYSTEM-F-FLTDIV_F, arithmetic fault, floating divide by zero at PC=000007C4, PSL=03C000A5
These messages are followed by a traceback message like the following:
%TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line relative PC absolute PC SETUP DIVIDE 9 00000074 000007C4 SETUP BEGIN%4 4 00000035 00000707 SETUP SETUP 4 0000000C 000006D0 LIBS NEXT 14 00000044 000006A3 LIBS LIBS 15 0000004C 0000065E
modulenameIndicates the name of a level-1 procedure that was active when the error occurred. The first module name is the name of the module in which the error occurred. Each subsequent line gives the name of the caller of the procedure named on the previous line. In this example, the level-1 procedures are LIBS and SETUP; a call to SETUP occurred during the execution of LIBS.
routinenameIndicates the entry name of the internal procedure or block in the calling sequence. When BEGIN%n appears in this column, it indicates that an unlabeled begin block, a PUT statement, or a GET statement was active when the error occurred.
PL/I assigns labels to these blocks, giving them names in this form, where n is the source program line number on which the block is entered.
In this example, an unlabeled begin block or PUT or GET statement occurs on line 4 of the routine SETUP; within this block or statement, the routine DIVIDE was invoked. Thus, this traceback indicates that the error occurred during execution of an instruction generated for the source statement on line 9, in the procedure DIVIDE.
lineIndicates the source program line number (generated by the compiler) of the statement at which the error occurred, or at which the call or reference to the next procedure was made. This line number matches the line numbers on the listing file created if /LIST was specified to the compiler.
relativePCGives the value of the PC (program counter). This value represents the location in the program image at which the error occurred or at which a procedure was called. The location is relative to the virtual memory address that the linker assigned to the code program section of the module indicated by module name.
absolutePCGives the value of the PC in absolute terms, that is, the actual address in virtual memory that represents the location at which the error occurred.
Traceback information is available at run time only for modules that were compiled and linked with the traceback option in effect. The traceback option is in effect by default for both the PLI and LINK commands. You can use the PLI command qualifier /NODEBUG and the LINK command qualifier /NOTRACEBACK to exclude traceback information. However, it is recommended that you exclude traceback information only from thoroughly debugged program modules.
For a complete list of PL/I run-time error messages, see Appendix A, PL/I Messages.