Chapter 1: Using Open PL/I

This chapter explains how to install the Open PL/I Compiler and how to enter, compile, link, and run Open PL/I programs.

Compiling a Program

Open PL/I consists of four executable programs:

• The Open PL/I Macro Preprocessor, named mfpp
• The Compiler itself, named mfpli
• A command-line driver that allows compiling and linking in one step, named mfplx
• An interactive menu-oriented program for managing indexed (VSAM) files, named mfvsam

Note that in the names mfpli and mfplx the fourth character is the lowercase letter "L".

mfpp is executed prior to the compilation, and its output is passed to the Open PL/I Compiler.

You can run mfpp directly, but the recommended way to run it is by use of the -macro option with mfplx when you are compiling your program. This allows the mfpp output to be automatically directed to the Compiler.

mfpli allows only one filename, accepts only Open PL/I Compiler options, and requires a separate ldpli step. The suffix of the filename to be compiled by mfpli is not restricted.

mfplx allows multiple filenames and accepts mfpli options as well as many standard UNIX or Windows system compiler and linker options, such as -c and -o. The -c option specifies compilation without linking. When -c is used, the -o option is passed to the compiler; when -c is not used, -o is passed to ldpli. Note that some file name suffixes are restricted to .pl1 or .pli when using mfplx.

mfvsam allows the creation of an indexed file, the addition or deletion of an index to an indexed file, and the display of information about an indexed file.

See the following sections for descriptions of the syntax to invoke mfpp, mfpli, mfplx, or mfvsam.

mfpp Syntax

The valid format for the mfpp command is:

mfpp [–ipath dir][-{isuffix|x} suffix] [–pp outfile]infile

where dir is a directory name, suffix defines a string to be appended to any unquoted filename in a %INCLUDE statement, infile specifies a source filename, and outfile specifies an output filename. At least one input file must be specified.

The preprocessor input is a file containing an Open PL/I source module, possibly including Open PL/I Macro Preprocessor statements. The preprocessor output is an Open PL/I source module containing no further preprocessor statements, but with the source code modified according to the semantics of the preprocessor statements that were encountered in the input file.

For information about options available for the mfpp command, see the section Preprocessor Options.

mfpp is usually run by use of the -macro option with mfplx. For more information, see the description of the -macro option in Table 1-3.

mfpli Syntax

The valid format for the mfpli command is:

mfpli [option] ... file [option]...

where option represents a Compiler option and file represents any single specified source file. There is no restriction on the suffix of the filename. option arguments can go either before or after file. (An error may result if the -I or -o option appears before file without specifying a list filename or object filename.)

mfplx Syntax

The valid format for the mfplx command is:

 mfplx {option | source_file | object_file} ...

where option represents an Open PL/I Compiler option or a system Compiler or linker option.

source_file represents any specified source file. Files with a .pl1 or .pli suffix are passed to mfpli. On UNIX systems, files with an .s suffix are passed to the system assembler. On Windows systems, files with an .asm suffix are passed to the system assembler.

mfplx supports wildcard characters and indirect files (@files).

object_file represents any specified object file (with an .o suffix for UNIX systems or a .obj suffix for Windows systems) or any specified library (with an .a suffix for UNIX systems or an .lib suffix for Windows systems). Files with an .o (or .obj) or an .a (or .lib) suffix are passed to mfpli, as are specified files with unknown or absent suffixes. The command line that mfpli constructs for each of these invocations is limited to 4096 characters. The .o files can be linked (possibly with other object files and/or libraries) using ldpli or mfplx -o.

mfplx processes options in one of the following ways:

• Passes the option to the preprocessor (mfpp).
• Passes the option to the compiler (mfpli).
• Passes the option to the linker (ldpli).
• Executes the option (for example, -c) in a fashion similar to cc.
• Ignores the option.

For more information about Compiler options see the section Compiler Options. For more information on compiling and linking programs, see the sections Compiling a Program and Linking a Program, respectively.

Program execution begins at the main entry point. For more information, see the section Main Procedure .

mfvsam Syntax

The mfvsam utility is invoked by the command mfvsam. This utility offers the following options when invoked:

1. Display information about a VSAM file.
2. Create a VSAM file.
3. Add an index to a VSAM file.
4. Delete an index from a VSAM file.
5. Exit.

Open PL/I Compiler Implementation Limits

The Compiler generates messages if your source program exceeds certain Open PL/I Compiler implementation limits. The following table lists these implementation limits.

