Customize debuggerConfig file

After you install the Client, you must modify its configuration file (debuggerConfig.xml) as described below. This file is installed in the same directory as the Debugger Client executable file. It can be accessed for editing via the Client's File menu.

If you are using the Client only for the TN3270 Debugger, begin with step 5.

The configuration file contains parameters that associate the Debugger with the Model 204 online(s) whose applications you wish to debug. A template debuggerConfig.xml file is placed in your client installation target folder along with the executable for the Debugger Client (JanusDebugger.exe). The template file is annotated with XML comments which describe the contents.

Basic configuration steps

1. As supplied, debuggerConfig.xml contains a single serverList element (bounded by the <serverList> start tag and the <\serverList> end tag) that has a single server subelement. A server element defines a Janus Web Server whose User Language requests you can debug.

Provide within the serverList element a server element for each Web Server with which you want to use the Janus Debugger. Simply copy and paste the supplied server element.

For example, if you are debugging for two Web Servers, the structure of your serverList element should be like this:

<serverList>       <server>          <host></host>          <webPort></webPort>          <workerPort></workerPort>       </server>         <server>          <host></host>          <webPort></webPort>          <workerPort></workerPort>       </server> <\serverList>

2. For each server element within serverList, provide values for the three entries shown in the Field column below. You obtained the appropriate values earlier. Specify the values between the pairs of angle-bracketed tags, as shown in the Comment column below:

Field	Comment
<host></host>	The identifier of the machine that hosts the Janus Web Server application for which requests will be debugged. Either a TCP/IP host name or an IP Number may be specified. For example: <host>rocketsoftware.com</host>. Note: If you use an IP Number in this configuration file to identify a host, you must use the IP number when you reference a URL in your web browser. If you use a DNS name in this configuration file, you must also use it from the browser.
<webPort></webPort>	The port on this host that runs a Janus Web Server whose threads you want to debug. For example: <webPort>3224</webPort>.
<workerPort></workerPort>	The port on which this host provides Janus Debugger worker threads. These are the server socket threads that control the thread being debugged. They are set up as part of your Model  204 Online configuration for the Debugger. For example: <workerPort>3226</workerPort>. Note: The worker port must be defined in the same Online that runs the Web Server identified by the values for host and webPort. If you are debugging multiple Web Servers in the same Online, they may all use the same worker port.

When an incoming HTTP request is received by the Debugger Client, its host and web port are extracted and matched against those of the servers in the serverList element. This matching is case insensitive, but otherwise it must be an exact match.

If you specify an invalid value (for example, a non-numeric port number), the Client will fail to start and you will receive an "Error reading the debuggerConfig.xml" message box.

3. If a Web Server you are debugging is secured (Janus Network Security), you must direct the Debugger Client to connect to the Web Server using the Secure Sockets Layer (SSL) protocol. Add an empty ssl subelement to the appropriate server element defined in the previous step.

For example:

<server>            <host>rocketsoftware.com</host>    <webPort>3224</webPort>             <workerPort>3226</workerPort>       <ssl/>        </server>       

4. By default, when the Janus Debugger examines a web request a browser sends, it excludes URLs with the following file types from debugging:  

css	jpeg	png
gif	jpg	xsl
htc	js	xml
ico

Each such skipped URL produces a "Web request will NOT be debugged" message in the Client's audit trail.

You may replace (entirely) the default list of file types, above, with a list you specify by adding a filter element to the debuggerConfig.xml file.

In the filetype element of the filter element, you specify (without regard for case and without a leading period) only the file types that will not be debugged, and these types replace the default list.

The filetype filter applies to all web servers you debug, so the filter tag is a child of the root in the debuggerConfig.xml file. For example:

<debuggerConfig version="1.0">     <serverList>        ...     </serverList>        ...     <filter>        <filetype>jpg</filetype>       <filetype>xml</filetype>     </filter>  </debuggerConfig>

5. As discussed in the preliminary tasks, the Debugger Client requires a host workstation TCP port on which to listen during Janus Debugger or TN3270 Debugger sessions. If the default port number, 8081, is not available on your workstation, specify a suitable value for the port field in the proxy element of the debuggerConfig.xml file.

For example:

