Using the EGL debugger to debug IMS, ZOSBATCH, and DL/I with the stored procedure linkage

You can debug EGL programs that call remote IMS™ or ZOSBATCH programs.

The program you are debugging can access an SQL database, a DL/I database, or both. Similarly, the remote IMS or ZOSBATCH called program can access an SQL database, a DL/I database, or both. The debugger makes database calls to the host and also makes calls to generated programs on the host, but otherwise interprets the code on the local client system.

The following restrictions apply to this IMS and DL/I debug support:
Whenever you debug a program that accesses DL/I or that does a remote call to IMS or ZOSBATCH, you must do as follows:

Configuring the host environment

Several prerequisites are needed on the host, for debugging:
  • Ensure that the following applications are in use:
    • TCPIP
    • DB2® v.7 or higher
    • IMS v.7 or higher
      • Open Database Access (ODBA)
    • Resource Recovery Services (RRS)
    • Workload Manager (WLM)
  • Note that the EGL DL/I debugger uses ODBA to talk to the DL/I database capabilities in IMS. RRS/MVS (Resource Recovery Services) is required; OS/390® Release 3 is the minimum level that can support the ODBA interface.
Carry out the following actions on your host system. Perform steps 1-5 only once. Complete the final step before starting your debugging session on the workstation.
  1. Create an EGL version of the AIBTDLI and CBLTDLI load modules (ELADL1). This step is only required if your debug session does a remote call to a program that accesses a DL/I database. This EGL version of these modules ensures that the called program runs in the same unit of work as the debugger session on the workstation. For more information, see “Creating the EGL version of AIBTDLI and CBLTDLI” in this topic.
  2. Create the DRA (Database Resource Adapter) Startup Table (ELADRA). For more information, see “DRA Startup Table” in this topic.
  3. Create the WLM (Workload manager) (ELADBWLM). For more information, see “Workload manager” in “Configuring DB2 for stored procedure linkage.”
  4. Create the DB2 stored procedure (EZESP1CR and EZESP1GR). For more information, see “DB2 stored procedure” in “Configuring DB2 for stored procedure linkage.”
  5. Provide the PSB information. For details, see "Local workspace configuration" later in this topic.
  6. Start the EGL DL/I Debug Server. For more information, see “Starting the DL/I Debug Server on the z/OS host.”.
    • For more information about the proxy startup JCL (ELADBGPX), see "Procedure" in “Starting the DL/I Debug Server on the z/OS host.”
    • For more information about the debug server startup JCL (ELADBGRN), see "JCL to start the Debug Server" in “Starting the DL/I Debug Server on the z/OS host.”

Rational® COBOL Runtime for zSeries provides sample files; the member names are shown above inside parentheses. All JCL and SQL samples are located in the COBOL runtime, either in ELA.V6R0M1.SELAJCL or ELA.V6R0M1.SELASAMP.

Creating the EGL version of AIBTDLI and CBLTDLI

Restrictions apply when you debug a program that calls a program with all of the following characteristics:
  • Runs on IMS or ZOSBATCH
  • Resides on the host
  • Accesses a DL/I database

In this case, the EGL debugger requires that you use EGL versions of the AIBTDLI and CBLTDLI load modules and not the IMS-provided load modules. Rational COBOL Runtime for zSeries provides sample JCL to create these load modules in ELA.V6R0M1.SELAJCL(ELADL1). Edit the JCL and modify it for your system requirements; comments in the JCL explain what you need to modify. After you run the job, make sure you add the PDS that contains the resulting AIBTDLI and CBLTDLI load modules to the STEPLIB for the Workload manager JCL.

Creating the DRA Startup Table

Rational COBOL Runtime for zSeries provides sample JCL for creating the DRA Startup Table in ELA.V6R0M1.SELASAMP(ELADRA). The following table lists the changes you need to make before running the job. After you run the job, make sure you add the PDS that contains the resulting DRA startup table to the STEPLIB for the DLI Debug Proxy. For more information, see “Starting the DL/I Debug Server on the z/OS host.”

Table 1. Changes to ELADRA.JCL
From To
  Add a jobcard
SYSLIB Modify to match your system configuration.
#dbctlid Replace #dbctlid with the DB control id for your database. This value also goes into the imsID build descriptor option.
The value comes from the JCL that you use to start IMS. The IMS JCL parameter should look like this:
IMSID   XXXX  IMS SUBSYSTEM IDENTIFIER
In this example, XXXX represents the DB control id.
IMS.SDFSRESL The PDS SDFSRESL for your system.
MAXTHRD=99 Replace 99 with the max number of simultaneous debug sessions (the minimum is 3).
CNBA=0 (FPBUF+FPBOF)*MAXTHREAD *
FPBUF=0 FPBUF is the number of buffers to be allocated to each thread for FP use. *
FPBOF=0 FPBOF is the number of buffers and overflow buffers to be allocated to each thread for FP use. *
TIMEOUT=60 Set the TIMEOUT startup parameter as high as possible, preferably longer than longest running UOR.
AGN=IVP See IMS 7 Administration Guide System for information on configuring IMS security.
//SYSLMOD DD DSN=ELA.V6ROM1.SELADBGL Replace ELA.V6ROM1.SELADBGL with the PDS where you want the DRA startup to reside.
NAME DFSIVP10(R) Replace DFSIVP10 with DFS followed by #dbctlid from above.
* Refer to the IMS Administration Guide for more information on setting these fields

The following listing shows the sample JCL:

//ASM EXEC PGM=IEV90,
//       PARM='DECK,NOOBJECT,LIST,XREF(SHORT),ALIGN',
//       REGION=4096K
//SYSLIB DD DSN=IMS.OPTIONS,DISP=SHR
//       DD DSN=IMS.SDFSMAC,DISP=SHR
//       DD DSN=SYS1.MACLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT2 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT3 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSPUNCH DD DSN=&&OBJMOD;,
//       DISP=(,PASS),UNIT=SYSDA,
//       DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
//       SPACE=(400,(100,100))
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
PZP      TITLE 'DATABASE RESOURCE ADAPTER STARTUP PARAMETER TABLE'
DFSIVP10 CSECT
**********************************************************************
*        MODULE NAME: DFSIVP10                                       *
*        DESCRIPTIVE NAME: DATABASE RESOURCE ADAPTER (DRA)           *
*                  STARTUP PARAMETER TABLE.                          *
*        FUNCTION: TO PROVIDE THE VARIOUS DEFINITIONAL PARAMETERS    *
*                  FOR THE COORDINATOR CONTROL REGION. THIS          *
*                  MODULE MAY BE ASSEMBLED BY A USER SPECIFYING      *
*                  THEIR PARTICULAR NAMES, ETC. AND LINKEDITED       *
*                  INTO THE USER RESLIB AS DFSPZPXX.  WHERE XX       *
*                  IS EITHER 00 FOR THE DEFAULT, OR ANY OTHER ALPHA- *
*                  NUMERIC CHARACTERS.                               *
**********************************************************************
         EJECT
         DFSPRP DSECT=NO,                                              X
               DBCTLIB=#dbctlid,                                       X
               DDNAME=,                                                X
               DSNAME=IMS.SDFSRESL,                                    X
               MAXTHRD=99,                                             X
               MINTHRD=2,                                              X
               TIMER=60,                                               X
               USERID=,                                                X
               CNBA=10,                                                X
               FPBUF=5,                                                X
               FPBOF=3,                                                X
               TIMEOUT=60,                                             X
               SOD=A,                                                  X
               AGN=IVP
         END
//LNKEDT EXEC PGM=IEWL,
//       PARM='LIST,XREF,LET,NCAL'
//SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(100,50))
//SYSPRINT DD SYSOUT=*
//SYSLMOD  DD DSN=ELA.V6R0M1.SELADBGL,DISP=SHR
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&OBJMOD;
//         DD DDNAME=SYSIN
//SYSIN    DD *
   NAME  DFSIVP10(R)

Local workspace configuration

Take the following actions in your local workspace to enable remote debugging:
  • In Window > Preferences > EGL > Debug, clear the Set systemType to DEBUG option. This will force EGL to use the system type from the build descriptor option.
  • You must have JDBC on the client system. The actual .jar files you need depend on the version of JDBC that you are running.
  • Make sure you have a functioning default JDBC DB2 connection to the host; the EGL debugger uses this connection to access DL/I.
  • If you access a DB2 database in both the debugged code and in a called program, the Default JDBC connection must be set to NOAUTOCOMMIT.
  • Set the imsID build descriptor option to the CHAR(4) name of your IMS subsystem.
  • Make sure you have a preference page for IMS DLI under Window > Preferences > EGL > Debug. If not, go to Window > Preferences > General > Capabilities and click Advanced. In the Advanced window, expand EGL Developer and select the EGL DLI check box. Close and reopen the Preferences window to see the IMS DLI debug page.
  • On the IMS DLI debug preferences page (see previous step), enter the following information
    StoredProcedure
    The stored procedure on the host. This can be the fully qualified name. If this is blank it is assumed to be the default value of EZESP1. The value of the sqlSchema property from the build descriptor is prepended to this value. The stored procedure name follows the rules for "procedure-name" as described in the SQL Reference for ZOS DB2.
    HostPort
    The number of the port where the debugger server is listening.
    ConversionTable
    Defines the language of the host. This is the same table used in call linkage conversion.
    ProxyIdleTimeout
    The amount of time the proxy will sit idle (no DL/I activity) before the debugger server tells it to abort. This should be long enough to allow for processing time, but short enough that you don't use up all available processes in case the connection drops repeatedly.
    PSB Name
    Select one of the following options for specifying the PSB name:
    Review the build descriptor option imsPSB
    A non-blank value in build description option imsPSB takes precedence over any other source of PSB name.
    Prompt user for PSB name
    At the start of each debug session, the user is prompted to enter the PSB name used to access DL/I data. With the ODBA interface, the PCB must be named and must match a PCB in the PSB defined either in the program for IMS or in dliLib.psbData for CICS.
    Use PSB name from DLILib.psbData
    The default for CICS. The program still uses a DL/I property for transaction commit/rollback determination, but the PSB name comes from the psbData record in dliLib.
    Use program name for PSB name
    The default for IMS. This is either the value of the alias property (if used), or the program name. This value is folded to upper case.

Feedback