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 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:
  1. EQADDCXT is supported for DB2 version 7 or later. If DB2 RUNOPTS is specified, EQADDCXT takes precedence over DB2 RUNOPTS.
  2. 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.
  3. 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). 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:

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:

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

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:

  1. Log on to Terminal Interface Manager.
  2. In the DEBUG TOOL TERMINAL INTERFACE MANAGER panel, press PF10.
  3. 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.
  4. 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.
  5. 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.
  6. 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:
    1. Press PF9.
    2. 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.
    3. (Optional) Press Enter. Terminal Interface Manager accepts the changes and refreshes the panel.
    4. 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.
  7. 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.

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:

  1. Start Debug Tool Utilities and select option 6, "Debug Tool User Exit Data Set".
  2. 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:
  3. 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.