How Application Dispatcher Version 1.2 Works

The SAS/IntrNet Application Dispatcher is an important addition to your SAS software installation because it allows you to offer the power of data analysis to Web users without having to install a large client software package on every desktop. Here's a summary of how it works:

1. A user fills out some fields in an HTML form from their Web browser and submits it. The information from the form is passed to the Web server, which invokes the first component of the Dispatcher called the Application Broker.
2. The Broker retrieves the data and sends it to the second Dispatcher component, called the Application Server. Information passed to the Broker tells the Broker which server should process the request.
3. The Application Server invokes a SAS program that processes the information. This is where the real power of the system comes into play.
4. The results of the program are streamed through the Broker to the browser and the waiting user.
5. Any necessary cleanup is done.

The whole process can complete in as little as one second, depending on the speed of the machines involved. The following diagram, described in detail later, illustrates how a communication request is submitted and processed.

Request is submitted to the Broker

Web users submit information and make processing requests from their Web browsers. The interface to the Application Dispatcher is usually an HTML form that users access from their Web browser, but the interface can also be a hypertext link containing hardcoded fields, or a specially coded inline image.

Depending on the design and purpose of the form, users can:

• formulate queries by selecting items from lists, check boxes, or radio buttons
• input data by completing text entry fields
• specify analysis variables by selecting items from lists, check boxes, or radio buttons, or by completing text entry fields.

When a user presses the Submit button or clicks on a hypertext link, the Web browser begins the processing by sending the form information to the Web server, which immediately invokes the Application Broker using a Common Gateway Interface (CGI) protocol. The Broker then contacts the Application Server. Because it is based on the CGI standard, the Application Broker is compatible with all major UNIX and PC Web servers on those platforms for which it has been compiled.

In addition to providing the user interface, the HTML form provides the following information:

• the location of the Application Broker, as defined in the ACTION attribute of the HTML FORM tag
• data contained in the _PROGRAM and _SERVICE required fields that identify the name of the Dispatcher program and the service that will be used to process it
• name and value information that is necessary for processing and is contained in optional fields such as INPUT fields.

To see how these fields are entered in the HTML code, and an explanation of how to make your own Dispatcher application form and associated SAS code, see Creating Dispatcher Applications.

Broker examines and sends request to Application Server

The Web server executes the Broker each time a user submits a request to process or access data using a Dispatcher application. The location of the Broker CGI program is provided by the ACTION attribute in the HTML form or by the HREF attribute on a hypertext link.

The Broker prepares fields such as text areas and check boxes for conversion to SAS macro variables, which enables the SAS program to process the information. Long text strings are divided into multiple variables to fit within the 200 character limit of SAS software, Version 6. The Broker then checks all of the field names to make sure they are valid SAS names. For a full explanation of how this works, see Understanding Name/Value Pairs.

The Broker reads the configuration file to determine the type of service that should receive the processing request. Dispatcher currently supports these types of services:

• Socket service: The Broker sends the data via a TCP/IP socket to the Application Server (a waiting SAS session). The Application Server does not have to be on the Web server machine as long as the Application Server and Web server machines are connected by a TCP/IP network.
• Launch service: The Broker sends the data via file input/output and launches the Application Server (a SAS session). The Application Server runs on the Web server machine and is terminated when the request is done.

The configuration file defines all the available services. Typically, one service corresponds to one Application Server, but a service can actually be a pool of Application Servers. For socket services, the configuration file also specifies the machine name or IP address and the TCP/IP port name or number that should receive the request. (For information about the configuration file, see Creating Your Own Configuration File.)

The Broker attempts to communicate with the Application Server. If the server is using the socket service, it accepts requests from the Broker on a defined TCP/IP socket. If the Application Server does not respond, the Broker performs one of the following actions:

• If the service defines a pool of servers, the Broker selects another Application Server.
• If the service does not define a pool of servers or if none of the Application Servers respond, the Broker generates an error page that displays in the user's browser.

If the Application Server is using the launch service, the Broker attempts to invoke the Application Server. If that fails for some reason, an error page is generated. All error pages contain local contact information as defined in the configuration file. The user should contact this person for help.

Application Server defines variables and runs program

After receiving a request, the Application Server defines macro variables or an SCL parameter list containing the name/value pairs passed from the HTML page. For details about how fields are converted to SAS variables, see Understanding Name/Value Pairs.

Next, the server examines the program name to determine the type and location of the program being run. If the Application Server does not find the program, it generates an error page that displays in the user's browser. Finally, the Application Server defines a special SAS fileref for program output, and runs the specified Dispatcher program.

Program output is streamed to the browser

The program output is sent directly to the Broker using a predefined file reference. The format of the output is defined by the HTTP standard and is explained fully in Creating Dispatcher Applications.

As the Broker receives the program output, it does a quick consistency check on the HTTP header and streams the results back to the Web server, which in turn streams the results back to the browser. Because of the streaming, results start appearing in the browser before the program has finished processing.

Application Server and Broker clean up and exit

When the program finishes, the Application Server returns the SAS log if the appropriate debug flag is set then closes the connection to the Broker. Before waiting for the next request, it cleans up various files and libraries, thus performing cleanup between processing requests. Of course, for launch services, the server exits instead of waiting for another request.

When the Broker determines there is no more output on the way, it returns a status line if one was requested through the debug flags, then return to the Web server. In the case of launch services, additional cleanup such as removal of Log files are performed. When the Broker exits, the user's page is done loading.