Ekern at 02:21, 7 January 2023

2023-01-07T02:21:08Z

← Older revision		Revision as of 02:21, 7 January 2023
Line 62:		Line 62:
	<span class="f_CodeExList3">!debugger exclude routine MyMethod </span></p>		<span class="f_CodeExList3">!debugger exclude routine MyMethod </span></p>

	: >Or:		: Or:

	** <span id="use_proc_list" class="hmanchor"></span><span class="f_ListBul3">Use the </span><var>Edit Include Proc List</var><span class="f_ListBul3"> or </span><var>Edit Include Routine List</var><span class="f_ListBul3"> buttons on the </span><var>Proc Selection</var><span class="f_ListBul3"> page to provide a list of the procedures or a list of the routines you want to exclude: </span>		** <span id="use_proc_list" class="hmanchor"></span><span class="f_ListBul3">Use the </span><var>Edit Include Proc List</var><span class="f_ListBul3"> or </span><var>Edit Include Routine List</var><span class="f_ListBul3"> buttons on the </span><var>Proc Selection</var><span class="f_ListBul3"> page to provide a list of the procedures or a list of the routines you want to exclude: </span>

Ekern: Created page with "TOC The User Language Macro Facility statements called '''Debugger directives''' let you exclude one or more blocks of sou..."

2022-11-10T05:15:26Z

Created page with "__TOC__ The User Language Macro Facility statements called '''Debugger directives''' let you exclude one or more blocks of sou..."

New page

__TOC__
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 <var>Source Code</var> 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 <var>Audit Trail</var> and <var>Web Buffer</var> 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 [[Selectively excluding source code blocks#Using Init Exclude mode|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 <var>Exclude Parts of Programs from Debugging</var> section on the <var>Proc Selection</var> page to specify lists of procedures or lists of subroutines or methods to exclude/include. 

As described in [[Selectively excluding source code blocks#Using Init Exclude mode|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 <var>File</var> menu, select the <var>Preferences</var> option. 
: b. In the <var>Display Options</var> section of the <var>Preferences</var> dialog, select the <var>Use !debugger directives</var> option: 

[[File:preferences22i_zoom50.gif|500x343px|preferences22i]] 

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 <var>Edit Include Proc List</var> or <var>Edit Include Routine List</var> buttons on the <var>Proc Selection</var> page to provide a list of the procedures or a list of the routines you want to exclude: 

[[File:procselect4a_zoom55.gif|412x284px|procSelect4a]] 

: These buttons open a blank excludeProc.txt or excludeRoutine.txt file in Microsoft's <var>Notepad</var> or in your [[Using a local editor|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 [[Running to a specific procedure#Shortcuts for specifying procedure names |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 <var>Reload Proc/Routine/Method Lists</var> button to make the file content known to the Client. Equivalent to using this button is the [[reloadLists command|reloadLists]] Client command.
: The <var>Use Proc Lists for exclude/include</var> and <var>Use Routine Lists for exclude/include</var> 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 <var>Use !debugger directives</var> 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 e'''xclude 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 <var>Edit Include Proc List</var> or <var>Edit Include Routine List</var> buttons on the <var>Proc Selection</var> 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 <var>Reload Proc/Routine/Method Lists</var> 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 <var>Source Code</var> 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 [[Changing the colors in Client displays|by default:]] 

[[File:directives2a_zoom60.gif|526x269px|directives2a]] 


=== 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|setPreference]] command has options that let you toggle the <var>Use !debugger directives, </var> <var>Use Proc Lists for exclude/include,</var> and <var>Use Routine Lists for exclude/include</var> 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 (<var>Proc Selection</var> 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 <var>Proc Selection</var> 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 <var>Use !debugger directives</var> option from the Client <var>File</var> menu, <var>Preferences</var> option. 
# Do either of the following: 
## Select <var>Toggle Init Exclude</var> from the Client's <var>Execution</var> menu. 
## Select the Client button, hot key, or macro you [[Introducing the configurable components|configured]] to execute the [[toggleInitExclude command|toggleInitExclude]] command. 
::: An Init Exclude mode is on message in the Client's [[Status bar|Status bar]] as well as a checkmark next to the <var>Toggle Init Exclude option </var>in the <var>Execution</var> 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: 

[[File:directives3a_zoom60.gif|526x269px|directives3a]] 

To leave Init Exclude mode, you repeat step 2, above.

'''See Also:'''
: [[Running to a specific procedure|Running to a specific procedure]]
: [[Running only to listed procedures|Running only to listed procedures]]

[[Category:Debugger Home]]

Selectively excluding source code blocks - Revision history

Ekern at 02:21, 7 January 2023

Ekern: Created page with "__TOC__ The User Language Macro Facility statements called '''Debugger directives''' let you exclude one or more blocks of sou..."

Ekern: Created page with "TOC The User Language Macro Facility statements called '''Debugger directives''' let you exclude one or more blocks of sou..."