1. The compiler lists the names of all external entry points in the module and their attributes.
2. 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.
3. The Procedure Definition Map lists each procedure and begin block in the program, giving the line number on which the block is defined.
4. 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, 41

Example 2-8 Compiler Performance Statistics for OpenVMS Alpha Systems

FLOWERS 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 (1) CPU (2) 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:

1. The compiler accumulates statistics for each phase of its operation.
2. For each phase of its operation, the compiler lists I/O, memory, and CPU time usage statistics.

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 illustrates this listing.

Example 2-9 Machine Code Listing for OpenVMS Alpha Systems

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) (1) 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$ + 0000

The following note is keyed to Example 2-9:

1. 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 Kednos PL/I for OpenVMS Alpha compiler.

Example 2-10 Preprocessor Compiler Listing for OpenVMS Alpha Systems

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'; (1) |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 (2) 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; (3) * 1 21 %ELSE %IF VARIANT() = 'MONTHS' %THEN %INCLUDE 'MONTHS.PLI'; 1 22 * 1 23 %WRITE: PROCEDURE(SCHEDULE,PAGE) STATEMENT RETURNS(CHAR); (4) 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; (5) 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); (6) 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.PLI

The following notes are keyed to Example 2-10:

1. The operand symbol (|) denotes a line of source text that contains comment text.
2. The I indicates text from an INCLUDE file. /SHOW=INCLUDE enables this indicator.
3. The asterisk (*) indicates unused preprocessor text.
4. The P indicates lines contained within a preprocessor procedure.
5. The T indicates each instance of preprocessor variable value replacement. /SHOW=TRACE enables this indicator.
6. The E indicates the final replacement value for the preprocessor variable. /SHOW=EXPANSION enables this indicator.

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 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-spec

Specifies 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 (interactive default)

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.

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.
• 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, SHELLS

  
  Because 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 Kednos PL/I for OpenVMS VAX and Kednos PL/I for OpenVMS Alpha compilers, see OpenVMS System Messages and Recovery Procedures Reference Manual.