Intended Audience

This manual is designed for programmers who have a working knowledge of PL/I and some familiarity with the Digital UNIX operating system and the C shell (csh).

Structure of This Manual

This manual is divided into the following sections:

• See gives an overview of the Kednos PL/I for UNIX compiler.
• See explains developing a PL/I program.
• See explains debugging PL/I programs.
• See describes the file system.
• See explains record and stream input/output.
• See summarizes ENVIRONMENT options.
• See explains input/output statement options.
• See explains file-handling built-in subroutines.
• Chapter 9 describes the Sort program interface, valid for the ibm dialect.
• See describes condition handling.
• See explains using PL/I in the common language environment

See contains the Free Software Foundation's Copyleft.

Where to Find More Information

The Kednos PL/I for UNIX Reference Manual contains a complete definition of PL/I for RISC ULTRIX and the VAX PL/I languages, with detailed reference information on all standard PL/I language elements.

The Kednos PL/I for UNIX Installation Guide gives instructions on how to install the PL/I for RISC ULTRIX compiler.

The manpages contain information on PL/I built-in functions and pseudovariables. For an introduction to manpages, type the following:

man 3pl1 intro

The Digital UNIX documentation set gives complete information on the operating system.

Conventions

For the purposes of this manual, the term PL/I refers to Kednos PL/I for UNIX, which runs on the DEC OSF/1 and Digital UNIX systems.

All descriptions of the effects of executing statements and evaluating expressions assume that the initial procedure activation of the program is through an entry point with OPTIONS(MAIN).

It is further assumed that any non-PL/I procedures called by the program follow all conventions of the PL/I run-time environment.

Format

option

A driver option. Driver options specify instructions to all the processing phases. You can specify either the long or short version of the options, as shown in See . Alphabetic List of PL/I Driver Options .

filename.suffix

An input source file containing the program or module to be compiled. You must specify a file suffix. Valid suffixes are:

• PL/I: .pli or .pl1
• Object code: .o

You can include more than one file specification on the same command line by separating the file specifications with a space as follows:

pl1 file1.pl1 file2.pl1

Compilation with pl1

The driver command, pl1, invokes the following processing phases to compile and optionally link edit the source file:

• PL/I compiler: The front-end processes the source file, producing an internal language called ucode. PL/I then converts the optimized ucode to assembly language.
• Assembly: Converts the assembly-language code to an object file.
• Link edit: Merges object files and libraries producing an executable binary.

By default, the pl1 command both compiles and link edits a source module. If you specify the -c driver option, processing stops after the assembler phase, producing a linkable object file. You can then use the pl1 or ld command to link edit the linkable object(s) into one executable binary. By default, the linkable object file has the same name as the source file, but with the suffix .o.

For example:

pl1 file.pli -c

This produces the linkable object file.o.

The default name of the executable binary is a.out. For example:

pl1 file.pl1

This command line produces the executable binary a.out.

You can specify a different name for the executable binary by using the driver option -o and supplying the desired file name. For example:

pl1 file.pl1 -o file

This command line compiles and link edits the source module file.pli and produces an executable binary, file.

If you have previously compiled the source module and used the -c option to produce the linkable object file.o, the following command line links edit the object module:

pl1 file.o -o file

This command link edits the object module file.o and produces the executable binary file. You can link edit several object modules together to produce a single executable binary, as follows:

pl1 file1.o file2.o -o file

This command link edits the object modules file1.o and file2.o and produces the executable binary file.

When specifying a name for your executable binary or object module, note that the full file name (file name and extension) must differ from the name of the source file(s). In other words, when compiling file.pli, do not supply file.pli as the full file name of your executable binary or object module.

Compiling Multi-Language Programs

When your application has two or more source programs written in different languages, including C, Pascal, and Fortran, compile each program module separately with the appropriate driver and then link them in a separate step. To create the linkable objects, use the pl1 command option -c. The following example compiles a PL/I program and a C program:

pl1 -c plifile.pli

cc -c cfile.c

When you compile the routines, the drivers produce the linkable object files plifile.o and cfile.o. Use the pl1 command to perform the link edit, which loads and initializes the appropriate run-time libraries for PL/I.

Driver Options

See . Alphabetic List of PL/I Driver Options lists the options for the pl1 command line. The UNIX manpage pl1(1) also describes the pl1 command options if the manual pages are installed on the system.

Run-Time Libraries

The object code for the PL/I built-in routines is in an archive library. The distinctive suffix .a identifies a file as an archive library. The link editor gets your program code from your object file or files, and then gets the built-in routine code from object libraries called run-time libraries. It merges them and resolves references.

Kednos PL/I for UNIX includes the following run-time libraries:

• libpli.a

The default run-time library for the pl1 command. It contains support for all PL/I language features except indexed file support (files declared or opened using the ENVIRONMENT(INDEXED) option). Programs using indexed files that are linked to this library generate fatal run-time errors.

• libplit.a

Contains the same features as libpli.a with the addition of indexed file support (see libpli.a). Because the library increases the size of executable binaries, slows the link editing process, and requires additional memory during execution, use it only when indexed file support is required.

Indexed file support is an add-on option to Kednos PL/I for UNIX.

• libpliisam.a

Contains additional support functions required by libplit.a.

To specify other libraries when invoking the link editor, use the -l option. Library names start with lib and have extensions .so (shared object), .a (archive) or .b (ucode). For example, if you have written a PL/I program that calls routines from the run-time library libx11.a, then specify:

pl1 . . . -lx11

Library Search Path

The link editor (ld) searches for any libraries you specify using the default search path listed in the manpage for ld. However, the system administrator or installer determines the actual location of the PL/I run-time libraries, so you might need to add directories to the default search path.

The -L option to the link editor, when followed by a directory name, adds the specified directory to the search path for run-time libraries. Do not type any separators between -L and the name of the directory. You can use this option several times; the link editor searches the directories in the order that you specify on the command line. Your definition of the search path must precede your specification of libraries (using the -l option described in See Run-Time Libraries ) on the command line.

The link editor searches the directories you specify with -L, in the order you specify them on the command line, before it searches the standard directories (which were specified during installation). This lets you specify files that supersede the usual run-time library.

If you use the -L option and do not follow it with a directory name, the link editor does not search its standard directories.

When you use the -L option, the link editor uses the following search path:

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 binary 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(60) VARYING INITIAL(T);

%IF VARIANT() = ''| VARIANT() = 'NORMAL'

%THEN

%INFORM 'NORMAL';

%ELSE

%DO;

%IF VARIANT() = 'SPECIAL';

%THEN

%INFORM 'SPECIAL';

%ELSE

%IF VARIANT() = 'NONE';

%THEN %;

%ELSE

%DO;

%T = '''unknown variant '||variant()||'''';

%WARN t;

INIT_MESSAGE=INIT_MESSAGE||' with '||T;

%END;

%END;

PUT SKIP LIST (INIT_MESSAGE);

This example illustrates several aspects of the preprocessor. First, you must compile this program 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 you only use the value of T 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 off of string constants. To ensure that the run-time program also has quotes around the string, you must supply additional quotes, as shown.

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 (using 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 using 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).

You can use either of the following two types of argument lists in preprocessor procedures:

• Positional argument lists end with a right parenthesis. They use parameters sequentially, as in a parenthesized list. Positional argument lists can be used in any preprocessor procedure.
• Keyword argument lists end with a semicolon. They 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. You can only use keyword argument lists when the preprocessor procedure contains the STATEMENT option and is invoked from a nonpreprocessor statement.

Since a keyword argument list ends with a semicolon rather than a right parenthesis, the STATEMENT option lets you use a preprocessor procedure that has a keyword argument list as if it were a statement. Consequently, preprocessor procedures using the STATEMENT option let you extend the PL/I language by simulating otherwise unavailable features.

The nn specifies the error number.

The s specifies the severity of the error. The following letters represent possible severities:

• 4-- Fatal. The compiler stops executing, does not continue the compilation, and does not produce an object module. You must correct the error before you can compile the program.
• 3-- Error. The compiler continues, but does not produce an object module. You must correct the error before you can successfully compile the program.
• 2-- Warning. The compiler produces an object module. It attempts to correct the error in the statement, but you should verify that the compiler's action is acceptable. Otherwise, your program may produce unexpected results.

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.
• 1 -- Informational. This message usually appears with other messages to inform you of specific actions taken by the compiler. Informational messages also indicate nonstandard constructs and items that are syntactically correct, but that may contain programming errors. No action is necessary on your part. You may, however, want to check that your code performs as expected, and possibly modify the specified line.

The filename indicates the file specification.

The 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. The error message also appears in the listing file (if listing is requested) with the listing line number.

The message-text is the 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.

Running a PL/I Program

To run a PL/I program, enter the name of the executable binary produced by the pl1 command. If you did not use the -o option in the pl1 command, the default name of the executable binary is a.out. Enter a.out to run your PL/I program. If you used the -o option and specified a filename, enter the filename to run your program.

Accessing Command Line Parameters in PL/I Programs

Kednos PL/I for UNIX provides two methods to access command line parameters:

Specifying Command Line Parameters

To specify command line parameters, type them after the command that runs your PL/I program. For example, if you compile the preceding example using the -o command line option, and call your program param_test, run it as follows:

% param_test "Jocelyn Wood" "92 Forest Path" "Groveland" "New Hampshire" "01110"

Command line format varies in different UNIX shells. If this format does not work, see the manual pages for your shell for the correct format.