Footnotes:

1.

The actual spelling of the constant is limited to 256 characters, where the spelling includes the surrounding quotation marks, the extra quotation mark when two single quotation marks represent a single quotation mark inside the string, and the possible trailing X in a hexadecimal string constant or the possibly trailing B and optional digit used to terminate bit-string constants.

2.

64 including the top level procedure.

Preprocessor Options

The options available for use with the mfpp command are explained in the following table. The -ipath and -suffix options obey the rules that apply when they are invoked as compiler options. For more details, see Table 1-3.

Precompiler and Preprocessor Order of Execution

The Open PL/I Macro Preprocessor and the precompilers used by Open PL/I are run by mfplx in the following order:

1. Open PL/I Macro Preprocessor
2. CICS Precompiler
3. Oracle Pro*PL/I Precompiler or DB2 Precompiler

The ordering of the Compiler switches you use has no impact.

You may change the order, if necessary, by separately invoking the preprocessor and precompilers you choose.

Examples

Example 1: Equivalent to an ordinary compilation with -macro.

The command line

mfplx -macro sample.pl1 -#

produces:

mfpp sample.pl1 -pp sample.pp 
mfpli sample.pp -o sample.o 
rm -f sample.pp 
ldpli sample.o

Example 2: Equivalent to an ordinary compilation with -macro and two precompilers.

The command line

mfplx -oracle -macro sample.pl1 -unikix -#

produces:

mfpp sample-pl1 -pp sample.pp 
kixplt -i sample.pp -o sample.pp1 
propli sample.pp1 sample.pp3 
mfpli sample.pp3 -o sample.o 
rm -f sample.pp sample.pp1 sample.pp3 
ldpli sample.o

Example 3: Run macro preprocessor and CICS precompiler only, preserving the intermediate output files.

The command line

mfplx -E sample.pl1 -macro -unikix

produces:

mfpp sample.pl1 -pp sample.pp 
kixplt sample.pp -o sample.pp1

Example 4: Ordinary compile, preserving CICS precompiler output.

The command line

mfplx -unikix -ppcics cicsout.pl1 sample.pl1 -#

produces:

kixplt -i sample.pl1 -o cicsout.pl1
mfpli cicsout.pl1 -o sample.o 
ldpli sample.o

Example 5: Multiple compilations.

The command line

mfplx sample*.pl1 -db2 -unikix -#

produces:

kixplt -i sampleA.pl1 -o samp1eA.pp1 
lpicdb2 -i sampleA.pp1 -o sampleA.pp2 
mfpli sampleA.pp2 -o sampleA.o 
rm -f samp1eA.pp1 sampleA.pp2
kixplt -i sampleB.pl1 -o sampleB.pp1 
lpicdb2 -i sampleB.pp1 -o sampleB.pp2 
mfpli sampleB.pp2 -o sampleB.o
rm -f sampleB.pp1 sampleB.pp2 
ldpli sampleA.o sampleB.o

Compiler Options

Refer to the tables in this section for descriptions of the options available with your Open PL/I Compiler.

• Table 1-3 lists general Compiler options.
• Table 1-4 lists target-specific Compiler options.

Table 1-3 lists and describes each of the Compiler options and its default setting, when applicable.

dirname[:dirname] ...

%INCLUDE partlist;

mfplx source_file -ipath .:/u/libr1:/u/libr2

mfplx source_file -ipath .;drive:\libr1;drive:\libr2

%INCLUDE partlist;

mfplx source_file -isuffix .INC

Intel-Specific Options

Table 1-4 names and describes each Intel-specific option and its default setting, where applicable. Use the default settings of the Compiler options to generate the most efficient code for your system.

Compiler Listings

The Compiler listing options are:

• -l (list)
• -map (storage allocation map)
• -xref (cross-reference)
• -exp (expanded code)

All listing information is directed to the listing file. When any of the listing options are specified, the -l option is invoked by default.

The -l Option

The -l option produces a listing file, which is named by default with the source program name (up to but not including the last ".") and the suffix .list. You can choose another name for the listing file by specifying a name after the -l option, in the following format:

-l file

The listing file contains a program listing, which consists of a copy of the source program with line numbers beginning at 1 in a column to the left of the source line.

The -map Option

The -map option produces a storage allocation map, which displays the location and allocation size of each program entity. The map categorizes this information by name, class, size, location, and attributes.

This information is presented in five columns:

