The Hello World Program

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 Input Component
The Program Component

The Input Component

The HTML code for this sample is installed with the Dispatcher program in the default location:

   http://yourserver/sasweb/IntrNet8/dispatch/webhello.html

The input component for this and most Dispatcher applications is an HTML page that contains 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 that 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 SUBMIT will cause the field to display as a button, and the value will set the text that is displayed on the button. For example,


   <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 name 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.webhello.sas. Like _SERVICE, this field is most often supplied as a hidden field.

   <INPUT TYPE="hidden" NAME="_program" VALUE="sample.webhello.sas">

This completes the basic HTML form. You can find the code in the Broker package sample directory in a file named webhello.html. Here is the complete HTML code for the input component of this Dispatcher application.

   <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.webhello.sas">
   <INPUT TYPE="HIDDEN" NAME="_SERVICE" VALUE="default">
   <INPUT TYPE="SUBMIT" VALUE="Say Hello">

   </FORM>

   </BODY>
   </HTML>

And it produces a form that looks like this:

The Program Component

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 the 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 language, macro, or SCL code. The following program is written in Base SAS language, specifically the DATA step:

   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 Web 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 or HTML, the program follows the header with the source code for the HTML page that it will produce.

The Broker actually receives this output before the Web browser and checks it for a correct header. It then goes through the following stages:

If the header is correct, the Broker streams the data to the browser.
The browser strips off the HTTP header.
It displays the page according to the HTML code.
The user sees
Hello World!

This example application was hardcoded so that it could be easily understood. However, using more input fields on the form will provide variables to the Dispatcher program that can then produce dynamic output.