|
|
SAS/IntrNet 8.2: Application Dispatcher |
|
The special variable _DEBUG provides you with several diagnostic options. Using this variable is a convenient way to debug a problem, because you can supply the debug values by using the Web browser to modify your HTML or by editing the URL in your browser location field.
You can activate the various debugging options by passing the _DEBUG variable to the Broker just as you pass the special variables _SERVICE and _PROGRAM. You can set more than one debug option by adding the flag values together. For example, to set both the options 256 and 4, use the value (256 + 4) = 260. Some flags may be locked out at your site in the Broker configuration file for security reasons. Verify with your administrator which flags are locked out at your site. See Setting the Default Value of _DEBUG for more information on setting the debug value. The following chart is a list of valid debug values:
| Value | Description |
|---|---|
| 1 | Echoes all fields. This is useful for debugging value-splitting problems. |
| 2 | Prints Broker version number and elapsed time after each run, for example, "This request took 2.46 seconds of real time (v8.0 build 1316)." Also, this value displays the Powered by SAS logo if you provide additional settings as described in Displaying the Powered by SAS Logo. |
| 4 | Lists definitions of all services as defined by the administrator, but does not run the program. |
| 8 | Skips all execution processing. |
| 16 | Displays output in hexadecimal. This is extremely helpful for debugging problems with the HTTP header or graphics. |
| 32 | Displays the Powered by SAS logo without Broker version or elapsed time information. See also Displaying the SAS Powered Logo. |
| 128 | Returns log file. This is useful for diagnosing problems in the SAS code. |
| 256 | Traces socket connection attempts. This is helpful for diagnosing the machine selection process. |
| 512 | Shows socket host and port number in status message (by default off for security reasons). |
| 1024 | Echoes data usually sent from Broker to the Application Server. It does not run the program. In the case of a launch service, this also shows the SAS command that would have been invoked by the Broker. |
| 2048 | Provides more extensive socket diagnostics. |
| 4096 | Prevents the deletion of temporary files that are created for launch. This is useful for debugging configuration problems in a launch service (prior to Version 8). |
| 8192 | Returns entire SAS log file from a launched service (prior to Version 8). |
| 16384 | Displays the Broker environment parameters. |
In the Broker configuration file, you can specify the debug values that you are and are not allowed to set. The DebugMask and ServiceDebugMask directives control this. The information below describes the DebugMask directive but it also applies to the ServiceDebugMask directive.
The default value for the DebugMask is 32767. This is adequate for most sites. The value 32767 indicates that all debug values are allowed. This means that commenting out the DebugMask directive is the same as allowing all debug values.
Note: Some debug values may pose a security risk. To avoid potential security risks, selectively disable them by specifying a DebugMask value that is the sum of the values that you want to allow. The safest approach is to set DebugMask to 0, 2, 32, or 34 (sum of 2 and 32). These values do not pose a security risk.
Below is an illustration of how the Broker uses DebugMask to restrict certain values. The value 32767 is the sum of all the allowed debug values (1 through 16384). The following chart shows all the bits enabled for the DebugMask=32767 value (in binary notation):
| 16384 | 8192 | 4096 | 2048 | 1024 | 512 | 256 | 128 | 64 | 32 | 16 | 8 | 4 | 2 | 1 |
| 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
If you want to prevent the use of debug value 256, disable the DebugMask bit for 256, as shown next:
| 16384 | 8192 | 4096 | 2048 | 1024 | 512 | 256 | 128 | 64 | 32 | 16 | 8 | 4 | 2 | 1 |
| 1 | 1 | 1 | 1 | 1 | 1 | 0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
To allow all debug values except 256, specify a DebugMask value of 32511 (which is 32767 - 256).
To allow only debug values of 2 and 256, specify a DebugMask value of 258 (which is 2 + 256).
Note: The last technique is safer because additional debug values exist that are not documented. But if you do enable them, these debug values could pose a security risk.
The Broker displays an error if the binary values for _DEBUG and DebugMask do not equal 0 using binary logic. The Broker performs error checking only on the _DEBUG value in the HTML form or link. It does not check to confirm that Debug and DebugMask do not overlap. In other words, it does not check Debug to see if it has an allowed value in DebugMask. DebugMask is used to check values of _DEBUG only.
Some combinations of content types and debug values do not produce the expected results. The debug values 2, 32, 128, and 8192 do not function correctly if the content type is anything other than TEXT or HTML. For example, if your program sends a content type of IMAGE or GIF, then the browser expects the data that follows to be binary graphic data. If you supply one of these debug values, then the Broker tries to append HTML code to the end of the binary graphic data. This HTML is not displayed in the browser; only the image is displayed. One way to work around this is to supply the debug value 1 in addition to the value(s) above. This causes the Broker to send the content type TEXT or HTML before your program can send the IMAGE or GIF content type. Because the browser sees the TEXT or HTML content type first, it displays the debug output that you have requested. However, because the binary graphic data is combined with HTML data, garbage characters will take the place of the expected image on the Web page.
Keep in mind that setting the debug variable to 1 or 128 generates an HTTP header. This will affect the behavior of a test that changes the HTTP header in any way.
Some HTML formatter macros create their own headers. For example, if you are using SETCOOKIE on a header, the cookies do not work when DEBUG=1 or DEBUG=128 is set.
broker "_service=default&_program=ping"
If the broker.cfg file is set up correctly and there is an Application Server running for service "default", the results will be similar to
Content-type: text/html Pragma: no-cache Ping. The Application Server xxx.yyy.com:5001 is functioning properly. ------------------------------------------------------------- This request took 0.22 seconds of real time (v8.2 build 1385).
Because CGI programs typically run as special nonprivileged users, it is sometimes useful to perform this test with a guest account. On OS/390 machines there are occasional problems with the installation of the SAS/C transient library that will be revealed by performing this test.
http://yourserver/cgi-bin/broker.exe?
The Broker program in the URL will be the correct image to use for the Web server machine. If the browser tries to download the program as a file, then you have discovered the problem: the Web server is not configured correctly to execute CGI programs. For UNIX Web servers, typically you must add a line to the Web server HTTP config file for the CGI directory.
When this command works correctly, an administration display is returned to the browser:
SAS/IntrNet Application Dispatcher
Application Broker Version 8.2 (Build 1385)
Application Dispatcher Administration
SAS/IntrNet Samples
SAS/IntrNet Documentation - requires Internet access
http://yourserver/cgi-bin/broker.exe?_service=default&_program=ping
If the broker.cfg file is set up correctly and there is an Application Server running for service "default", the results will be similar to
Ping. The Application Server xxx.yyy.com:5001 is functioning properly. ------------------------------------------------------------- This request took 1.74 seconds of real time (v8.2 build 1385).
If this test fails but the test in the first step succeeds, there is usually a permission problem with the CGI running from the Web server. CGI programs are typically started under a nonprivileged account that may not have access to required system resources. Try totally disabling anonymous access for the CGI directory in the Web server. This forces the Broker to run with an authenticated user name. On Windows systems, check the permissions on the entire \winnt\system32 directory tree and verify that the user account IUSR_nodename has the user rights "Access this computer from network" and "Log on locally."
If the server starts but the Broker times out, verify that there are not multiple TCP/IP node names defined for a given host. The Broker and Load Manager hosts must resolve all node names to the same value. Host name mismatches can cause various error messages to appear in the Load Manager log.
To debug problems with launch and pool services, it is useful to obtain the SAS log and investigate any errors concerning the SasCommand that was executed.
To see the SasCommand that is being processed, add the parameter _DEBUG=1024 to the URL that is being used to start the service. This shows any errors with quotes or non-escaped back slashes.
Under UNIX, using the following syntax puts the SAS log, STDOUT, and STDERR messages into files using the Broker PID for the file names:
SasCommand "/bin/ksh -c '/usr/local/bin/sas /user/web/launchsas.sas +
-rsasuser -noterminal -noprint -log $$.log -SYSPARM $$.out 2>$$.err'"
Note: The username that the Broker runs under must be able to write to the directory where the Broker runs.
|
|
SAS/IntrNet 8.2: Application Dispatcher |
|