Rational Developer for System z, Version 7.6

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:

Debug Tool provides the following user exits:

Table 13. Language Environment user exits for various environments
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
Notes:
  1. EQADDCXT is supported for DB2 version 7 or later. If DB2 RUNOPTS is specified, EQADDCXT takes precedence over DB2 RUNOPTS.
  2. 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:

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:

  1. Editing the source code of CEEBXITA.
  2. 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.
  3. 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:

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

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.

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

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 15. Language Environment runtime module and user exit required for various environments
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.

Creating and managing the TEST runtime options data set

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:


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)