Customize debuggerConfig file: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 6: Line 6:
<span class="f_Para">The configuration file contains parameters that associate the Debugger with the </span><span class="term">Model 204</span><span class="f_Para"> online(s) whose applications you wish to debug. A template </span><var>debuggerConfig.xml</var><span class="f_Para"> file is placed in your client installation target folder along with the executable for the Debugger Client (</span><var>JanusDebugger.exe</var><span class="f_Para">). The template file is annotated with XML comments which describe the contents. </span>
<span class="f_Para">The configuration file contains parameters that associate the Debugger with the </span><span class="term">Model 204</span><span class="f_Para"> online(s) whose applications you wish to debug. A template </span><var>debuggerConfig.xml</var><span class="f_Para"> file is placed in your client installation target folder along with the executable for the Debugger Client (</span><var>JanusDebugger.exe</var><span class="f_Para">). The template file is annotated with XML comments which describe the contents. </span>


<span class="f_Subhead">Basic configuration steps </span>
=== Basic configuration steps ===
 
: 1. <span id="hostserverlist" class="hmanchor"></span><span class="f_ListNum1">As supplied, debuggerConfig.xml contains a single </span><span class="f_Monospace">serverList</span><span class="f_ListNum1"> element (bounded by the </span><span class="f_Monospace">&lt;serverList&gt;</span><span class="f_ListNum1"> start tag and the </span><span class="f_Monospace">&lt;\serverList&gt;</span><span class="f_ListNum1"> end tag) that has a single </span><span class="f_Monospace">server</span><span class="f_ListNum1"> subelement. A </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element defines a Janus Web Server whose User Language requests you can debug. </span>
: 1. <span id="hostserverlist" class="hmanchor"></span><span class="f_ListNum1">As supplied, debuggerConfig.xml contains a single </span><span class="f_Monospace">serverList</span><span class="f_ListNum1"> element (bounded by the </span><span class="f_Monospace">&lt;serverList&gt;</span><span class="f_ListNum1"> start tag and the </span><span class="f_Monospace">&lt;\serverList&gt;</span><span class="f_ListNum1"> end tag) that has a single </span><span class="f_Monospace">server</span><span class="f_ListNum1"> subelement. A </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element defines a Janus Web Server whose User Language requests you can debug. </span>
 
:: Provide within the <span class="f_Monospace">serverList</span><span class="f_ListContinue"> element a </span><span class="f_Monospace">server</span><span class="f_ListContinue"> </span><span class="f_ListNum1">element</span><span class="f_ListContinue"> for each Web Server with which you want to use the </span><span class="term">Janus Debugger.</span><span class="f_ListContinue"> Simply copy and paste the supplied </span><span class="f_Monospace">server</span><span class="f_ListContinue"> </span><span class="f_ListNum1">element</span><span class="f_ListContinue">. </span>
<span class="f_ListContinue">Provide within the </span><span class="f_Monospace">serverList</span><span class="f_ListContinue"> element a </span><span class="f_Monospace">server</span><span class="f_ListContinue"> </span><span class="f_ListNum1">element</span><span class="f_ListContinue"> for each Web Server with which you want to use the </span><span class="term">Janus Debugger.</span><span class="f_ListContinue"> Simply copy and paste the supplied </span><span class="f_Monospace">server</span><span class="f_ListContinue"> </span><span class="f_ListNum1">element</span><span class="f_ListContinue">. </span>
:: For example, if you are debugging for two Web Servers, the structure of your <var>serverList</var><span class="f_ListContinue"> element should be like this: </span>
 
<span class="f_ListContinue">For example, if you are debugging for two Web Servers, the structure of your </span><span class="f_Monospace">serverList</span><span class="f_ListContinue"> element should be like this: </span>


<p class="syntax"><span class="f_CodeExList">&lt;serverList&gt;</span>
<p class="syntax"><span class="f_CodeExList">&lt;serverList&gt;</span>
Line 28: Line 25:
<span class="f_CodeExList">&lt;\serverList&gt;</span></p>
<span class="f_CodeExList">&lt;\serverList&gt;</span></p>


: 2.<span class="f_Para">For each </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element within </span><span class="f_Monospace">serverList</span><span class="f_Para">, provide </span><span class="f_ListNum1">values for the three entries shown in the </span><span class="f_Monospace">Field</span><span class="f_ListNum1"> column below. You obtained the appropriate values [[perform_preliminary_tasks.html|earlier]]. Specify the values between the pairs of angle-bracketed tags, as shown in the </span><span class="f_Monospace">Comment</span><span class="f_ListNum1"> column below: </span>
: 2. <span class="f_Para">For each </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element within </span><span class="f_Monospace">serverList</span><span class="f_Para">, provide </span><span class="f_ListNum1">values for the three entries shown in the </span><span class="f_Monospace">Field</span><span class="f_ListNum1"> column below. You obtained the appropriate values [[Perform preliminary tasks|earlier]]. Specify the values between the pairs of angle-bracketed tags, as shown in the </span><span class="f_Monospace">Comment</span><span class="f_ListNum1"> column below: </span>


