Selectively excluding source code blocks

The User Language Macro Facility statements called Debugger directives let you exclude one or more blocks of source code or entire procedures, methods, or User Language routines from interactive debugging.

“Excluding” code from interactive debugging means:

The excluded code is not displayed in the Debugger Source Code tab, nor are the excluded source code lines sent from the mainframe to the client.
You may not step through or set breakpoints in the excluded code.
Excluded statements are not shown in the results of Debugger execution tracing or statement history displays.
However, the excluded code is executed normally (there is no difference in the runtime evaluation of the request), and the Janus Debugger Audit Trail and Web Buffer tabs will show output from excluded statements.

This feature is useful both for tidying your source code display (removing non-pertinent sections of code) and for decreasing the download time of source code sent from the mainframe to the Client.

The Debugger directives have the following format:

!debugger directive

Where directive may be one of the following:

exclude on exclude off exclude proc pname_or_pattern exclude routine rname_or_pattern include on include off include proc pname_or_pattern include routine rname_or_pattern

Within excluded code you can specify blocks of lines that will not be excluded and will be presented for debugging; for example, an important subroutine or method. You indicate such non-excluded blocks by Include directives.

As described in Using the code exclude feature in its normal mode, Debugger Exclude and Include directives are also implied and invoked if you use the buttons in the Exclude Parts of Programs from Debugging section on the Proc Selection page to specify lists of procedures or lists of subroutines or methods to exclude/include.

As described in Using Init Exclude mode, another approach to debugging a small block of code within a larger excluded block is to invert the way the code exclude feature operates: Instead of including all code from the beginning of the request until an Exclude directive, the "Init Exclude" variation of the feature initially excludes all code from the beginning until an Include directive. You invoke Init Exclude mode from a Client menu item or command (or mapped button or hot key).

User Language Macro Facility statements, which start with an exclamation character (!), are described in the Model 204 wiki.

Using the code exclude feature in its normal mode

In any single compilation unit (BEGIN statement to END), you may exclude as many as 300 blocks of code from debugging, and within excluded blocks, you may designate as many as 300 blocks of code that will not be excluded. A block may be a designated group of code lines or a named routine or procedure.

To exclude code:

1. Enable Debugger directives. By default, the feature is not enabled (no code is excluded from debugging).

a. From the Client File menu, select the Preferences option.

b. In the Display Options section of the Preferences dialog, select the Use !debugger directives option:

2. In your source code, specify an Exclude directive to indicate the code to be excluded from debugging:

To exclude any block of consecutive lines, indicate the beginning of the block to be excluded:

!debugger exclude on

This statement must appear between a BEGIN and END statement; it may not be used at command level.

To exclude a particular procedure, or the code that defines a method or subroutine:

- Use the appropriate keyword and case insensitive name in the directive. You can also use wildcards (described below) to form a name pattern. Also, for a method or User Language subroutine, use routine:

!debugger exclude proc MyProc*
!debugger exclude routine MyMethod

Or:

- Use the Edit Include Proc List or Edit Include Routine List buttons on the Proc Selection page to provide a list of the procedures or a list of the routines you want to exclude:

These buttons open a blank excludeProc.txt or excludeRoutine.txt file in Microsoft's Notepad or in your local editor. In the files, you specify the items you want to exclude, observing the following syntax rules:

One entry per line

Leading and trailing blanks are ignored
Case matching is insensitive
Wildcard matching using asterisk (*), question mark (?), and double quote (") is allowed (see Shortcuts for procedure names)
Blank lines are ignored
Any line starting with a number sign (#) is treated as a comment

After you Save and Exit the file(s), click the Reload Proc/Routine/Method Lists button to make the file content known to the Client. Equivalent to using this button is the reloadLists Client command.

The Use Proc Lists for exclude/include and Use Routine Lists for exclude/include checkboxes enable and suspend the feature. They are selected by default.

Note: Whether or not you select these checkboxes does not affect Debugger recognition of any !debugger directives you specify in source code outside of these lists. Such directives are controlled only by the Use !debugger directives option.

Your checkbox selections are remembered in subsequent Client sessions.

3. If excluding a block of lines (that is, not a named procedure or routine), indicate the last line to exclude.

From the exclude on directive, source code lines are excluded until the first of the following is encountered:

A !debugger exclude off statement
The end of the compilation (END statement is reached)
The end of the procedure that contains the starting exclude on directive
An Include directive (described next)

4. Indicate (with Include blocks) any lines within the excluded code that you do not want to be excluded:

If a (non-named) block of lines:

a. Specify an include on directive to indicate the beginning of a section of code you want to be included in debugging:

!debugger include on

b. Indicate the last line to include.

From the include on directive, source code lines are included for debugging until the first of the following is encountered:

A !debugger include off statement

The end of the Exclude block that contains the starting include on directive

The end of the compilation (END statement is reached)

The end of the procedure that contains the starting include on directive

If a named procedure or routine:

Specify after the Exclude directive and before the procedure or routine an include proc name_or_pattern or include routine name_or_pattern directive to indicate the code you want to be included in debugging.

Or:

Specify the procedures or routines in a list file you access via the Edit Include Proc List or Edit Include Routine List buttons on the Proc Selection page (see image and description above).

In the file, specify the items you want to include (that are located within code you are excluding).

After you save and Exit the files, click the Reload Proc/Routine/Method Lists button (or use the reloadLists command) to make the file content known to the Client.

5. Invoke and debug the code.

In place of the excluded lines, the Debugger inserts a comment to the exclude off directive in the Client Source Code display that specifies the number of lines excluded. Any lines within the excluded block that contain Include directives are also denoted. All directive statements are shown in purple text by default:

Usage notes:

If you define more than 300 Exclude blocks, or more than 300 Include blocks, an error is issued. A block may be a designated section of consecutive code lines or a named routine or procedure.
Until an exclude on directive ends, subsequent exclude on statements are ignored. This is also true for the implied exclude on created by Init Exclude mode (described in the subsection below).
A !debugger include on directive has an effect only within an Exclude block. For example:

!debugger exclude on ... lots of code that is not debugged !debugger include on ... an important subroutine that needs debugging !debugger include off ... lots more code that is not debugged !debugger exclude off

Dummy string substitution is done on !debugger directives before they are parsed and processed. This lets you build a directive conditionally.

For example:

begin trace $sirver if ($sirver >= 706) then $setg('COMMENT',) else $setg('COMMENT','*') end if end begin * Code to debug trace 'Debug me' ?&COMMENT !debugger exclude on * Code not to debug trace 'Do not debug me' ?&COMMENT !debugger exclude off end

When you compile a program that contains Exclude blocks or Exclude and Include blocks, Model 204 writes a summary of the exclusions to the Audit Trail at the end of compilation:

MS MSIR.1003: 2 Debugger Exclude block(s) defined
MS MSIR.1004: Lines 5-9 excluded from the debugger
MS MSIR.1005: Quads 24-135 excluded from the debugger
MS MSIR.1004: Lines 15-18 excluded from the debugger
MS MSIR.1005: Quads 160-271 excluded from the debugger

The Client setPreference command has options that let you toggle the Use !debugger directives, Use Proc Lists for exclude/include, and Use Routine Lists for exclude/include checkboxes.

Using Init Exclude mode

By default, starting from your program's Begin statement, the code exclude feature preserves for your debugging all the code lines that you do not explicitly exclude via directives. However, you may have cases where it would be advantageous to invert the default behavior, that is, starting from the Begin statement, to exclude all the code from debugging except the blocks you explicitly preserve via directives. "Init Exclude" mode provides such an inversion of the default.

Init Exclude mode is the equivalent of explicitly specifying !debugger exclude on immediately following your program's BEGIN statement. It changes nothing else about the operation of the code exclude feature. All program code lines are excluded from debugging until one of the following directives is encountered explicitly or is encountered implicitly via specification of an Include Proc or Include Routine list (Proc Selection tab):

!debugger include on
!debugger include proc !debugger include routine
!debugger exclude off

Subsequent code is then included until the first of one of the following:

A !debugger include off or a !debugger exclude on statement

A !debugger exclude proc or a !debugger exclude routine statement (explicit, or implicit via Proc Selection page button)

The end of the compilation (END statement is reached)

The end of the procedure that contains the starting include on directive

To invoke Init Exclude mode:

Enable Debugger directives by selecting the Use !debugger directives option from the Client File menu, Preferences option.
Do either of the following:
1. Select Toggle Init Exclude from the Client's Execution menu.
2. Select the Client button, hot key, or macro you configured to execute the toggleInitExclude command.

An Init Exclude mode is on message in the Client's Status bar as well as a checkmark next to the Toggle Init Exclude option in the Execution menu confirm that Init Exclude mode is on.

3. Run the program you want to debug.

A "!debugger exclude on set by client" comment in the code indicates that lines were excluded from the beginning of the program: