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 remote called program must be an EGL program generated for the IMSVS, IMSBMP, or ZOSBATCH environment. Non-EGL programs that run in these environments are also supported. Calling remote programs that access DL/I on CICS® is not supported.
- Only DL/I database PCBs are supported. The calling and the called program cannot access an I/O PCB, TP PCBs, or GSAM PCBs. For programs that you debug on the workstation, if you plan to associate a serial record with an I/O, TP, or GSAM PCB at generation time for debugging purposes, use a resource association with a fileType of seqws to access a sequential file on the workstation instead.
- Only database PCBs can be passed to the called program. You cannot pass other types of PCBs or pass dliLib.psbData to the called program.
- Remote calls to Text UI programs are not supported.
- Transfers to a remote program and transfers to a transaction are not supported.
- The following DL/I calls are not supported: CHKP, GSCD, PCB, TERM, and XRST.
- All database PCBs in the IMS™ PSB must be named and the name must match the corresponding pcbName property in the EGL PSB.
- Configure a linkage options part with the remoteComType set to STOREDPROCEDURE. This will direct the call to the host through the stored procedure so it participates in the transaction and can access the DL/I specified PSB.
- Configure your debug build descriptor so that the build descriptor option linkage points to the linkage options part that you created.
- Configure the host environment.
- Configure your local workspace.
- Start the EGL DL/I Debug Server on the host. The information about configuring the host environment and your local workspace is contained in this section. For information on starting the debug server, see Starting the DL/I Debug Server on the z/OS® host.
Configuring the host environment
- 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.
- 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.
- Create the DRA (Database Resource Adapter) Startup Table (ELADRA). For more information, see DRA Startup Table in this topic.
- Create the WLM (Workload manager) (ELADBWLM). For more information, see Workload manager in Configuring DB2® for stored procedure linkage.
- Create the DB2® stored procedure (EZESP1CR and EZESP1GR). For more information, see DB2® stored procedure in Configuring DB2® for stored procedure linkage.
- Provide the PSB information. For details, see "Local workspace configuration" later in this topic.
- 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
- 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.
| 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: 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
- In , 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 . If not, go to 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.