JANUSDEBUG
Overview
The JANUSDEBUG command (which can be entered as JANDEB, JANUSDEB, or JANDEBUG), allows a Janus Web Server request to be run on the 3270 thread that issued the command. JANUSDEBUG requires no special user privileges and is available in Sirius Mods version 6.0 and later.
JANUSDEBUG works in conjunction with JANUS WEB DEBUG rules -- if a JANUS WEB DEBUG rule matches a request, the request is suspended until a user issues a JANUSDEBUG command for that request. When the JANUSDEBUG command is issued for the request, these actions follow:
- The request is transferred to the user that issued the JANUSDEBUG command.
- The commands specified in the JANUS WEB ON rules are issued and run.
- The request completes, and a response is sent back to the browser.
While the request is running on the 3270 thread, any debugging tools that are available for 3270 applications such as SoftSpy, TEST DEBUG, or SSTEST can be used for the web request, though the means by which these tools are invoked might be different in a JANUSDEBUG context.
Informational messages describing the initial request and web status code for the response are sent to the 3270 terminal. Other Model 204 messages and even the text being sent to the browser can also be sent to the 3270 screen (under control of the JANDEBM user parameter described in Janus User Parameters).
If a browser should cancel a request that is waiting for a user to issue a JANUSDEBUG command, the request is immediately cleaned up and the thread is made available to process other requests. Until then, however, a request will tie up a Janus Web Server thread and an sdaemon thread. Since most browsers will wait indefinitely for a response, heavy use of JANUS WEB DEBUG rules could increase an Online's JanusWeb Server and sdaemon thread requirements. The fact that most browsers will wait indefinitely for a response while the request is being debugged becomes convenient indeed, however, as the debugging process for a request can take arbitrarily long. If the browser request is cancelled while the request is being debugged, the request will be cancelled because of the lost connection.
JANUSDEBUG can only debug these requests:
- Those run under the userid that issued the command
- Those run against a public URL (that is, running under the WEBUSER user when the JANUS WEB DEBUG rule has the PUBLIC keyword)
While it might seem useful to be able to debug PUBLIC requests, it can be quite confusing and difficult to manage in an environment where there are many programmers running against the URLs to be debugged. In such a case, unless programmers qualify their JANUSDEBUG commands with IP addresses, URLs, or PORTs, they find themselves debugging someone else's requests. For this reason, it is highly recommended that all URLs to be debugged also have ALLOW rules that force a user login, even if the URL would ultimately run as a public URL. By using this approach, a programmer can run their browser requests under the same userid that they'll be using for debugging. Then, as long as he or she doesn't request multiple URLs at the same time from a browser, they can easily debug the current request with an unqualified JANUSDEBUG (abbreviated JANDEB) command.
While it is possible to temporarily turn on debugging for a URL that is ordinarily not debugged, this can be problematic in a multiple programmer, multiple tester, or production environment because:
- If debugging is turned on for a URL, it is turned on for all requests for the URL, unless JANUS WEB DEBUG rules are issued for the specific userids for which debugging is required.
- Dynamically changing the debugging attributes of a URL requires access to the JANUS command, which ordinarily requires system manager privileges (as it should).
Consequently, it is recommended that when users of the Janus Web Server debug facility are setting up the standard JANUS WEB ON rules, they set up parallel JANUS WEB ON rules for all application URLs that might be debugged. This can be done by specifying the path /debug before the application URLs. A JANUS WEB ON rule for the URL /history/* could have a parallel JANUS WEB ON rule for URL /debug/history/*, for example. Another approach is to define a separate port to have all the same JANUS WEB ON rules as the primary port.
In any case, once the parallel JANUS WEB ON rules are set up, debugging could simply be enabled for those URLs. If the parallel ON rules use the /debug path prefix, a debug rule like the following could be issued:
JANUS WEB WEBPORT DEBUG /DEBUG/*
Or, if a debugging port is set up, the rule could simply be this:
JANUS WEB DEBUGPORT DEBUG *
With this in place, a programmer could debug an application simply by changing the URL being debugged to include the debugging prefix, or by pointing the URL at the debugging port.
In no cases can one debug a JANUS WEB ON rule that indicates SEND or RECV instead of CMD. Also, a NEWSESCMD command cannot be debugged via JANUSDEBUG. A port command, that is the CMD on the JANUS DEFINE for a port, can be debugged via JANUSDEBUG if DEBPORTCMD is specified in the port definition or if PORTCMD is specified in the JANUS WEB DEBUG rule in effect.
The files or groups that are specified in the OPEN clause of the JANUS WEB ON rule for a request being debugged are opened just as if the request were running on an sdaemon. At request completion the files and groups are automatically closed. However, if any of the files or groups specified in the OPEN clause is already open on the debugging user's thread, it is left open with the file/group privileges unchanged. This means that it is possible for a request to fail because the file or group privileges indicated in the JANUS WEB ON rule OPEN clause are different from the ones with which the debugging user has them open.
Any APSY subsystem invocation during JANUSDEBUG processing will, as with all subsystem processing, open the subsystem's required files and groups with their required privileges and close them upon exit from the subsystem. By default, files and groups specified in the OPEN clause of the JANUS DEFINE command for a port are not opened as part of JANUSDEBUG command processing. If these files or groups are required for an application, the DEBPORTOPEN command should be specified in the port definition, or PORTOPEN should be specified in the JANUS WEB DEBUG rule. Processing for files or groups opened in this way is identical to that for files or groups opened as a result of JANUS WEB ON rule processing.
JAN[US]DEB[UG] [IPADDR ipaddr] [PORT port] [URL url]
JANUSDEBUG command syntax
Where:
| ipaddr | The IP address from which the request to be debugged must have come.
The IP address could be a single IP address like 198.242.244.99, or it could be a subnet such as 198.242.244.96-27 or 198.242.244.96/255.255.255.224. The utility of subsetting by IP address is greatly reduced if all users access the application through a few proxy servers, though often it is a simple matter to tell a browser to not go through a proxy. |
|---|---|
| port | The Janus port name of the port to which the request to be debugged must
have gone. The port name can be a literal port name, or it can contain wildcards like DEBUG* or TEST?. |
| url | The URL of the request to be debugged. The URL can be a literal URL, or it
can contain wildcards like /DEBUG/HR/* or */HR/PAY/** |