Running only to listed procedures

From a large domain, you may only want to interactively debug a particular set of procedures, say the procedures for which you are responsible. “Run Until Procedure” processing lets the Debugger run through code until it reaches a procedure whose name matches a name or pattern you specified. But it may be simpler to eliminate the repeated specifying of individual names and instead to debug just the procedures specified in a list. In the Debugger, this is "White List" processing. Alternatively, it might be easier to specify in a "Black List" the procedures you do not want to debug.

To enable White or Black List processing, you:

1. Provide a file that contains either the names of the procedures to be debugged or a file that contains the names of the procedures not to be debugged.
2. Invoke the feature in the Client GUI.

Enabling and updating white or black list processing is discussed further in the following subsections:

Setting up a White or Black List file

Invoking White or Black List processing

Updating a White or Black List file

Setting up a White or Black List file

You must create a simple ASCII text file named whitelist.txt or blacklist.txt. In whitelist.txt, you list the Model 204 procedures that you want to debug; in blacklist.txt, you list those you do not want to debug. The Debugger Client will create these files for you (using Notepad, as described below). Or, you can create "manually" the file you want, in the same folder as the Debugger Client executable file (JanusDebugger.exe), using any text editor.

If you provide no whitelist.txt or blacklist.txt file, the user interface for White List or Black List invocation is disabled.

In the Debugger Client:

1. From the File menu, select Edit White List or Edit Black List (or, as mentioned below, use the Edit White List or the Edit Black List button in the White/Black List box in the Proc Selection page).

A blank Notepad whitelist.txt or blacklist.txt file is opened for you. (If such a file already exists, that file is opened.)

2. If a whitelist.txt file, specify the procedures you want to debug; if a blacklist.txt, specify those you don't want to be debugged. Note the following syntax rules:

• One entry per line
• Leading and trailing blanks are ignored
• Matching is case insensitive
• Wildcards are allowed
• Blank lines are ignored
• Any line starting with a number sign (#) is treated as a comment

Here is an example of a valid file specification:

# white list the three stooges   p.moe   p.larry   p.shemp 

3. Save and Exit the file.

Invoking White List or Black List processing

If the Debugger Client detects a valid White List or Black List file, it enables the option to turn the appropriate feature on or off.

To invoke white or black list filtering at any time (it is off by default):

1. Select the Client's Proc Selection tab.
2. If the Client was already started before you created or updated the whitelist.txt or the blacklist.txt file, click the Reload White List or Reload Black List button so the Client can detect the file. This enables the button that invokes White List or Black List processing, and it also reports the file's contents to the Client log file (log.txt).
3. In the White/Black List box in the Skip Whole Programs area, click the Turn on White List or Turn on Black List button.

Once you click the Turn on White List button, for example, White list is active displays in the Status bar, and white list filtering is enabled for the session until you turn it off by clicking the Turn off Lists button.  Your filtering selection persists over runs of the Client until you undo it.

The Client's Execution menu also has Turn On White List and Turn Off White List and Turn On Black List and Turn Off Black List options that have the same effect as the Proc Selection tab buttons.

When white or black listing is on, the Debugger filters outer procedures automatically, stopping to interactively debug only the requests that are on the white list or not on the black list. A procedure not on the white list or on the black list still executes normally, but it is not interactively debugged, and the Client's Audit Trail displays are immediately refreshed to specify that such a procedure has been "skipped."

You can also enable and disable White List or Black List processing by using the mappable Client commands that are equivalent to the above steps. The commands are turnOnWhiteList, turnOnBlackList, turnOffWhiteList, and turnOffBlackList.

Interrupting White List processing

Once White List or Black List processing is invoked, it continues in effect unless you explicitly turn it off or until you exit the Client. It is interruptible, however: the command breakOnNextProc lets you override the White List or Black List to interactively debug the next procedure.

To use a manual interrupt for White List or Black List processing:

1. Map the breakOnNextProc command to a Client button or hot key (as described in Setting up the ui.xml file) or in a macro (as described in Using Debugger macros).
2. While debugging an application where White List or Black List processing is active, invoke the button or hot key or macro.

Break on next proc set displays in the Client's Status bar to indicate the command has been successfully issued, and the next procedure included at command level (or from APSY) will be debugged, even if the active White List or Black List would normally ignore it. When this next procedure is debugged, the Audit Trail will display, for example, "White list accepted: procedure name."

The interrupt applies only to a single procedure, and you must manually invoke it again for each subsequent procedure you want to exclude from White List or Black List processing.

You cannot invoke an interrupt while debugging daemon code.

In the same way you interrupt White List or Black List processing, you can also interrupt Run Until procedure processing.

Updating a White List or Black List file

To update a White List, for example, at any time, from the Client:

1. Select either of the following two options (which let you update and save the current whitelist.txt file)

• The Edit White List button in the White List box in the Proc Selection page
• The Edit White List option of the File menu

2. On the Proc Selection page, click the Reload White List button (or execute the reloadWhiteList command).

After a successful reload, White List reloaded displays in the Status bar.

Alternatively, you can use your text editor to modify a White List or Black List file at any time, after which you click the Reload White List or the Reload Black List button on the Debugger Client Proc Selection page.

See Also

Selectively excluding source code blocks

Locating and editing procedure source files