<div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 24px 0 24px 30px;">
<div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 24px 0 24px 30px;">
Line 47: Line 44:
| <span class="f_DefListDDTable">&lt;workerPort&gt;&lt;/workerPort&gt; </span>
| <span class="f_DefListDDTable">&lt;workerPort&gt;&lt;/workerPort&gt; </span>
|
|
<span class="f_DefListDDTable">The port on which this host provides </span><span class="termTable">Janus Debugger</span><span class="f_DefListDDTable"> worker threads. These are the server socket threads that control the thread being debugged. They are [[def_start_server_port.html|set up]] as part of your </span><span class="termTable">Model  204</span><span class="f_DefListDDTable"> Online configuration for the Debugger. For example: </span><span class="f_MonoSpTable">&lt;workerPort&gt;3226&lt;/workerPort&gt;</span><span class="f_DefListDDTable">. </span>
<span class="f_DefListDDTable">The port on which this host provides </span><span class="termTable">Janus Debugger</span><span class="f_DefListDDTable"> worker threads. These are the server socket threads that control the thread being debugged. They are [[Define and start the Debugger Server port|set up]] as part of your </span><var>Model  204</var><span class="f_DefListDDTable"> Online configuration for the Debugger. For example: </span><span class="f_MonoSpTable">&lt;workerPort&gt;3226&lt;/workerPort&gt;</span><span class="f_DefListDDTable">. </span>


'''Note:'''<span class="f_NotesTable"> The worker port </span><span class="f_EmphBoldTable">must</span><span class="f_NotesTable"> be defined in the same Online that runs the Web Server identified by the values for </span><span class="f_MonoSpTable">host</span><span class="f_NotesTable"> and </span><span class="f_MonoSpTable">webPort</span><span class="f_NotesTable">. If you are debugging multiple Web Servers in the same Online, they may all use the same worker port. </span>
'''Note:'''<span class="f_NotesTable"> The worker port </span>'''must'''<span class="f_NotesTable"> be defined in the same Online that runs the Web Server identified by the values for </span><span class="term">host</span><span class="f_NotesTable"> and </span><span class="term">webPort</span><span class="f_NotesTable">. If you are debugging multiple Web Servers in the same Online, they may all use the same worker port. </span>
|}
|}




</div>
</div>
<span class="f_ListContinue">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 </span><span class="f_Monospace">serverList</span><span class="f_ListContinue"> element. This matching is case insensitive, but otherwise it must be an exact match. </span>
: 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 <span class="f_Monospace">serverList</span><span class="f_ListContinue"> element. This matching is case insensitive, but otherwise it must be an exact match. </span>
 
: If you specify an invalid value (for example, a non-numeric port number), the Client will fail to start and you will receive an &quot;Error reading the debuggerConfig.xml&quot; message box.
<span class="f_ListContinue">If you specify an invalid value (for example, a non-numeric port number), the Client will fail to start and you will receive an &quot;Error reading the debuggerConfig.xml&quot; message box. </span>


: 3.<span class="f_ListNum1">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 </span><span class="f_Monospace">ssl</span><span class="f_ListNum1"> subelement to the appropriate </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element defined in the previous step. </span>
: 3. <span class="f_ListNum1">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 </span><span class="f_Monospace">ssl</span><span class="f_ListNum1"> subelement to the appropriate </span><span class="f_Monospace">server</span><span class="f_ListNum1"> element defined in the previous step. </span>
 
: For example:  
<span class="f_ListContinue">For example: </span>


<p class=/syntax><span class="f_CodeExList">&lt;server&gt;        </span>
<p class="syntax"><span class="f_CodeExList">&lt;server&gt;        </span>
<span class="f_CodeExList">   &lt;host&gt;rocketsoftware.com&lt;/host&gt;</span>
<span class="f_CodeExList">   &lt;host&gt;rocketsoftware.com&lt;/host&gt;</span>
<span class="f_CodeExList">   &lt;webPort&gt;3224&lt;/webPort&gt;         </span>
<span class="f_CodeExList">   &lt;webPort&gt;3224&lt;/webPort&gt;         </span>
Line 96: Line 91:
: You may replace (entirely) the default list of file types, above, with a list you specify by adding a <span class="f_Monospace">filter</span><span class="f_ListContinue"> element to the </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListContinue"> file. </span>
: You may replace (entirely) the default list of file types, above, with a list you specify by adding a <span class="f_Monospace">filter</span><span class="f_ListContinue"> element to the </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListContinue"> file. </span>
: In the <span class="f_Monospace">filetype</span><span class="f_ListContinue"> element of the </span><var>filter</var><span class="f_ListContinue"> element, you specify (without regard for case and without a leading period) only the file types that will </span>''not''<span class="f_ListContinue"> be debugged, and these types replace the default list. </span>
: In the <span class="f_Monospace">filetype</span><span class="f_ListContinue"> element of the </span><var>filter</var><span class="f_ListContinue"> element, you specify (without regard for case and without a leading period) only the file types that will </span>''not''<span class="f_ListContinue"> be debugged, and these types replace the default list. </span>
 
: The filetype filter applies to all web servers you debug, so the <span class="f_Monospace">filter</span><span class="f_ListContinue"> tag is a child of the root in the </span><var>debuggerConfig.xml </var><span class="f_ListContinue">file. For example: </span>
<span class="f_ListContinue">The filetype filter applies to all web servers you debug, so the </span><span class="f_Monospace">filter</span><span class="f_ListContinue"> tag is a child of the root in the </span><var>debuggerConfig.xml </var><span class="f_ListContinue">file. For example: </span>


<p class="syntax"><span class="f_CodeExList">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
<p class="syntax"><span class="f_CodeExList">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
Line 110: Line 104:
<span class="f_CodeExList">&lt;/debuggerConfig&gt;</span></p>
<span class="f_CodeExList">&lt;/debuggerConfig&gt;</span></p>


