Developing a PL/I Program

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

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.

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.

Table 2.1, “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.

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.

Endless PL/I for POSIX Systems includes the following run-time libraries:

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.

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.

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

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 Section 2.2.2.1, “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:

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.

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:

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:

%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 */

%label: preprocessor-statement;

Endless PL/I for POSIX Systems provides two methods to access command line parameters:

For example:

PARAM: PROCEDURE (name,address,city,state,zip)
               OPTIONS(MAIN);
DECLARE (name,address,city,state,zip) CHAR(100) VARYING;

Your program can access these parameters only if the parameters are actually passed upon program invocation. To check the number of specified parameters, reference the external variable ARGC (argument count), included in the global definitions file pl1std.in, as shown in the example below.

Both ARGC and ARGV are included in the global declarations include file, plistd.in, supplied with Endless PL/I for POSIX Systems.

The following example shows both methods of accessing command line parameters:

%INCLUDE pl1std;

PARAM_TEST: PROCEDURE (name, address, city, state, zip)                OPTIONS(MAIN);
DECLARE (name, address, city, state, zip) CHARACTER(100)               VARYING;
DECLARE i FIXED BIN;

IF ARGC >= 1  THEN
       PUT SKIP EDIT ('Name: ',Name) (a,a);
ELSE
       PUT SKIP EDIT ('Name is missing') (a);

IF ARGC >= 2  THEN
       PUT SKIP EDIT ('Address: ',Address) (a,a);
ELSE
       PUT SKIP EDIT ('Address is missing') (a);

IF ARGC >= 3  THEN
       PUT SKIP EDIT ('City: ',City) (a,a);
ELSE
       PUT SKIP EDIT ('City is missing') (a);

IF ARGC >= 4  THEN
       PUT SKIP EDIT ('State: ',State) (a,a);
ELSE
       PUT SKIP EDIT ('State is missing') (a);

IF ARGC >= 5  THEN
       PUT SKIP EDIT ('Zip: ',Zip) (a,a);
ELSE
       PUT SKIP EDIT ('Zip is missing') (a);

DO I = 1 TO ARGC;
       PUT SKIP EDIT ('Parameter ',i, 'is ',ARGS(i)->ARG_CV) (a,f(2),a,a);
END; /* of do loop */

END; /* of program */

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"