The first time the page is called, the URL needs only the required _service and
_program parameters. The user then fills in the input box, checks a conversion type, and clicks the Submit button. Pressing Submit causes the Web server to send the values of all the input fields (including the hidden ones) to the Application Dispatcher. (Blanks in a character variable value are changed to plus signs (+) by the server; SAS text formatting functions such as inputn,left,trim or strip can be used to specify the desired number of decimal places.)
There are five name/value pairs in this program: _service and _program parameters are passed to the broker to identify the service and program. The input and convert fields are used to collect the user input and pass it to the SAS program as macro variable values.
Finally, the result field is used to display the answer; this field is also passed as a parameter that is never read by the SAS program.
Defining Application Server Libraries
One tricky point that was glossed over in the previous example is the value of the _program parameter: in this case, sample.example6-2.sas. The question of where to store the SAS program and how to reference it brings us to the promised discussion of editing the appstart.sas program. You probably do not want to store your code in the same directory as the samples supplied by SAS, so how do you define a new library to the service?
Recall that the batch scripts used to start the default SAS application service are in a subfolder called default in the root directory defined by the inetcfg utility (see Display 6.2). These scripts are used to run the appstart.sas program which contains the APPSRV procedure along with the various program statements that define the server.
A default version of this program is created by the inetcfg utility; in this case, the path to the program is C:\Program Files\SAS\IntrNet\default\appstart.sas. The ALLOCATE statement, shown in bold, associates the filename examples with the specified directory. The PROGLIBS statement indicates that the referenced directory contains SAS programs.
Example 6.3 PROC APPSRV
proc appsrv unsafe='&";%''' &sysparm;
allocate file sample '!SASROOT\IntrNet\sample';
allocate library samplib '!SASROOT\IntrNet\sample' access=readonly;
allocate library sampdat '!SASROOT\IntrNet\sample' access=readonly;
allocate library tmplib 'C:\Program Files\SAS\IntrNet\default\temp';
allocate file logfile
'C:\Program Files\SAS\IntrNet\default\logs\%a_%p.log';
/* allocate new program library */
allocate file examples 'c:\Inetpub\scripts\examples';
proglibs examples;
proglibs sample samplib %ifcexist(sashelp.webeis) sashelp.webprog;
proglibs sashelp.websdk1;
adminlibs sashelp.webadmn;
datalibs sampdat tmplib;
log file=logfile;
In this way, the library C:\Inetpub\scripts\examples can be referenced in a URL as examples. Note that it is generally considered not a good idea to put your SAS programs in the directory reserved for Web server scripts. This is akin to putting your personal SAS programs in a directory like C:\Program Files\SAS\SAS 9.1\intrnet\sashelp. Installing or changing the SAS installation could result in a loss of your files. Similarly, changing the installation of the Web server software could result in the loss of your files.
And storing the files together adds great confusion, because later it is stated that unlike CGI programs, the SAS programs don't need to be stored in a directory that the Web server recognizes as a CGI alias. A better choice might to define a new folder such as C:\examples to hold the SAS code.
In any case, if the file webhello.sas is located in the folder specified, the URL (all on one line) would now be as follows:
http://hunding/scripts/broker.exe?_service=default&
_program=examples.webhello.sas
Chapter 6 SAS/IntrNet: the Application Dispatcher 119
There are several kinds of Application Server libraries; the most important are program libraries and data libraries. Two SAS statements are required to define each:
Program libraries allocate a file reference to a directory and then include the FILENAME reference in a PROGLIBS statement; only programs that reside in a library designated by a PROGLIB statement can be executed.
Data libraries allocate a library reference to a directory and then include the LIBNAME reference in a DATALIBS statement; DATALIB libraries are intended to store data, not programs.
You can also use the ALLOCATE LIBRARY statement to allocate program libraries for executing SCL, SOURCE, or MACRO catalog entries. You can include as many
ALLOCATE, PROGLIBS and DATALIBS statements as you wish.
The Application Broker program is a CGI program, so it must be stored in a directory that the Web server recognizes as a CGI alias. In contrast, you can store the SAS programs anywhere you want; just be sure to modify appstart.sas by adding the appropriate directory references.
A valid system administrator account must be used to modify the appstart.sas program. It is also important to note that you must stop the Windows service before modifying the program, or else you will get a “Sharing Violation” message when you try to save it. Just don’t forget to restart the service after saving the changes.
Obviously, there are a number of other options available in this procedure; the developer is directed to the APPSRV procedure syntax in the SAS Help and Documentation for more information about the other statements shown. (See also
http://support.sas.com/rnd/web/intrnet/dispatch/appsrv.html).
Debugging SAS Output
The default HTML message when a CGI program fails for some reason is that the program has an error. This can be somewhat frustrating, since there is no way to figure out what is causing the error. SAS/IntrNet has a handy device for displaying the input parameters and the log file of the SAS program. If nothing else, this would justify using SAS for CGI programming. Just add the debug flag to the end of the URL string, as in the following example:
http://hunding/scripts/broker.exe?
_service=default&
_program=examples.webhello.sas&
_debug=131
The numeric values of the debug flag for the Application Dispatcher are computed as the sum of the codes in Table 6.2; thus 131=1+2+128.
Table 6.2 List of Valid Debug Values
Value Keyword Description
1 FIELDS Echoes all fields. This is useful for debugging value-splitting problems.
2 TIME Prints the 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” in the SAS Help and Documentation.
4 SERVICES Lists definitions of all services as defined by the administrator, but does not run the program.
8 Skips all execution processing.
16 DUMP 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 Powered by SAS Logo” in the SAS Help and Documentation.
128 LOG Returns the 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 the socket host and port number in the status message (by default this is off for security reasons).
1024 ECHO Echoes data usually sent from the 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 TRACE 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 SAS 8).
8192 Returns the entire SAS log file from a launched service (prior to SAS 8).
16384 ENV Displays the broker environment parameters.
Note that the use of the keywords is not supported in the SAS 8 broker; that support was added to the broker in SAS®9.
Display 6.11 illustrates the results of choosing the debug values for echoing fields (1), broker version (2), and the log (128). If there were any errors in the execution of the SAS code, they would show up in the log.
Chapter 6 SAS/IntrNet: the Application Dispatcher 121