<debuggerConfig version="1.0">     <serverList>        ...     </serverList>     <proxy>       <port>8888</port>     </proxy>     <editor>        ...     </editor>        ... </debuggerConfig>

6. A log file (log.txt) that captures the Client activity is written by default in the Client installation folder. Useful for troubleshooting, the file can grow quite large. The logging element has attributes that let you control the size and retention of log files:

• The mode attribute's daily option lets you specify automatic creation of a new log file on a daily basis to prevent excessive growth of the log:

<logging>            <mode>daily</mode>    <maxDays>2</maxDays> </logging> 

If daily is set, each day's new log file is named log.txt, and the previous day's file is renamed with its date: logyyyymmdd.txt.

The default mode is single which leaves the file unmaintained, and the file will grow. You can also specify the off mode to stop further additions to the log.

• The maxDays attribute of the logging element is a positive integer that specifies the number of daily logs to retain prior to the current log.txt file. maxDays is only valid if mode is daily.

If maxDays is set to 2, for example, as many as two prior daily logs are kept in addition to log.txt.

The maxDays maximum is 99999, and the default is 100.

7. Save your changes to the debuggerConfig.xml file, then restart the Debugger Client (either select Restart from the Client's File menu, or exit and run the Client again). The changes to the debuggerConfig.xml file do not take effect until the Debugger Client is recycled.

The Client should open, ready for debugging, with information lines like the following:

For Janus Debugger sessions, the message report includes the number of Web Servers for which the Client is configured and whether the Internet Explorer browser settings, if any, will be automatically toggled by the Debugger. For TN3270 Debugger-only sessions, the highlighted message will be the same as seen earlier, reporting that the Janus Debugger is not active.

Note: Your modified debuggerConfig.xml file is not overwritten if you rerun the Debugger Client setup.exe file, for this or any subsequent versions of the Client.

Additional configuration options

The following options are separated from the preceding steps because they are not essential to an initial installation of the Debugger.

Audit Trail Control

The Debugger Client captures audit trail lines from the Model 204 Online which can be controlled using the <auditLines> tag as described in the Audit Trail Control section below.

TN3270 DEBUG WAIT Support

If you use TN3270 DEBUG WAIT, you must set up a <workers> section in the configuration as described under TN3270 DEBUG WAIT.

Alternative locations for Client files

During your debugging session, the Client stores information in various text files it creates or expects to find, by default, in the same folder as the Debugger Client executable file. If this folder location is inconvenient,  optional elements in the debuggerConfig.xml file let you specify alternative locations files. You can add these root-child elements to debuggerConfig.xml:

• <stateFileFolder> specifies where most Client work files are written (log, preferences, searches, for example)

• <macroLibraryFolder> specifies where macro files are stored

• <uiFolder> specifies where the Client UI customization settings (ui.xml, uimore.xml) are stored  

• <scriptFolder> specifies a location for scripts run with the shell command and its value is available with the &&scriptFolder function.  If not specified, it defaults to the stateFileFolder location.

 

For example:

<debuggerConfig version="1.0">    <serverList>        ...    </serverList>    ...    <stateFileFolder>c:\myData</stateFileFolder>    <uiFolder>c:\myUI</uiFolder>    <scriptFolder>C:\myScripts\python</scriptFolder>    <macroLibraryFolder>c:\myMacros</macroLibraryFolder>    ... </debuggerConfig>

For more information about the Client work files, see Changing the location of Client work files.

For information about how to specify a location for these folders from a command line, see Specifying a startup command for the Client.

Alternative locations for Debugger documentation files

During Client installation, the Debugger product documentation files (.pdf and .chm) are stored by default in the same folder as the Debugger Client executable file. To specify an alternative location for these files, you can add the manual and helpFile elements to debuggerConfig.xml:

• <manual> specifies where and with what name the Client searches for the Janus/TN3270 Debugger User Guide PDF file when you select Help Topics from the Client Help menu.

For compatibility with older Client versions, if this element is not specified, the Client searches the folder containing the .exe Debugger executable file and searches its Doc subfolder, if any.

• <helpFile> specifies where and with what name the Client searches for its Windows Help file (.chm) when you press the F1 key or select View PDF Manual from the Client Help menu.

For both elements:

• The search is not case-sensitive.
• A relative folder path is relative to the folder containing the Debugger executable file.
• An absolute path is accepted and treated as such.
• It is an error to begin a relative path with a backslash (\).
• These locations are not affected if a separate folder is designated (by startup command or configuration file setting) for Client working files.

For example, the following settings direct the Client to search for the so-named documentation files in the Doco folder:

<debuggerConfig version="1.0">     <serverList>        ...     </serverList>        ...     <manual>Doco\JDebugr.pdf</manual>     <helpFile>Doco\JDebugger.chm</helpFile>        ... </debuggerConfig> 

Font size

The font size in most Client windows is scalable by specifying a valid setting of the fontScale element. For example:

<debuggerConfig version="1.0">     <fontScale>1.33</fontScale>     <serverList>       ...    </serverList>        ... </debuggerConfig> 

Window transparency

The degree of transparency of windows is adjustable by specifying a valid setting of the opacity element (max transparency is .01; max opacity is 1; default is .9). For example:

<debuggerConfig version="1.0">     <opacity>.75</opacity>     <serverList>       ...    </serverList>        ... </debuggerConfig> 

Information URLs

The destination URL of the Model 204 Wiki link in the Debugger Client's Help menu defaults to http://m204wiki.rocketsoftware.com. If your Internet access is limited, you can override the default by specifying the wikiURL element. For example:

<debuggerConfig version="1.0">     <wikiURL>http://123.4.5.666/myM204Wiki</wikiURL>    <serverList>       ...    </serverList>       ... </debuggerConfig> 

This must be an absolute URL.

Text file editor

Many Debugger tasks entail the editing of small text files, and typically the Client opens by default the Notepad editor (notepad.exe), which is guaranteed to be present on a Windows system. You can change default editors by specifying a suitable value in the notepadReplacement element.

For example, the following defines Notepad++ (http://notepad-plus-plus.org/) as the default text editor:

<debuggerConfig>    <notepadReplacement>C:\whereItIsInstalled\notepad++.exe</notepadReplacement>

The element value must be a full operating system (DOS style) path that identifies the executable file. An eligible editor must take the file to be edited as its first command line parameter. Given the definition above, for example, and selecting the Edit debuggerConfig.xml option from the Client's File menu, directs the Client to execute the following:

C:\whereItIsInstalled\notepad++.exe debuggerConfig.xml 

Multiple Client configurations

If, for testing purposes, you want to have multiple configurations, you can specify a configuration file other than debuggerConfig.xml on the command line:

1. Open and MS DOS command line window.
2. Navigate to the Debugger installation folder (it contains JanusDebugger.exe)
3. At the command line, issue JanusDebugger myconfig. This starts the Debugger using the file specified by myconfig, instead of debuggerConfig.xml. For example:

JanusDebugger test1.xml 

If you are going to make multiple configuration files, start by cloning the debuggerConfig.xml file that is installed by default. This will save work and minimize the chance of errors.

Startup macro

A Debugger macro lets you automate a variety of Client tasks. You can invoke a macro in various ways, one of which is automatically, whenever the Client is started. To invoke such an automatic running of a macro at Client startup, you specify the macro name as the value of the startup attribute of the top level tag of the debuggerConfig.xml file. For example:

<debuggerConfig version="1.0" startup="startup.macro"> 

PAC file server

The Chrome and Internet Explorer PAC file feature requires that you provide an HTTP (Web) server to hold the PAC files. You can use any web server that supports HTTP PUT and GET. Further details and an example are provided in Setting up an HTTP server for PAC files. You specify the server location with the httpPacURL tag. For example:

<debuggerConfig version="1.0">  <httpPacURL>http://pacServerHost:pacServerPort/pacman</httpPacURL>       ... </debuggerConfig> 

Where:

• pacServerHost is the host name or IP number of the PAC web server.
• pacServerPort is the port number used by the PAC web server. It must not be the same as any port in the serverList element in debuggerConfig.xml.

• pacman is an optional qualifier in the PAC file URL. It is used in the example in "Setting up an HTTP server for PAC files" (see the JANUS WEB commands in the Janus Web Server definition).

When the Debugger Client is started, and the httpPacURL element is specified in the Client configuration, the Client validates the URL with an HTTP PUT and GET of a test file. If there is a problem with httpPacURL, an error is displayed in the Client's Audit Trail tab. For example: