Creating Dispatcher Applications - Hello World
The classic "Hello World" program illustrates how to
create a simple Dispatcher application. Keep in mind
that the software is far more powerful than this example
will show. The discussion of this application is divided into
two parts:
The HTML Page
The user interface for this and most Dispatcher applications is an HTML page containing an HTML form. The form for this program consists of a single button that will run the program component of the application when selected. The
<FORM> tag begins a form and the </FORM> tag ends it. Tags which create the pieces of the form are inserted between these begin and end form tags.
The browser must be instructed what action to take when a user completes and submits the form. The ACTION= parameter inside the begin form tag does this. For Dispatcher applications, the action is the URL for the Application Broker. For example,
<FORM ACTION="/cgi-bin/broker">
form components go here
</FORM>
At this point, the form does not contain any input fields or buttons. For this application, a single button is added to the form by inserting an <INPUT> tag in the HTML code. A type of SUBMIT and a value of Say Hello are supplied as parameters to the input tag. The type of submit will display the field as a button, and the value will set the text that is displayed on the button. This is the new code:
<FORM ACTION="/cgi-bin/broker">
<INPUT TYPE="SUBMIT" VALUE="Say Hello">
</FORM>
This is enough to create a visible, functional HTML form, but it is not enough to make it work with the Dispatcher. The Dispatcher has input requirements beyond those of the basic HTML form. Two special variables must be supplied when the form is submitted.
The _SERVICE Field
The _SERVICE field is one of the required fields in the HTML form for a Dispatcher application. The value must match the ID of a service defined in your
Broker configuration file.
Most often, this information will be supplied in a hidden field, as shown in the following example:
<INPUT TYPE="hidden" NAME=_SERVICE VALUE="default">
Specifying the type as "hidden" prevents the browser from showing the field to the user.
The _PROGRAM Field
The _PROGRAM field is also required.
Its value indicates the name of the Dispatcher program that the Application Server should look for and run. The program name
for this application is sample.hello.sas. Like
_SERVICE, this field is most often supplied as a hidden field.
<INPUT TYPE="hidden" NAME="_program" VALUE="sample.hello.sas">
That completes this basic HTML form. Here is the complete HTML code for the input component of this Dispatcher application. You can also find this code in the Broker package sample directory in a file named hello.html.
<HTML>
<HEAD>
<TITLE>Hello World!</TITLE>
</HEAD>
<BODY>
<H2>Hello World Sample Application</H2>
<HR>
<FORM ACTION="/cgi-bin/broker">
<INPUT TYPE="HIDDEN" NAME="_PROGRAM" VALUE="sample.hello.sas">
<INPUT TYPE="HIDDEN" NAME="_SERVICE" VALUE="default">
<INPUT TYPE="SUBMIT" VALUE="Say Hello">
</FORM>
</BODY>
</HTML>
And it produces a form which looks like this:
For more detailed information on creating the input component of a Dispatcher application, see
Input Component Details.
The Dispatcher Program
When the submit button on the HTML form is pressed, the browser passes the form data to the Application Broker. The Broker then passes the data on to an Application Server, which runs the Dispatcher program. For an overview of this process, see
How Application Dispatcher Works.
The Dispatcher program for this application has a simple function: to make the words "Hello World!" appear in the user's Web browser. Because the program is run inside a SAS session, it must be written in Base SAS, macro, or SCL code. The following program is written in Base SAS code:
data _null_;
file _webout;
put 'Content-type: text/html';
put ;
put '<HTML>';
put '<HEAD><TITLE>Hello World!</TITLE></HEAD>';
put '<BODY>';
put '<H1>Hello World!</H1>';
put '</BODY>';
put '</HTML>';
run;
A data _null_ step references a fileref of _WEBOUT. This fileref is predefined by the Application Server. You can think of writing to this fileref as writing to the client's browser. Because the Application Dispatcher software operates within the Common Gateway Interface (CGI), the first output a program produces must be an abbreviated HTTP header. In this program, the header is the Content-type declaration followed by a null record. Because the content was declared to be text/html, the program follows the header with the source code for the HTML page it will produce.
The Broker actually receives this output before the Web browser and checks it for a correct header. If the header is correct, the Broker streams the data to the browser. The browser then strips off the HTTP header, displays the page according to the HTML code, and the user sees
Hello World!
This example application was completely hardcoded so that it could be easily understood. However, using more input components on the form will provide variables to the Dispatcher program that can then produce dynamic output. Read the other example application sections to learn more, or jump right to the details about the program component
in Dispatcher Program Details.
|
