B3_Debuging_IMS_200902

Debugging Applications IMS

RePenser IMS - Février 2009 - Paris 1

Software Group

© 2009 IBM Corporation

Debugging IMSwith Debug Tool

Sylvie Delahaye [email protected]

Software Group

2

Debug Tool OverviewProvides debugging of enterprise applications

3270

Debug Tool

BATCH CICSIMS DB2TSO USSWeb

Sphere

Application LanguagesCOBOL, PL/I, ASSEMBLER, C/C++

GUI

� Features:

– Playback support

– Automonitor support for COBOL and PL/I programs

– An interface to the Fault Analyzer tool– A code coverage tool

– Support for identifying and converting OS/VS COBOL source programs to ANSI 85 standard COBOL

– Preparation and compile facilities for programs

– Commands to query, allocate, and free files

� Consistent Across Languages

– COBOL, C, C++, PL/I, Assembler

� Environments Supported

– CICS, TSO, JES/Batch, IMS Including IMS/TM, DB2 Including Stored Procedures

– Uses the GUI debug interface built into products such as:• Rational Developer for SystemZ (RDz)

Debugapplication

insupported

environments

RDz



Software Group

3

Debug Tool Highlights� 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)

–VTAM Terminals (MFI)

–Rational Developer for System z

–batch

RDz

MFI

Software Group

4

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

5

Debug Tool Build Process:

Compiler Link Edit

LoadModule

SYSDEBUG orCompiler listing

TEST compiler option

Program source

Software Group

6

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

7

Choosing compiler options for debugging

� Compiler options affects the size of your load module and the amount ofDebug Tool functionality available to you. Debug Tool uses information such as hooks and symbol tables to gain control of a program, run theprogram statement-by-statement or line-by-line, and display information about your program.

TEST(ALL,SYM)PL/I (< Ent. V3.4)

TEST(NOHOOK,SEPARATE)Enterprise COBOL V4.1

TEST(ALL,NOHOOK,SYM,SEPARATE,SOURCE)Enterprise PL/1 V3.7

TEST(NONE,SYM,SEPARATE)COBOL

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

8

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 atcompile time. Hooks can be placed at the entrances and exits of blocks, atstatement boundaries, and at points in the program where program flowmight change between statement boundaries (called path points).

If you compile a program with the TEST compiler option and specify anysuboption except NONE or NOHOOK, the compiler inserts hooks into yourprogram.



Software Group

9

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 separatedebug file if you compile or assemble your programs with one of thefollowing 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

10


� Build:


� Invoke:


� Execute:




Software Group

11

Milestone

� Program ready for debugging.

� Next step : how do you want to debug ?

Software Group

12

Choosing a debugging mode3 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;



Software Group

13

Interface type by subsystem

xx*IMS without BTS IMS TM

xx*xIMS without BTS IMS DB batch

xx*xIMS (TM and DB) with BTS batch

xxIMS (TM and DB) with BTS TSO foreground

xx*DB2 stored procedures

xxxDB2

xxxCICS

xx*UNIX System Services

xx*xJES batch

xxxTSO

Remote modeFull-screen modeBatch modeSubsystem

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

Software Group

14

z/OS

• Run the application as it normally runs in IMS, or run in batch using Batch Terminal Simulator (BTS).

• Dual Terminal mode: Run the application inan online IMS region.Debug Tool connects to a terminal or workstation that you specify.

• BTS mode: Run the application in an IMS Batch Terminal Simulator (BTS) region. Debug Tool connects to a VTAM terminal or workstation that you specify.

Debug ToolIMS

Application

Transaction

z/OS

IMS/TM region

Debug Tool

IMS

CI CS

XX XX XX X XX XX X XX XX X XX X XX XX X XX X X XX X XX XX

-- -- -- - -- -- - -- -- - -- - -- -- - -- - - -- - -- --

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

Debug ToolIMS

Application

Language Environment

IMS BTS region

RDzor

VTAM terminal

Debugging IMS applications

WK



Software Group

16

Milestone


� Debugging interface selected.

� How do you tell Language Environment that thisprogram is ready for debug ?

Software Group

17

Debug Tool Application

Debug Tool Invocation Process

LoadModuleSYSDEBUG or

Compiler listing TESTRuntime Parameter

Preferences file

Commands file

Log file

Language Environment



Software Group

