JANUSDEBUG

From m204wiki
Jump to navigation Jump to search

The JANUSDEBUG command invokes the Janus Web Server debug facility. This facility allows a Janus Web Server request to be run on the 3270 thread that issued the command, so 3270 debugging tools can be used to debug the request.

Note: The need for this facility is largely obviated by the Janus Debugger.

JANUSDEBUG can be entered as JANDEB, JANUSDEB, or JANDEBUG, and it requires no special user privileges.

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.

Overview

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 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 Janus Web 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 user ID 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)

Using JANUSDEBUG

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, programmers can run their browser requests under the same user ID that they'll be using for debugging. Then, as long as they don'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 user IDs 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 with JANUSDEBUG. A port command, that is, the CMD value on the JANUS DEFINE for a port, can be debugged with 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.

Syntax

JAN[US]DEB[UG] [IPADDR ipaddr] [PORT port] [URL url]

Where:

ipaddr The IP address from which the request to be debugged must have come.

The IP address can be an IPV4 dotted-decimal address, an IPV6 address (as of version 7.7 of Model 204), or it can be a subnet.

  • IPV4 subnets are indicated by an IP address followed by one of these:
    • A forward slash (/) followed by a netmask (with no intervening blanks)
    • A hyphen (-) followed by the number of bits in the subnet mask (with no intervening blanks)

    For example, 198.242.244.97 is a simple IP address that must be matched exactly. .198.242.244.0/255.255.255.0, which is equivalent to 198.242.244.0-24, indicates that any machine on subnet 198.242.244.0 is to be allowed access to url.

  • IPV6 addresses are 128-bit integers, represented with eight, colon-separated, 16-bit (four hex-digit) groups, which may be abbreviated and represented with fewer groups. For example, fe80:0000:0000:0000:0200:0000:0300:0016 or fe80::200:0:300:16.

    An IPV6 subnet is indicated by the first address in the range, followed by a forward slash, and a decimal value equal to the number of bits in the network prefix. A subnet that includes the example address above is: fe80::200:0/48.

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/**.

If logins are required for URLs to be debugged, an unqualified JANUSDEBUG command is usually sufficient for a programmer to be sure that the request being debugged is the one she initiated on her browser.

References

List of Janus commands