The map first lists external entry points to the program: external constants, subroutines, or programs, including the source program itself. These entry points are listed with name, class, and attributes.

The map then lists program procedures and entities by line number.

The -xref Option

The -xref option provides cross-reference information for each program entity, displaying the line number on which it was declared and the line numbers of all references to it.

The -xref listing for a program is added to the map listing; when you specify the -xref option, you receive a data storage allocation map by default. The cross-reference information appears on the map in the ATTRIBUTES column for each entity, after the line of map attributes information.

References to each entity are listed in the following format:

 DEF line_number REF line_number[...]

A sample map listing with the -xref option follows.

Figure 1-1 Sample Output from the -xref Option

EXTERNAL ENTRY POINTS 
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES 
SYSPRINT     CONSTANT                        FILE EXTERNAL 
                                             DEF 41 REF 41 48 49 
PRIMES       CONSTANT                        ENTRY(MAIN)EXTERNAL
PROCEDURE PRIMES ON LINE 10 
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES 
STORE_CLASS  CONSTANT                        ENTRY 
                                             DEF 90 REF 45 
ARITH_STR    CONSTANT                        ENTRY 
                                             DEF 56 REF 43 
PROCEDURE ARITH_STR ON LINE 56
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES 
DECIMAL      BUILTIN                   BUILTIN 
ESC          AUTOMATIC 6     FFFFFFD8  PICTURED 
FLT_BIN      AUTOMATIC 4     FFFFFFE4  FLOAT BIN(15) 
                                       DEF 63 REF 71 
FIX_DEC      AUTOMATIC 3     FFFFFFEC  FIXED DEC(4,2) 
                                       DEF 62 REF 70
CHR_STR      AUTOMATIC 4     FFFFFFEO  CHAR(4) 
                                       DEF 61 REF 69 
BIT_STR      AUTOMATIC 4B    FFFFFFD4  BIT(4) 
                                       DEF 60 REF 68 
PROCEDURE STORE_CLASS ON LINE 90 
NAME         CLASS     SIZE  LOCATION  ATTRIBUTES 
NUMBER       AUTOMATIC 16B   FFFFFFE8  UNION 
 FIXED_N     MEMBER    2     00000000  FIXED BIN(15,0) 
 FIXED_N_BIT MEMBER    16B   00000000  BIT(16) 
STAT_A_EX    STATIC    3     External  FIXED DEC(5,0)EXTERNAL 
Y            BASED     4     -V-       FLOAT BIN(23)

The -exp Option

The -exp option produces an expanded code listing at the end of the listing file, providing the location and low-level language translation for each instruction and label in the program. The following information is displayed for each statement, in five columns:

Compilation Statistics

The -stat compiler option provides a listing of statistics for each phase of the compilation. The statistics are displayed at the terminal by default or can be redirected to a file. The following figure is a sample terminal display from a UNIX system.

Figure 1-2 Sample Output from the -stat Option (UNIX)

PHASE            USER     SYSTEM    CPU  REAL  13:43:26 
Parser Pass 1    0.05       0.02   0.07     0  13:43:26 
Declare          0.00       0.00   0.00     0  13:43:26 
Parser Pass 2    0.08       0.03   0.11     0  13:43:26 
Allocator        0.01       0.00   0.01     0  13:43:27 
Code Generator   0.71       0.05   0.76     1  13:43:27 
Total            0.85       0.10   0.95     1  13:43:27 

Total source lines:                  38 
Lines per minute (CPU):           2,400 
Lines per minute (real):          2,280 

Text size:                 2,574 bytes 
Data size:                   914 bytes 
Bss Size:                      0 bytes

The following names and describes each of the columns displayed in the printout.

Temporary Files

Compiler-generated temporary files are normally placed in the /tmp directory. If you wish to put them in your current working directory, use the command appropriate to your shell program.

To store Compiler-generated temporary files elsewhere, specify a pathname by using the command appropriate to your shell program.

Optimization

By default, programs are not optimized during compilation. You can specify optimization at level 1, 2, or 3, using the following syntax:

-opt level

For example, "-opt 2". If you specify -opt with no level, level 3 optimizations are performed by default. (Remember that if you use the -deb option, only level 1 or 2 is allowed. If you use -deb and specify -opt with no level, level 2 optimizations are performed.) A brief description of the optimizations performed at each level follows.

Linking a Program

ldpli -dll [options…]

To link an Open PL/I program, use either mfplx or ldpli.

• mfplx compiles and links in one step, automatically invoking ldpli if the -c option is not used. For the use of mfplx, see the section mfplx Syntax .
• ldpli references the components that were installed with this version of Open PL/I and is the recommended link command when using mfpli.

Link Options

Table 1-5 lists link options that permit the use of Open PL/I with other software products. For more information, see the section Using Open PL/I with Other Software Products.

Using ldpli

ldpli references the components, such as libraries, that were installed with Open PL/I. ldpli generates executable files from relocatable object files.

The ldpli command-line syntax is as follows:

ldpli [option] ... object_file [object_file] ... [optional_library] ...

where

Using ldpli with Windows Systems

In addition to supporting all LINK32 options, ldpli includes the following support for Windows systems:

• Indirect files (@ files).
• The -# option, which echoes the command line used to invoke LINK32. This can also be used to redirect output for later use in indirect files.

ldpli enhances the default behavior of the following LINK32 options:

• If -out:filename is not specified, ldpli will generate an executable file with an extension .exe using the basename of the first object file rather than defaulting to noname.exe.
• If -map is specified without specifying the filename (-map:filename), ldpli will generate a map file with the extension .map using the basename of the first object file.

If -deb was used on the command line at compilation time for debugging purposes with CodeWatch, -deb must also be supplied on the command line to ldpli. If using mfplx for both compilation and linking, mfplx will automatically invoke ldpli with -deb.

Running a Program

To run an Open PL/I program, invoke the executable object file produced by the link utility.

The name of the executable object file produced by the linker defaults to a.out. However, if you include the -o filename option on the link command line, the executable object file has the filename that you specified.

For example, "-o sample" on the mfplx command line produces an executable object file named "sample".

Run-time Errors

If an error occurs at run time, a message appears on the terminal. For a description of run-time error conditions and messages, see the appendix Open PL/I Run-time Error Messages .

You can use Open PL/I's ON statement to develop handlers for the conditions that can occur in your program. The ON ERROR statement can be used for arbitrary errors. The ONLOC built-in function can be used in an ON-unit to report the name of an entry in which a condition was raised, and the ONCODE built-in function can be used to report the status value of a run-time error.

When a fatal error condition occurs at run time, a message is displayed naming the condition that has been raised; the program address where this occurred; and the source file, entry, and line number at which the condition was raised, as well as the lines in each procedure above it in the call stack. For example:

*** Condition ERROR raised 
***Unhandled condition ZERODIVIDE at PC=00010233 
CALCDIV line 26 in /dirl/dir2/calcs.pl1 
SUBR3 line 444 in /dirl/dir2/subprog.pl1 
MYPROG line 871 in /dirl/dir2/mainprog.pl1

In this example,

If you have compiled your program using the -nounixdebug option, only the program address where the condition was raised will be displayed:

*** Condition ERROR raised 
*** Unhandled condition ZERODIVIDE at PC=00010233

Accessing Command-Line Arguments in Open PL/I Programs

It is sometimes useful to be able to execute a program specifying one or more arguments on the command line in order to cause a variation in the program's behavior. For example, to run a departmental expense report program, you might issue the command deptexp summary to indicate that you wish to see only category totals rather than all the line items.

Command-line arguments can be accessed in a PL/I main program using the following technique:

/* PL/I main program accessing command line args. */ 

PMAIN: PROCEDURE OPTIONS(MAIN); 

   DECLARE ARGC_     FIXED BIN(31) EXTERNAL STATIC; 
   DECLARE ARGV_     POINTER EXTERNAL STATIC; 
   DECLARE ARG(10)   POINTER BASED; 
   DECLARE ARGS      CHAR(50) BASED; 
   DECLARE ARGSV     CHAR(50) VARYING; 
   DECLARE I         FIXED BIN(31); 

   PUT SKIP EDIT(ARGC_)(f(2)); 
   DO I = 1 TO ARGC_; 
      ARGSV = SUBSTR(ARGV_->ARG(I)->ARGS,1,
            INDEX(ARGV_->ARG(I)->ARGS,BYTE(0))-1); 
      PUT SKIP EDIT('"',argsv,'"')(a,a,a); 
      END; 
   PUT SKIP; 

   END PMAIN;

If your PL/I program is controlled by a C main program, you can pass the command-line arguments through to the PL/I program in the following manner:

/* C main program calling PL/I subroutine */ 

