B3 Debuging IMS 200902

Debugging Applications IMS
Software Group
Debugging IMS
with Debug Tool
Sylvie Delahaye Sylvie.Delahaye@fr.ibm.com
© 2009 IBM Corporation
Software Group
Debug Tool Overview

Provides debugging of enterprise applications
Features:
– Playback support
– Automonitor support for COBOL and PL/I
DB2
Web programs
BATCH IMS TSO CICS USS
Sphere – An interface to the Fault Analyzer tool
Application Languages – A code coverage tool
COBOL, PL/I, ASSEMBLER, C/C++ – Support for identifying and converting OS/VS
COBOL source programs to ANSI 85
standard COBOL
Debug
application – Preparation and compile facilities for
in programs
supported
environments – Commands to query, allocate, and free files
Debug
Tool Consistent Across Languages
– COBOL, C, C++, PL/I, Assembler
Environments Supported
3270 GUI – CICS, TSO, JES/Batch, IMS Including

RDz IMS/TM, DB2 Including Stored Procedures
– Uses the GUI debug interface built into
products such as:
• Rational Developer for SystemZ (RDz)
RePenser IMS - Février 2009 - Paris 1

Software Group
Debug Tool Highlights

MFI
Common User Interface Across
Systems And Subsystems
Consistent Across Languages
–COBOL (all versions), C/C++,
PL/I, Assembler
Environments Supported
–CICS, TSO, JES/Batch, IMS
including IMS/TM, DB2 Including
Stored Procedures, Unix System
Services (USS), WebSphere MQ
Interfaces:
–Terminal Interface Manager (UID) RDz
–VTAM Terminals (MFI)
–Rational Developer for System z
–batch
Software Group
Process for All z/OS Debuggers (IBM and vendor):
Build:
– Compile and Link a z/OS load module generating support
for the interactive debugging
Invoke:
– Load the module under the control of the debugger
Execute:
– Control the execution of the module via the debugger
interface

Software Group
Debug Tool Build Process:
TEST compiler option
Compiler Link Edit
Program source
Load
Module
SYSDEBUG or
Compiler listing
Software Group
IBM Debug Tool Build Process
Debug Tool module support is integrated into all IBM compilers

(COBOL (all versions), PLI, C/C++)
Module support for Debug Tool is generated as part of the base
compile process
Debug Tool sidefile (SYSDEBUG or compiler listing) support is
built internally into the load module, not at program invocation
Debug Tool compiler function supports:
– Compiled in Debug Hooks:
• supporting “read only” memory
– Dynamic Hooks:
• supporting production modules

Software Group
Choosing compiler options for debugging
Compiler options affects the size of your load module and the amount of
Debug Tool functionality available to you. Debug Tool uses information
such as hooks and symbol tables to gain control of a program, run the
program statement-by-statement or line-by-line, and display information
about your program.
COBOL TEST(NONE,SYM,SEPARATE)
Enterprise COBOL V4.1 TEST(NOHOOK,SEPARATE)
PL/I (< Ent. V3.4) TEST(ALL,SYM)
Enterprise PL/1 V3.7 TEST(ALL,NOHOOK,SYM,SEPARATE,SOURCE)
You need to have the Dynamic Debug facility installed and you might need the Authorized Debug facility installed.
If you want to compile your program with the OPT(STD) or OPT(FULL) compiler option, you must also specify the
EJPD suboption of
Software Group
Hooks : how they work and why you need them
Hooks enable you to set breakpoints.

Hooks are instructions that can be inserted into a program by a compiler at
compile time. Hooks can be placed at the entrances and exits of blocks, at
statement boundaries, and at points in the program where program flow
might change between statement boundaries (called path points).
If you compile a program with the TEST compiler option and specify any
suboption except NONE or NOHOOK, the compiler inserts hooks into your
program.

Software Group
Symbol tables
The symbol table contains descriptions of variables, their attributes,

and their location in storage. Debug Tool uses these descriptions
when it references variables.
The symbol tables can be stored in the object file of the program or
in a separate debug file. You can save symbol tables in a separate
debug file if you compile or assemble your programs with one of the
following compilers or assembler:
– Enterprise COBOL for z/OS, Version 4.1

– Enterprise COBOL for z/OS and OS/390, Version 3
– COBOL for OS/390 & VM, Version 2 Release 2
– COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
– OS/VS COBOL Version 1, Release 2.4
– Enterprise PL/I for z/OS, Version 3 Release 5 or later
– High Level Assembler for MVS & VM & VSE, Release 4 or later
Software Group
Build:
Invoke:
Execute:
interface
10

Software Group
Milestone
Program ready for debugging.
Next step : how do you want to debug ?
11
Software Group
Choosing a debugging mode

3 modes
1. 3270 terminal
– MFI or TIM
2. Eclipse terminal
– RDz or RDDz
3. Batch interface
– command file
AT TERMINATION;
SET FREQUENCY ON;
GO:
LIST FREQUENCY *;
QUIT;
12

Software Group
Interface type by subsystem
Subsystem Batch mode Full-screen mode Remote mode
TSO x x x
JES batch x x* x
UNIX System Services x* x
CICS x x x
DB2 x x x
DB2 stored procedures x* x
IMS (TM and DB) with BTS TSO foreground x x
IMS (TM and DB) with BTS batch x x* x
IMS without BTS IMS DB batch x x* x
IMS without BTS IMS TM x* x
* Support is for full-screen mode through a VTAM terminal only
13
Software Group
Debugging IMS applications
• Run the application as it normally runs in IMS, or run in batch using Batch
Terminal Simulator (BTS).
Debug Tool
• Dual Terminal mode:

Run the application in IMS
an online IMS region. Debug Tool
Application
Debug Tool connects CI CS
Transaction
XX XX XX X XX XX X XX XX X XX X XX XX X XX X X XX X XX XX
to a terminal or workstation
-- -- -- - -- -- - -- -- - -- - -- -- - -- - - -- - -- --
11 2 2 22 2 3 33
1 11 2 22 2 22 22 2 22 2 3 33 33
11 22 22 2 22 2 3 3 33 33
that you specify. IMS/TM region
z/OS
IMS
• BTS mode:
Run the application in
an IMS Batch Terminal
Simulator (BTS) region. IMS
Debug Tool connects Debug Tool
Application
to a VTAM terminal or
RDz Language Environment
workstation that you specify. or
VTAM terminal IMS BTS region
WK z/OS
14

Software Group
Milestone
Debugging interface selected.
How do you tell Language Environment that this

program is ready for debug ?
16
Software Group
Debug Tool Invocation Process
Load
SYSDEBUG or Module
Compiler listing TEST
Runtime Parameter
Debug Tool Application
Language Environment
Preferences file Log file
Commands file
17

Software Group
Starting Debug Tool - TEST runtime option

To specify how Debug Tool gains control of your application and begins a
debug session, you use the TEST run-time option. The simplest form of
the TEST option is TEST with no suboptions specified; however,
suboptions provide you with more flexibility. There are four types of
suboptions available, summarized below.
test_level
Determines what high-level language conditions raised by your program cause
Debug Tool to gain control of your program
commands
Determines which primary commands file is used as the initial source of commands
prompt_level
Determines whether an initial commands list is unconditionally run during program
initialization
preferences
Specifies the session parameter and a file that you can use to specify default settings
for your debugging environment,
18
Software Group
Debug Tool V9 : options in CEEOPTS

//CEEOPTS DD * DLM '/*'
TEST(ALL,CMDS,PROMPT,VTAM%USERID:PREFS)
/*
//* using DT terminal Interface Manager
//* TEST(ALL,*,PROMPT,VTAM%USERID:*)
//* using dual VTAM
//* TEST(ALL,*,PROMPT,MFI%EQBMV002:*)
//* using Eclipse interface (RDz)
//* TEST(ALL,*,PROMPT,TCPIP&9.123.45.67%8003:*)
//* if Debug Tool not in LINKLIST
//STEPLIB DD DISP=SHR,DSN=DEBUG.V9R1.SEQAMOD
//* where DT will look for listings
//EQADEBUG DD DISP=SHR, DSN=MY.SYSDEBUG.FILE
// DD DISP=SHR, DSN=MY.EQALANGX.FILE
//* log for debug session
//INSPLOG DD SYSOUT=*
//* commands file to run at the beginning of session
//CMDS DD DISP=SHR,DSN=MY.COMMANDS.FILE
//* 3270 interface preferences to set before session
//PREFS DD DISP=SHR,DSN=MY.PREFER.FILE
19

Software Group
Language Environment RunTime Options

LE runtime options for IMS programs are set at the system,
dependent region, or application program level
LE run-time options sometimes need to be changed
– To collect problem identification information
• Produce a dump, collect trace data, invoke a debug tool
– To change the storage options for a transaction Systemwide
Options
– ... CEEDOPT
Adding or changing LE run-time options prior to

IMS V8 requires one or more of the following Overridden by
– Recompile and relink the LE modules Dependent

Region
used to supply run-time options (CEEDOPT) CEEROPT Options
– Stop and restart the dependent region

with new/changed run-time options (CEEROPT) Overridden by
– Recompile and relink the application

containing run-time options (CEEUPOT) CEEUOPT
Application
Linked
Options
20
Software Group
Dynamic LE Run-Time Options

Ability to dynamically update LE run-time options
– Eliminates the need to
• Stop/start dependent regions
• Recompile and relink application programs or LE modules
– Implementation thru the “IMS Common Service Layer (CSL)”
architecture
• Including Operation Manager to route the new LE commands to IMS
• Including the TSO Single Point Of Control (SPOC) to enter commands
User-entered LE run-time options override ...
– CEEDOPT, CEEROPT, and CEEUOPT options that are not specified
as non-overridable (NONOVR)
Filters can be applied based on ...
– Program (PSB) name, transaction code, lterm name, or userid
21

Software Group
Milestone


– Oldest method ? Pass parameters in special module
linked with application or region.
24
Software Group
Starting DT under IMS : CEEUOPT or CEEROPT
You can specify your TEST runtime options by using
o d
th
CEEUOPT (which is an assembler module that uses the CEEXOPT macro to set
application level defaults, and is link-edited into an application program) or
e
CEEROPT (which is an assembler module that uses the CEEXOPT macro to set
region level defaults).
m
Every time your application program runs, Debug Tool is started.
t
e s
ld
25
O

Software Group
1
CEEUOPT
To request that Language Environment start Debug Tool every time the
application is run, assemble a CEEUOPT module with an appropriate
TEST run-time option.
o d
th
It is a good idea to link-edit the CEEUOPT module into a library and just
add an INCLUDE LibraryDDname(CEEUOPT-MemberName) statement to
e
the link-edit options when you link your application. Once the application
program has been placed in the load library (and NEWCOPY'd if required),
t m
whenever it is run Debug Tool will be started.
Debug Tool runs in the mode defined in the TEST run-time option you
es
supplied, normally Single Terminal mode, although you could provide a
primary commands file and a log file and not use a terminal at all. To start
Debug Tool, simply run the application.
ld
Don’t forget to remove the CEEUOPT containing your TEST run-time option
28
O
when you have finished debugging your program.
Software Group
CEEUOPT
d
//ASM EXEC PGM=ASMA90,PARM='OBJECT,NODECK'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=CEE.SCEEMAC
o
// DD DISP=SHR,DSN=SYS1.MACLIB
//SYSLIN DD UNIT=3390,DISP=(,PASS,DELETE),SPACE=(CYL,(1,1)),
h
// DCB=(RECFM=F,LRECL=80,BLKSIZE=80)
//SYSUT1 DD UNIT=3390,DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1))
t
//SYSUT2 DD UNIT=3390,DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=(3390,SEP=(SYSLIB,SYSUT1,SYSUT2)),
e
// DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1))
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
m
CEEUOPT RMODE ANY
CEEXOPT RPTOPTS=(ON), X
t
TEST=(ALL,'*',PROMPT,'MFI%EQBMV002:*')
END
/*
s
//*
//LKED EXEC PGM=IEWL,COND=(0,LT,ASM),
e
// PARM='RENT,REFR,NCAL,LET,LIST,XREF,SIZE(880K,64K)'
//SYSLIN DD DISP=(OLD,DELETE,DELETE),
d
// DSN=*.ASM.SYSLIN,VOL=REF=*.ASM.SYSLIN
l
// DD DDNAME=SYSIN
//SYSLMOD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD
//SYSUT1 DD UNIT=(3390,SEP=(SYSLMOD,SYSLIN)),
O
// DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1))
//SYSIN DD *
NAME CEEUOPT(R)
/*
//*
29

Software Group
CEEUOPT
//DELDS
//SYSIN
EXEC PGM=IDCAMS
//SYSPRINT DD
DD
SYSOUT=*
DATA
DELETE DELAHAY.ADTOOLS.LOAD.DEBUG(COBIVP) PURGE
o d
h
SET MAXCC=0
t
/*
//*
//LINKAPP EXEC PGM=IEWL,PARM='LIST,LET,MAP,CALL,XREF'
e
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
//SYSLOAD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD
m
//SYSLMOD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD.DEBUG
//SYSLIN DD *
t
INCLUDE SYSLOAD(COBIVP)
INCLUDE SYSLOAD(CEEUOPT)
es
ENTRY COBIVP
NAME COBIVP(R)
/*
ld
30
O
Software Group
Milestone


– Oldest method ? Always valid
– New method ? Pass parameters through exit
31

Software Group
Preparing an IMS program
Specify TEST run time options:

Specifying the TEST runtime options in a data set, which is then extracted by a
customized version of the Language Environment user exit routine CEEBXITA.
Specifying the TEST runtime options in a CEEUOPT (application level, which you
link-edit to your application program) or CEEROPT module, (region level).
Specifying the TEST runtime options through the EQASET transaction for non-
Language Environment assembler programs running in IMS TM.
Managing runtime options for IMSplex users by using Debug Tool Utilities.
32
Software Group
2-3
The DFSBXITA user exit
You can use the DFSBXITA user exit supplied by IMS.

This exit contains a copy of the Language Environment
CEEBXITA user exit that is customized for IMS.
The DFSBXITA user exit either replaces the exit supplied by
Language Environment in CEEBINIT, or is placed in your load
module.
33

Software Group
Creating setup file for your IMS program : DTU 4
For use with the DFSBXITA exit
You can create setup files for your IMS Batch Messaging Process (BMP) program
which describe how to create a custom region and defines the STEPLIB
concatenation statements that reference the data sets for your IMS program’s load
module and the Debug Tool load module.
You can also create and customize a setup file to create a private message region
that you can use to test your IMS message processing program (MPP). Creating a
private message region with class X allows you to test your IMS program run by
transaction X and reduce the risk of interfering with other regions being used by
other IMS programs.
35
EQAàPRIM Software
-------------------
Group Debug Tool Utilities ----------------------------
More: +
0 Job Card
Create Job Card image.
1 Program Preparation
Convert, compile, assemble or link edit program.
2 Debug Tool Setup File

Manage setup files and start debug session in TSO foreground or batch.
3 Code Coverage
Measure code coverage in programs.
4 IMS TM Setup
Update Language Environment run-time options in IMS. Create message region.
5 Load Module Analyzer

Analyze load modules and each CSECT in the load module.
6 Debug Tool User Exit Data Set

Modify the data set used by user exit during program initialization.
7 Other IBM Problem Determination Tools

Invoke IBM File Manager for z/OS.
8 JCL for Batch Debugging

Modify JCL to start a debugging session for batch programs.
Option ===>
F1=Help
36
F2=Split F3=Exit F7=Backward F8=Forward F9=Swap N
F12=Cancel

Software Group
Runtime options for IMSplex users by using DTU 4.1

This topic describes how to add, delete, or modify TEST runtime options that are stored in the
IMS Language Environment runtime parameter repository.
To manage the items in this repository, do the following steps:
e
1. From the main Debug Tool Utilities panel (EQA@PRIM), type 4 in the Option line and
press Enter.
u
2. In the Manage IMS Programs panel (EQAPRIS), type 1 in the Option line and press Enter.
3. In the Manage LE Runtime Options in IMS panel (EQAPRI), type in the IMSplex ID and
iq
optional qualifiers. Debug Tool Utilities uses this information to search through the IMS
Language Environment runtime parameter repository and find the entries that most closely
n
match the information you typed in. You can use wild cards (* and %) to increase the
chances of a match. After you type in your search criteria, press Enter.
4.
c h
In the Edit LE Runtime Options Entries in IMS panel (EQAPRIM), a table displays all the
entries found in the IMS Language Environment runtime parameter repository that most
closely match your search criteria. You can do the following tasks in this panel:
e
Delete an entry.
Add a new entry.
5.

T
Edit an existing entry.
Copy an existing entry.
For more information about a command or field, press PF1 to display a help panel.
After you finish making your changes, press PF3 to save your changes and close the panel
that is displayed. If necessary, press the PF3 repeatedly to close other panels until you
reach the Manage IMS Programs panel (EQAPRIS).
37
EQAPRIS ---------------------
Software Group Manage IMS Programs ----------------------------
2
1 Manage LE Runtime Options
2 Create Private Message Regions
Option ===>
F1=Help
39
F12=Cancel

EQAPRI ---------------
Software Group Manage LE Runtime Options in IMS ----------------------
Press Enter to display matched entries.

Press Cancel or Exit command to exit.
IMSPlex ID . . . . . IMSA Required; No CSL prefix
IMSPlex Member. . . .
Query qualifiers:
Trancode. . . . . .
Program . . . . . .
Lterm . . . . . . .
Userid. . . . . . .
Command ===>
F1=Help
40
F12=Cancel
EQAPRIM -----------
Software Group Edit LE Runtime Options Entries in IMS --- Row 1 to 2 of 2
IMSPlex ID: IMSA IMSPlex Mbr:
Query qualifiers:
Trancode: Program: Lterm: Userid:
Use line command

E to edit an entry C to copy an entry D to delete an entry
Mbr Trancode Program Lterm Userid LE runtime options

IMA2 I4TCB TEST(ALL,*,PROMPT,TCPIP&9.212.3.161
******************************* Bottom of data ********************************
Command ===> Scroll ===> PAGE

F1=Help
41
F3=Exit F4=New F7=Backward F8=Forward F10=Refresh
F11=RefreshA F12=Cancel

EQAPRIDN Software
--------------
Group Create LE Runtime Options Entry ----------------------
More: +
Provide subsystem information:
IMSPlex ID : IMSA
IMSPlex Mbr:
Qualifiers:
Trancode: I1TCB Program: Lterm: Userid:
Select Test Options:
Test Option. . . TEST Test/Notest

Test Level . . . ALL All/Error/None
Commands File *, DD name, data set name
. . . . . . . . *
Prompt Level ==> PROMPT Prompt/NoPrompt/"cmd"
Preference File *, DD name, data set name
. . . . . . . . *
Select (/) a session type and provide parameters:
/ Full-screen mode
Network . . Blank or VTAM Network name
Terminal LU. . EQBMV002 VTAM Terminal LU
Full-screen mode using the Debug Tool Terminal Interface Manager

User ID. . . . User ID
Command ===>
F1=Help
42
F12=Cancel
EQAPRIM -----------
Software Group Edit LE Runtime Options Entries in IMS --- Row 1 to 4 of 4
IMSPlex ID: IMSA IMSPlex Mbr:
Query qualifiers:
Trancode: Program: Lterm: Userid:
Use line command

E to edit an entry C to copy an entry D to delete an entry
Mbr Trancode Program Lterm Userid LE runtime options

IMA2 I1TCB TEST(ALL,*,PROMPT,MFI%EQBMV002:*)
IMA1 I1TCB TEST(ALL,*,PROMPT,MFI%EQBMV002:*)
******************************* Bottom of data ********************************
Command ===> Scroll ===> PAGE

F1=Help
43
F3=Exit F4=New F7=Backward F8=Forward F10=Refresh
F11=RefreshA F12=Cancel

EQAPRIS ---------------------
Software Group Manage IMS Programs ----------------------------
3
1 Manage LE Runtime Options
2 Create Private Message Regions
Option ===>
F1=Help
46
F12=Cancel
EQAPFORA Software
--------- Manage Message Regions - Edit Setup File ------------------
Group
Setup File Library:

Project . . . DELAHAY
Group . . . . DEBUG . . . . . . . . .
Type . . . . CNTL
Member . . . DTIMS01 (Blank or pattern for member selection list)
(or existing or new member name)
Other Data Set Name:

Data Set Name . . .
Volume Serial . . . (If not cataloged)
Command ===>
F1=Help
47
F12=Cancel

EQAPFORI Software
it Setup File 'DELAHAY.DEBUG.CNTL(DTIMS01)'
Group Row 1 to 20 of 20
Batch Job Name. . . JMETCH26

Load Module Name. . DFSRRC00
Job type. . . . . . MSG (MSG,BMP)
/ Enter / to modify parameters
Cmd DD Name Seq C DD Information (DSN/Sysin/Sysout/Dummy) DISP

***************** Top of Data ********************
DFSRESLB 1 'IMS710.RESLIB' SHR
DFSVSAMP 1 'SYS2.PROCLIB(£DLIDP)' SHR
IEFRDER 1 DUMMY
IMS 1 'PPIMS.DBD.LOAD' SHR
2 'PPIMS.PSB.LOAD' SHR
KCDDATA 1 'DP000.CIDG.KCD01P00' SHR
KCDINDX 1 'DP000.CIDG.KCD01X00' SHR
STEPLIB 1 'DPIMS.USERLIB' SHR
2 'IMS710.RESLIB' SHR
3 'CEE.SCEERUN' SHR
4 'DPSYN.EST.BTLOAD' SHR
5 'PPSYN.GEN.BTLOAD' SHR
6 'DPGEN.PO.SPLOAD' SHR
SYSABOUT 1 SYSOUT=*
SYSDBOUT 1 SYSOUT=*
SYSOUT 1 SYSOUT=*
SYSPRINT 1 SYSOUT=*
2 SYSOUT=*
SYSUDUMP 1 SYSOUT=D
Command ===> Submit - Create and submit JCL for batch execution Scroll ===> CSR
F1=Help
48
F3=Exit F7=Backward F8=Forward F10=Submit F11=ShowDD
F12=Cancel
EQAPRIP1 Software
--------- Parameters for Message Processing Region ------------------
Group
Key parameters for message processing region.
IMSID . . . N specify a 1-4 character IMS subsystem ID
CLASSES . . 000 000 000 000 specify 4 3-digit decimal numbers indicating
classes of messages to be served
APPLFE. . . specify a 1-8 character name of an appli-

cation front-end routine that is called
whenever a message processing program is
scheduled. (Front-end routine is required
to debug non-LE Assembler program)
STIMER. . . specify a process time statistics code (0,1,

2). 0 means no statistics are gathered.
Other parameters for message processing region.

More: +
AGN . . . . N ALTID . . .
APARM . . .
DBLDL . . . LOCKMAX . .
NBA . . . . OBA . . . . Y
OPT . . . . 0 OVLA. . . . 0
PCB . . . . 000 PREINIT . . N
PRLD. . . . 0 PWFI. . . .
SOD . . . . SPIE. . . . 0
SSM . . . . TLIM. . . . 00
Command ===>
F1=Help
49
F12=Cancel

Software Group
Milestone

– Old method ? Pass parameters through IMS exit
– New method ? Pass parameters through DT exit
50
Software Group
Specifying the TEST runtime options through the 4

Language Environment exit routine
Language Environment exit routines for various environments
Environment Exit routine name

IMS TM and BTS² EQADICXT
Batch and BTS EQADBCXT
Note:
² For BTS, you need to specify Environment command (./E) with the user ID of the IO PCB.
For example, if the user ID is ECSVT2, then the Environment command is .
/E USERID=ECSVT2.
To prepare a program by using the Language Environment exit routine, do the following tasks:
1. “Editing the source code of CEEBXITA (optional)”
2. “Linking in the CEEBXITA user exit routine”
51

Software Group
Specifying the TEST runtime options through the

Language Environment exit routine
Debug Tool provides a customized version of the Language Environment user exit routine (CEEBXITA)
to link into the application load module. The routine returns a TEST runtime option when called by the
Language Environment initialization logic. The routine extracts the TEST runtime option from a data
set with a name that is constructed from a naming pattern. The naming pattern can include the
following tokens:
&USERID Debug Tool replaces the &USERID token with the user ID of the current user. Each user can
specify an individual TEST runtime option when debugging an application. This token is mandatory.
&PGMNAME Debug Tool replaces the &PGMNAME token with the name of the main program (load
module). Each program can have its own TEST runtime options. This token is optional.
Debug Tool provides the user exit routine in two forms:
A load module that the user includes in the link-edit step of his or her application build job. The load
modules for the three environments are in the hlq.SEQAMOD data set. Use this load module if you
want the default naming patterns and message display level. The default naming pattern is
&USERID.DBGTOOL.EQAUOPTS and the default message display level is X'00'.
Sample assembler routine that you can edit. The assembler routines for the three environments are
in the hlq.SEQASAMP data set. You can also merge this source with an existing version of
CEEBXITA. Use this source code if you want naming patterns or message display levels that are
different than the default values.
Three different exit routines are provided. The load module form of these routines are in the
hlq.SEQAMOD data set. The sample assembler routines are in the hlq.SEQASAMP data set.
64
Software Group
Starting Debug Tool for IMS/TM programs
Debug Tool is started when you pass a TEST parm to LE when your IMS/TM
program runs
Use Debug Tool panel 6 and a supplied exit program so that a TEST parm will be
passed automatically when you run the transaction that runs the program
65

Software Group
Enabling Debug Tool panel 6

How it works:
Panel 6 saves your Debug Tool specs in a TEST option data set
By default: userid.DBGTOOL.EQAUOPTS
Debug Tool provides special LE exits. If an exit is enabled when the

program runs:
– It uses the IMS User ID to determine the name of the test option data
set
– The exit program reads your test option data set
– If the program name matches, the exit passes a ‘TEST’parm to
Language Environment (LE) to start Debug Tool
67
Software Group
Option 1: exit linked into application load module
1. Include a special LE user

exit for DT in the
application load module
2. Use DT panel 6 to identify
programs and a terminal or
remote GUI interface
3. Run the IMS transaction
4. LE runs the exit
automatically
5. If the program name is in
the TEST option file, the
exit passes a TEST parm
to LE
6. LE starts Debug Tool
69

Software Group
Option 2: STEPLIB to the exit

1. To install it, the Sys.
Programmer prepares a
special library with the exit
and adds it to the STEPLIB
of the IMS MPR
2. Use DT panel 6 to identify
programs and a terminal or
remote GUI
3. Run the IMS transaction
4. LE runs the exit
automatically
5. If the program name is in
the TEST option file, the exit
passes a TEST parm to LE
6. LE starts Debug Tool
70
Software Group
Comparing the two ways to enable panel 6

In option 1, a special Debug Tool module is link-edited into the
application load module
– Advantage:
• No IMS setup needed by the Systems Programmer
– Disadvantages:
• Requires a change to the compile process, or re-link of the application load
module
• You may prefer to remove the exit from the load module before using it in
production
In option 2, the exit is made available by the Systems Programmer
adding a special library to STEPLIB in the IMS MPRs
– Advantages:
• Works automatically for Debug Tool users
• No change to the compilation process
71

Software Group
Enabling Debug Tool panel 6

A deep-dive into the details
Debug Tool provides 3 exit programs that work with panel 6:
– EQADBCXT: for all batch LE applications (including IMS and DB2 batch)
e
– EQADICXT: for online IMS (IMS/TM) LE applications only
– EQADDCXT: for LE DB2 stored procedures only
–
–
These modules reside in Debug Tool library SEQAMOD
q u
Source for the exits (in library SEQASAMP) can be customized to:
i
• Change the naming convention for the TEST option data set
n
• Change to “quiet” mode to reduce system log messages
To enable them:
module, or
c h
– Option 1: Link-edit the appropriate version of the exit into each application load
T e
– Option 2: The Systems Programmer can create 3 new load libraries, which can
be added to STEPLIB or JOBLIB to enable the exits
• A loadlib for batch applications containing a copy of LE module CEEBINIT linked with
exit module EQADBCXT
• A loadlib for IMS/TM applications containing a copy of LE module CEEBINIT linked
with exit module EQADICXT
• A loadlib for DB2 stored procedures containing a copy of LE module CEEPIPI linked
with exit module EQADDCXT
72
Software Group
Link exit for BTS
. . .
//SYSLMOD DD DISP=SHR,DSN=DELAHAY.BTS.LOAD
//*YSLMOD DD DSN=&EXEHQ..PGMLIB,DISP=SHR
//* for debug : B=batch, I=Interactive
//CEEBXITA DD DISP=SHR,DSN=DEBUG.V9R1.SEQAMOD(EQADBCXT)
//*EEBXITA DD DISP=SHR,DSN=DEBUG.V9R1.SEQAMOD(EQADICXT)
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,1))
//SYSLIN DD DSN=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
// PEND
//********************************************************************
//*
//* COMPILE AND LINK-EDIT THE CONVERSATIONAL MPP APPLICATION PROGRAM
//*
//DFSIVA34 EXEC PROC=COMLK,SRC=DFSIVA34,MBR=DFSIVP34,
// SYSHQ=IMS.V10R1
//L.SYSIN DD *
INCLUDE RESLIB(DFSLI000)
INCLUDE CEEBXITA
NAME DFSIVP34(R)
//*
73

Software Group
Starting Debug Tool for an IMS/TM program

Steps
– 1. Prepare a debugging display device. It can be:
• A 3270 terminal using the Debug Tool Terminal Interface Manager (TIM), or
• A Debug Tool 3270 terminal, or
• Remote GUI debugging software such as RDz or RDDz
– 2. In TSO, on Debug Tool panel 6 (the TEST parm data set panel):
• Specify the name of the main programs to trap
• Identify the debugging display device
– 3. Log on to the IMS region (if you are not already logged on)
– 4. Run the transaction that will run the main program
Things you need to know that are unique to your system:

– How to open a 3270 terminal session or remote GUI debugger for
Debug Tool on your system
– How to navigate to Debug Tool in ISPF
– How to navigate to and log on to your IMS/TM system
74
EQAàPRIM Software
-------------------
Group Debug Tool Utilities ----------------------------
More: +
0 Job Card
Create Job Card image.
4
1 Program Preparation
Convert, compile, assemble or link edit program.
2 Debug Tool Setup File

Manage setup files and start debug session in TSO foreground or batch.
3 Code Coverage
Measure code coverage in programs.
4 IMS TM Setup
Update Language Environment run-time options in IMS. Create message region.
5 Load Module Analyzer

Analyze load modules and each CSECT in the load module.
6 Debug Tool User Exit Data Set

Modify the data set used by user exit during program initialization.
7 Other IBM Problem Determination Tools

Invoke IBM File Manager for z/OS.
8 JCL for Batch Debugging

Modify JCL to start a debugging session for batch programs.
Option ===>
F1=Help
75
F12=Cancel

EQAPTOP ------
Software Debug
Group Tool - Manage TEST Run-time Option Data Set -------------
Specify the name of a TEST run-time option data set that you want to
create or edit.
Press Enter to edit the data set.

Press Exit or Cancel to exit.
The data set provides a TEST run-time option for debugging application
that uses Debug Tool Language Environment user exit.
Use Help and the Debug Tool User Guide section: Preparing a program
using Debug Tool Language Environment user exit, for more information.
Data Set Name:

Data Set Name . . . 'DELAHAY.DBGTOOL.EQAUOPTS'
Volume Serial . . . (If not cataloged)
Command ===>
F1=Help
76
F12=Cancel
EQAPTPRM Software
------ Group
Debug Tool - Edit TEST Run-time Option Data Set --------------
More: +
Enter test program names: (* is a valid wild card, by itself or as the last
character of a name)
Name 1: DFSIVP34 Name 2: Name 3: Name 4:

Name 5: Name 6: Name 7: Name 8:
Select Test Options:
Test Option ==> TEST Test/Notest

Test Level ==> ALL All/Error/None
Commands File *, DDname, or Data Set Name
==> *
Prompt Level Prompt, NoPrompt, ;, *, command
==> PROMPT
Preference File *, DDname, or Data Set Name
==> *
Select (/) a session type and provide parameters:
/ Full-screen mode
Network ==> Blank or VTAM Network name
Terminal LU ==> EQBMV007 VTAM Terminal LU
Full-screen mode using the Debug Tool Terminal Interface Manager

User ID ==> User ID
Command ===>
F1=Help
77
F12=Cancel

Software Group
TEST runtime option dataset
78
Software Group
Milestone

– Old method ? Pass parameters through IMS exit
– New method ? Pass parameters through DT exit
Specifics for batch programs
79

Software Group
Debugging IMS batch programs in batch mode
You can use Debug Tool to debug IMS programs in batch mode.
The debug commands must be predefined and included in one of the
Debug Tool commands files, or in a command string. The command string
can be specified as a parameter either in the TEST run-time option, or
when CALL CEETEST or __ctest is used.
Although batch mode consumes fewer resources, you must know
beforehand exactly which debug commands you are going to issue.
When you run BTS as a batch job, the batch mode of Debug Tool is the
only mode available for use.
80
Software Group
Debugging IMS batch programs interactively by

running BTS in TSO foreground
If you want to debug an IMS batch program interactively, you can run BTS in the
TSO foreground, by doing the following steps:
1. Define a dummy transaction code on the ./T command to initiate your program
2. Include a dummy transaction in the BTS input stream
3. Start BTS in the TSO foreground.
FSS is the default option when BTS is started in the TSO foreground, and is
available only when you are running BTS in the TSO foreground. FSS can only
be turned off by specifying TSO=NO on the ./O command. When running in the
TSO foreground, all call traces are displayed on your TSO terminal by default.
This can be turned off by parameters on either the ./O or ./T commands.
Note: If your source (C and C++) or listing (COBOL and PL/I) does not come up in
Debug Tool when you launch it, check that the source or listing file name
corresponds to the MVS library name, and that you have at least read access
to that MVS library.
81

Software Group

Debug Tool can only be used to debug one iteration of a transaction at a time.
When the program terminates you must close down Debug Tool before you can
view the output of the transaction. Therefore, if you use an input data set, you can
only specify data for one transaction in that data set. The data for the next
transaction must be entered from your TSO terminal.
A new debug session will be started automatically for the next transaction. When
using FSS, you must enter the /* command on your TSO terminal to terminate the
BTS session.
82
Software Group

Unsupported BYPASS :
You can also use an alternate copy of the BTS startup CLIST with reference to
alternate libraries where you store debug-ready copies of your load modules.
83

Software Group
---------------------------- BTS execution options ----------------------------

BTS
Optionexecution
===> options
Select the function(s) you need:
Allocate datasets before execution? ===> Y (Y or N) At least once per session
Execute BTS? ===> Y (Y or N)
Free datasets after execution? ===> N (Y or N)
Browse BTSLIST after execution? ===> Y (Y or N)
You will find that BTS initialises faster if you don't continually allocate.
BTS region type ===> DLI (BMP,DBB or DLI) IMS system ===> IMA1
Use DBRC? ===> N (Y or N)
Start DB Monitor? ===> N (Y or N - not used for BMP)
BTSIN file(s) ===> IMSBTS.V3R1.BTSIN(IMSIVP)

===>
===>
VSAM buffers ===> IMSBTS.V3R1.BTSIN(DFSVSAMP)
To access DB2, enter the subsystem id and the name of SDSNLOAD

DB2 Subsystem ===> (leave blank to omit DB2)
DB2 SDSNLOAD ===>
F1=HELP F2=SPLIT F3=END F4=RETURN F5=RFND F6=RCHANGE

F7=UP F8=DOWN F9=Swap N F10=LEFT F11=RIGHT F12=RETRIEVE
85
Software Group
BTS input parameters

BTS display some information and wait for your input.
BTS0007I BTS V3R1 SIMULATION STARTED. TIME=14:24:43, DATE=2009.034, IMS=10.1.

./T TC=IVTNO MBR=DFSIVP1 LANG=ASM TYPE=MSG PLC=99
./T TC=IVTNV MBR=DFSIVP2 LANG=ASM TYPE=MSG PLC=99
./T TC=IVTCV MBR=DFSIVP3 LANG=ASM TYPE=MSG PLC=99 SPA=80
./T TC=IVTCB MBR=DFSIVP34 LANG=CBL TYPE=MSG PLC=99 SPA=80
./T TC=IVTPV MBR=IVTPV LANG=PLI TYPE=MSG PLC=99 SPA=80
./T TC=IVTFD MBR=DFSIVP4 LANG=ASM TYPE=IFP PLC=99
./D LTERM=IOPCB TYPE=3270-A02 SIZE=(24,80) EOS=° EOM=$
./E USERID=IBMUSER FSSEND=YES
./*
./* ENTER /FOR IVTNO AND PRESS "ENTER " TO START
./*
ENTER BTS COMMAND OR /FORMAT OR /*
At the prompt, type «/FOR IVTCB» and press Enter.
If you selected the Interactive exit, you must make sure of the userid before starting the transaction.
Type «./E USERID=userid» and press Enter.
86

Software Group
Alternative to DTU
You can have your customized panels for use with

customized LE exit
Already used in many locations
87
ADTDEBUG Software Group Debug Utility: Wilfried's LE Exits

OPTION ===>
5
1 For Batch, DB2 Stored Procedure and CICS
2 For Batch, DB2 Stored Procedure and IMS / TM
Press PF3 to return.
F1=HELP
88
F2=SPLIT F3=END F4=RETURN F5=RFND F6=RCHANGE

DBGPRIM --------- Debug tool parameter file initialisation

Software Group -----------------
Parameter file:
UserID. . . DELAHAY _ File Name . DELAHAY.DBGTOOL.TESTPARM
Debug Options:
Test. . . . Y Y or N Debug this programs
PGM Names . DFSIVP34
Jobname . . ________ Batch Jobname Customizable
Stepname. . ________ Batch Stepname parameter file name
IMS TRX . . IVTCB IMS Transaction
Runtime . . ________________________________________________________________
Debug display device:
Address . . MFI%EQBMV007
Debug files:
_ Command file. . . __________________________________________
_ Preference file . __________________________________________
_ Log file. . . . . __________________________________________
_ Submit Job. . . . __________________________________________
Press ENTER to change parameter file PF1 HELP PF3 END
COMMAND ===>
F1=HELP
89
F2=SPLIT F3=END F4=RETURN F5=RFND F6=RCHANGE
Software Group
The three recommended methods for invoking

Debug Tool for IMS DC (online) applications
IMS Supplied Exit DFSBXITA Uses IMS online LE RunOpts

(Cannot be used with IMS batch)
DT Supplied Exit EQADICXT Uses DT TEST Run-time Option Data Set

(Could also be used with IMS batch)
WVH Supplied Exit EQADICXT Uses WVH TEST Run-time Option Special Data Set
The method by which this Exit has been deployed
WVH=Wilfried Van Hecke means there is no need to link the Exit
to the application module !
(Could also be used with IMS batch)
Note: There should be no reason any more to use the static CEEUOPT module linked to
the IMS application program module
90

Software Group
Build:
Invoke:
Execute:
interface
91
Software Group
Customizable 3270 Interface
92

Software Group
Memory display
93
Software Group
Rational Developer for System z
Monitoring and changing the value of variables

Breakpoints managing.
94

Software Group
Variables
VARBL1=10
95
Software Group
Conclusion
Debug Tool is the tool of choice to debug

mainframe applications
Integration with RDz
Customization
Debug Tool for z/OS (5655-U27)

http://www.ibm.com/software/awdtools/debugtool/
96

Software Group
Education Assistant
http://publib.boulder.ibm.com/infocenter/ieduasst/stgv1r0/index.jsp
97
Software Group
Redbooks www.redbooks.com
98

B3 Debuging IMS 200902

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

B3 Debuging IMS 200902

Uploaded by

Copyright:

Available Formats

Debugging Applications IMS

Sylvie Delahaye Sylvie.Delahaye@fr.ibm.com

© 2009 IBM Corporation

Debug Tool Overview

3270 GUI – CICS, TSO, JES/Batch, IMS Including

RePenser IMS - Février 2009 - Paris 1

Debug Tool Highlights

Process for All z/OS Debuggers (IBM and vendor):

RePenser IMS - Février 2009 - Paris 2

Debug Tool Build Process:

TEST compiler option

Compiler Link Edit

IBM Debug Tool Build Process

Debug Tool module support is integrated into all IBM compilers

RePenser IMS - Février 2009 - Paris 3

Choosing compiler options for debugging

Hooks : how they work and why you need them

Hooks enable you to set breakpoints.

RePenser IMS - Février 2009 - Paris 4

The symbol table contains descriptions of variables, their attributes,

– Enterprise COBOL for z/OS, Version 4.1

Process for All z/OS Debuggers (IBM and vendor):

RePenser IMS - Février 2009 - Paris 5

Program ready for debugging.

Next step : how do you want to debug ?

Choosing a debugging mode

RePenser IMS - Février 2009 - Paris 6

Interface type by subsystem

Subsystem Batch mode Full-screen mode Remote mode

IMS (TM and DB) with BTS TSO foreground x x

IMS (TM and DB) with BTS batch x x* x

IMS without BTS IMS DB batch x x* x

IMS without BTS IMS TM x* x

* Support is for full-screen mode through a VTAM terminal only

Debugging IMS applications

• Dual Terminal mode:

that you specify. IMS/TM region

RePenser IMS - Février 2009 - Paris 7

Program ready for debugging.

Debugging interface selected.

How do you tell Language Environment that this

Debug Tool Invocation Process

Debug Tool Application

Preferences file Log file

RePenser IMS - Février 2009 - Paris 8

Starting Debug Tool - TEST runtime option

Debug Tool V9 : options in CEEOPTS

RePenser IMS - Février 2009 - Paris 9

Language Environment RunTime Options

Adding or changing LE run-time options prior to

– Recompile and relink the LE modules Dependent

– Stop and restart the dependent region

– Recompile and relink the application

Dynamic LE Run-Time Options

RePenser IMS - Février 2009 - Paris 10

Program ready for debugging.

How do you tell Language Environment that this

Starting DT under IMS : CEEUOPT or CEEROPT

You can specify your TEST runtime options by using

RePenser IMS - Février 2009 - Paris 11

RePenser IMS - Février 2009 - Paris 12

Program ready for debugging.