EQAOPTS commands

EQAOPTS commands are commands that alter some of the basic behavior of Debug Tool. These commands must be processed before normal Debug Tool command processing is available. You can specify most EQAOPTS commands in the following ways:

If you want the commands to apply to only a few debugging sessions, it might be easier to supply the EQAOPTS command dynamically at run time. If you want the commands to apply to a group of debugging sessions, it might be better to supply the EQAOPTS commands through the EQAOPTS load module.

Except for commands that can be validly specified more than once (for example, the NAMES commands), if Debug Tool finds a command more than once, it uses the first specification of the command. Debug Tool processes EQAOPTS commands specified at run time before those specified through the EQAOPTS load module. This means that commands specified at run time override duplicate commands specified in the EQAOPTS load module.

Any or all of the following people can create EQAOPTS specifications:

If you are the system programmer or you are creating EQAOPTS specifications for specific groups, you might change the EQAOPTS specifications less frequently, so specifying them by generating a new EQAOPTS load module might be more efficient. If you are an individual user, you might change the EQAOPTS specifications more frequently, so specifying them dynamically at run time might be more efficient.

Table 8 summarizes the available EQAOPTS commands and indicates whether a system programmer (S), a specific group (G), or an individual user (U) most commonly uses a command.

Table 8. A brief description of each EQAOPTS command and the type of user most likely to use that command
Command Description Commonly used by
BROWSE Allows users with the authority to use Debug Tool in normal mode to restrict their access to Browse Mode. U
CACHENUM Controls the size of the Debug Tool cache to minimize rereading the debug information. U, G
CODEPAGE Controls the codepage used by Debug Tool. U, G, S
COMMANDSDSN Specifies the default naming pattern Debug Tool uses to name the user’s commands file. U, G, S
DEFAULTVIEW Controls the default view of assembler programs. U, G
DTCNFORCExxxx Controls whether to require certain fields in DTCN. S
EQAQPP Enables Debug Tool to debug MasterCraft Q++ programs. U, G
EXPLICITDEBUG Enables explicit debug mode. U
GPFDSN Specifies that Debug Tool process a global preferences file. U, G, S
LOGDSN Specifies the default naming pattern Debug Tool uses to name the user’s log file. U, G, S
LOGDSNALLOC Specifies the allocation parameters Debug Tool uses when it creates the log file. U, G, S
MDBG Allows users of programs compiled with z/OS® XL C/C++ Version 1.10, or later, to indicate whether Debug Tool searches for .mdbg files. U, G
NAMES Controls whether Debug Tool processes or ignores certain load module or compile unit names. U, G
NODISPLAY Controls the Debug Tool behavior when the display requested by the Debug Tool user is not available. U, G, S
PREFERENCESDSN Specifies the default naming pattern Debug Tool uses to name the preferences file. U, G, S
SAVEBPDSN, SAVESETDSN Specifies the default naming pattern for the data sets used to save and restore the breakpoints and monitors (SAVEBPS) and the settings (SAVESETS). U, G, S
SAVEBPDSNALLOC, SAVESETDSNALLOC Specifies the allocation parameters Debug Tool uses when it creates the SAVEBPS and SAVESETS data sets. U, G, S
SUBSYS Specifies a subsystem used by certain library systems. G, S
SVCSCREEN Controls whether and how Debug Tool uses SVC screening to intercept LOAD and LINK SVC's. This is necessary for debugging non-Language Environment assembler programs. S
THREADTERMCOND Controls whether Debug Tool prompts the user when it encounters a FINISH, enclave termination, or thread termination condition. U, G
TIMACB Specifies that the Debug Tool Terminal Interface Manager (TIM) use a name other than EQASESSM. S
END Specifies the end of a list of EQAOPTS commands. You must specify END. U, G, S

Use the following list to help you record the commands and value you want to implement:

Table 9. Checklist you can print to record which EQAOPTS commands you selected and the values to use for each command.
  • _ EQAXOPT BROWSE, then select one of the following options:
    • _ RACF
    • _ ON
    • _ OFF
  • _ EQAXOPT CACHENUM,number:_____________________________________
  • _ EQAXOPT CODEPAGE,code_page_number:___________________________
  • _ EQAXOPT COMMANDSDSN,file name pattern:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT DEFAULTVIEW, then select one of the following options:
    • _ STANDARD
    • _ NOMACGEN
  • _ EQAXOPT DTCNFORCECUID, then select one of the following options:
    • _ YES
    • _ NO
    This option performs the same function as DTCNFORCEPROGID. If you select YES for DTCNFORCEPROGID, you do not need to specify this option.
  • _ EQAXOPT DTCNFORCEIP, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCELOADMODID, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCENETNAME, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCEPROGID, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCETERMID, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCETRANID, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT DTCNFORCEUSERID, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT EQAQPP, then select one of the following options:
    • _ ON
    • _ OFF
  • _ EQAXOPT EXPLICITDEBUG, then select one of the following options:
    • _ ON
    • _ OFF
  • _ EQAXOPT GPFDSN,'file_name:_______________________________________'
  • _ EQAXOPT LOGDSN,file name pattern:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT LOGDSNALLOC,allocation parameters:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT MDBG, then select one of the following options:
    • _ YES
    • _ NO
  • _ EQAXOPT NAMES, then select one of the following options:
    • _ EXCLUDE,LOADMOD,pattern:____________________________________
    • _ EXCLUDE,CU,pattern:_________________________________________
    • _ INCLUDE,LOADMOD,name:_______________________________________
    • _ INCLUDE,CU,name:____________________________________________
  • _ EQAXOPT NODISPLAY, then select one of the following options:
    • _ DEFAULT
    • _ QUITDEBUG
  • _ EQAXOPT PREFERENCESDSN,file name pattern:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT SAVEBPDSN,'file_name:____________________________________'
  • _ EQAXOPT SAVESETDSN,'file_name:___________________________________'
  • _ EQAXOPT SAVEBPDSNALLOC,allocation parameters:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT SAVESETDSNALLOC,allocation parameters:_______________________

    Append ,LOUD if you want Debug Tool to display WTO messages, which helps you debug processing done by this command.

  • _ EQAXOPT SUBSYS,subsystem library name:____________________________
  • _ EQAXOPT SVCSCREEN, then select one of the following options:
    • _ ON
    • _ OFF
    Select one of the following options to indicate what you want Debug Tool to do if there is an existing SVC screening environment:
    • _ CONFLICT=OVERRIDE
    • _ CONFLICT=NOOVERIDE
    Select one of the following options to indicate whether you want Debug Tool to temporarily replace the existing SVC screening environment:
    • _ NOMERGE
    • _ MERGE=(COPE)
  • _ EQAXOPT THREADTERMCOND, then select one of the following options:
    • _ PROMPT
    • _ NOPROMPT
  • _ EQAXOPT TIMACB,ACB-name:_________________________________________
  • _ EQAXOPT END Always specify this command.

After you have made all of you selections, define the options as described in Creating EQAOPTS load module.

Format of the EQAOPTS command

When you specify EQAOPTS commands through the EQAOPTS load module, you create them as assembler macro invocations and you must subsequently assemble and link-edit them into the EQAOPTS load module. To provide a consistent format for all forms of EQAOPTS commands, when you specify the EQAOPTS commands at run time, you must use the assembler macro invocation format. The following format rules apply to all EQAOPTS commands:

EQAOPTS commands that have equivalent Debug Tool commands

Some EQAOPTS commands have equivalent Debug Tool commands. Table 10 shows a few examples.

Table 10. Examples of EQAOPTS commands and their equivalent Debug Tool commands
EQAOPTS command Debug Tool command
DEFAULTVIEW SET DEFAULTVIEW
NAMES NAMES
EXPLICITDEBUG SET EXPLICITDEBUG

For these commands, specifying them as EQAOPTS commands or Debug Tool commands produces the same action. The timing (when these commands take effect) differs between EQAOPTS commands and Debug Tool commands.

Debug Tool processes Debug Tool commands after it processes the initial load module and creates the compile units contained in the initial load modules. Debug Tool processes EQAOPTS commands during Debug Tool initialization, prior to processing the initial load module. This means that when Debug Tool processes the initial load module, Debug Tool commands like NAMES are not in effect but the corresponding EQAOPTS commands are in effect and are applied to the initial load module.

EQAOPTS commands like DEFAULTVIEW provide a way of specifying a site- or group-wide default for the corresponding Debug Tool command. However, a better way to specify a site- or group-wide default for these types of commands is by putting the Debug Tool command in a global preferences file.

Providing EQAOPTS commands at run time

You can provide EQAOPTS commands to Debug Tool at run time. You must save the commands in a data set with 80-byte, fixed-length records. The following list describes the methods of specifying this data set to Debug Tool:

The following example shows what the data set might contain:

EQAXOPT MDBG,YES
EQAXOPT NODISPLAY,QUITDEBUG
EQAXOPT NAMES,EXCLUDE,LOADMOD,USERMOD1
EQAXOPT NAMES,EXCLUDE,LOADMOD,USERMOD7
EQAXOPT END

The instructions in Creating EQAOPTS load module contain examples with specifications for CSECT, AMODE, RMODE, and END (without EQAXOPTS) statements. Do not include these specifications if you provide EQAOPTS command at run time.

Creating EQAOPTS load module

If you have chosen to use the EQAOPTS load module to specify your EQAOPTS commands, do the following steps:

  1. Copy the EQAOPTS2 member from the hlq.SEQASAMP library to a private library.
  2. Edit this copy of EQAOPTS and code the EQAOPTS command or commands you want. To this minimum source, add each EQAXOPT option you want to include. The following example describes the minimum assembler source required to generate the EQAOPTS load module:
    EQAOPTS  CSECT ,
    EQAOPTS  AMODE 31
    EQAOPTS  RMODE ANY
             Add your customized EQAXOPT statements here.  For example:
             EQAXOPT MDBG,YES
             EQAXOPT NODISPLAY,QUITDEBUG
             EQAXOPT NAMES,EXCLUDE,LOADMOD,USERMOD1
             EQAXOPT NAMES,EXCLUDE,LOADMOD,USERMOD7
             EQAXOPT END
             END ,
  3. Follow the directions in the EQAOPTS sample to generate a new EQAOPTS load module. These directions describe how to assemble the source and link-edit the generated object into a load module named EQAOPTS.
  4. Place the EQAOPTS load module in a private data set that is in the load module search path and appears before hlq.SEQAMOD.

Descriptions of EQAOPTS commands

To learn how EQAOPTS commands work and how to specify them, see EQAOPTS commands.

BROWSE

Debug Tool browse mode can be controlled by either the browse mode RACF® facility, through the EQAOPTS BROWSE command, or both. For a description of how to control browse mode through RACF, see "Debugging in browse mode" in Debug Tool User’s Guide.

Users who have sufficient RACF authority can specify the EQAOPTS BROWSE command to indicate that the current invocation of Debug Tool be in browse mode.

The following diagram describes the syntax of the BROWSE command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--BROWSE--,--+-RACF-+--------------------------------><
                       +-ON---+
                       '-OFF--'
 

The following list describes the parameters of the EQAOPTS BROWSE command:

RACF
Indicates that you want Debug Tool to use the browse mode access as determined by the current user's RACF access to the applicable RACF profile. If you do not specify the BROWSE command, Debug Tool defaults to RACF.
ON
Indicates that unless the user's RACF access is NONE, set BROWSE MODE to ON.
OFF
Indicates that if no RACF profile exists or if the user has UPDATE access or higher, set BROWSE MODE to OFF.

Examples

EQAXOPT BROWSE,ON
EQAXOPT BROWSE,RACF

If you choose to implement this option, remember to record your selection on the form at the beginning of EQAOPTS commands.

CACHENUM

To reduce CPU consumption, Debug Tool stores information about the application programs being debugged in a cache. By default, for each debug session, Debug Tool stores the information for a maximum of 10 programs. Application programs that do a LINK, LOAD, or XCTL to more than 10 programs can degrade Debug Tool's CPU performance. You can enhance Debug Tool's CPU performance for these application programs by specifying an increased CACHENUM value in EQAOPTS. An increased value causes Debug Tool to use more storage for each debugging session.

The following diagram describes the syntax of the CACHENUM command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--CACHENUM--,--cache_value---------------------------><
 
cache_value
Specifies the size of the Debug Tool cache. It must be no smaller than 10 and no larger then 999.

Example

EQAXOPT CACHENUM,40

CODEPAGE

The default code page used by Debug Tool and the remote debuggers is 037. For any of the following situations, you need to use a different code page:

Debug Tool uses the z/OS Unicode Services to process characters that need code page conversion.

The following diagram describes the syntax of the CODEPAGE command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--CODEPAGE--,--nnnn----------------------------------><
 
nnnn
A positive integer indicating the code page to use.

After implementing the EQAOPTS CODEPAGE command, if application programmers using full-screen mode still cannot display some characters correctly, have them verify that their emulator’s code page matches the code page of the characters they need to display.

You might need to create your own conversion images as described in Creating a conversion image for Debug Tool.

Example

EQAXOPT CODEPAGE,121

Creating a conversion image for Debug Tool

You might need to create a conversion image so that Debug Tool can properly transmit characters in a code page other than 037 between the remote debugger and the host. A conversion image contains the following information:

You might need to create a conversion image so that users debugging COBOL programs in full screen or batch mode can modify NATIONAL variables with the STORAGE command or to properly display C/C++ variables that contain characters in a code page other than 037. To create the conversion image, you need to do the following steps:

  1. Ask your system programmer for the host's CCSID.
  2. Submit a JCL job that specifies the conversion image between the host CCSID, which you obtained in step 1, and CCSID 1200 (UTF-16).

Example: JCL for generating conversion images describes how one JCL creates the conversion images for both situations.

Example: JCL for generating conversion images

The following JCL generates the conversions images required for Debug Tool.

This JCL is a variation of the JCL located at hlq.SCUNJCL(CUNJIUTL), which is provided by the Unicode conversion services package.

//CUNMIUTL EXEC PGM=CUNMIUTL
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIMG DD DSN=UNI.IMAGES(CUNIMG01),DISP=SHR
//TABIN DD DSN=UNI.SCUNTBL,DISP=SHR
//SYSIN DD *
  /********************************************************************/
  /* Conversion image input for Debug Tool in Remote                  */
  /* debug mode                                                       */
  /********************************************************************/  
  CONVERSION 1390,1208;   /* IBM-930 to UTF-8,RECLM */
  CONVERSION 1208,1390;   /* UTF-8 to IBM-930,RECLM */
  CONVERSION 1399,1208;   /* IBM-939 to UTF-8,RECLM */
  CONVERSION 1208,1399;   /* UTF-8 to IBM-939,RECLM */
  CONVERSION  933,1208;   /* IBM-933 to UTF-8,RECLM */
  CONVERSION 1208,933;    /* UTF-8 to IBM-933,RECLM */
  CONVERSION 1141,1208;   /* IBM-1141 to UTF-8,RECLM */
  CONVERSION 1208,1141;   /* UTF-8 to IBM-1141,RECLM */
  CONVERSION 1047,1208;   /* IBM-1047 to UTF-8,RECLM */
  CONVERSION 1208,1141;   /* UTF-8 to IBM-1141,RECLM */
  /********************************************************************/
  /* Conversion image input for Debug Tool to modify COBOL NATIONAL   */
  /* variables with the STORAGE command while in full screen mode     */
  /********************************************************************/  
  CONVERSION 0037,1200;   /*IBM-37 to UTF-16,RECLM */
/*

Debug Tool uses the character conversion services but not the case conversion or the normalization services of Unicode conversion services. You do not need to include CASE or NORMALIZE control statements unless other applications require them.

COMMANDSDSN

Indicates that you want Debug Tool to read a user’s commands file (with the name of the data set containing the commands file determined by the specified naming pattern) each time it starts. This works in the following situation:

The following diagram describes the syntax of the COMMANDSDSN command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--COMMANDSDSN--,--'--file-name-pattern--'--,--+------+-><
                                                        '-LOUD-'
 
file-name-pattern
Specifies a naming pattern that determines the name of the data set that contains the user’s commands file. Follow these guidelines when you create the naming pattern:
LOUD
Specifies that Debug Tool display WTO messages, which helps you debug processing done by this command. Debug Tool normally does not display any messages if it does not find the data set or data set member. If you are trying to determine why Debug Tool is not processing a user’s commands file, specify LOUD to see if it displays a message that it can not find the data set or the member.

If you choose to implement this option, do the following tasks:

  1. If you are implementing several EQAOPTS commands, record your selections on your copy of Table 9. Use this form to remind you of your selections so that you can implement all the EQAOPTS commands at one time.
  2. Each user that wants to use this function creates the commands file as a PDS or PDSE with the allocation parameters described in "Data sets used by Debug Tool" of the Debug Tool User’s Guide. Then, each user creates a member for each program he wants to debug, with the name of the member matching the initial load module name in the first enclave.

Example

EQAXOPT  COMMANDSDSN,'&&USERID.DBGTOOL.COMMANDS'

If you log in with user ID jsmith, Debug Tool determines the name of the data set to be JSMITH.DBGTOOL.COMMMANDS.

DEFAULTVIEW

A user can control whether to display the statements of an assembler macro in the Source window by entering the SET DEFAULT VIEW command. Every time a LOADDEBUGDATA command is run for an assembler compile unit, Debug Tool uses the setting of this command to determine whether to display the macro-generated statements. You can control the initial default for this setting by using the EQAOPTS DEFAULTVIEW command.

The following diagram describes the syntax of the DEFAULTVIEW command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--DEFAULTVIEW--,--+-STANDARD-+-----------------------><
                            '-NOMACGEN-'
 

Each of these fields corresponds to the similar field in the SET DEFAULT VIEW command. If you do not code the EQAOPTS DEFAULTVIEW command, the initial setting for DEFAULTVIEW is STANDARD.

Example

EQAXOPT DEFAULTVIEW,NOMACGEN

DTCNFORCExxxx

You can specify these commands only in the EQAOPTS load module. You cannot specify them at run time.

If your users create debugging profiles with DTCN, you can use the DTCNFORCExxxx commands to require that certain DTCN fields are not left blank. The following list describes each resource type you can require each user to specify:

If any of the statements are not included, the statement defaults to NO.

The following diagram describes the syntax of the DTCNFORCExxxx command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--+-DTCNFORCECUID--,------+--+-YES-+-----------------><
            +-DTCNFORCEIP--,--------+  '-NO--'
            +-DTCNFORCELOADMODID--,-+
            +-DTCNFORCENETNAME--,---+
            +-DTCNFORCETERMID--,----+
            +-DTCNFORCETRANID--,----+
            '-DTCNFORCEUSERID--,----'
 
YES
Indicates that the specified field is required.
NO
Indicates that the specified field is not required.

Examples

EQAXOPT DTCNFORCEUSERID,YES
EQAXOPT DTCNFORCETRANID,NO

EQAQPP

You must specify this command to enable Debug Tool to debug MasterCraft Q++ programs, provided by Tata Consultancy Services Ltd. For more information about how to enable Debug Tool to support MasterCraft Q++, contact Tata Consultancy Services Ltd.

The following diagram describes the syntax of the EQAQPP command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--EQAQPP--,--+-ON--+---------------------------------><
                       '-OFF-'
 
ON
Indicates Debug Tool supports Q++ debugging.
OFF
Indicates Debug Tool does not support Q++ debugging. If you do not specify the EQAQPP command, OFF is the default.

Example

EQAXOPT EQAQPP,ON

EXPLICITDEBUG

The Debug Tool Reference and Messages describes how you use the SET EXPLICITDEBUG command to enable explicit debug mode in Debug Tool. However, before you can enter the SET EXPLICITDEBUG command, Debug Tool has already processed the initial load module and loaded the debug data for the compile units it contains. If you want to enable explicit debug mode prior to processing the initial load module, use the EQAOPTS EXPLICITDEBUG command.

The following diagram describes the syntax of the EXPLICITDEBUG command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--EXPLICITDEBUG--,--+-ON--+--------------------------><
                              '-OFF-'
 
ON
Enables explicit debug mode.
OFF
Disables explicit debug mode. This is the default.

Example

EQAXOPT EXPLICITDEBUG,ON

GPFDSN

You can create a global preferences file that runs a set of Debug Tool commands at the start of all Debug Tool sessions. For example, a global preferences file can have a command that sets PF keys to specific values. If your site uses the PF6 key as the program exit key, you can specify the SET PF6 "EXIT" = QUIT; command, which assigns the Debug Tool QUIT command to the PF6 key, in the global preferences file. (See "Customizing your full-screen session" in Debug Tool User’s Guide for a description of the interface features you can change.)

Whenever a user starts Debug Tool, Debug Tool processes the commands in the global preferences file first. The user can also create his or her own preferences file and a commands file. In this situation, Debug Tool processes the files in the following order:

  1. Global preferences file
  2. User preferences file
  3. Commands file

To create a global preferences file, do the following steps:

  1. Create a preferences file that is stored as a sequential file or a PDS member. Refer to Debug Tool User’s Guide for a description of preferences files.

    The rules for the preferences file are dependant on the programming language of the first program Debug Tool encounters. Because you might not know what programming language Debug Tool will encounter first, use the following rules when you create the preferences file:

  2. Specify the GPFDSN command to indicate the name of the global preferences file.

    For file_name, specify the name of the data set where the global preferences file will be stored.

The following diagram describes the syntax of the GPFDSN command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--GPFDSN--+--------------------+---------------------><
                    '-,--'--file_name--'-'
 
file_name
The name of the data set where you stored the global preferences file.

Examples

EQAXOPT GPFDSN,'GROUP1.COMMON.DTOOL.PREFS'
EQAXOPT GPFDSN

LOGDSN

By default, Debug Tool handles the log file data set in one of the following ways:

LOGDSN allows a site or a user to specify the default data set name for the log file. If you specify the LOGDSN command, Debug Tool handles the log file in the following way:

If you are an existing Debug Tool user that uses a SAVESETS data set, and you or your site specify the EQAOPTS commands LOGDSN and LOGDSNALLOC, then the SAVESETS data set contains a SET LOG command that overrides the EQAOPTS command LOGDSN.

The following diagram describes the syntax of the LOGDSN command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--LOGDSN--,--'--file-name-pattern--'--,--+------+----><
                                                   '-LOUD-'
 
file-name-pattern
Specifies a naming pattern that determines the name of the data set that contains the log file. Follow these guidelines when you create the naming pattern:
LOUD
Specifies that Debug Tool display WTO messages, which helps you debug processing done by this command. Debug Tool normally does not display any messages if it does not find the data set. If you are trying to determine why Debug Tool is not writing to this log file, specify LOUD to see if it displays any messages.

If you choose to implement this option, do the following tasks:

  1. If you are implementing several EQAOPTS commands, record your selections on your copy of Table 9. Use this form to remind you of your selections so that you can implement all the EQAOPTS command at one time.
  2. Each user that wants to use the EQAOPTS LOGDSN command must create a log file in one of the following ways:

Example

EQAXOPT  LOGDSN,'&&USERID.DBGTOOL.LOG'

If you log in with user ID jsmith, Debug Tool determines the name of the data set to be JSMITH.DBGTOOL.COMMMANDS.

LOGDSNALLOC

Indicates that you want Debug Tool to create the log file data set specified by EQAOPTS LOGDSN command if it does not exist. You specify the EQAOPTS LOGDSNALLOC command with the corresponding allocation parameters for the data set, which Debug Tool uses when it creates the data set.

The following diagram describes the syntax of the LOGDSNALLOC command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--LOGDSNALLOC--,--'--allocation-parms--'--,--+------+-><
                                                       '-LOUD-'
 
allocation-parms
Specifies the allocation parameters you want Debug Tool to use when it creates the data set. You can specify only the keys in the following list: Separate the keys by one or more blanks. Debug Tool does not provide defaults for any of the keys.

For information on the format of the keys, see the chapter "BPXWDYN: a text interface to dynamic allocation and dynamic output" in the z/OS Using REXX and z/OS UNIX System Services manual. Specify that the data set be sequential. To learn about other formatting rules for the log file, see "Data sets used by Debug Tool" of the Debug Tool User’s Guide.

LOUD
Specifies that Debug Tool display WTO messages, which helps you debug processing done by this command. Debug Tool normally does not display any messages when it creates this data set. If you are trying to determine why the log file was not created, specify LOUD to view any messages.

If you are implementing several EQAOPTS commands, record your selections on your copy of Table 9. Use this form to remind you of your selections so that you can implement all the EQAOPTS command at one time.

Example

EQAXOPT  LOGDSNALLOC,'MGMTCLAS(STANDARD) STORCLAS(DEFAULT)    +
         LRECL(72) BLKSIZE(0) RECFM(F,B) DSORG(PS) SPACE(2,2) +
         CYL'                                                                                             

MDBG

If you are using z/OS XL C/C++, Version 1.10 or later, you can indicate that Debug Tool always searches for .mdbg files to retrieve the source and debug information by using the MDBG command.

The following diagram describes the syntax of the MDBG command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--MDBG--,--+-YES-+-----------------------------------><
                     '-NO--'
 
YES
Indicates that Debug Tool searches for .mdbg files.
NO
Indicates that Debug Tool does not search for .mdbg files.

When you set MDBG to YES, Debug Tool retrieves the debug information from an .mdbg file and does not try to find the debug information from the following sources, even if they exist:

If you do not specify MDBG or set it to NO, Debug Tool retrieves the debug information from either the .dbg file or, if the program was compiled with the ISD compiler option, the object.

Example

EQAXOPT MDBG,YES

NAMES

The topic "Solving Problems in Complex Applications" in the Debug Tool User’s Guide describes how the NAMES command can be used to perform several specific functions dealing with load module and compile unit names recognized by Debug Tool. However, the NAMES command cannot be used to alter the behavior of load module or compile unit names that have already been seen by Debug Tool at the time the NAMES command is processed.

If it becomes necessary to perform these functions on the initial load module processed by Debug Tool or on any of the compile units contained in that load module, you must provide the information (that would otherwise have been specified using the NAMES command) through the EQAOPTS NAMES command.

One or more invocations of the EQAOPTS NAMES command can be used for this purpose.

The following diagram describes the syntax of the NAMES command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--NAMES--,--+-EXCLUDE--,--+-LOADMOD-+--,--pattern-+--><
                      |             '-CU------'             |
                      '-INCLUDE--,--+-LOADMOD-+--,--name----'
                                    '-CU------'
 

Each of these fields corresponds to the similar parameter in the Debug Tool NAMES command. If you use an asterisk (*) in pattern to indicate a wildcard, you must enclose pattern in apostrophes.

Examples

EQAXOPT NAMES,EXCLUDE,LOADMOD,'ABC1*'
EQAXOPT NAMES,EXCLUDE,CU,MYCU22
EQAXOPT NAMES,EXCLUDE,CU,'MYCU*'
EQAXOPT NAMES,INCLUDE,LOADMOD,CEEMYMOD
EQAXOPT NAMES,INCLUDE,CU,EQATESTP

NODISPLAY

In the following two situations, in which a user can request a specific user interface, that interface might not be available:

In both cases, Write To Operator (WTO) messages also appear.

You can modify these behaviors by specifying the EQAOPTS NODISPLAY command so that Debug Tool continues processing as if the user immediately entered a QUIT DEBUG command. This modification prevents any forced abend or prevents the debugger from starting.

The following diagram describes the syntax of the NODISPLAY command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--NODISPLAY--,--+-QUITDEBUG-+------------------------><
                          '-DEFAULT---'
 
DEFAULT
Debug Tool follows the default behavior.
QUITDEBUG
Debug Tool displays a message that indicates that Debug Tool will quit, and that the user interface could not be used. Debug Tool processing continues as if the user entered a QUIT DEBUG command.

Example

EQAXOPT NODISPLAY,QUITDEBUG

PREFERENCESDSN

Indicates that you want Debug Tool to read a user’s preferences file (with the name of the data set containing the preferences file determined by the specified naming pattern) each time it starts. This works in the following situation:

The following diagram describes the syntax of the PREFERENCESDSN command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--PREFERENCESDSN--,--'--file-name-pattern--'--,--+------+-><
                                                           '-LOUD-'
 
file-name-pattern
Specifies a naming pattern that determines the name of the data set that contains the preferences file. Follow these guidelines when you create the naming pattern:
LOUD
Specifies that Debug Tool display WTO messages, which helps you debug processing done by this command. Debug Tool normally does not display any messages if it does not find the data set. If you are trying to determine why Debug Tool is not processing your preferences file, specify LOUD to see if it displays any messages about not finding the data set.

If you choose to implement this option, do the following tasks:

  1. If you are implementing several EQAOPTS commands, record your selections on your copy of Table 9. Use this form to remind you of your selections so that you can implement all the EQAOPTS command at one time.
  2. Each user that wants to use this function creates the preferences file as a sequential data set with the allocation parameters described in "Data sets used by Debug Tool" of the Debug Tool User’s Guide.

Example

EQAXOPT  PREFERENCESDSN,'&&USERID.DBGTOOL.PREFS'

If you log in with user ID jsmith, Debug Tool determines the name of the data set to be JSMITH.DBGTOOL.PREFS.

SAVEBPDSN, SAVESETDSN

You can modify the default names of the data sets used to save and restore settings and breakpoints, monitor values, and LOADDEBUGDATA (LDD) specifications. The following list describes the initial default names:

To change the default name for either or both of these data sets, you need to specify the EQAOPTS SAVESETDSN and SAVEBPDSN commands, along with a corresponding naming pattern for the data set.

The following diagram describes the syntax of the SAVESETDSN and SAVEBPDSN commands:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--+-SAVEBPDSN--+--,--'--file-name-pattern--'---------><
            '-SAVESETDSN-'
 
file-name-pattern
Specifies a naming pattern for the data set that stores this information.

In most environments, you should choose one of the following rules for the naming pattern:

Examples

EQAXOPT SAVESETDSN,'CICS.DTDATA.&&USERID.SAVSET'
EQAXOPT SAVEBPDSN,'&&USERID.USERDATA.DTOOL.SAVBPMON';

SAVESETDSNALLOC, SAVEBPDSNALLOC

Indicates that you want Debug Tool to create the data sets for SAVESETS, SAVEBPS, or both (specified by EQAOPTS SAVESETDSN or SAVEBPDSN commands) if they do not exist. You specify the EQAOPTS SAVESETDSNALLOC and SAVEBPDSNALLOC commands with the corresponding allocation parameters for the data sets, which Debug Tool uses when it creates the data sets. After creating each data set, Debug Tool runs commands that save the information (settings, breakpoints, monitors, preferences, and LDD specifications) in the corresponding data set.

The following diagram describes the syntax of the SAVEBPDSNALLOC and SAVESETDSNALLOC commands:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--+-SAVEBPDSNALLOC--+--,--'--allocation-parms--'--,--+------+-><
            '-SAVESETDSNALLOC-'                                '-LOUD-'
 
allocation-parms
Specifies the allocation parameters you want Debug Tool to use when it creates the data set. You can specify only the keys in the following list: Separate the keys by one or more blanks. Debug Tool does not provide defaults for any of the keys.

For information on the format of the keys, see the chapter "BPXWDYN: a text interface to dynamic allocation and dynamic output" in the z/OS Using REXX and z/OS UNIX System Services manual. Specify that the data set be sequential for SAVESETS; a PDS or PDSE for SAVEBPS. To learn about other formatting rules for these files, see "Data sets used by Debug Tool" of the Debug Tool User’s Guide.

LOUD
Specifies that Debug Tool display WTO messages, which helps you debug processing done by this command. Debug Tool normally does not display any messages when it creates these data sets. If you are trying to determine why the data sets were not created, specify LOUD to view any messages.

Debug Tool does the following tasks when you specify these commands:

  1. If you specified the SAVESETDSNALLOC command, it creates the SAVESETS data set.
  2. If it creates the SAVESETS data set successfully, it runs the following commands:
    SET SAVE SETTINGS AUTO;
    SET RESTORES SETTINGS AUTO;

    If it did not create the SAVESETS data set successfully, it skips the rest of these steps and does the next processing task.

  3. If you specified the SAVEBPDSNALLOC command, it creates the SAVEBPS data set.
  4. If it creates the SAVEBPS data set successfully, it runs the following commands:
    SET SAVE BPS AUTO;
    SET SAVE MONITORS AUTO;
    SET RESTORE BPS AUTO;
    SET RESTORE MONITORS AUTO;

In a CICS environment, review the performance implications discussed in the "Performance considerations in multi-enclave environments" section of the "Using full-screen mode: overview" topic in the Debug Tool User’s Guide before choosing to implement the SAVEBPDSNALLOC command. If you think the performance implications might adversely affect your site, do not implement the SAVEBPDSNALLOC command in the EQAOPTS for CICS.

If you are implementing several EQAOPTS commands, record your selections on your copy of Table 9. Use this form to remind you of your selections so that you can implement all the EQAOPTS command at one time.

Example

      EQAXOPT  SAVESETDSNALLOC,'MGMTCLAS(STANDARD) STORCLAS(DEFAULT)  +
               LRECL(3204) BLKSIZE(0) RECFM(V,B) DSORG(PS) SPACE(2,2) +
               TRACKS'
      EQAXOPT  SAVEBPDSNALLOC,'MGMTCLAS(STANDARD) STORCLAS(DEFAULT)   +
               LRECL(3204) BLKSIZE(0) RECFM(V,B) DSORG(PO)            +
               DSNTYPE(LIBRARY) SPACE(1,3) CYL'

SUBSYS

If both of the following conditions apply at your site, you need to use the EQAOPTS SUBSYS command:

In this case, you must run Debug Tool and the specified subsystem on the same system.

You cannot use SUBSYS to debug programs that run under CICS.

The following diagram describes the syntax of the SUBSYS command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--SUBSYS--+------------------------------+-----------><
                    '-,--'--four-character-name--'-'
 
four-character-name
Specifies the subsystem name to be used.

Examples

EQAXOPT SUBSYS
EQAXOPT SUBSYS,'SBSX'

SVCSCREEN

In a non-CICS environment, Debug Tool requires SVC screening for the following situations:

If you need to run Debug Tool in any of the following situations, you must specify the actions that Debug Tool must take regarding SVC screening:

The following diagram describes the syntax of the SVCSCREEN command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--SVCSCREEN--,--+-ON--+--,--CONFLICT--=--------------->
                          '-OFF-'
 
>--+-OVERRIDE---+--+---------------------------------+---------><
   '-NOOVERRIDE-'  |    .-NOMERGE------------------. |
                   '-,--+-MERGE--+---------------+-+-'
                                 '-=--(--COPE--)-'
 
ON
Indicates that you want Debug Tool to use SVC screening in order to support MVS LOAD, DELETE, and LINK SVCs.
OFF
Indicates that you want Debug Tool to not use SVC screening. Debug Tool will not know about programs started through MVS LOAD, DELETE, and LINK SVCs. If you start Debug Tool by using the EQANMDBG program, the OFF setting is ignored.
CONFLICT=
Specifies what you want Debug Tool to do when ON is specified or defaulted and SVC screening is already used by another program.
OVERRIDE
Indicates that you want Debug Tool to override the current SVC screening and take control of SVC screening.
NOOVERRIDE
Indicates that if SVC screening is already in use, Debug Tool does not initiate SVC screening and proceeds as if OFF were specified.
NOMERGE
Indicates that SVC screening is not to be merged with SVC screening used by any other product. NOMERGE is the default.
MERGE
Indicates that when SVC screening is already being used by another program when Debug Tool starts, Debug Tool saves the current SVC screening environment, then enables SVC screening for both Debug Tool and the other program. When Debug Tool terminates, it restores the original SVC screening environment.

Currently, Debug Tool supports the MERGE command with only one other program: COPE.

If you specify the MERGE command and Debug Tool does not recognize the program that is using the SVC screening, the MERGE command is ignored and Debug Tool starts based on the value of the CONFLICT option.

MERGE=(COPE)
If COPE is active, Debug Tool saves the current SVC screening environment, then enables SVC screening for both Debug Tool and COPE. When Debug Tool terminates, it restores COPE's SVC screening environment.

If COPE is not active, Debug Tool starts based on the value of the CONFLICT option.

The default parameters for the EQAOPTS SVCSCREEN command is one of the following situations:

Use Table 12 as a guide to select the appropriate suboptions.

Examples

EQAXOPT SVCSCREEN,ON,CONFLICT=OVERRIDE,NOMERGE
EQAXOPT SVCSCREEN,OFF,CONFLICT=NOOVERRIDE,NOMERGE

Combinations of suboptions for the EQAOPTS SVCSCREEN command

The following table shows examples of combinations of suboptions for the EQAOPTS SVCSCREEN command:

Table 12. Combination of SVSCREEN options and their effects
SVCSCREEN options Type of Debug Tool session Action
OFF,CONFLICT=NOOVERRIDE (default) Debug Tool started by using EQANMDBG Same as for ON,CONFLICT=NOOVERRIDE.
Debug Tool started by any other method
  • Debug Tool does not enable its SVC screening.
  • You cannot debug programs that do not run in Language Environment which were started by programs that do run in Language Environment.
  • Debug Tool does not detect the MVS services LINK, LOAD and DELETE.
  • The CONFLICT setting is ignored when the OFF setting is specified.
OFF,CONFLICT=OVERRIDE Debug Tool started by using EQANMDBG Same as for ON,CONFLICT=OVERRIDE.
Debug Tool started by any other method Same as for OFF,CONFLICT=NOOVERRIDE.

The CONFLICT setting is ignored when the OFF setting is specified.

ON,CONFLICT=NOOVERRIDE Debug Tool started by using EQANMDBG If SVC screening is active, Debug Tool terminates. If SVC screening is not active, Debug Tool enables its SVC screening, runs the debugging session, and disables its SVC screening after the debugging session ends.
Debug Tool started by any other method If SVC screening is active, Debug Tool does not enable its SVC screening. You cannot debug programs that do not run in Language Environment which were started by programs that do run in Language Environment. Debug Tool does not detect the MVS services LINK, LOAD and DELETE.

If SVC screening is not active, Debug Tool enables its SVC screening, runs the debugging session, and disables its SVC screening after the debugging session ends.

ON,CONFLICT=OVERRIDE Debug Tool started by using EQANMDBG If any SVC screening is active and the NOMERGE option is in effect, Debug Tool overrides the existing SVC screening. This is also the default behavior. Debug Tool enables its SVC screening, runs the debugging session, and disables its SVC screening after the debugging session ends. If any SVC screening was active, Debug Tool restores the previous SVC screening. If you specify the MERGE option, see the following information about MERGE.
Debug Tool started by any other method

THREADTERMCOND

You can indicate that Debug Tool should not prompt the user when a FINISH, CEE066, or CEE067 thread termination condition is raised by Language Environment, regardless of the suboptions used in the TEST runtime option. These conditions are raised by statements like STOP RUN, GOBACK, or EXEC CICS RETURN, which can occur frequently in an application program. Suppressing the display of these prompts can reduce the number of times your users are interrupted by this prompt during a debugging session.

The following diagram describes the syntax of the THREADTERMCOND command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--THREADTERMCOND--,--+-NOPROMPT-+--------------------><
                               '-PROMPT---'
 
NOPROMPT
Suppress the display of termination prompts.
PROMPT
Prompts the user at termination. If you do nto specify the THREADTERMCOND command, the default PROMPT is used.

Example

EQAXOPT THREADTERMCOND,NOPROMPT

TIMACB

You can include this command only in the EQAOPTS load module. You cannot specify it at run time.

TIMACB identifies the name of an ACB, other than EQASESSM, that Debug Tool uses to make full-screen mode using a dedicated terminal with Terminal Interface Manager work in an environment where you want to run the Terminal Interface Manager on more than one LPAR in the same VTAM® network. You specify TIMACB as the last step in "Running the Terminal Interface Manager on more than one LPAR on the same VTAM network" in the Debug Tool Customization Guide.

The following diagram describes the syntax of the TIMACB command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--TIMACB--,--ACB-name--------------------------------><
 
ACB-name
The new ACB name you want used. The default name is EQASESSM.

Example

EQAXOPT TIMACB,EQASESS2

END

The END command identifies the last EQAOPTS command. You must always specify it and it must be the last command in the input stream.

The following diagram describes the syntax of the END command:

Read syntax diagramSkip visual syntax diagram>>-EQAXOPT--END------------------------------------------------><
 

Example

EQAXOPT END

2.
See "SMP/E USERMODs" in the Debug Tool Customization Guide for an SMP/E USERMOD for this customization.