Debugger Client Beta documentation: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎New RetryHTTPPac command: avoid proxy mode for this command)
 
(63 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Introduction==
==Introduction==
This page describes any beta versions of the Janus/Tn3270 Debugger Workstation Client that
This page describes any beta versions of the Janus/TN3270 Debugger Workstation Client that
are available.
are available.  
 
==Build 63, Tag 1 Beta==
==Build 63, Tag 1 Beta==
===Run Until/White list/Black list with Daemons===
When used with Model 204 Version 7.6 and up, Build 63 performs the
procedure name matching for RUN UNTIL, White Lists and Black Lists on
DAEMONS as well as the main/master level.  Prior to this feature, matching
only occurred at the main/master level. For example RUNUNTIL ''desiredProc'' will stop
if a DAEMON includes ''desiredProc''.


===HTTP PAC File URLs===
===Run Until, White lists, Black lists with Daemons===
The Janus Debugger Client supports Proxy Auto Config (PAC) files, to
When used with Model 204 Version 7.6 and higher, Client Build 63 extends to
provide a method to control which web requests are routed through the Janus
[[Sdaemons|sdaemon]] threads the procedure-name matching for Run Until, White List, and Black List processing that formerly ran only at the main/master thread level. For example, <code>runUntil ''desiredProc''</code> now stops if a Daemon thread includes the ''desiredProc'' procedure.
Debugger Client when Internet Explorer (IE) is used.  IE references PAC files
with a URL. Prior to Build 63, only file mode URLs are supported (file:), which
requires the PAC files generated by the debugger client to be stored on the local file
system of the debugger client.  As of version 11, IE is deprecating the use of file URLs for
PAC files and wants http (http:) URLs to be used. Eventually file URLs will not be supported at
all, hence the need for this feature.


The client has been modified to upload the PAC files generated in the existing "New Pac" or "Merged Pac"  mode to
===HTTP URLs for PAC file===
an HTTP server.  It had also been modified to set the PAC URL in IE to an http style URL that points to the PAC
The Janus Debugger Client supports Proxy Auto Config (PAC) files,
that was generated and uploaded.
providing a method to control which web requests are routed through the Janus
====HTTP Server requirements/setup for PAC files====
Debugger Client when you use the Internet Explorer (IE) or Chrome browser.   
Before changing client settings you must provide an HTTP (Web) server which will hold
the PAC files
Any web server that supports HTTP PUT and GET may be used.  This
document provides an example of how to set up a Janus Web Server to handle HTTP based PAC files. Note that
the PAC files are temporary; when the client starts a new PAC is generated and uploadedThis prevents the
problem of http PAC files being out of date since they are based on workstation based configuration files which
can change at any time.


The following SOUL program takes one command line argument, a TCP/IP port number, and creates a Janus
IE and Chrome use a URL to reference PAC files. Prior to Build 63 of the Debugger Client, the Client supported only file-mode URLs (<code>file://</code>), so the PAC files it generated had to be stored on the local file system of the workstation running the Client.  As of its version 11, IE is deprecating the use of file URLs for PAC files in favor of HTTP (<code>http://</code>) URLs. Eventually file URLs will not be supported at all.
Web server for uploading and serving PAC files:
 
To provide an HTTP URL, the Client will:
<ul>
<li>Upload to an HTTP server the PAC files it generates in the existing "New Pac" or "Merged Pac" modes. </li>
 
<li>Set the PAC URL in IE or Chrome to an HTTP-style URL that points to the PAC that was generated and uploaded. </li>
</ul>
 
====Setting up an HTTP server for PAC files====
Before changing Client settings, you must provide an HTTP (Web) server to hold the PAC files. 
You can use any web server that supports HTTP PUT and GET. This document provides an example of how to set up a Janus Web Server to handle HTTP-based PAC files.
 
<p class="note"><b>Note:</b>
Note that the PAC files are temporary: when the Client starts, a new PAC is generated and uploaded. This prevents the problem of HTTP PAC files being out of date, since they are workstation-based configuration files which can change at any time. </p>
 
The following SOUL program takes one command line argument, a TCP/IP port number, and it creates a Janus Web server for uploading and serving PAC files:
<p class="code">begin
<p class="code">begin
   variables are undefined
   variables are undefined
   local subroutine closeFile(%iFile is string len 8 input)  
   local subroutine closeFile(%iFile is string len 8 input)  
       * Close the file whose name is passed. Messages surpressed.
       * Close the file whose name is passed. Messages supressed.
       %rc is float
       %rc is float
       $resetn('MSGCTL', 6, %rc)
       $resetn('MSGCTL', 6, %rc)
Line 45: Line 42:
   local function openFile(%iFile is string len 8 input) is float  
   local function openFile(%iFile is string len 8 input) is float  
       * Open the file whose name is passed and return 0 for success or  
       * Open the file whose name is passed and return 0 for success or  
       * non-zero for failure. Messages surpressed.
       * non-zero for failure. Messages supressed.
       %rc is float
       %rc is float
       $resetn('MSGCTL', 6, %rc)
       $resetn('MSGCTL', 6, %rc)
Line 91: Line 88:
   
   
   * Set up a simple Janus web server with web rules for loading
   * Set up a simple Janus web server with web rules for loading
   * serving and listing PAC files generated bythe debugger client.
   * serving and listing PAC files generated by the debugger client.
   %portName is string len 8 initial('JDPACSRV')
   %portName is string len 8 initial('JDPACSRV')
   
   
Line 116: Line 113:
   %worker:run(%workForDaemon):print
   %worker:run(%workForDaemon):print
end</p>
end</p>
Since the PAC files are temporary, the are stored in a memory file (not persistent between runs).  This also means
Since the PAC files are temporary, they are stored in an [[In-memory files|in-memory file]] (not persistent between runs) which does not need any disk files, DD cards, etc. The PAC files are stored as Model&nbsp;204 procedures. The name of a PAC file procedure created by the Client (see the following sections) is based on the IP number of the Client workstation to avoid conflicts.
that this procedure does not need any disk files, DD cards, etc. The PAC files are stored as Model 204 procedures.
The PAC file procedures created by the client (see the following sections), have names based on the IP number of the
client workstation to avoid conflicts.


====DebuggerConfig.xml changes====
====DebuggerConfig.xml changes====
Once the HTTP server is set up to accept and serve PAC files, the debugger client configuration
Once the HTTP server is set up to accept and serve PAC files, the Debugger Client configuration
must be updated to identify it.
must be updated to identify it. You do this with the new <var>httpPacURL</var> tag in the <code>debuggerConfig.xml</code> file:
<p class="code"><debuggerConfig version="1.0">
<p class="syntax"><debuggerConfig version="1.0">
     <httpPacURL>http://sirius.sirius-software.com:1217/pacman</httpPacURL></p>
     <httpPacURL>http://<span class="term">pacServerHost</span>:<span class="term">pacServerPort</span>/pacman</httpPacURL></p>
Where:
<ul>
<li><var class="term">pacServerHost</var> is the host name or IP number of the PAC Janus Web Server described above. </li>
 
<li><var class="term"> pacServerPort</var> is the port number passed to the SOUL program shown above. It must not be the same as any port being used for debugging. </li>
 
<li><code>pacman</code> is a qualifier in the PAC file URL. See the <var>JANUS WEB</var> commands in the Janus Web Server definition in the example above in [[#Setting up an HTTP server for PAC files|Setting up an HTTP server for PAC files]]. <code>pacman</code> is part of the <var>httpPacURL</var> tag specification only because <code>PACMAN</code> is specified in the <var>JANUS WEB</var> commands.</li>
</ul>
 
When the Debugger Client is started, and <code>httpPacURL</code> is specified in the configuration, the URL is validated with an HTTP PUT and GET of a test file. If there is a problem with <var>httpPacURL</var>, an error is displayed in the Client's Audit Trail tab. For example:
<p class="figure">[[File:PACerror.png|600px]] </p>


====Preferences UI changes====
====Preferences UI changes====
* File->preferences
Once the server is set up and the Client configuration includes <code>httpPacURL</code>, you enable the HTTP PAC feature through Client user preferences or through the [[#setIEMode command changes|setIEmode command]]:
* If newPac or mergedPac is selected and the configuration has been set up.
<ol>
* Preferences Section->PAC Button
<li>Start the client. </li>


====SetIeMode command changes====
<li>Select <code>File > preferences</code>. </li>
<p class="code">setIeMode {none|proxy|newPac|mergedPac} [file|http]</p>
 
<li>Select <code>newPac</code> or <code>mergedPac</code> for an IE Mode.
<p>This enables the <b>PAC Options</b> button: </p>
<p class="figure">[[File:IeOptions.png|460px]] </p></li>
 
<li>Click the <b>PAC Options</b> button.
<p>This displays the <b>PAC Options</b> dialog box: </p>
<p class="figure">[[File:PacOptions.png|460px]] </p></li>
 
<li>Select <code>file://</code> or <code>http://</code> mode for the PAC URL. </li>
</ol>
 
As an alternative to the Client GUI, you can use the <var>setIEMode</var> command, which is enhanced to support this feature.
 
====setIEMode command changes====
If you use a <var>setIEMode</var> command to invoke a PAC mode (<code>newPac</code> or <code>mergedPac</code>), specifying <code>file</code> or <code>http</code> controls the type of the PAC URL. <code>file</code> is the default:
<p class="syntax">setIEMode <span class="squareb">{</span>none<span class="squareb">|</span>proxy<span class="squareb">|</span>newPac<span class="squareb">|</span>mergedPac<span class="squareb">}</span> <span class="squareb">[</span><u>file</u><span class="squareb">|</span>http<span class="squareb">]</span></p>


====ShowIE command changes====
====ShowIE command changes====
ShowIE has been enhanced to display URL info for any PAC file in use by the debugger client.
<var>ShowIE</var> output has been enhanced (see <code><== New line</code> comments below) to display URL info for any PAC file in use by the Debugger Client. For example:  
For example:  
<p class="code">Current ie mode: mergedPac
<p class="code">Tbd</p>
Current ie settings
...Proxy flags=(5)
...Proxy server=()
...Proxy bypass=()
...Proxy autoConfigUrl=(http://''pacServerHost'':''pacServerPort''/pacman/PAC.10.111.2.82.JS)
...Raw flag byte=(05)
...Read from registry
key=(HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings)
Generated New Pac file: c:\debugger\stateFiles\debuggerInternalPac.js
Added: 54 web servers from the configuration.
Generated Pac File:
<b>pacURLMode: http  <== New line
httpPacUrl='http://''pacServerHost'':''pacServerPort''/pacman/' <== New line
httpPac upload filename: 'PAC.10.111.2.82.JS' <== New line</b></p>
 
====New retryHttpPac command====
If you have an error on the validation of the HTTP PAC server when you bring up the Client, and then you fix the HTTP server, you can issue the <var>retryHttpPac</var> command from the Client as an alternative to restarting the Client.
<p class="note"><b>Note:</b> The Client must not be in proxy mode when you issue the command. </p>


====RetryHTTPPac command====
====New &&currentPacFile function====
====&&currentPacFile function added====
The <var>&&currentPacFile</var> function returns the URL of the PAC file in use, or it returns <code>""</code> if no PAC file is in use. The URL returned could be either a <code>file:</code> or <code>http:</code> URL.
The &&currentPacFile function returns the URL of the PAC file in use or "" if none. The URL returned could bee either a file: or http: style URL.
<p class="code"><b>Command:</b> echo &&currentPacFile
<b>Macro message:</b> http://''pacServerHost'':''pacServerPort''/pacman/PAC.10.111.2.82.JS</p>


====Other new commands====
====Other new commands====
* httpPutFile
Developing and testing the HTTP URL support added these commands for general use:
* httpPutString
<ul>
* httpGet
<li><code>httpPutFile <i>file url</i></code> &mdash; Do an <code>HTTP PUT</code> file upload for the file and URL specified. </li>
 
<li><code>httpPutString <i>string url</i></code> &mdash; Do an <code>HTTP PUT</code> file upload for the string and URL specified. </li>
 
<li><code>httpGet <i>url</i></code> &mdash; Do an <code>HTTP GET</code> for the URL specified; display in Client console. </li>
</ul>

Latest revision as of 22:30, 12 June 2015

Introduction

This page describes any beta versions of the Janus/TN3270 Debugger Workstation Client that are available.

Build 63, Tag 1 Beta

Run Until, White lists, Black lists with Daemons

When used with Model 204 Version 7.6 and higher, Client Build 63 extends to sdaemon threads the procedure-name matching for Run Until, White List, and Black List processing that formerly ran only at the main/master thread level. For example, runUntil desiredProc now stops if a Daemon thread includes the desiredProc procedure.

HTTP URLs for PAC file

The Janus Debugger Client supports Proxy Auto Config (PAC) files, providing a method to control which web requests are routed through the Janus Debugger Client when you use the Internet Explorer (IE) or Chrome browser.

IE and Chrome use a URL to reference PAC files. Prior to Build 63 of the Debugger Client, the Client supported only file-mode URLs (file://), so the PAC files it generated had to be stored on the local file system of the workstation running the Client. As of its version 11, IE is deprecating the use of file URLs for PAC files in favor of HTTP (http://) URLs. Eventually file URLs will not be supported at all.

To provide an HTTP URL, the Client will:

  • Upload to an HTTP server the PAC files it generates in the existing "New Pac" or "Merged Pac" modes.
  • Set the PAC URL in IE or Chrome to an HTTP-style URL that points to the PAC that was generated and uploaded.

Setting up an HTTP server for PAC files

Before changing Client settings, you must provide an HTTP (Web) server to hold the PAC files. You can use any web server that supports HTTP PUT and GET. This document provides an example of how to set up a Janus Web Server to handle HTTP-based PAC files.

Note: Note that the PAC files are temporary: when the Client starts, a new PAC is generated and uploaded. This prevents the problem of HTTP PAC files being out of date, since they are workstation-based configuration files which can change at any time.

The following SOUL program takes one command line argument, a TCP/IP port number, and it creates a Janus Web server for uploading and serving PAC files:

begin variables are undefined local subroutine closeFile(%iFile is string len 8 input) * Close the file whose name is passed. Messages supressed. %rc is float $resetn('MSGCTL', 6, %rc) $close('FILE ' with %iFile) $resetn('MSGCTL', 0, %rc) end subroutine local function openFile(%iFile is string len 8 input) is float * Open the file whose name is passed and return 0 for success or * non-zero for failure. Messages supressed. %rc is float $resetn('MSGCTL', 6, %rc) openc file %iFile $resetn('MSGCTL', 0, %rc) return $status end function * Get and validate the command line argument: port number %args is object stringlist %args = %(system):arguments:unspace:parseLines(', ') %portNumber is float if (%args:count eq 0) then print 'No port number specified' stop elseif (%args:count > 1) then print 'Too many arguments' stop elseif (%args(1) is not like '/2-5(#)') then print 'Invalid port number' stop else %portNumber = %args(1) end if %pacRepo is string len 8 initial('JDPACREP') %worker is object daemon auto new %workForDaemon is object Stringlist auto new * See if the memory file for a PAC repository is there, if not create it if (%(local):openFile(%pacRepo) eq 0) then printText Memory file {%pacRepo} already present  %(local):closeFile(%pacRepo) else printText creating memory file {%pacRepo} text to %workForDaemon = new ALLOCATE {%pacrepo} WITH MEMORY PAGES=300 CREATE {%pacrepo} PARAMETER BSIZE=1, DSIZE=250 END OPENC {%pacrepo} IN {%pacrepo} INITIALIZE CLOSE {%pacrepo} end text %worker:run(%workForDaemon):print end if * Set up a simple Janus web server with web rules for loading * serving and listing PAC files generated by the debugger client. %portName is string len 8 initial('JDPACSRV') * Get rid of any earlier one, so this script can be rerun as needed text to %workForDaemon = new JANUS DRAIN {%portName} JANUS DELETE {%portName} end text %worker:run(%workForDaemon) * Create the server and its rules text to %workForDaemon = new * Create a web server JANUS DEFINE {%portName} {%portNumber} WEBSERV 20 TRACE 7 * Allow upload of PAC files via HTTP PUT of a URL of format /pacman/xxx.js JANUS WEB {%portName} ON PUT /PACMAN/*.JS OPEN FILE {%pacRepo} RECV *.JS BASE64 JANUS WEB {%portName} ALLOW PUT /PACMAN/*.JS * Provide HTTP GET access for URLs of format /pacman/xxx.js JANUS WEB {%portName} ON GET /PACMAN/*.JS OPEN FILE {%pacRepo} - SEND *.JS BINARY EXPIRE +0 * Start the web server JANUS START {%portName} end text %worker:run(%workForDaemon):print end

Since the PAC files are temporary, they are stored in an in-memory file (not persistent between runs) which does not need any disk files, DD cards, etc. The PAC files are stored as Model 204 procedures. The name of a PAC file procedure created by the Client (see the following sections) is based on the IP number of the Client workstation to avoid conflicts.

DebuggerConfig.xml changes

Once the HTTP server is set up to accept and serve PAC files, the Debugger Client configuration must be updated to identify it. You do this with the new httpPacURL tag in the debuggerConfig.xml file:

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

Where:

  • pacServerHost is the host name or IP number of the PAC Janus Web Server described above.
  • pacServerPort is the port number passed to the SOUL program shown above. It must not be the same as any port being used for debugging.
  • pacman is a qualifier in the PAC file URL. See the JANUS WEB commands in the Janus Web Server definition in the example above in Setting up an HTTP server for PAC files. pacman is part of the httpPacURL tag specification only because PACMAN is specified in the JANUS WEB commands.

When the Debugger Client is started, and httpPacURL is specified in the configuration, the URL is validated 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:

Preferences UI changes

Once the server is set up and the Client configuration includes httpPacURL, you enable the HTTP PAC feature through Client user preferences or through the setIEmode command:

  1. Start the client.
  2. Select File > preferences.
  3. Select newPac or mergedPac for an IE Mode.

    This enables the PAC Options button:

  4. Click the PAC Options button.

    This displays the PAC Options dialog box:

  5. Select file:// or http:// mode for the PAC URL.

As an alternative to the Client GUI, you can use the setIEMode command, which is enhanced to support this feature.

setIEMode command changes

If you use a setIEMode command to invoke a PAC mode (newPac or mergedPac), specifying file or http controls the type of the PAC URL. file is the default:

setIEMode {none|proxy|newPac|mergedPac} [file|http]

ShowIE command changes

ShowIE output has been enhanced (see <== New line comments below) to display URL info for any PAC file in use by the Debugger Client. For example:

Current ie mode: mergedPac Current ie settings ...Proxy flags=(5) ...Proxy server=() ...Proxy bypass=() ...Proxy autoConfigUrl=(http://pacServerHost:pacServerPort/pacman/PAC.10.111.2.82.JS) ...Raw flag byte=(05) ...Read from registry key=(HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings) Generated New Pac file: c:\debugger\stateFiles\debuggerInternalPac.js Added: 54 web servers from the configuration. Generated Pac File: pacURLMode: http <== New line httpPacUrl='http://pacServerHost:pacServerPort/pacman/' <== New line httpPac upload filename: 'PAC.10.111.2.82.JS' <== New line

New retryHttpPac command

If you have an error on the validation of the HTTP PAC server when you bring up the Client, and then you fix the HTTP server, you can issue the retryHttpPac command from the Client as an alternative to restarting the Client.

Note: The Client must not be in proxy mode when you issue the command.

New &&currentPacFile function

The &&currentPacFile function returns the URL of the PAC file in use, or it returns "" if no PAC file is in use. The URL returned could be either a file: or http: URL.

Command: echo &&currentPacFile Macro message: http://pacServerHost:pacServerPort/pacman/PAC.10.111.2.82.JS

Other new commands

Developing and testing the HTTP URL support added these commands for general use:

  • httpPutFile file url — Do an HTTP PUT file upload for the file and URL specified.
  • httpPutString string url — Do an HTTP PUT file upload for the string and URL specified.
  • httpGet url — Do an HTTP GET for the URL specified; display in Client console.