The Input Component

An Application Dispatcher application consists of input and program components. The program component is the actual SAS program that runs on the Application Server. The input component is the remainder of the application, which runs on the Web server or the client. It normally consists of static or dynamically generated HTML pages that contain one or more of the following:

The input component selects what program component to run and passes input data to the program component as a list of name/value pairs. The name/value pairs can be specified in a URL, in input fields in an HTML form, by an object such as a Java applet or ActiveX control, or in the Application Broker configuration file as described below. The Web user, who does not need to know how the Application Dispatcher passes and processes the information, receives the results of the application in the Web browser. The results are typically displayed as an HTML page, but they can be presented as a downloaded file in more sophisticated applications.

The Application Dispatcher uses macro variables to pass name/value pair data to your programs. SAS Component Language (SCL) programs are supplied with an SCL list as an additional mechanism for accessing the data. Usually, both the macro variable names and list-item names match the names supplied in the HTML code. The HTML names that are used to create the macro variable names must be valid SAS names and must be expected by the program. The Application Dispatcher rejects invalid SAS names.

Because the SAS rules for names are more restrictive than the rules for HTML names, Application Dispatcher application developers use the following SAS naming rules for all fields:

Reserved names have special meaning to the Application Dispatcher. For example, every request must include a _PROGRAM name/value pair to identify the program to be run by the Application Dispatcher. In most cases, a _SERVICE name/value pair is required to identify the service that handles the request. More details about these and other special variables (name/value pairs) are available in Reserved or Special Variables.

You can specify name/value pairs in a URL by using Application Broker CGI-parameter syntax. For example, the URL

http://yourserver/cgi-bin/broker?
_service=default&_program=sample.webhello.sas

specifies two name/value pairs. Note the question mark (?) that follows BROKER. The section of the URL that follows the question mark is called the query string. The query string contains the name/value pair data that is input to the application. Each name is separated from the following value by an equal sign (=). Multiple name/value pairs are separated by ampersands (&). In this example, the _SERVICE=DEFAULT pair specifies the service that handles this request, and the _PROGRAM=SAMPLE.WEBHELLO.SAS pair specifies the request program that is executed.

The Web browser has strict rules about the format of the query string. Any special characters (including spaces) in a value must be URL encoded. Spaces can be encoded as a plus sign (+) or %20. For example, if you want to pass the name AUTHOR with a value of John Doe, specify it in the URL as AUTHOR=John+Doe or AUTHOR=John%20Doe. See HTML Syntax Reference and the URLENCODE function for more complete information.

URLs with name/value pairs can be manually typed in a Web browser location field, saved as a Web browser bookmark, included as an HREF attribute of an anchor tag, included as an SRC attribute of an IMG tag, or used anywhere a URL can be used. Java or ActiveX components such as the SAS/GRAPH thin-client graphic components might generate URLs with name/value pairs to activate Application Dispatcher programs.

URLs with name/value pairs that are included in an HTML page (for example, as an HREF= or SRC= attribute) must be properly encoded to prevent incorrect interpretation of the ampersand characters. For example, the anchor tag

<A HREF="http://yourserver/cgi-bin/broker?
_program=lib.pgm.sas&copy=true">

causes the Web browser to interpret &COPY as the character entity reference for a copyright character. The correct way to encode this URL is

<A HREF="http://yourserver/cgi-bin/broker?
_program=lib.pgm.sas&amp;copy=true">

In addition, some Web browsers incorrectly identify a character entity reference even if it is not terminated by punctuation. For example, &REGION=EAST might be interpreted as ®ION=EAST by some (but not all) Web browsers. To avoid this problem, encode all ampersands that separate name/value pairs in a URL as & when used in an HTML tag.

HTML forms provide the most versatile mechanism for data input in an Application Dispatcher application. A form definition begins with the <FORM> tag and ends with the </FORM> tag. Between these two tags, other HTML tags define the various components of the form, including input fields, selection lists, push buttons, and more. Several forms of varying complexity are included in the HTML file section of the Application Broker package sample directory. The HTML code in these files, as well as the descriptions in the following sections, helps you learn how to create forms. A detailed list of form requirements and components can be found in HTML Syntax Reference.

Hidden fields are name/value pairs that do not appear as buttons, selection lists, and so on, in the HTML page. Here is an example of a hidden field:

<INPUT TYPE="hidden" NAME="_service" VALUE="default">

This HTML tag passes the name/value pair _SERVICE=DEFAULT when the form that contains the name/value pair is submitted. The required Application Dispatcher fields _SERVICE and _PROGRAM are often passed as hidden fields, but you can also include your own fields as hidden fields. Although hidden fields do not appear visually in the Web browser, you can use them to

You can specify name/value pairs in the Application Broker configuration file (broker.cfg). The Set directive defines a constant name/value pair that is passed to all program components. For example, your broker.cfg might contain

Set IMGHOME http://server.xyz.com/images

This directive defines the name/value pair IMGHOME=http://server.xyz.com/images for all requests executed by this Application Broker. The IMGHOME macro variable can then be used to construct URL links to images in an HTML page without coding a fixed URL path in each Application Dispatcher program. This feature is used to define the codebase location of SAS/GRAPH Java applets (in the _GRAFLOC name/value pair) in a default SAS/IntrNet installation. The ServiceSet directive defines a name/value pair for a specific service.

You can define name/value pairs by issuing the Export and ServiceExport directives. These directives enable you to export a CGI environment variable as a name/value pair. The default configuration file exports a number of variables. For example, the

Export REMOTE_USER _RMTUSER

directive exports the REMOTE_USER environment variable as the _RMTUSER name/value pair. See Exporting Environment Variables for more information.

In some cases, multiple name/value pairs with the same name are created. Because SAS macro variables do not allow multiple values, the Application Broker creates a unique macro variable name for each value provided. It does this by adding numbers to the end of the name.

For example, assume you have a group of four check boxes, each named CBOX. The value associated with each box is ONE, TWO, THREE, and FOUR, respectively. The HTML for these check boxes is as follows:

<input type="CHECKBOX" name="CBOX" value="one">
<input type="CHECKBOX" name="CBOX" value="two">
<input type="CHECKBOX" name="CBOX" value="three">
<input type="CHECKBOX" name="CBOX" value="four">

If you select all four boxes, part of the query string that is passed to the Application Broker looks like

CBOX=one&CBOX=two&CBOX=three&CBOX=four

The Application Broker then sends the following name/value pairs to your application:

The CBOX0 value indicates the number of boxes selected. The original variable name is passed with a value equal to the first selection. Though it might seem redundant to have CBOX and CBOX1 with the same value, it is done for consistency in the case of a single selection. This example also applies to a multiple selection list named CBOX that contains the same four selected values.

The input types that can generate multiple values for one name are as follows: