View source for Selectively excluding source code blocks

__TOC__
<span class="f_Para">The User Language Macro Facility statements called </span>'''Debugger directives'''<span class="f_Para"> let you exclude one or more blocks of source code or entire  procedures, methods, or User Language routines from interactive debugging. </span>

<span class="f_Para">“Excluding” code from interactive debugging means:</span>

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

<span class="f_Para">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.</span>

<span class="f_Para">The Debugger directives have the following format: </span>

<p class="syntax"><span class="f_CodeExample">!debugger </span><span class="term">directive</span><span class="f_CodeExample"> </span></p>

<span class="f_Para">Where </span><span class="term">directive</span><span class="f_Para"> may be one of the following: </span>

<p class="syntax"><span class="f_MonoBold">exclude on </span>
<span class="f_MonoBold">exclude off </span>
<span class="f_MonoBold">exclude proc </span><span class="f_MonoBoldItalic">pname_or_pattern</span><span class="f_MonoBold"> </span>
<span class="f_MonoBold">exclude routine </span><span class="f_MonoBoldItalic">rname_or_pattern</span><span class="f_MonoBold"> </span>
<span class="f_MonoBold"> </span>
<span class="f_MonoBold">include on </span>
<span class="f_MonoBold">include off </span>
<span class="f_MonoBold">include proc </span><span class="f_MonoBoldItalic">pname_or_pattern</span>
<span class="f_MonoBold">include routine </span><span class="f_MonoBoldItalic">rname_or_pattern</span><span class="f_MonoBold"> </span><span class="f_SimpleList"> </span></p>

<span class="term">Within</span><span class="f_Para"> excluded code you can specify blocks of lines that will </span><span class="f_EmphBold">not</span><span class="f_Para"> be excluded and will be presented for debugging; for example, an important subroutine or method. You indicate such non-excluded blocks by </span><span class="f_Monospace">Include</span><span class="f_Para"> directives. </span>

<span class="f_Para">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 </span><var>Exclude Parts of Programs from Debugging</var><span class="f_Para"> section on the </span><var>Proc Selection</var><span class="f_Para"> page to specify lists of procedures or lists of subroutines or methods to exclude/include. </span>

<span class="f_Para">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 &quot;Init Exclude&quot; 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).</span>

<span class="f_Para">User Language Macro Facility statements, which start with an exclamation character (!), are described in the Model  204 wiki. </span>

=== Using the code exclude feature in its normal mode ===

<span class="f_Para">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.</span>

<span class="f_Para">To exclude code: </span>

1. <span class="f_ListNum1">Enable Debugger directives. By default, the feature is not enabled (no code is excluded from debugging). </span>
: a. <span class="f_ListNum2">From the Client </span><var>File</var><span class="f_ListNum2"> menu, select the </span><var>Preferences</var><span class="f_ListNum2"> option. </span>
: b. <span class="f_ListNum2">In the </span><var>Display Options</var><span class="f_ListNum2"> section of the </span><var>Preferences</var><span class="f_ListNum2"> dialog, select the </span><var>Use !debugger directives</var><span class="f_ListNum2"> option: </span>

[[File:preferences22i_zoom50.gif|500x343px|preferences22i]]<span class="f_ListContinue2"> </span>

2. <span class="f_ListNum1">In your source code, specify an Exclude</span><span class="f_ListContinue"> directive to indicate the code to be excluded from debugging: </span>

* <span class="f_ListBul2">To exclude any block of consecutive lines, indicate the beginning of the block to be excluded: </span>

<p class="syntax"><span class="f_CodeExList2">!debugger exclude on </span></p>

: This statement must appear between a BEGIN and END statement; it may not be used at command level. </span>

* <span class="f_ListBul2">To exclude a particular procedure, or the code that defines a method or subroutine: </span>

** <span class="f_ListBul3">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 </span><span class="f_Monospace">routine</span><span class="f_ListBul3">: </span>

<p class="syntax"><span class="f_CodeExList3">!debugger exclude proc MyProc*</span><br />
<span class="f_CodeExList3">!debugger exclude routine MyMethod </span></p>

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

[[File:procselect4a_zoom55.gif|412x284px|procSelect4a]]<span class="f_ListContinue3"> </span>

