The Input Component

A Dispatcher application is composed 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:

an HTML form that has a Submit button. When the Web user provides the required information and submits the request, the browser sends the data that was entered plus data from any hidden fields to the Application Broker.
a hypertext link to the Application Broker. When the user selects the link, the browser sends a request, which includes parameters that are specified in the link's Universal Resource Locator (URL), to the Application Broker.
an inline image whose source is a reference to the Application Broker. When the user brings the page up for viewing, the browser loads the image and sends a request to the Application Broker. Similar to the process used for a hypertext link, parameters can be included in the URL.
a Java applet, ActiveX control, or Plug-in that contains a reference to the Application Broker. Depending on the object, the Application Server may send a request to the Application Broker immediately or wait for a user action, such as clicking a button.

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 Dispatcher passes and processes the information, receives the results of the application in the browser. The results are typically displayed as an HTML page, but they can be presented as a downloaded file in more sophisticated applications.

The 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 Dispatcher rejects invalid SAS names.

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

Use between 1 and 32 characters.
Begin the name with a letter or an underscore.
Continue the name with letters, underscores, or digits.

Reserved Names

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 on these and other special variables (name/value pairs) are available in Reserved or Special Variables.

Specifying Name/Value Pairs in a URL

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 wish 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 the HTML Syntax Reference section and the URLENCODE function in the SAS Language Reference: Dictionary for more complete information.

URLs with name/value pairs can be manually typed in a browser location field, saved as a 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 may 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 browser to interpret &COPY as the Named Character Reference (NCR) 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 browsers incorrectly identify an NCR even if it is not terminated by punctuation. For example, &REGION=EAST might be interpreted as ®ION=EAST by some (but not all) browsers. To avoid this problem, encode all ampersands that separate name/value pairs in a URL as & when used in an HTML tag.

Specifying Name/Value Pairs in an HTML Form

HTML forms provide the most versatile mechanism for data input in a 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 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 the HTML Syntax Reference section.

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 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 Browser, you can use them to

pass parameters to the Dispatcher program. For example, you can pass a list of variables to a Dispatcher program for processing. A single Dispatcher program can then be referenced by many HTML files.
pass name/value pairs from one form to the next. The input component to a complicated application often has more than one form and more than one page, which means that the name/value pair data must be propagated through each of the forms until the final program is invoked. Hidden fields are an easy way to accomplish this.
capture data generated by user interaction with screen widgets if your application uses JavaScript or Visual Basic Script.

Specifying Name/Value Pairs in the Broker Configuration File

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 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 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.

Broker directives are documented in Configuration File Directives.

Multiple Value Pairs

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

As an 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

   <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 Broker looks like

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

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

Name Value

CBOX0 4

CBOX one

CBOX1 one

CBOX2 two

CBOX3 three

CBOX4 four

Name	Value
CBOX0	4
CBOX	one
CBOX1	one
CBOX2	two
CBOX3	three
CBOX4	four

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 may 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:

check boxes: You can select multiple check boxes from a group of boxes. All of the check boxes can have the same HTML name, which can create multiple values for one name.
selection lists: You can select multiple items from some selection lists. These lists generate multiple values with the same name if more than one item is selected.
text entry fields: You can enter free-form text in text entry fields. Only one value is passed from the browser to the Broker. If the text is too long for a single variable (usually 32000 characters), the Broker splits the text into multiple name/value pairs.