main(argc,argv) 
   int argc; 
   char **argv;
{ 
   PSUBR(argc,argv); 
}

/* PL/I subroutine receiving command line args 
   from C main program */ 

PSUBR: PROCEDURE(ARGC,ARGV); 

   DECLARE ARGC      FIXED BIN(31) VALUE;
   DECLARE ARGV      POINTER VALUE; 
   DECLARE ARG(10)   POINTER BASED; 
   DECLARE ARGS      CHAR(50) BASED; 
   DECLARE ARGSV     CHAR(50) VARYING; 
   DECLARE I         FIXED BIN(31); 

   PUT SKIP EDIT(ARGC)(f(2)); 
   DO I = 1 TO ARGC; 
      ARGSV = SUBSTR(ARGV->ARG(I)->ARGS,1, 
            INDEX(ARGV->ARG(I)->ARGS,BYTE(0)));
      PUT SKIP EDIT('"',ARGSV,'"')(a,a,a); 
      END; 
   PUT SKIP; 

END PSUBR;

Associating a Logical Open PL/I File with a Physical Disk Data File

Open PL/I supports a number of ways to associate your physical disk data files with the logical file names used in Open PL/I sources.

Method 1 (Default)

The run-time environment will use the name of the file variable (or constant) used in the source, shifted to all uppercase.

Example

dcl Payroll file input; 
open file(Payroll);

A file named PAYROLL will be used for all I/O operations using file Payroll.

Method 2

Using the TITLE option on the OPEN statement allows one to specify an explicit disk file name with an optional directory prefix. The use of the TITLE option takes precedence over method 1.

Example

dcl Payroll file input; 
open file(Payroll) title ('/global/acct/sep-95.days')

A file named /global/acct/sep-95.days will be used for all I/O operations using file Payroll.

dcl Payroll file input; 
dcl filename character(100) varying; 
<assignment into filename> 
open file(Payroll) title (filename); 
                                   /* Using a variable name */

The value of filename determines the file that will be used for all I/O operations using file Payroll.

Method 3

The physical disk file name can be specified with the use of UNIX shell environment variables. This method takes precedence over methods 1 and 2. This method allows you to easily alter the physical disk file used for different invocations of the same application.

The environment variable name is the value of the derived name from either of the above methods with MF_ or DD_ prefixed.

Example

dcl file data2 update; 
dcl file specs output; 

open file (data2); 
open file (specs) title('report');

By setting the following environment variables:

• setenv MF_DATA2   /common/data
• setenv MF_REPORT   /common/report

I/O operations for file data2 will access /common/data and I/O for file specs will access /common/report.

Note that to override the name for file variable "specs", the name MF_REPORT was used, because of the title option on its OPEN statement.

In the above example, environment variables of the names DD_DATA2 and DD_report would also be allowed.

Using CodeWatch

CodeWatch is a powerful software development tool that can help you locate bugs in your Open PL/I programs. There are two versions of CodeWatch available with Open PL/I:

• a command-line interface
• a Windows interface

The command-line version offers a traditional line-oriented interface allowing you to interactively enter commands from the keyboard. The Windows interface offers at least two main windows: one that allows you to enter commands and one that allows you to view your source code. You access CodeWatch commands through pulldown menus and dialogs. The Windows interface runs on a graphical workstation running X-Windows.

CodeWatch enables you to control program execution to set breakpoints, monitor what is happening, examine static type data, and evaluate results. CodeWatch keeps track of variables, subroutines, and data types in terms of the symbols used in the source language. You can reference these items without having to consider the underlying machine language or architecture. You can use CodeWatch to access the source text of the program, to identify and reference program entities, and to detect errors in the program's algorithms and logic.

For detailed information on CodeWatch, see your CodeWatch Reference Manual.

Creating a Sharable Library

Open PL/I can be used to create sharable libraries on any of the following operating systems:

• HP–UX
• Solaris 2
• AIX
• UNIX SVR4

To produce code that can be included in a sharable library, other than on AIX, you must ask Open PL/I to produce position-independent code by using the -pic option. The -pic option is not required for AIX, because all Open PL/I code on AIX is position-independent. Once you have object files generated as position-independent code, you link them into a sharable library using the following commands.

On HP–UX, to make a new shared library newshare.sl library:

ld -b -o newshare.sl x1.0 x2.o x3.o 

On Solaris 2 or UNIX SVR4:

ld -G -o newshare.sl xl.o x2.o x3.o 

On AIX:

ld -o newshare.o x1.o x2.o x3.o -bE:newshare.exp -bM:SRE

Using Open PL/I with Other Software Products

Because Open PL/I supports a wide range of data types and because it supports standard calling sequences, Open PL/I can be used with many other software products. These include other Micro Focus products as well as products from other companies. This section lists some of the products that Open PL/I is known to work with and gives some hints about using them with Open PL/I.

UniKix

UniKix is UniKix Technologies' CICS system for open systems. Open PL/I supports and is supported by UniKix to enable you to develop On-Line Transaction Processing applications in PL/I.

To create UniKix screens, use UniKix's BMS screen generator utility. Within your screen definition place the command:

LANGUAGE = PLI

Open PL/I provides a CICS precompiler, kixplt, that you can use to process embedded EXEC CICS statements within your PL/I programs. For more information about using Open PL/I's CICS precompiler, see the section Precompiler and Preprocessor Order of Execution .

The following restrictions apply to Open PL/I programs being used as UniKix applications:

• Ordinary PL/I input/output statements must not be used. There are EXEC CICS commands for accessing data files.
• Open PL/I sort routines, PLISRTx, must not be used.
• STATIC storage must be read-only. The INITIAL attribute can be used to assign values to variables in STATIC storage.
• The following PL/I statements must not be used: DELAY, STOP.
• Variables or structures must not be defined with variable names that are the same as variable names generated by the CICS precompiler. These names begin with "DFH."

If OPTIONS(MAIN) is specified in an application program, that program can be the first program of a transaction, or control can be passed to it by means of an EXEC CICS LINK or XCTL command.

The definition of the External Interface Block (EIB) is generated in each program based upon the pointer variable DFHEIPTR. In programs compiled with OPTIONS(MAIN), the DFHEIPTR variable is set by UniKix to address the EIB on entry; therefore, the CICS precompiler will insert DFHEIPTR and DFHCOMMAREA (pointer to the communications area) as parameters of the MAIN program. For example, the following source line

TEST: PROCEDURE OPTIONS(MAIN);

will be translated to

TEST: PROCEDURE(DFHEIPTR, DFHCOMMAREA) OPTIONS(CICSMAIN);

In programs other than those declared with OPTIONS(MAIN), addressability to the EIB is the user's responsibility. This can be achieved by using the CICS command

EXEC CICS ADDRESS EIB(DFHEIPTR);

or by passing the EIB address or the values of particular EIB fields as parameters.

To perform proper initialization and cleanup, all procedures declared with OPTIONS(MAIN) that contain EXEC CICS statements, or that are calling other procedures containing EXEC CICS statements, must be run through the CICS precompiler.

Open PL/I's UniKix support is license managed. You must obtain a special license from Micro Focus to use it. Of course, you must also have the UniKix product.

Oracle

Open PL/I can be used with the Oracle database system. Oracle's Pro*PL/I SQL precompiler is supplied with Open PL/I.

For more information about using Pro*PL/I with Open PL/I, see the section Precompiler and Preprocessor Order of Execution , and for information about Open PL/I SQL options, see the chapter Open PL/I SQL Options . Also refer to the following other documents: Programmer's Guide to the Oracle Precompilers and Pro*PL/I Supplement to the Oracle Precompiler Guide.

Open PL/I's Oracle support is license managed. You must obtain a special license from Micro Focus to use it. Of course, you must also have the Oracle product.

DB2

Open PL/I can be used with the IBM's DB2 database system. Open PL/I has a precompiler for embedded EXEC SQL statements in your PL/I programs.

For more information about using the DB2 SQL precompiler with Open PL/I, see the section Precompiler and Preprocessor Order of Execution , and for information about Open PL/I SQL options, see the chapter Open PL/I SQL Options .

Open PL/I's DB2 support is license managed. You must obtain a special license from Micro Focus to use it. Of course, you must also have IBM's DB2 product.

C++/Views

C++/Views is Intersolv's object-oriented graphical user interface (GUI) program framework. C++/Views includes an interactive graphical designer, as well as an extensive C++ class library. Using C++/Views, you can create the framework for an application with an attractive and efficient graphical user interface. Your C++ framework can then call procedures written with Open PL/I to do your ordinary data processing work.

A C++/Views example, PhoneList, is included in the product set. The example consists of a number of C++ source modules and one PL/I module, a readme file, and a makefile.

C++/Views is not yet available on the following platform supported by Open PL/I:

• Intel-based computers running UNIX SVR4 or Windows

SyncSort

SYNCSORT_DEBUG 33
export SYNCSORT_DEBUG

Open PL/I and Informix

Open PL/I follows the native C compiler's naming conventions. This allows you to mix subroutines and functions compiled with Open PL/I with any other language or third-party library that supports a C language interface. However, you must link the Open PL/I run-time libraries into the final stand-alone program. The -cisam link option enables the C-ISAM package from Informix for VSAM/indexed files.

Informix fully documents their Application Programming Interface for the C language. In general, you should follow the Informix directions for mixing Informix and C, simply treating the modules compiled with Open PL/I as C modules. For information on how to write programs that mix PL/I with C, please see the chapter Language Concepts in this guide.

The following examples illustrate the command used to link an Open PL/I program that uses the Informix libraries. For the purposes of this illustration the Open PL/I Compiler and Informix modules are running on a Sun Solaris system. The Open PL/I modules are called "testobj1.o" and "testobj 2.o", the Open PL/I Compiler has been installed in /opt /pl1, and the environment variable $MFPLI_PRODUCT_DIR has been set to that directory.

ldpli testobj1.o testobj2.o -o testprogram 
/opt/informix/lib/esql/libsql.a
/opt/informix/lib/esql/libgen.a 
/opt/informix/lib/esql/libos.a
/usr/ucblib/libucb.a 
/opt/SUNWspro/SC3.0/lib/cg92/_fstd.o

Note that the names and locations of the Open PL/I and Informix libraries are specific to your installation of Informix and Open PL/I. This illustrates a typical installation.

Open PL/I and Micro Focus

Open PL/I follows the native C compiler's naming conventions. This allows you to mix subroutines and functions compiled with Open PL/I with any other language or third party library that supports a C language interface. You must link the Open PL/I run-time libraries into the final stand-alone program. Micro Focus fully documents inter-language calling between COBOL/2 and C. In general, you should follow the Micro Focus directions for mixing COBOL and C, simply treating the modules compiled with Open PL/I as C modules. The following test program illustrates a COBOL program that calls a PL/I function, passing a string as an argument.

The COBOL source code module:

WORKING-STORAGE SECTION. 01 STR PIC X(20). 
*
PROCEDURE DIVISION.
CALL-PL1 SECTION. 
DISPLAY "Calling the PL/I program". 
CALL "PL1PROC" USING STR.
DISPLAY "Return from PL/I program".
DISPLAY STR. 
STOP RUN.

The PL/I source code module:

PL1PROC: PROCEDURE ( CHARSTR );
DECLARE CHARSTR CHARACTER(20); 

CHARSTR = 'This is a real test!'; 

END PL1PROC;

The commands to compile and link:

mfplx mfpll.pl1 -stat -c 

cob mfcob.cbl mfpl1.o -o mf -v -V -x \ 
    /pl1dir/lib/dflock.o071030 \ 
    /pl1dir/lib/noofm.o071030\ 
    /pl1dir/lib/lpi.a071030

Note that the names and locations of the Open PL/I libraries are specific to your version of Open PL/I. This illustrates a typical installation.

Open PL/I and Encina

Encina is Transarc Corporation's online transaction processing system. Encina can be accessed from Open PL/I using Encina's open application program interface (API). All Encina functions can be accessed. The -tisam link option enables the TISAM package from Transarc for VSAM/indexed files. This allows for sharing datafiles in the SFS format. You can use Open PL/I to develop transaction processing client server applications with one caveat concerning multi-threaded programming.

The I/O subroutines in Open PL/I's run-time library are not thread-safe. Code that contains PL/I I/O can be made thread-safe by using the global lock to serialize PL/I I/O, as in the following example:

DECLARE 

  PTHREAD_LOCK_GLOBAL_NP 
      EXTRY() EXTERNAL('pthread_lock_global_np'), 
  PTHREAD_UNLOCK_GLOBAL_NP 
      ENTRY() EXTERNAL('pthread_unlock_global_np'); 

  CALL PTHREAD_LOCK_GLOBAL_NP(); 

  /* PL/I I/O ... */ 

  CALL PTHREAD_UNLOCK_GLOBAL_NP();

For information on programming with threads, see the OSF DCE Application Development Guide.

A complete example of using Encina with Open PL/I can be found in the directory $MFPLI_PRODUCT_DIR/examples/OpenPLI/encina.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.