| Debugging PL/I Applications | |
This chapter describes the principal features of the Mainframe Express PL/I Option.
PL/I Option lets you work with PL/I programs in Mainframe Express in a similar way to COBOL programs:
When you add a PL/I source module to a project, Mainframe Express scans the source module to find any references to included modules. These are shown as dependencies on the Project View.
The compiler and linker object modules are placed in a Load Libraries folder, in the usual way.
The methods for working with PL/I programs are similar to those for COBOL programs.
When you install PL/I Option, the following changes are made to the IDE:
The output from the PL/I compiler and linker is displayed in the Mainframe Express Output window in the usual way. However, the VisualAge PL/I debugger uses its own windows, outside of the Mainframe Express IDE, to display debugging information and let you interact with the debugger.
More information on debugging is given in the chapter Debugging PL/I Applications and sample tutorial sessions are included in the chapters Getting Started with PL/I Applications and Getting Started with CICS and PL/I Applications. Also, comprehensive online help is available from the Help menu within the VisualAge PL/I debugger or from the Windows desktop by clicking Start>Programs>Micro Focus Mainframe Express 2.0>IBM VisualAge PLI Help.
The following list summarizes the things you need to do when defining a project for a PL/I application:
The compiler directives for the build settings that you have selected with the controls described above are shown in a field on the dialog box. You can also specify explicitly any other compiler directives you want that are not set by these controls.
The following list shows the sample applications that are supplied with PL/I Option. For each application, a readme.txt file is supplied which describes how to create a project and execute the applications.
| Application |
Summary |
| PLIBATCH | The PLIBATCH application demonstrates the use of
mixed-language programming and I/O operations with a shared DB2
subsystem.
The Readme file is in folder \mfuser\projects\demo\plibatch. The source files are in folder \mfuser\projects\demo\plibatch\source. The data files are in folder \mfuser\projects\demo\plibatch\data. |
| PLICICS | The PLICICS application demonstrates an online CICS
application written in PL/I.
The Readme file is in folder \mfuser\projects\demo\plicics. The source files are in folder \mfuser\projects\demo\plicics\source. The data files are in folder \mfuser\projects\demo\plicics\data. |
| PLIIMS | The PLIIMS application demonstrates an online IMS
application written in PL/I and performing SQL calls.
The Readme file is in folder \mfuser\projects\demo\pliims. The source files are in folder \mfuser\projects\demo\pliims\source. The data files are in folder \mfuser\projects\demo\pliims\data. |
You can mix PL/I, COBOL and Assembler programs in a single application. Mainframe Express supports this for PL/I .dll modules, COBOL .int (intermediate) and .gnt (optimized) modules, and Assembler .390 modules. It does not support the linking of PL/I and COBOL programs in the same .dll module.
When one module in a mixed-language application calls another, Mainframe Express looks for the module to load in a specific order:
This takes care of the situation where, for example, there is an Assembler module and a PL/I module of the same name: Mainframe Express finds and loads the Assembler module first.
If you enable PL/I debugging in a mixed PL/I and COBOL application, only COBOL .int modules are debuggable; COBOL .gnt modules are run at full speed without being debugged.
For more information about mixed PL/I and Assembler applications, see the section Using PL/I with Assembler Option later in this chapter.
As with COBOL and Assembler programs, an addressing mode (AMODE) can be defined for each PL/I load module. This is done at link time.
PL/I uses a different method for representing mainframe addresses than COBOL and Assembler. This can cause a problem if a pointer is passed as a parameter between a PL/I program and COBOL or Assembler program. You can avoid this problem in either of two ways:
Mainframe Express automatically manages the passing of pointers between PL/I and the system environment, such as CICS and IMS.
You need to use the PL/I pointer-conversion functions supplied with Mainframe Express if not all programs in the application use 31-bit addressing mode (AMODE 31) and a pointer is passed as a parameter between a PL/I program and a COBOL or Assembler program. These functions are supplied in a macro file that you can include in your PL/I source modules. It is named idapconv.inc in the \mfe\source folder.
You do not need to change your PL/I source modules to remove these functions before you recompile the modules on the mainframe. The functions are treated as null operations on the mainframe.
The VisualAge PL/I pointer format is known as the DFT (default) type. The Mainframe Express pointer format is known as the MFPM (Mainframe Pointer Manager) type. The two functions for pointer conversion are:
You can use them as PL/I function references in the usual way, as shown in the following examples.
some_pointer=ptr_type_mfpm(some_pointer);
call asm_rtn(ptr_type_mfpm(some_pointer));
some_pointer=ptr_type_dft(some_pointer);
ptr_type_dft(some_pointer)->some_variable='New Value';
The MVS control blocks emulated by Mainframe Express are described in the chapter MVS Control Blocks in your IDE Technical Guide.
Mainframe Express supplies bilingual macros for Assembler and PL/I to define the MVS control blocks. They are located in the folder \mfe\source. The macros have the same name as the control blocks and have the .mac file extension. They describe the key problem program state fields. Only fields that are supported are named in the macros; the others are defined as "fillers".
The MVS control blocks are located from the Communications Vector Table (CVT) which is located from the Prefixed Save Area (PSA) which starts at byte 0. On the mainframe, the PSA can be addressed directly. On the PC, a protection exception is raised if a PL/I application uses a pointer with a value of zero. To avoid this, you should use the idalpsa macro to locate the PSA. This macro sets a given pointer to the address of the PSA. It operates correctly on both PC and System/390 hardware.
The idalpsa macro is contained in the idalpsa.inc file that is supplied with Mainframe Express in the folder \mfe\source. Include this file after the first PROCEDURE statement or after the PACKAGE statement and check Macros on the Preproc page of the PL/I page of the Build Settings dialog box.
You can invoke the idalpsa macro as a PL/I function. For example:
some_pointer = idalpsa(some_pointer);
sets some_pointer to the address of the PSA.
The following list shows the sample projects that are supplied with Mainframe Express to illustrate how to access the MVS control blocks in a PL/I program. For each project, a readme.txt file is supplied which describes how to create the project and run it.
| Project |
Summary |
| CTLBLKP | The CTLBLKP project contains a PL/I program which calls
an Assembler routine to extract information from the MVS control blocks.
The Readme file is in folder \mfuser\projects\demo\ctlblkp. The source files are in folder \mfuser\projects\demo\ctlblkp\source. |
| CTLPLI | The CTLPLI project contains a PL/I program which uses
the idalpsa macro to locate the PSA and then extracts
information from the MVS control blocks.
The Readme file is in folder \mfuser\projects\demo\ctlpli. The source files are in folder \mfuser\projects\demo\ctlpli\source. |
For PL/I programs, all entry points are automatically known to the Entry Point Mapping facility after the program is linked. Thus, unlike COBOL and Assembler programs, you do not need to specify any entry points explicitly.
Like Assembler, you can use the ALIAS command to create an alias Entry Point Mapping entry automatically during the static link process for a load module.
For more information, see the section Entry Point Mapping for COBOL and Assembler Programs in the chapter Compatibility with the Mainframe Environment in your User's Guide.
Mainframe Express emulates a subset of Language Environment (LE) for PL/I as well as COBOL. For full information on the support provided, see the chapter Language Environment (LE) Support chapter in your IDE Technical Guide.
The chapter Compiling and Linking Assembler Modules in the Assembler Option Technical Guide provides a full description of how modules can be linked together, including the difference between static linking (which takes place at build time) and dynamic linking (which takes place at run time). The following section contains information that you need to consider when using PL/I and Assembler modules in the same application.
You cannot statically link Assembler modules with PL/I modules in one executable program. However, there are two methods of dynamically linking to PL/I modules:
You need an INCLUDE command in your link (.lin) file for each PL/I module that you want to be linked with the main module to produce one .390 file. The INCLUDE command is documented in full in the online help; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Link File Commands. With PL/I Option installed, the TYPE parameter can take the value PLI, indicating that you want to include a PL/I object module (.pli)
The LOAD Assembler macro is documented in full in the online help; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Macro Instructions. With PL/I Option installed, the stub Assembler macro (that is generated if the LOAD macro cannot locate an Assembler module) can load and link to a PL/I module. If a PL/I module is to be loaded, the LOAD macro loads the stub Assembler module below the 16 MB line; the stub Assembler module then loads the PL/I module above or below the line, depending on its AMODE setting.
CICS Option supports IBM mainframe PL/I application programs in conjunction with PL/I Option. You should be aware of the following PL/I-specific information when running these programs on the PC:
SQL Option for DB2 supports IBM mainframe PL/I application programs in conjunction with PL/I Option. You should be aware of the following PL/I-specific information when running these programs on the PC.
You can use the Declaration Generator utility to create the PL/I definition for an SQL table in a similar way to creating a COBOL definition. The utility generates an EXEC SQL DECLARE statement and a PL/I structure in a copybook (.inc) file.
For full information on how to use the Declaration Generator, see the Declaration Generator Online Reference.
You can run the utility in batch or interactive mode. If you want to use batch mode to create a PL/I definition, specify -lpli as the language option. If you want to use interactive mode to create a PL/I definition, perform the following steps:
If you specify a file that already exists, you will be given the choice of appending to it or replacing it when you click Generate later.
If you don't specify a path, the copybook is written to ProjectFolder\COPYLIB.
/* PL/I DECLARATION FOR TABLE TUTORIAL.EMPLOYEE */
DECLARE
1 DCLEMPLOYEE,
5 EMP_001 BIN FIXED(15),
5 EMP_002 CHAR(10),
5 EMP_003 CHAR(10);
If you specify a field prefix and want to use the actual field names instead of numbers for the variable part of each name, select the Text radio button. Then, for example, the fields in the above structure could be generated as:
5 EMP_E_NO BIN FIXED(15),
5 EMP_LNAME CHAR(10),
5 EMP_FNAME CHAR(10);
Remember to take into account PL/I variable-naming rules when assigning a prefix. Do not assign a prefix containing characters that are not supported by the compiler or that make the field name too long.
If you do not specify a field prefix, the above example would be generated as:
5 E_NO BIN FIXED(15),
5 LNAME CHAR(10),
5 FNAME CHAR(10); 3 E_NO BIN FIXED(15),
3 LNAME CHAR(10),
3 FNAME CHAR(10); DCL IEMPLOYEE(3) BIN FIXED(15);
The structure of the SQL communications area (SQLCA) is defined below. It must be included in every PL/I program that contains embedded SQL.
DECLARE
1 SQLCA,
2 SQLCAID CHAR(8)
2 SQLCABC FIXED(31) BINARY,
2 SQLCODE FIXED(31) BINARY,
2 SQLERRM CHAR(70) VAR,
2 SQLERRP CHAR(8),
2 SQLERRD(6) FIXED(31) BINARY,
2 SQLWARN,
3 SQLWARN0 CHAR(1),
3 SQLWARN1 CHAR(1),
3 SQLWARN2 CHAR(1),
3 SQLWARN3 CHAR(1),
3 SQLWARN4 CHAR(1),
3 SQLWARN5 CHAR(1),
3 SQLWARN6 CHAR(1),
3 SQLWARN7 CHAR(1),
2 SQLEXT,
3 SQLWARN8 CHAR(1),
3 SQLWARN9 CHAR(1),
3 SQLWARNA CHAR(1),
3 SQLSTATE CHAR(5);
The structure of the SQL descriptor area (SQLDA) is shown below. It should be included by all PL/I programs that use dynamic SQL.
DECLARE
1 SQLDA BASED(SQLDAPTR),
2 SQLDAID CHAR(8),
2 SQLDABC FIXED(31) BINARY,
2 SQLN FIXED(15) BINARY,
2 SQLD FIXED(15) BINARY,
2 SQLVAR(SQLSIZE) REFER(SQLN)),
3 SQLTYPE FIXED(15) BINARY,
3 SQLLEN FIXED(15) BINARY,
3 SQLDATA POINTER,
3 SQLIND POINTER,
3 SQLNAME CHAR(30) VAR;
DECLARE SQLSIZE FIXED(15) BINARY;
DECLARE SQLDAPTR POINTER;
Host Compatibility Option supports IBM mainframe PL/I application programs in conjunction with PL/I Option. You should be aware of the following PL/I-specific information when running these programs on the PC:
IMS Option supports IBM mainframe PL/I application programs in conjunction with PL/I Option. You should be aware of the following PL/I-specific information when running these programs on the PC:
There are two PCB address list formats for PSBs which specify LANG=PL/I. These are direct addressing and indirect addressing.
The PCB address list format applies only to main programs. It is specified under PCB address list format for LANG=PL/I on the General page of IMS System properties. This is found by right-clicking IMS System on the IMS View and clicking Properties. There are two fields, one for when the main program is PL/I and one for when the main program is not PL/I. The second field is available only when indirect addressing is specified for the first.
PSBs that don't specify LANG=PL/I are not affected by these settings and always result in a direct PCB address list.
Each time a PL/I compiler message is generated, the PL/I compiler can invoke the user exit program IBMUEXIT. This exit is controlled by the EXIT compiler directive and is set on by default.
You can use IBMUEXIT to suppress a compiler message or to change its severity. The changes made by the exit take effect before the message limit specified in the Stop after field on the General page of the PL/I page on the Build Settings dialog box (or by the FLAG directive) is evaluated.
Full information about IBMUEXIT and the IBM-supplied modules is given in the section Using User Exits in the IBM VisualAge PL/I Programming Guide. Several modules to support IBMUEXIT are supplied with PL/I Option in the folder \mfe\mfpli\source:
If you want to disable IBMUEXIT, specify the NOEXIT compiler directive in the Additional directives field on the General page of the PL/I page of the Build Settings dialog box.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Debugging PL/I Applications | |