: These buttons open a blank <span class="f_Monospace">excludeProc.txt</span><span class="f_ListContinue3"> or </span><span class="f_Monospace">excludeRoutine.txt</span><span class="f_ListContinue3"> file in Microsoft's </span><var>Notepad</var><span class="f_ListContinue3"> or in your [[Using a local editor|local editor]]. In the files, you specify</span><span class="f_Para"> the items you want to exclude, observing </span><span class="f_ListContinue3">the following syntax rules: </span>

* <span class="f_ListBul4">One entry per line </span>

* <span class="f_ListBul2">Leading and trailing blanks are ignored</span>
* <span class="f_ListBul2">Case matching is insensitive</span>
* <span id="wildcard" class="hmanchor"></span><span class="f_ListBul4">Wildcard matching using </span><span class="f_ListBul5">asterisk </span><span class="f_ListBul4">(*), </span><span class="f_ListBul5">question mark </span><span class="f_ListBul4">(?), and </span><span class="f_ListBul5">double quote </span><span class="f_ListBul4">(&quot;) is allowed (see [[Running to a specific procedure#Shortcuts for specifying procedure names |Shortcuts for procedure names]]) </span>
* <span class="f_ListBul3">Blank lines are ignored </span>
* <span class="f_ListBul3">Any line starting with a number sign (#) is treated as a comment </span>
: After you Save and Exit the file(s), click the <var>Reload Proc/Routine/Method Lists</var><span class="f_ListContinue3"> button to make the file content known to the Client. Equivalent to using this button is the </span><span class="f_Monospace">[[reloadLists command|reloadLists]]</span><span class="f_ListContinue3"> Client command.</span>
: The <var>Use Proc Lists for exclude/include</var><span class="f_ListContinue3"> and </span><var>Use Routine Lists for exclude/include</var><span class="f_ListContinue3"> checkboxes enable and suspend the feature. They are selected by default. </span>

'''Note:'''<span class="f_ListContinue3"> Whether or not you select these checkboxes does </span>'''not'''<span class="f_ListContinue3"> affect Debugger recognition of any !debugger directives you specify in source code outside of these lists. Such directives are controlled only by the </span><var>Use !debugger directives</var><span class="f_ListContinue3"> option.</span>
: Your checkbox selections are remembered in subsequent Client sessions.

3. <span class="f_ListNum1">If excluding a block of lines (that is, not a named procedure or routine), indicate the last line to exclude. </span>
: From the e'''xclude on''' directive, source code lines are excluded until the first of the following is encountered: 

* <span class="f_ListBul2">A </span><span class="f_MonoBold">!debugger exclude off</span><span class="f_ListBul2"> statement </span>
* <span class="f_ListBul2">The end of the compilation (END statement is reached) </span>
* <span class="f_ListBul2">The end of the procedure that contains the starting </span><span class="f_MonoBold">exclude on</span><span class="f_ListContinue"> directive</span><span class="f_ListBul2"> </span>
* <span class="f_ListBul2">An Include directive (described next)</span>

4. <span class="f_ListNum1">Indicate (with Include blocks) any lines </span><span class="term">within the excluded code</span><span class="f_ListNum1"> that you do </span>'''not'''<span class="f_ListNum1"> want to be excluded: </span>

<span class="term">If a (non-named) block of lines:</span><span class="f_ListContinue"> </span>

: a. <span class="f_ListNum2">Specify an</span><span class="f_ListContinue"> </span><span class="f_MonoBold">include on</span><span class="f_ListContinue"> directive to </span><span class="f_ListNum2">indicate the beginning of </span><span class="f_ListContinue">a section of code </span><span class="f_ListNum2">you want to be included</span><span class="f_ListContinue"> in debugging</span><span class="f_ListNum2">: </span>

<p class="syntax"><span class="f_CodeExList2">!debugger include on </span></p>

: b. <span class="f_ListNum2">Indicate the last line to include. </span>
: From the '''include on'''<span class="f_ListContinue2"> directive, source code lines are included for debugging until the first of the following is encountered: </span>

* <span class="f_ListBul3">A </span>'''!debugger include off'''<span class="f_ListBul3"> statement </span>

* <span class="f_ListBul3">The end of the Exclude block that contains the starting </span>'''include on'''<span class="f_ListContinue"> directive</span><span class="f_ListBul3"> </span>

* <span class="f_ListBul3">The end of the compilation (END statement is reached) </span>

* <span class="f_ListBul3">The end of the procedure that contains the starting </span><span class="f_MonoBold">include on</span><span class="f_ListContinue"> directive</span><span class="f_ListBul3"> </span>

<span class="term">If a named procedure or routine:</span><span class="f_ListContinue"> </span>

* <span class="f_ListContinue2">Specify after the Exclude directive and before the procedure or routine an</span><span class="f_ListBul2"> </span><span class="f_MonoBold">include proc name_or_pattern</span><span class="f_ListContinue2"> or </span><span class="f_MonoBold">include routine name_or_pattern </span><span class="f_ListBul2">directive to </span><span class="f_ListContinue2">indicate the </span><span class="f_ListBul2">code </span><span class="f_ListContinue2">you want to be included</span><span class="f_ListBul2"> in debugging. </span>

<span class="f_ListContinue">Or:</span>

* <span class="f_ListBul2">Specify the procedures or routines in a list file you access via the </span><var>Edit Include Proc List</var><span class="f_ListBul2"> or </span><var>Edit Include Routine List</var><span class="f_ListBul2"> buttons on the </span><var>Proc Selection</var><span class="f_ListBul2"> page (see image and description above).</span>
: In the file, specify the<span class="f_Para"> items you want to include (that are located within code you are excluding).</span><span class="f_ListContinue2">  </span>
: After you save and Exit the files, click the <var>Reload Proc/Routine/Method Lists</var><span class="f_ListContinue2"> button (or use the </span><span class="f_Monospace">reloadLists</span><span class="f_ListContinue2"> command) to make the file content known to the Client. </span>

5. <span class="f_ListNum1">Invoke and debug the code. </span>
: In place of the excluded lines, the Debugger inserts a comment to the <span class="f_Monospace">exclude off</span><span class="f_ListContinue"> directive in the Client </span><var>Source Code</var><span class="f_ListContinue"> 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:]] </span>

[[File:directives2a_zoom60.gif|526x269px|directives2a]]<span class="f_ListContinue">  </span>

<span id="usage-notes"></span>
=== Usage notes: ===

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

<p class="syntax"><span class="f_CodeExList">!debugger exclude on </span>
<span class="f_CodeExList">... lots of code that is not debugged</span>
<span class="f_CodeExList">  !debugger include on </span>
<span class="f_CodeExList">  ... an important subroutine that needs debugging</span>
<span class="f_CodeExList">  !debugger include off </span>
<span class="f_CodeExList">... lots more code that is not debugged</span>
<span class="f_CodeExList">!debugger exclude off  </span></p>

* <span class="f_ListBul1">Dummy string substitution is done on !debugger directives </span>'''before'''<span class="f_ListBul1"> they are parsed and processed. This lets you build a directive conditionally.</span>

<span class="f_ListContinue">For example: </span>

<p class="syntax"><span class="f_CodeExList">begin     </span>
<span class="f_CodeExList">   trace $sirver   </span>
<span class="f_CodeExList">   if ($sirver &gt;= 706) then </span>
<span class="f_CodeExList">      $setg('COMMENT','')  </span>
<span class="f_CodeExList">   else   </span>
<span class="f_CodeExList">      $setg('COMMENT','*') </span>
<span class="f_CodeExList">   end if  </span>
<span class="f_CodeExList">end  </span>
<span class="f_CodeExList">begin </span>
<span class="f_CodeExList">   * Code to debug  </span>
<span class="f_CodeExList">   trace 'Debug me'  </span>
<span class="f_CodeExList">   ?&amp;COMMENT !debugger exclude on  </span>
<span class="f_CodeExList">   * Code not to debug   </span>
<span class="f_CodeExList">   trace 'Do not debug me'  </span>
<span class="f_CodeExList">   ?&amp;COMMENT !debugger exclude off </span>
<span class="f_CodeExList">end  </span></p>

* <span class="f_ListBul1">When you compile a program that contains Exclude blocks or Exclude and Include blocks, </span><span class="f_Product">Model 204</span><span class="f_ListBul1"> writes a summary of the exclusions to the Audit Trail at the end of compilation: </span>

<p class="syntax"><span class="f_CodeExList">MS MSIR.1003: 2 Debugger Exclude block(s) defined </span><br />
<span class="f_CodeExList">MS MSIR.1004: Lines 5-9 excluded from the debugger </span><br />
<span class="f_CodeExList">MS MSIR.1005: Quads 24-135 excluded from the debugger </span><br />
<span class="f_CodeExList">MS MSIR.1004: Lines 15-18 excluded from the debugger </span><br />
<span class="f_CodeExList">MS MSIR.1005: Quads 160-271 excluded from the debugger </span></p>

* <span class="f_ListBul1">The Client </span><span class="f_Monospace">[[setPreference command|setPreference]]</span><span class="f_ListBul1"> command has options that let you toggle </span><span class="f_ListNum2">the </span><var>Use !debugger directives, </var><span class="f_ListContinue3"> </span><var>Use Proc Lists for exclude/include,</var><span class="f_ListContinue3"> and </span><var>Use Routine Lists for exclude/include</var><span class="f_ListContinue3"> checkboxes.</span><span class="f_ListBul1"> </span>

=== Using Init Exclude mode ===

<span class="f_Para">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. &quot;Init Exclude&quot; mode provides such an inversion of the default. </span>

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

<p class="syntax"><span class="f_Monospace">!debugger include on</span><br />
<span class="f_Monospace">!debugger include proc</span>

<span class="f_Monospace">!debugger include routine</span><br />
<span class="f_Monospace">!debugger exclude off</span></p>

<span class="f_Para">Subsequent code is then included until the first of one of the following: </span>

* <span class="f_ListBul1">A </span><span class="f_MonoBold">!debugger include off</span><span class="f_ListBul1"> or</span><span class="f_Para"> a </span><span class="f_MonoBold">!debugger exclude on</span><span class="f_Monospace"> </span><span class="f_ListBul1">statement  </span>

* <span class="f_ListBul1">A </span><span class="f_MonoBold">!debugger exclude proc</span><span class="f_ListBul1"> or</span><span class="f_Para"> a </span><span class="f_MonoBold">!debugger exclude routine</span><span class="f_Monospace"> </span><span class="f_ListBul1">statement  (explicit, or implicit via </span><var>Proc Selection</var><span class="f_Para"> page button</span><span class="f_ListBul1">)</span>

* <span class="f_ListBul1">The end of the compilation (END statement is reached) </span>

* <span class="f_ListBul1">The end of the procedure that contains the starting </span><span class="f_MonoBold">include on</span><span class="f_ListContinue"> </span><span class="f_ListBul1">directive </span>

<span id="to-invoke-init-exclude-mode"></span>
=== To invoke Init Exclude mode: ===

# <span class="f_ListNum1">Enable Debugger directives by selecting the </span><var>Use !debugger directives</var><span class="f_ListNum1"> option from the Client </span><var>File</var><span class="f_ListNum1"> menu, </span><var>Preferences</var><span class="f_ListNum1"> option. </span>
# <span class="f_ListNum1">Do either of the following: </span>
## <span class="f_ListBul2">Select </span><var>Toggle Init Exclude</var><span class="f_ListBul2"> from the Client's </span><var>Execution</var><span class="f_ListBul2"> menu.  </span>
## <span class="f_ListBul2">Select the Client button, hot key, or macro you [[Introducing the configurable components|configured]] to execute the <span class="f_Monospace">[[toggleInitExclude command|toggleInitExclude]] </span><span class="f_ListBul2">command. </span><br />
::: An <span class="f_Monospace">Init Exclude mode is on</span><span class="f_ListContinue"> message in the Client's [[Status bar|Status bar]] as well as </span><span class="f_ListBul2">a checkmark next to the </span><var>Toggle Init Exclude option </var><span class="f_ListContinue">in the </span><var>Execution</var><span class="f_ListBul2"> menu confirm that Init Exclude mode is on.</span></span>
: 3. <span class="f_ListNum1">Run the program you want to debug. </span>

<span class="f_ListContinue">A &quot;!debugger exclude on set by client&quot; comment in the code indicates that lines were excluded from the beginning of the program: </span>

[[File:directives3a_zoom60.gif|526x269px|directives3a]]<span class="f_ListContinue"> </span>

<span class="f_Para">To leave Init Exclude mode, you repeat step 2, above.</span>

'''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]]