: 5. <span id="client_listening_port" class="hmanchor"></span><span class="f_ListNum1">As discussed in the [[perform_preliminary_tasks.html|preliminary tasks]], the Debugger Client requires a host workstation TCP port on which to listen during </span><span class="term">Janus Debugger</span><span class="f_ListNum1"> or </span><span class="term">TN3270 Debugger</span><span class="f_ListNum1"> sessions. If the default port number, 8081, is not available on your workstation, specify a suitable value for the </span><span class="f_Monospace">port</span><span class="f_ListNum1"> field in the </span><span class="f_Monospace">proxy</span><span class="f_ListNum1"> element of the </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListNum1"> file. </span>
: 5. <span id="client_listening_port" class="hmanchor"></span><span class="f_ListNum1">As discussed in the [[Perform preliminary tasks|preliminary tasks]], the Debugger Client requires a host workstation TCP port on which to listen during </span><span class="term">Janus Debugger</span><span class="f_ListNum1"> or </span><span class="term">TN3270 Debugger</span><span class="f_ListNum1"> sessions. If the default port number, 8081, is not available on your workstation, specify a suitable value for the </span><span class="f_Monospace">port</span><span class="f_ListNum1"> field in the </span><span class="f_Monospace">proxy</span><span class="f_ListNum1"> element of the </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListNum1"> file. </span>


<span class="f_ListContinue">For example: </span>
<span class="f_ListContinue">For example: </span>
Line 136: Line 130:
<span class="f_CodeExList2">&lt;/logging&gt; </span></p>
<span class="f_CodeExList2">&lt;/logging&gt; </span></p>


: If <span class="f_Monospace">daily</span><span class="f_ListContinue2"> is set, each day's new log file is named </span><var>log.txt</var><span class="f_ListContinue2">, and the previous day's file is renamed with its date: </span><var">log</var>''yyyymmdd''<var>.txt</var><span class="f_ListContinue2">.</span>
: If <span class="f_Monospace">daily</span><span class="f_ListContinue2"> is set, each day's new log file is named </span><var>log.txt</var><span class="f_ListContinue2">, and the previous day's file is renamed with its date: </span><var>log</var>''yyyymmdd''<var>.txt</var><span class="f_ListContinue2">.</span>
 
: The default mode is <var>single</var><span class="f_ListContinue2"> which leaves the file unmaintained, and the file will grow. You can also specify the </span><var>off</var><span class="f_ListContinue2"> mode to stop further additions to the log.</span>
<span class="f_ListContinue2">The default mode is </span><var>single</var><span class="f_ListContinue2"> which leaves the file unmaintained, and the file will grow. You can also specify the </span><var>off</var><span class="f_ListContinue2"> mode to stop further additions to the log.</span>


*<span class="f_ListBul2">The </span><var>maxDays</var><span class="f_ListBul2"> attribute of the </span><var>logging</var><span class="f_ListBul2"> element is a positive integer that specifies the number of daily logs to retain prior to the current </span><var>log.txt</var><span class="f_ListBul2"> file. </span><var>maxDays</var><span class="f_ListContinue2"> is only valid if </span><var>mode</var><span class="f_ListContinue2"> is </span><var>daily</var><span class="f_ListContinue2">.</span>
*<span class="f_ListBul2">The </span><var>maxDays</var><span class="f_ListBul2"> attribute of the </span><var>logging</var><span class="f_ListBul2"> element is a positive integer that specifies the number of daily logs to retain prior to the current </span><var>log.txt</var><span class="f_ListBul2"> file. </span><var>maxDays</var><span class="f_ListContinue2"> is only valid if </span><var>mode</var><span class="f_ListContinue2"> is </span><var>daily</var><span class="f_ListContinue2">.</span>
 
:: If <var>maxDays</var><span class="f_ListBul2"> is set to 2</span><span class="f_ListContinue2">, for example, as many as two prior daily logs are kept in addition to </span><var>log.txt</var><span class="f_ListContinue2">. </span>
<span class="f_ListContinue2">If </span><var>maxDays</var><span class="f_ListBul2"> is set to 2</span><span class="f_ListContinue2">, for example, as many as two prior daily logs are kept in addition to </span><var>log.txt</var><span class="f_ListContinue2">. </span>
:: The <var>maxDays</var><span class="f_ListContinue2"> maximum is 99999, and the default is 100.</span>
 
<span class="f_ListContinue2">The </span><var>maxDays</var><span class="f_ListContinue2"> maximum is 99999, and the default is 100.</span>


: 7. <span class="f_ListNum1">Save your changes to the </span><var>debuggerConfig.xml</var><span class="f_ListNum1"> file, then restart the Debugger Client (either select </span><span class="term">Restart</span><span class="f_ListNum1"> from the Client's </span><span class="term">File</span><span class="f_ListNum1"> menu, or exit and run the Client again). The changes to the </span><var>debuggerConfig.xml</var><span class="f_ListNum1"> file do </span>'''not'''<span class="f_ListNum1"> take effect until the Debugger Client is recycled. </span>
: 7. <span class="f_ListNum1">Save your changes to the </span><var>debuggerConfig.xml</var><span class="f_ListNum1"> file, then restart the Debugger Client (either select </span><span class="term">Restart</span><span class="f_ListNum1"> from the Client's </span><span class="term">File</span><span class="f_ListNum1"> menu, or exit and run the Client again). The changes to the </span><var>debuggerConfig.xml</var><span class="f_ListNum1"> file do </span>'''not'''<span class="f_ListNum1"> take effect until the Debugger Client is recycled. </span>
:: The Client should open, ready for debugging, with information lines like the following:


<span class="f_ListContinue">The Client should open, ready for debugging, with information lines like the following: </span>
[[File:cliguinew7c1_zoom70.gif|746x351px|cliguiNew7c1]]
 
:: For </span><span class="term">Janus Debugger</span><span class="f_ListContinue"> sessions, the message report includes the [[Debugging multiple Web Servers|number of Web Servers]] for which the Client is configured and whether the Internet Explorer browser settings, if any, will be [[Configure web browser (Janus Debugger only)|automatically toggled]] by the Debugger. For </span><span class="term">TN3270 Debugger</span><span class="f_ListContinue">-only sessions, the highlighted message will be the same as seen [[Run, check, and verify the Client installation|earlier]], reporting that the </span><span class="term">Janus Debugger</span><span class="f_ListContinue"> is not active. </span>
[[File:cliguinew7c1_zoom70.gif|746x351px|cliguiNew7c1]]<span class="f_ListContinue"> </span>
 
<span class="f_ListContinue">For </span><span class="term">Janus Debugger</span><span class="f_ListContinue"> sessions, the message report includes the [[debugging_multiple_web_servers.html|number of Web Servers]] for which the Client is configured and whether the Internet Explorer browser settings, if any, will be [[configure_test_browser.html#internet_explorer|automatically toggled]] by the Debugger. For </span><span class="term">TN3270 Debugger</span><span class="f_ListContinue">-only sessions, the highlighted message will be the same as seen [[run_check_verify_install.html|earlier]], reporting that the </span><span class="term">Janus Debugger</span><span class="f_ListContinue"> is not active. </span>
 
'''Note:'''<span class="f_ListNote"> Your modified </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListNum1"> file is </span><span class="f_EmphBoldItal">not</span><span class="f_ListNum1"> overwritten if you rerun the Debugger Client setup.exe file, for this or any subsequent versions of the Client.</span><span class="f_ListNote"> </span>


<span class="f_Subhead">Additional configuration options <span id="additional_config_opts" class="hmanchor"></span></span>
'''Note:'''<span class="f_ListNote"> Your modified </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_ListNum1"> file is </span>'''not'''<span class="f_ListNum1"> overwritten if you rerun the Debugger Client setup.exe file, for this or any subsequent versions of the Client.</span><span class="f_ListNote"> </span>


=== Additional configuration options ===
<span class="f_Para">The following options are separated from the preceding steps because they are not essential to an initial installation of the Debugger. </span>
<span class="f_Para">The following options are separated from the preceding steps because they are not essential to an initial installation of the Debugger. </span>


Line 163: Line 151:


<span id="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."></span>
<span id="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."></span>
=== <span class="f_Heading3" style="font-weight: normal;">The Debugger Client captures audit trail lines from the Model 204 Online which can be controlled using the </span><span class="f_CodeExample">&lt;auditLines&gt; </span><span class="f_Heading3" style="font-weight: normal;">tag as described in the [[audit_trail_contol.html|Audit Trail Control]] section below</span><span class="f_Heading3">.</span> ===
The Debugger Client captures audit trail lines from the Model 204 Online which can be controlled using the </span><span class="f_CodeExample">&lt;auditLines&gt; </span><span class="f_Heading3" style="font-weight: normal;">tag as described in the [[Audit Trail Control (Debugger)|Audit Trail Control]] section below</span><span class="f_Heading3">.</span>


<span style="font-weight: bold; background-color: #e6e6e6;">TN3270 DEBUG WAIT Support</span>
<span style="font-weight: bold; background-color: #e6e6e6;">TN3270 DEBUG WAIT Support</span>


<span style="background-color: #ffffff;">If you use [[tn3270_debug_wait.html|TN3270 DEBUG WAIT]], you must set up a </span><span class="f_CodeExample">&lt;workers&gt;</span><span style="background-color: #ffffff;"> section in the configuration as described under [[tn3270_debug_wait.html#workers|TN3270 DEBUG WAIT]].</span>
<span style="background-color: #ffffff;">If you use [[TN3270 DEBUG WAIT|TN3270 DEBUG WAIT]], you must set up a </span><span class="f_CodeExample">&lt;workers&gt;</span><span style="background-color: #ffffff;"> section in the configuration as described under [[TN3270 DEBUG WAIT|TN3270 DEBUG WAIT]].</span>


<span id="alternative-locations-for-client-files"></span>
<span id="alternative-locations-for-client-files"></span>
=== <span class="f_Heading3">Alternative locations for Client files<span id="workfile_cfg" class="hmanchor"></span> </span> ===
=== Alternative locations for Client files ===


<span class="f_Para">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 </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para"> file let you specify alternative locations files. You can add these root-child elements to </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para">: </span>
<span class="f_Para">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 </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para"> file let you specify alternative locations files. You can add these root-child elements to </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para">: </span>
Line 180: Line 168:
*<span class="f_MonoBold">&lt;uiFolder&gt;</span><span class="f_ListBul2"> specifies where the Client UI customization settings (ui.xml, uimore.xml) are stored</span><span class="f_ListBul1">  </span>
*<span class="f_MonoBold">&lt;uiFolder&gt;</span><span class="f_ListBul2"> specifies where the Client UI customization settings (ui.xml, uimore.xml) are stored</span><span class="f_ListBul1">  </span>


*<span id="scriptfolder" class="hmanchor"></span><span class="f_MonoBold">&lt;scriptFolder&gt;</span><span class="f_ListBul2"> specifies a location for scripts run with the [[shellcommand.html|shell]] command and its value is available with the [[scriptfolder_function.html|&amp;&amp;scriptFolder]] function.</span><span class="f_ListBul1">  If not specified, it defaults to the stateFileFolder location.</span>
*<span id="scriptfolder" class="hmanchor"></span><span class="f_MonoBold">&lt;scriptFolder&gt;</span><span class="f_ListBul2"> specifies a location for scripts run with the [[Shell command|shell]] command and its value is available with the [[&&scriptFolder|&amp;&amp;scriptFolder]] function.</span><span class="f_ListBul1">  If not specified, it defaults to the stateFileFolder location.</span>


 
 
Line 186: Line 174:
<span class="f_Para">For example: </span>
<span class="f_Para">For example: </span>


<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
<p class="syntax"><span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">    &lt;serverList&gt;</span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">    &lt;serverList&gt;</span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">        ...</span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">        ...</span>
Line 200: Line 188:
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">    ...</span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">    ...</span>


<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExList" style="font-size: 16px; font-weight: bold;">&lt;/debuggerConfig&gt; </span></p>


<span class="f_Para">For more information about the Client work files, see [[change_location_client_work.html|Changing the location of Client work files.]] </span>
<span class="f_Para">For more information about the Client work files, see [[Changing the location of Client work files|Changing the location of Client work files.]] </span>


<span class="f_Para">For information about how to specify a location for these folders from a command line, see [[spec_start_command_for_client.html|Specifying a startup command for the Client.]] </span>
<span class="f_Para">For information about how to specify a location for these folders from a command line, see [[Specifying a startup command for the Client|Specifying a startup command for the Client.]] </span>


<span id="alternative-locations-for-debugger-documentation-files"></span>
<span id="alternative-locations-for-debugger-documentation-files"></span>
=== <span class="f_Heading3">Alternative locations for Debugger documentation files<span id="docfile_cfg" class="hmanchor"></span> </span> ===
=== Alternative locations for Debugger documentation files ===
 
<span class="f_Para">During Client installation, the Debugger product documentation files (</span><span class="f_Monospace">.pdf</span><span class="f_Para"> and </span><span class="f_Monospace">.chm</span><span class="f_Para">) 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 </span><span class="f_Monospace">manual</span><span class="f_Para"> and </span><span class="f_Monospace">helpFile</span><span class="f_Para"> elements to </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para">:</span>
 
*<span class="f_MonoBold">&lt;manual&gt;</span><span class="f_ListBul1"> </span><span class="f_ListBul2">specifies where and with what name the Client searches for t</span><span class="f_DefListDD">he </span><span class="f_EmphItal">Janus/TN3270 Debugger User Guide</span><span class="f_ListBul2"> PDF file </span><span class="f_DefListDD">when you select </span><span class="f_GUIlabel">Help Topics</span><span class="f_DefListDD"> from the Client </span><span class="f_GUIlabel">Help</span><span class="f_DefListDD"> menu.</span><span class="f_ListBul2"> </span>


<span class="f_ListContinue">For compatibility with older Client versions, if this element is not specified, the Client searches the folder containing the </span><span class="f_Monospace">.exe</span><span class="f_ListContinue"> Debugger executable file</span><span class="f_ListBul1"> and searches its </span><span class="f_Monospace">Doc</span><span class="f_ListBul1"> subfolder, if any.</span>
<span class="f_Para">During Client installation, the Debugger product documentation files (</span><span class="f_Monospace">.pdf</span><span class="f_Para"> and </span><span class="term">.chm</span><span class="f_Para">) 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 </span><span class="f_Monospace">manual</span><span class="f_Para"> and </span><var>helpFile</var><span class="f_Para"> elements to </span><span class="term">debuggerConfig.xml</span><span class="f_Para">:</span>


*<span class="f_MonoBold">&lt;helpFile&gt;</span><span class="f_ListBul1"> specifies where</span><span class="f_ListBul2"> and with what name</span><span class="f_ListBul1"> </span><span class="f_ListBul2">the Client searches for its Windows</span><span class="f_DefListDD"> Help file </span><span class="f_Monospace">(.chm)</span><span class="f_DefListDD"> when you press the F1 key or select </span><span class="f_GUIlabel">View PDF Manual </span><span class="f_DefListDD">from the Client </span><span class="f_GUIlabel">Help</span><span class="f_DefListDD"> menu.</span>
*<span class="f_MonoBold">'''&lt;manual&gt;'''</span><span class="f_ListBul1"> </span><span class="f_ListBul2">specifies where and with what name the Client searches for t</span><span class="f_DefListDD">he </span><span class="term">Janus/TN3270 Debugger User Guide</span><span class="f_ListBul2"> PDF file </span><span class="f_DefListDD">when you select </span><var>Help Topics</var><span class="f_DefListDD"> from the Client </span><var>Help</var><span class="f_DefListDD"> menu.</span><span class="f_ListBul2"> </span>
: For compatibility with older Client versions, if this element is not specified, the Client searches the folder containing the <span class="term">.exe</span><span class="f_ListContinue"> Debugger executable file</span><span class="f_ListBul1"> and searches its </span><span class="f_Monospace">Doc</span><span class="f_ListBul1"> subfolder, if any.</span>


<span class="f_ListContinue">For both elements: </span>
*<span class="f_MonoBold">'''&lt;helpFile&gt;'''</span><span class="f_ListBul1"> specifies where</span><span class="f_ListBul2"> and with what name</span><span class="f_ListBul1"> </span><span class="f_ListBul2">the Client searches for its Windows</span><span class="f_DefListDD"> Help file </span><span class="term">(.chm)</span><span class="f_DefListDD"> when you press the F1 key or select </span><var>View PDF Manual </var><span class="f_DefListDD">from the Client </span><var>Help</var><span class="f_DefListDD"> menu.</span>


*<span class="f_ListBul1">The search is </span><span class="f_EmphItal">not</span><span class="f_ListBul1"> case-sensitive. </span>
: For both elements:


*<span class="f_ListBul1">The search is </span><span class="term">not</span><span class="f_ListBul1"> case-sensitive. </span>
*<span class="f_ListBul1">A relative folder path is relative to the folder containing the Debugger executable file. </span>
*<span class="f_ListBul1">A relative folder path is relative to the folder containing the Debugger executable file. </span>
*<span class="f_ListBul1">An absolute path is accepted and treated as such.</span>
*<span class="f_ListBul1">An absolute path is accepted and treated as such.</span>
*<span class="f_ListBul1">It is an error to begin a relative path with a backslash (</span><span class="f_Monospace">\</span><span class="f_ListBul1">).</span>
*<span class="f_ListBul1">It is an error to begin a relative path with a backslash (</span><span class="f_Monospace">\</span><span class="f_ListBul1">).</span>
*<span class="f_ListBul1">These locations are </span><span class="term">not</span><span class="f_ListBul1"> affected if a separate folder is designated (by [[Specifying a startup command for the Client|startup command]] or [[Customize debuggerConfig file#Alternative locations for Debugger documentation files|configuration file setting]]) for Client working files. </span>


*<span class="f_ListBul1">These locations are </span><span class="f_EmphItal">not</span><span class="f_ListBul1"> affected if a separate folder is designated (by [[spec_start_command_for_client.html|startup command]] or [[customize_debugger_cfg_file.html#workfile_cfg|configuration file setting]]) for Client working files. </span>
<span class="f_Para">For example, the following settings direct the Client to search for the so-named documentation files in the </span><span class="term">Doco</span><span class="f_Para"> folder: </span>
 
<span class="f_Para">For example, the following settings direct the Client to search for the so-named documentation files in the </span><span class="f_Monospace">Doco</span><span class="f_Para"> folder: </span>


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
<p class="syntax"><span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt;</span>
<span class="f_CodeExample">    &lt;serverList&gt;</span>
<span class="f_CodeExample">    &lt;serverList&gt;</span>
<span class="f_CodeExample">       ...</span>
<span class="f_CodeExample">       ...</span>
Line 239: Line 222:
<span class="f_EmphRedMono">    &lt;helpFile&gt;Doco\JDebugger.chm&lt;/helpFile&gt;</span>
<span class="f_EmphRedMono">    &lt;helpFile&gt;Doco\JDebugger.chm&lt;/helpFile&gt;</span>
<span class="f_CodeExample">       ...</span>
<span class="f_CodeExample">       ...</span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span></p>


<span id="font-size"></span>
<span id="font-size"></span>
=== <span class="f_Heading3">Font size <span id="config_fontsize" class="hmanchor"></span></span> ===
=== Font size ===
 
<span class="f_Para">The font size in most Client windows is [[Changing the font size in Client displays|scalable]] by specifying a valid setting of the </span><var>fontScale</var><span class="f_Para"> element. For example: </span>
<span class="f_Para">The font size in most Client windows is [[changing_font_size_in_client.html|scalable]] by specifying a valid setting of the </span><span class="f_Monospace">fontScale</span><span class="f_Para"> element. For example: </span>


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<p class="syntax"><span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<span class="f_CodeExample">   </span><span class="f_EmphRedMono">&lt;fontScale&gt;1.33&lt;/fontScale&gt;</span><span class="f_CodeExample"> </span>
<span class="f_CodeExample">   </span><span class="f_EmphRedMono">&lt;fontScale&gt;1.33&lt;/fontScale&gt;</span><span class="f_CodeExample"> </span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
Line 252: Line 234:
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span></p>


<span id="window-transparency"></span>
<span id="window-transparency"></span>
=== <span class="f_Heading3">Window transparency <span id="config_opacity" class="hmanchor"></span></span> ===
=== Window transparency ===


<span class="f_Para">The degree of transparency of windows is adjustable</span><span class="f_ListBul1"> </span><span class="f_Para">by specifying a valid setting of the </span><span class="f_Monospace">opacity</span><span class="f_Para"> element (max transparency is .01; max opacity is 1; default is .9). For example: </span>
<span class="f_Para">The degree of transparency of windows is adjustable</span><span class="f_ListBul1"> </span><span class="f_Para">by specifying a valid setting of the </span><span class="f_Monospace">opacity</span><span class="f_Para"> element (max transparency is .01; max opacity is 1; default is .9). For example: </span>


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<p class="syntax"><span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<span class="f_CodeExample">   </span><span class="f_EmphRedMono">&lt;opacity&gt;.75&lt;/opacity&gt;</span><span class="f_CodeExample"> </span>
<span class="f_CodeExample">   </span><span class="f_EmphRedMono">&lt;opacity&gt;.75&lt;/opacity&gt;</span><span class="f_CodeExample"> </span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
Line 265: Line 247:
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span></p>


<span id="information-urls"></span>
<span id="information-urls"></span>
=== <span class="f_Heading3">Information URLs<span id="siriusdoc_url" class="hmanchor"></span></span> ===
=== Information URLs ===


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


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<p class="syntax"><span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<span class="f_EmphRedMono">   &lt;wikiURL&gt;http://123.4.5.666/myM204Wiki&lt;/wikiURL&gt;</span>
<span class="f_EmphRedMono">   &lt;wikiURL&gt;http://123.4.5.666/myM204Wiki&lt;/wikiURL&gt;</span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
<span class="f_CodeExample">   &lt;serverList&gt;</span>
Line 278: Line 260:
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">   &lt;/serverList&gt; </span>
<span class="f_CodeExample">     ...</span>
<span class="f_CodeExample">     ...</span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span></p>


<span class="f_Para">This must be an absolute URL. </span>
<span class="f_Para">This must be an absolute URL. </span>


<span class="f_Heading3">Text file editor<span id="texteditor" class="hmanchor"></span></span>
=== Text file editor ===


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


<span class="f_Para">For example, the following defines </span><span class="term">Notepad++</span><span class="f_Para"> (http://notepad-plus-plus.org/) as the default text editor: </span>
<span class="f_Para">For example, the following defines </span><span class="term">Notepad++</span><span class="f_Para"> (http://notepad-plus-plus.org/) as the default text editor: </span>


<span class="f_CodeExample" style="font-size: 13px; font-weight: bold;">&lt;debuggerConfig&gt;</span><span class="f_CodeExample" style="font-size: 13px;"> </span>
<p class="syntax"><span class="f_CodeExample" style="font-size: 13px; font-weight: bold;">&lt;debuggerConfig&gt;</span><span class="f_CodeExample" style="font-size: 13px;"> </span>
<span class="f_EmphRedMonoSmall">    &lt;notepadReplacement&gt;C:\</span><span class="f_EmphRedMonoSmall" style="font-style: italic;">whereItIsInstalled</span><span class="f_EmphRedMonoSmall">\notepad++.exe&lt;/notepadReplacement&gt;</span>
<span class="f_EmphRedMonoSmall">    &lt;notepadReplacement&gt;C:\</span><span class="f_EmphRedMonoSmall" style="font-style: italic;">whereItIsInstalled</span><span class="f_EmphRedMonoSmall">\notepad++.exe&lt;/notepadReplacement&gt;</span></p>


<span class="f_Para">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 </span><span class="f_GUIlabel">Edit debuggerConfig.xml</span><span class="f_Para"> option from the Client's </span><span class="f_GUIlabel">File</span><span class="f_Para"> menu, directs the Client to execute the following: </span>
<span class="f_Para">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 </span><span class="term">Edit debuggerConfig.xml</span><span class="f_Para"> option from the Client's </span><span class="term">File</span><span class="f_Para"> menu, directs the Client to execute the following: </span>


<span class="f_CodeExample">C:\</span><span class="f_CodeExample" style="font-style: italic;">whereItIsInstalled</span><span class="f_CodeExample">\notepad++.exe debuggerConfig.xml </span>
<p class="syntax"><span class="f_CodeExample">C:\</span><span class="f_CodeExample" style="font-style: italic;">whereItIsInstalled</span><span class="f_CodeExample">\notepad++.exe debuggerConfig.xml </span></p>


<span id="multiple-client-configurations"></span>
<span id="multiple-client-configurations"></span>
=== <span class="f_Heading3">Multiple Client configurations </span> ===
=== Multiple Client configurations ===
 
<span class="f_Para">If, for testing purposes, you want to have multiple configurations, you can specify a configuration file other than </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para"> on the command line: </span>
<span class="f_Para">If, for testing purposes, you want to have multiple configurations, you can specify a configuration file other than </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para"> on the command line: </span>


# Open and MS DOS command line window.
# Open and MS DOS command line window.
# Navigate to the Debugger installation folder (it contains <span class="f_CodeExList">JanusDebugger.exe)
# Navigate to the Debugger installation folder (it contains <span class="f_CodeExList">JanusDebugger.exe)
# At the command line, issue <span class="f_Monospace">JanusDebugger </span><span class="f_MonoItal">myconfig</span><span class="f_ListNum1">. This starts the Debugger using the file specified by </span><span class="f_MonoItal">myconfig</span><span class="f_ListNum1">, instead of </span><span class="f_CodeExList">debuggerConfig.xml</span><span class="f_ListNum1">. For example: </span>
# At the command line, issue <span class="f_Monospace">JanusDebugger </span><span class="term">myconfig</span><span class="f_ListNum1">. This starts the Debugger using the file specified by </span><span class="term">myconfig</span><span class="f_ListNum1">, instead of </span><span class="term">debuggerConfig.xml</span><span class="f_ListNum1">. For example: </span>


<span class="f_CodeExList">JanusDebugger test1.xml </span>
<p class="syntax">JanusDebugger test1.xml </p>


<span class="f_Para">If you are going to make multiple configuration files, start by cloning the </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para"> file that is installed by default. This will save work and minimize the chance of errors. </span>
<span class="f_Para">If you are going to make multiple configuration files, start by cloning the </span><span class="term">debuggerConfig.xml</span><span class="f_Para"> file that is installed by default. This will save work and minimize the chance of errors. </span>


<span id="startup-macro"></span>
<span id="startup-macro"></span>
=== <span class="f_Heading3">Startup macro <span id="startup_macro" class="hmanchor"></span> </span> ===
=== Startup macro ===
 
<span class="f_Para">A Debugger [[Using Debugger Macros|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 </span><span class="f_Monospace">startup</span><span class="f_Para"> attribute of the top level tag of the </span><span class="f_CodeExList">debuggerConfig.xml</span><span class="f_Para"> file. For example: </span>
<span class="f_Para">A Debugger [[using_debugger_macros.html|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 </span><span class="f_Monospace">startup</span><span class="f_Para"> attribute of the top level tag of the </span><span class="f_CodeExList">debuggerConfig.xml</span><span class="f_Para"> file. For example: </span>


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot; startup=&quot;startup.macro&quot;&gt; </span>
<p class="syntax">&lt;debuggerConfig version=&quot;1.0&quot; startup=&quot;startup.macro&quot;&gt; </p>


<span id="pac-file-server"></span>
<span id="pac-file-server"></span>
=== <span class="f_Heading3">PAC file server<span id="pacfile_server" class="hmanchor"></span> </span> ===
=== PAC file server ===
 
<span class="f_EndTopic">The Chrome and Internet Explorer [[Configure web browser (Janus Debugger only)#pacfile|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 [[Configure web browser (Janus Debugger only)#setup_http_server|Setting up an HTTP server for PAC files]]. You specify the server location with the </span><span class="f_Monospace">httpPacURL</span><span class="f_EndTopic"> tag. For example:</span>
<span class="f_EndTopic">The Chrome and Internet Explorer [[configure_test_browser.html#pacfile|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 [[configure_test_browser.html#setup_http_server|Setting up an HTTP server for PAC files]]. You specify the server location with the </span><span class="f_Monospace">httpPacURL</span><span class="f_EndTopic"> tag. For example:</span>


<span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<p class="syntax"><span class="f_CodeExample">&lt;debuggerConfig version=&quot;1.0&quot;&gt; </span>
<span class="f_CodeExample">&lt;httpPacURL&gt;http://</span><span class="f_CodeExample" style="font-style: italic;">pacServerHost</span><span class="f_CodeExample">:</span><span class="f_CodeExample" style="font-style: italic;">pacServerPort</span><span class="f_CodeExample">/pacman&lt;/httpPacURL&gt;</span>
<span class="f_CodeExample">&lt;httpPacURL&gt;http://</span><span class="f_CodeExample" style="font-style: italic;">pacServerHost</span><span class="f_CodeExample">:</span><span class="f_CodeExample" style="font-style: italic;">pacServerPort</span><span class="f_CodeExample">/pacman&lt;/httpPacURL&gt;</span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">      ...</span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span>
<span class="f_CodeExample">&lt;/debuggerConfig&gt; </span></p>


<span class="f_Para">Where:</span>
<span class="f_Para">Where:</span>
 
*<span class="term">pacServerHost</span><span class="f_ListBul1"> is the host name or IP number of the PAC web server. </span>
*<span class="f_EmphItal">pacServerHost</span><span class="f_ListBul1"> is the host name or IP number of the PAC web server. </span>
*<span class="term">pacServerPort</span><span class="f_Para"> is the port number used by </span><span class="f_ListBul1">the PAC web server.</span><span class="f_Para"> It must </span>'''not'''<span class="f_Para"> be the same as any port in the</span><span class="f_ListContinue"> </span><span class="f_Monospace">serverList</span><span class="f_ListContinue"> element in </span><span class="term">debuggerConfig.xml</span><span class="f_Para">. </span>
 
*<span class="f_EmphItal">pacServerPort</span><span class="f_Para"> is the port number used by </span><span class="f_ListBul1">the PAC web server.</span><span class="f_Para"> It must </span><span class="f_EmphBold">not</span><span class="f_Para"> be the same as any port in the</span><span class="f_ListContinue"> </span><span class="f_Monospace">serverList</span><span class="f_ListContinue"> element in </span><span class="f_Monospace">debuggerConfig.xml</span><span class="f_Para">. </span>


*<span class="f_ListBul1">pacman is an optional qualifier in the PAC file URL. It is used in the example in &quot;Setting up an HTTP server for PAC files&quot; (see the JANUS WEB commands in the Janus Web Server definition). </span>
*<span class="f_ListBul1">pacman is an optional qualifier in the PAC file URL. It is used in the example in &quot;Setting up an HTTP server for PAC files&quot; (see the JANUS WEB commands in the Janus Web Server definition). </span>


<span class="f_Para">When the Debugger Client is started, and the </span><span class="f_Monospace">httpPacURL</span><span class="f_Para"> 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 </span><span class="f_Monospace">httpPacURL</span><span class="f_Para">, an error is displayed in the Client's </span><span class="f_GUIlabel">Audit Trail</span><span class="f_Para"> tab. For example: </span>
<span class="f_Para">When the Debugger Client is started, and the </span><span class="f_Monospace">httpPacURL</span><span class="f_Para"> 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 </span><span class="f_Monospace">httpPacURL</span><span class="f_Para">, an error is displayed in the Client's </span><span class="term">Audit Trail</span><span class="f_Para"> tab. For example: </span>


[[File:pacerror.png|431x106px|PACerror]]<span class="f_Para"> </span>
[[File:pacerror.png|431x106px|PACerror]]


[[Catgory:Debugger Home]]
[[Category:Debugger Home]]

Latest revision as of 20:38, 7 April 2023

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:

cliguiNew7c1

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:

PACerror