18

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 ofthe TEST option is TEST with no suboptions specified; however, suboptions provide you with more flexibility. There are four types ofsuboptions available, summarized below.

test_levelDetermines 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_levelDetermines whether an initial commands list is unconditionally run during programinitialization

preferencesSpecifies the session parameter and a file that you can use to specify default settingsfor your debugging environment,

Software Group

19

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



Software Group

20

Overridden by

Overridden by

CEEDOPT

Systemwide Options

CEEROPT

Dependent Region Options

CEEUOPTApplication Linked Options

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

– ...

� Adding or changing LE run-time options prior to IMS V8 requires one or more of the following

– Recompile and relink the LE modules used to supply run-time options (CEEDOPT)

– Stop and restart the dependent region with new/changed run-time options (CEEROPT)

– Recompile and relink the application containing run-time options (CEEUPOT)

Software Group

21

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



Software Group

24

Milestone




– Oldest method ? Pass parameters in special module linked with application or region.

Software Group

25

Starting DT under IMS : CEEUOPT or CEEROPT

You can specify your TEST runtime options by using

� 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

� CEEROPT (which is an assembler module that uses the CEEXOPT macro to set region level defaults).

Every time your application program runs, Debug Tool is started.

Oldestmethod



Software Group

28

Don’t forget to remove the CEEUOPT containing your TEST run-time option when you have finished debugging your program.

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.

It is a good idea to link-edit the CEEUOPT module into a library and just add an INCLUDE LibraryDDname(CEEUOPT-MemberName) statement to 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), whenever it is run Debug Tool will be started.

Debug Tool runs in the mode defined in the TEST run-time option you 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.

Oldestmethod

1

Software Group

29

CEEUOPT//ASM EXEC PGM=ASMA90,PARM='OBJECT,NODECK' //SYSPRINT DD SYSOUT=* //SYSLIB DD DISP=SHR,DSN=CEE.SCEEMAC // DD DISP=SHR,DSN=SYS1.MACLIB //SYSLIN DD UNIT=3390,DISP=(,PASS,DELETE),SPACE=( CYL,(1,1)), // DCB=(RECFM=F,LRECL=80,BLKSIZE=80) //SYSUT1 DD UNIT=3390,DISP=(,DELETE,DELETE),SPACE =(CYL,(1,1)) //SYSUT2 DD UNIT=3390,DISP=(,DELETE,DELETE),SPACE =(CYL,(1,1)) //SYSUT3 DD UNIT=(3390,SEP=(SYSLIB,SYSUT1,SYSUT2) ), // DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1 )) //SYSIN DD * CEEUOPT CSECT CEEUOPT AMODE ANY CEEUOPT RMODE ANY

CEEXOPT RPTOPTS=(ON), X

TEST=(ALL,'*',PROMPT,'MFI%EQBMV002:*')END

/* //* //LKED EXEC PGM=IEWL,COND=(0,LT,ASM), // PARM='RENT,REFR,NCAL,LET,LIST,XREF,SIZE( 880K,64K)' //SYSPRINT DD SYSOUT=* //SYSLIN DD DISP=(OLD,DELETE,DELETE), // DSN=*.ASM.SYSLIN,VOL=REF=*.ASM.SYSLIN // DD DDNAME=SYSIN //SYSLMOD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD //SYSUT1 DD UNIT=(3390,SEP=(SYSLMOD,SYSLIN)), // DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1 )) //SYSIN DD *

NAME CEEUOPT(R) /* //* Oldest

method



Software Group

30

CEEUOPT

//DELDS EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD DATA

DELETE DELAHAY.ADTOOLS.LOAD.DEBUG(COBIVP) PURGE SET MAXCC=0

/* //* //LINKAPP EXEC PGM=IEWL,PARM='LIST,LET,MAP,CALL,XR EF' //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR //SYSLOAD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD //SYSLMOD DD DISP=SHR,DSN=DELAHAY.ADTOOLS.LOAD.D EBUG //SYSLIN DD *

INCLUDE SYSLOAD(COBIVP)

INCLUDE SYSLOAD(CEEUOPT)ENTRY COBIVP NAME COBIVP(R)

/*

Oldestmethod

Software Group

31

Milestone




– Oldest method ? Always valid

– New method ? Pass parameters through exit



Software Group

32

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 youlink-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.

Software Group

33

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.

2-3



Software Group

35

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) programwhich describe how to create a custom region and defines the STEPLIB concatenation statements that reference the data sets for your IMS program’s loadmodule and the Debug Tool load module.

You can also create and customize a setup file to create a private message regionthat 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.

Software Group

36

EQAàPRIM ------------------- Debug Tool Utilities ------ ----------------------More: +

0 Job CardCreate Job Card image.

1 Program PreparationConvert, compile, assemble or link edit program.

2 Debug Tool Setup File Manage setup files and start debug session in TSO foreg round or batch.

3 Code CoverageMeasure code coverage in programs.

4 IMS TM SetupUpdate Language Environment run-time options in IMS. C reate message region.

5 Load Module AnalyzerAnalyze 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 ini tialization.

7 Other IBM Problem Determination ToolsInvoke IBM File Manager for z/OS.

8 JCL for Batch DebuggingModify JCL to start a debugging session for batch prog rams.

Option ===>F1=Help F2=Split F3=Exit F7=Backward F 8=Forward F9=Swap N

F12=Cancel



Software Group

37

Runtime options for IMSplex users by using DTU 4.1This 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: 1. From the main Debug Tool Utilities panel (EQA@PRIM), type 4 in the Option line and

press Enter. 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

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 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. 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:

� Delete an entry. � Add a new entry. � Edit an existing entry. � Copy an existing entry.� For more information about a command or field, press PF1 to display a help panel.

5. 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).

Technique

Software Group

39

EQAPRIS --------------------- Manage IMS Programs --- -------------------------

1 Manage LE Runtime Options

2 Create Private Message Regions


F12=Cancel

2



Software Group

40

EQAPRI --------------- Manage LE Runtime Options in I MS ----------------------

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 F2=Split F3=Exit F7=Backward F 8=Forward F9=Swap N

F12=Cancel

Software Group

41

EQAPRIM ----------- 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 IMA1 I4TCB TEST(ALL,* ,PROMPT,TCPIP&9.212.3.161

******************************* Bottom of data ****** **************************

Command ===> Scroll ===> PAGE F1=Help F3=Exit F4=New F7=Backward F8=Forward F10=Refresh

F11=RefreshA F12=Cancel



Software Group

42

EQAPRIDN -------------- Create LE Runtime Options Entr y ----------------------More: +

Provide subsystem information:

IMSPlex ID : IMSAIMSPlex Mbr:

Qualifiers: Trancode: I1TCB Program: Lterm: Userid:

Select Test Options:

Test Option. . . TEST Test/NotestTest Level . . . ALL All/Error/None Commands File *, DD name, data se t 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 nameTerminal LU. . EQBMV002 VTAM Terminal LU

Full-screen mode using the Debug Tool Terminal Interface Manager User ID. . . . User ID


F12=Cancel

Software Group

43

EQAPRIM ----------- 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:*) IMA2 I4TCB TEST(ALL,* ,PROMPT,TCPIP&9.212.3.161 IMA1 I1TCB TEST(ALL,* ,PROMPT,MFI%EQBMV002:*) IMA1 I4TCB TEST(ALL,* ,PROMPT,TCPIP&9.212.3.161

******************************* Bottom of data ****** **************************

Command ===> Scroll ===> PAGE F1=Help F3=Exit F4=New F7=Backward F 8=Forward F10=Refresh

F11=RefreshA F12=Cancel



Software Group

46

EQAPRIS --------------------- Manage IMS Programs --- -------------------------

1 Manage LE Runtime Options

2 Create Private Message Regions


F12=Cancel

3

Software Group

47

EQAPFORA --------- Manage Message Regions - Edit Setup File ------------------

Setup File Library: Project . . . DELAHAYGroup . . . . DEBUG . . . . . . . . . Type . . . . CNTLMember . . . 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)


F12=Cancel



Software Group

48

EQAPFORI it Setup File 'DELAHAY.DEBUG.CNTL(DTIMS01)' Row 1 to 20 of 20

Batch Job Name. . . JMETCH26Load Module Name. . DFSRRC00Job type. . . . . . MSG (MSG,BMP) / Enter / to modify parameters

Cmd DD Name Seq C DD Information (DSN/Sysin/Sysout/Dum my) 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' S HR KCDDATA 1 'DP000.CIDG.KCD01P00' SHR KCDINDX 1 'DP000.CIDG.KCD01X00' SHR STEPLIB 1 'DPIMS.USERLIB' SHR

2 'IMS710.RESLIB' S HR 3 'CEE.SCEERUN' S HR 4 'DPSYN.EST.BTLOAD' S HR 5 'PPSYN.GEN.BTLOAD' S HR 6 'DPGEN.PO.SPLOAD' S HR

SYSABOUT 1 SYSOUT=* SYSDBOUT 1 SYSOUT=* SYSOUT 1 SYSOUT=* SYSPRINT 1 SYSOUT=*

2 SYSOUT=* SYSUDUMP 1 SYSOUT=D

Command ===> Scroll ===> CSR F1=Help F3=Exit F7=Backward F8=Forward F10= Submit F11=ShowDD

F12=Cancel

Submit - Create and submit JCL for batch execution

Software Group

49

EQAPRIP1 --------- Parameters for Message Processing R egion ------------------

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 indicatingclasses of messages to be served

APPLFE. . . specify a 1-8 charac ter name of an appli-cation front-end routine that is calledwhenever a message processing program isscheduled. (Front-end routine is requiredto debug non-LE Assembler program)

STIMER. . . specify a process tim e 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 . . . . YOPT . . . . 0 OVLA. . . . 0PCB . . . . 000 PREINIT . . NPRLD. . . . 0 PWFI. . . . SOD . . . . SPIE. . . . 0SSM . . . . TLIM. . . . 00


F12=Cancel



Software Group

50

Milestone





– Old method ? Pass parameters through IMS exit

– New method ? Pass parameters through DT exit

Software Group

51

Specifying the TEST runtime options through the Language Environment exit routine

Language Environment exit routines for various environments

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”

EQADBCXTBatch and BTS

EQADICXT IMS TM and BTS²

Exit routine nameEnvironment

4



Software Group

64

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 theLanguage 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 thefollowing tokens:

&USERID Debug Tool replaces the &USERID token with the user ID of the current user. Each user canspecify 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 (loadmodule). 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 loadmodules for the three environments are in the hlq.SEQAMOD data set. Use this load module if youwant 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 ofCEEBXITA. 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 thehlq.SEQAMOD data set. The sample assembler routines are in the hlq.SEQASAMP data set.

Software Group

65

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



Software Group

67

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

Software Group

69

Option 1: exit linked into application load module

1. Include a special LE user exit for DT in theapplication load module

2. Use DT panel 6 to identifyprograms 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, theexit passes a TEST parmto LE

6. LE starts Debug Tool



Software Group

70

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 identifyprograms 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

Software Group

71

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



Software Group

72

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)– EQADICXT: for online IMS (IMS/TM) LE applications only– EQADDCXT: for LE DB2 stored procedures only– These modules reside in Debug Tool library SEQAMOD– Source for the exits (in library SEQASAMP) can be customized to:

• Change the naming convention for the TEST option data set• Change to “quiet” mode to reduce system log messages

� To enable them:– Option 1: Link-edit the appropriate version of the exit into each application load

module, or– 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

Technique

Software Group

73

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(EQADI CXT)//SYSPRINT DD SYSOUT=* //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 AP PLICATION PROGRAM //* //DFSIVA34 EXEC PROC=COMLK,SRC=DFSIVA34,MBR=DFSIVP34, // SYSHQ=IMS.V10R1 //L.SYSIN DD *

INCLUDE RESLIB(DFSLI000)

INCLUDE CEEBXITANAME DFSIVP34(R)

//*



Software Group

74

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

Software Group

75

EQAàPRIM ------------------- Debug Tool Utilities ------ ----------------------More: +

0 Job CardCreate Job Card image.

1 Program PreparationConvert, compile, assemble or link edit program.

2 Debug Tool Setup File Manage setup files and start debug session in TSO foreg round or batch.

3 Code CoverageMeasure code coverage in programs.

4 IMS TM SetupUpdate Language Environment run-time options in IMS. C reate message region.

5 Load Module AnalyzerAnalyze 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 ini tialization.

7 Other IBM Problem Determination ToolsInvoke IBM File Manager for z/OS.

8 JCL for Batch DebuggingModify JCL to start a debugging session for batch prog rams.


F12=Cancel

4



Software Group

76

EQAPTOP ------ Debug Tool - Manage TEST Run-time Opti on 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 de bugging application that uses Debug Tool Language Environment user exit .

Use Help and the Debug Tool User Guide section: Pre paring a program using Debug Tool Language Environment user exit, fo r more information.

Data Set Name:Data Set Name . . . 'DELAHAY.DBGTOOL.EQAUOPTS'Volume Serial . . . (If not cataloged)

Command ===>F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=Swap N

F12=Cancel

Software Group

77

EQAPTPRM ------ Debug Tool - Edit TEST Run-time Optio n 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/NotestTest Level ==> ALL All/Error/None Commands File *, DDname, or D ata Set Name

==> * Prompt Level Prompt, NoPromp t, ;, *, command

==> PROMPT Preference File *, DDname, or D ata Set Name

==> *

Select (/) a session type and provide parameters:

/ Full-screen mode Network ==> Blank or VTAM Netw ork name Terminal LU ==> EQBMV007 VTAM Terminal LU

Full-screen mode using the Debug Tool Terminal Inte rface Manager User ID ==> User ID

Command ===>F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=Swap N

F12=Cancel



Software Group

78

TEST runtime option dataset

Software Group

79

Milestone





– Old method ? Pass parameters through IMS exit

– New method ? Pass parameters through DT exit

� Specifics for batch programs



Software Group

80

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 theDebug 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 knowbeforehand exactly which debug commands you are going to issue.

When you run BTS as a batch job, the batch mode of Debug Tool is theonly mode available for use.

Software Group

81

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 theTSO 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 isavailable only when you are running BTS in the TSO foreground. FSS can onlybe turned off by specifying TSO=NO on the ./O command. When running in theTSO 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 namecorresponds to the MVS library name, and that you have at least read accessto that MVS library.



Software Group

82


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 canview the output of the transaction. Therefore, if you use an input data set, you canonly specify data for one transaction in that data set. The data for the nexttransaction must be entered from your TSO terminal.

A new debug session will be started automatically for the next transaction. Whenusing FSS, you must enter the /* command on your TSO terminal to terminate theBTS session.

Software Group

83


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.



Software Group

85

BTS execution options---------------------------- BTS execution options - ---------------------------Option ===>

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 do n't continually allocate.

BTS region type ===> DLI (BMP,DBB or DLI) IMS system ===> IMA1Use 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 DB 2) 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

Software Group

86

BTS input parametersBTS display some information and wait for your input.

BTS0007I BTS V3R1 SIMULATION STARTED. TIME=14:24:4 3, 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.



Software Group

87

Alternative to DTU

� You can have your customized panels for use withcustomized LE exit

� Already used in many locations

Software Group

88

ADTDEBUG Debug Utility: Wilfried's LE Ex its OPTION ===>

1 For Batch, DB2 Stored Procedure and CICS

2 For Batch, DB2 Stored Procedure and IMS / TM

Press PF3 to return.

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

5



Software Group

89

DBGPRIM --------- Debug tool parameter file initialisat ion -----------------

Parameter file: UserID. . . DELAHAY _ File Name . DELAHAY.DBGTOOL.TESTPARM

Debug Options: Test. . . . Y Y or N Debug this programsPGM Names . DFSIVP34Jobname . . ________ Batch JobnameStepname. . ________ Batch StepnameIMS 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 F2=SPLIT F3=END F4=RETURN F5=RFND F6=RCHANGE F7=UP F8=DOWN F9=Swap N F10=LEFT F11=RIGHT F12=RETRIEVE

Customizableparameter file name

Software Group

90

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 SetThe method by which this Exit has been deployedmeans 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 tothe IMS application program module

WVH=Wilfried Van Hecke



Software Group

91


� Build:


� Invoke:


� Execute:


Software Group

92

CustomizableCustomizable 3270 Interface3270 Interface



Software Group

93

Memory display

Software Group

94

Rational Rational DeveloperDeveloper for for SystemSystem zz

Monitoring and changing the value of variablesBreakpoints managing.



Software Group

95

Variables

VARBL1=10

Software Group

96

Conclusion

� Debug Tool is the tool of choice to debugmainframe applications

� Integration with RDz

� Customization

Debug Tool for z/OS (5655-U27)

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



Software Group

97

Education Assistant

http://publib.boulder.ibm.com/infocenter/ieduasst/stgv1r0/index.jsp

Software Group

98

Redbooks www.redbooks.com

Date post:	28-Nov-2014
Category:	Documents
Upload:	suresh-babu
View:	128 times
Download:	5 times

B3_Debuging_IMS_200902

Documents