Specifying the TEST runtime options through the Language Environment user
exit
Debug Tool provides a customized version of the Language Environment® user
exit (CEEBXITA). The user exit returns a TEST runtime option when
called by the Language
Environment initialization logic. Debug Tool provides user exits
for three different environments. This topic is
also described in Debug Tool Customization Guide with information specific
to system programmers.
The user exit extracts the TEST runtime option from
a user controlled 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 optional.
- &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 in two forms:
- A load module. 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 user exit that you can edit. The assembler user
exits 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.
Debug Tool provides the following user exits:
Table 14. Language Environment user exits for various environments
| Environment |
User exit name |
The following types of DB2® stored procedures that run in
WLM-established address spaces1:
- type MAIN
- type SUB, invoked by the call_sub function
|
EQADDCXT |
| IMS™ TM2 and BTS3 |
EQADICXT |
| Batch and BTS |
EQADBCXT |
Notes:
- EQADDCXT is supported for DB2 version
7 or later. If DB2 RUNOPTS is
specified, EQADDCXT takes precedence over DB2 RUNOPTS.
- For IMS TM,
if you do not sign on to the IMS terminal,
you might need to run the EQASET transaction with the TSOID option.
For instructions on how to run the EQASET transaction, see Debugging Language Environment IMS MPPs
without issuing /SIGN ON.
- 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.
Each user exit can be used in one of the following
ways:
- You can link the user exit into your application program.
- You can link the user exit into a private copy of a Language Environment module
(CEEBINIT, CEEPIPI, or both), and then, only for the modules you might
debug, place the SCEERUN data set containing this module in front
of the system Language Environment modules in CEE.SCEERUN in the load module
search path.
To learn about the advantages and disadvantages of each method,
see Comparing the two methods of linking CEEBXITA.
To prepare a program to use the Language Environment user exit,
do the following tasks:
- Editing the source code of CEEBXITA.
- Linking the CEEBXITA user exit into your application program or Linking the CEEBXITA user exit into a private copy of a Language Environment runtime
module.
- Creating and managing the TEST runtime options data set.
Editing the source code of CEEBXITA
You can edit the sample assembler user exit that is provided in hlq.SEQASAMP
to customize the naming patterns or message display level by doing
one of the following tasks:
- Use an SMP/E USERMOD to update the copy of the exit in the hlq.SEQAMOD
data set. The system programmer usually implements
USERMODs. Use the following sample USERMODs in hlq.SEQASAMP
for this task:
| User exit name |
USERMOD name |
| EQADDCXT |
EQAUMODC |
| EQADICXT |
EQAUMODD |
| EQADBCXT |
EQAUMODB |
- Create a private load module for the customized exit. Copy the
assembler user exit that has the same name as the user exit from hlq.SEQASAMP
to a local data set. Edit the patterns or message display level. Customize
and run the JCL to generate a load module.
Modifying the naming pattern
The naming pattern of the data set that has the TEST runtime
option is in the form of a sequential data set name. You can optionally
specify a &USERID token, which Debug Tool substitutes with
the user ID of the current user. You can also add a &PGMNAME token,
which Debug Tool substitutes with the name of the main program (load module). However, if users create and manage the TEST runtime option
data set with the DTSP Profile view
in the remote debugger, do not specify the &PGMNAME token
because the view does not support that token.
In some cases, the first character of a user ID is not valid for
a name qualifier. A character can be concatenated before the &USERID token
to serve as the prefix character for the user ID. For example, you
can prefix the token with the character "P" to form P&USERID,
which is a valid name qualifier after the current user ID is substituted
for &USERID. For IMS, &USERID token
might be substituted with one of the following values:
- IMS user ID, if users sign
on to IMS.
- TSO user ID, if users do
not sign on to IMS.
The default naming pattern is &USERID.DBGTOOL.EQAUOPTS.
This is the pattern that is in the load module provided in hlq.SEQAMOD.
The following table shows examples of naming patterns and the corresponding
data set names after Debug Tool substitutes the token with a value.
Table 15. Data set naming patterns, values for tokens, and resulting data set names
| Naming pattern |
User ID |
Program name |
Name after user ID substitution |
| &USERID.DBGTOOL.EQAUOPTS |
JOHNDOE |
|
JOHNDOE.DBGTOOL.EQAUOPTS |
| P&USERID.EQAUOPTS |
123456 |
|
P123456.EQAUOPTS |
| DT.&USERID.TSTOPT |
TESTID |
|
DT.TESTID.TSTOPT |
| DT.&USERID.&PGMNAME.TSTOPT |
TESTID |
IVP1 |
DT.TESTID.IVP1.TSTOPT |
To customize the naming pattern of the data set that has TEST runtime
option, change the value of the DSNT DC statement in the sample user
exit. For example:
* Modify the value in DSNT DC field below.
*
* Note: &USERID below has one additional '&', which is an escape
* character.
*
DSNT_LN DC A(DSNT_SIZE) Length field of naming pattern
DSNT DC C'&&USERID.DBGTOOL.EQAUOPTS'
DSNT_SIZE EQU *-DSNT Size of data set naming pattern
*
Modifying the message display level
You can modify the message display level for CEEBXITA. The following
values set WTO message display level:
- X'00'
- Do not display any messages.
- X'01'
- Display error and warning messages.
- X'02'
- Display error, warning, and diagnostic messages.
The default value, which is in the load module in hlq.SEQAMOD,
is X'00'.
To customize the message display level, change the value of the MSGS_SW
DC statement in the sample user exit. For example:
* The following switch is to control WTO message display level.
*
* x'00' - no messages
* x'01' - error and warning messages
* x'02' - error, warning, and diagnostic messages
*
MSGS_SW DC X'00' message level
*
Comparing the two methods of linking CEEBXITA
You can link in the user exit CEEBXITA in the following ways:
- Link it into the application program.
- Advantage
- The user exit affects only the application program being debugged.
This means you can control when Debug Tool is started for the application
program. You might also not need to make any changes to your JCL to
start Debug Tool.
- Disadvantage
- You must remember to remove the user exit for production or,
if it isn't part of your normal build process, you must remember
to relink it to the application program.
- Link it into a private copy of a Language Environment runtime load module
(CEEBINIT, CEEPIPI, or both)
- Advantage
- You do not have to change your application program to use the
user exit. In addition, you do not have to link edit extra modules
into your application program.
- Disadvantage
- You need to take extra steps in preparing and maintaining your
runtime environment:
- Make a private copy of one or more Language Environment runtime routines
- Only for the modules you might debug, customize your runtime environment
to place the private copies in front of the system Language Environment modules
in CEE.SCEERUN in the load module search path
- When you apply maintenance to Language Environment, you might need to relink
the routines.
- When you upgrade to a new version of Language Environment, you must relink
the routines.
If you link the user exit into the application program and into
a private copy of a Language Environment runtime load module, which is in the
load module search path of your application execution, the copy of
the user exit in the application load module is used.
Linking the CEEBXITA user exit into your application program
If you choose to link the CEEBXITA user exit into your application
program, use the following sample JCL, which links the user exit with
the program TESTPGM. If you have customized the user exit and placed
it in a private library, replace the data name, (hlq.SEQAMOD)
of the first SYSLIB DD statement with the data set name that contains
the modified user exit load module.
//SAMPLELK JOB ,
// MSGCLASS=H,TIME=(,30),MSGLEVEL=(2,0),NOTIFY=&SYSUID,REGION=0M
//*
//LKED EXEC PGM=HEWL,REGION=4M,
// PARM='CALL,XREF,LIST,LET,MAP,RENT'
//SYSLMOD DD DISP=SHR,DSN=USERID.OUTPUT.LOAD
//SYSPRINT DD DISP=OLD,DSN=USERID.OUTPUT.LINKLIST(TESTPGM)
//SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(200,20))
//*
//SYSLIB DD DISP=SHR,DSN=hlq.SEQAMOD
// DD DISP=SHR,DSN=CEE.SCEELKED
//*
//OBJECT DD DISP=SHR,DSN=USERID.INPUT.OBJECT
//SYSLIN DD *
INCLUDE OBJECT(TESTPGM)
INCLUDE SYSLIB(EQADICXT)
NAME TESTPGM(R)
/*
Linking the CEEBXITA user exit into a private copy of a Language Environment runtime
module
If you choose to customize a private copy of a Language Environment runtime
load module, you need to ensure that your private copy of these load
modules is placed ahead of your system copy of CEE.SCEERUN in your
runtime environment.
The following table shows the Language Environment runtime load module and
the user exit needed for each environment.
Table 16. Language Environment runtime module and user exit required for various environments
| Environment |
User exit name |
CEE load module |
The following types of DB2 stored procedures that run in
WLM-established address spaces:
- type MAIN
- type SUB, invoked by the call_sub function1
|
EQADDCXT |
CEEPIPI |
| IMS TM
and BTS |
EQADICXT |
CEEBINIT |
| Batch |
EQADBCXT |
CEEBINIT |
Notes:
- This requires that you install the PTF for APAR PM15192 for Language Environment Version
1.10 to Version 1.12.
Edit and run sample hlq.SEQASAMP(EQAWLCEE) to create these
updated Language Environment runtime modules. This is typically
done by the system programmer installing Debug Tool. The sample creates
the following load module data sets:
- hlq.DB2SP.SCEERUN(CEEPIPI)
- hlq.IMSTM.SCEERUN(CEEBINIT)
- hlq.BATCH.SCEERUN(CEEBINIT)
When
you apply service to Language Environment that affects either of these modules
(CEEPIPI or CEEBINIT) or you move to a new level of Language Environment, you
need to rebuild your private copy of these modules by running the
sample again.
Option 8 of the Debug Tool Utilities ISPF panel,
"JCL for Batch Debugging", uses hlq.BATCH.SCEERUN if you
use Invocation Method E.
Creating and managing the TEST runtime options data set
The TEST runtime options data set is an MVS™ data set that contains the Language Environment runtime
options. The Debug Tool Language Environment user exits (EQADDCXT,
EQADICXT, and EQADBCXT) construct the name of this data set based
on a naming pattern described in "Modifying
the naming pattern" in the Debug Tool Customization Guide.
You can create this data set in one of
the following ways:
Creating and managing the TEST runtime options data set by
using Terminal Interface Manager (TIM)
Before you begin, verify that the user ID that you use
to log on to Terminal Interface Manager (TIM) has permission to read
and write the TEST runtime options data set.
To create the TEST runtime options data set by using Terminal
Interface Manager, do the following steps:
- Log on to Terminal Interface Manager.
- In the DEBUG TOOL TERMINAL INTERFACE
MANAGER panel, press PF10.
- In the * Specify TEST Run-time
Option Data Set * panel, type in the name of a data set which
follows the naming pattern specified by your system administrator,
in the Data Set Name field. If the
data set is not cataloged, type in a volume serial.
- Press Enter. If Terminal Interface Manager cannot find the data
set, it displays the * Allocate TEST Run-time
Option Data Set * panel. Specify allocation parameters for the
data set, then press Enter. Terminal Interface Manager creates the
data set.
- In the * Edit TEST Run-time Option
Data Set * panel, make the following changes:
- Program name(s)
- Specify the names of up to eight programs you want to debug.
You can specify specific names (for example, EMPLAPP), names appended
with a wildcard character (*), or just the wildcard character (which
means you want to debug all Language Environment programs).
- Test Option
- Specify whether to use TEST or NOTEST runtime
option.
- Test Level
- Specify which TEST level to use: ALL, ERROR, or NONE.
- Commands File
- If you want to use a commands file, specify the name
of a commands file in the format described in the commands_file_designator section
of the topic "Syntax of the TEST run-time
option" in the Debug Tool Reference and Messages.
- Prompt Level
- Specify whether to use PROMPT or NOPROMPT.
- Preferences File
- If you want to use a preferences file, specify the
name of a preferences file in the format described in the preferences_file_designator section
of the topic "Syntax of the TEST run-time
option" in the Debug Tool Reference and Messages.
- EQAOPTS File
- If you want Debug Tool to run any EQAOPTS commands at
run time, specify the name of the EQAOPTS file as a fully-qualified
data set name.
- Other run-time options
- Type in any other Language Environment runtime options.
- Terminal Interface Manager displays the part of
the TEST runtime option that specifies which session type (debugging
mode and display information) you want to use under the Current debug display information field. To
change the session type, do the following steps:
- Press PF9.
- In the Change session type panel,
select one of the following options:
- Full-screen mode using
the Debug Tool Terminal Interface Manager
- Type in the user ID you will use to log on to Terminal
Interface Manager and debug your program in the User
ID field.
- Remote debug mode
- Type in the IP address in the Address field
and port number in the Port field of
the remote debugger’s daemon.
- (Optional) Press Enter. Terminal Interface Manager accepts the
changes and refreshes the panel.
- Press PF4. Terminal Interface Manager displays the * Edit TEST Run-time Option Data Set
* panel and under the Current debug
session type string: displays one of the following strings:
- VTAM%userid, if you selected Full-screen mode using the Debug Tool Terminal
Interface Manager.
- TCPIP&IP_address%port, if you
selected Remote debug mode.
- Press PF4 to save your changes to the TEST runtime options data
set and to return to the main Terminal Interface Manager screen.
Refer to the following topics for more information
related to the material discussed in this topic.
- For more information about the values to specify for the Test
Option, Test Level, and Prompt Level fields, see the topic "Syntax of the TEST run-time option" in Debug Tool Reference and Messages.
- For instructions on creating a commands file or preferences file,
see the topics Creating a commands file or Creating a preferences file.
- For instructions on creating an EQAOPTS file, see the topic "Providing EQAOPTS commands
at run time" in the Debug Tool Reference and Messages or Debug Tool Customization Guide.
- For more information about other Language Environment runtime options, see Language Environment Programming Reference, SA22-7562.
- For more information about the values to specify for the Full-screen mode using the Debug Tool Terminal
Interface Manager field, see Starting a debugging session in full-screen mode using a dedicated terminal.
- For more information about the values to specify for
the Remote debug mode field, see the
online help for the compiled language debugger component of Rational Developer for System z or the IBM Debug Tool plug-in for Eclipse.
Creating and managing the TEST runtime options data
set by using Debug Tool Utilities
To create the TEST runtime options data set by using Debug Tool Utilities,
do the following steps:
- Start Debug Tool Utilities and select option 6, "Debug Tool User Exit
Data Set".
- Provide the name of a new or existing data set. Make sure the
name matches the naming pattern. If you do not know the naming pattern,
ask your system administrator. Remember the following rules:
- Substitute the &PGMNAME token with the name of
the program you want to debug. The program must be the main CSECT
of the load module in a Language
Environment enclave.
- For IMS, &USERID token
might be substituted with one of the following values:
- IMS user ID, if users sign
on to IMS.
- TSO user ID, if users do
not sign on to IMS.
- Fill out the rest of the fields with the TEST runtime options
you want to use and the names of up to eight additional programs to
debug.