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:
Debug Tool provides the user exit in two forms:
Debug Tool provides the following user exits:
| Environment | User exit name |
|---|---|
| DB2® stored procedures of type MAIN that run in WLM-established address spaces1 | EQADDCXT |
| IMS™ TM and BTS2 | EQADICXT |
| Batch and BTS | EQADBCXT |
Each user exit can be used in one of the following ways:
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:
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:
| User exit name | USERMOD name |
|---|---|
| EQADDCXT | EQAUMODC |
| EQADICXT | EQAUMODD |
| EQADBCXT | EQAUMODB |
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).
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.
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.
| 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 *
You can modify the message display level for CEEBXITA. The following values set WTO message display level:
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 *
You can link in the user exit CEEBXITA in the following ways:
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.
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)
/*
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.
| Environment | User exit name | CEE load module |
|---|---|---|
| DB2 stored procedures of type MAIN that run in WLM-established address spaces | EQADDCXT | CEEPIPI |
| IMS TM and BTS | EQADICXT | CEEBINIT |
| Batch | EQADBCXT | CEEBINIT |
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:
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.
The TEST runtime options data set contains the values for the program name list, the TEST runtime option string, and other Language Environment runtime option strings. Use option 6 of the Debug Tool Utilities ISPF panel, "Debug Tool User Exit Data Set," to create and manage this data set. Option 8, "JCL for Batch Debugging," also uses this data set if you use Invocation Method E or A.
The data set has the following requirements: