Creating Dispatcher Applications - Input Component Details

• Techniques for input
• Understanding name/value pairs
• Using hidden fields

Techniques for Input

There are four primary techniques for sending input to a Dispatcher application:

• HTML form
• Hyperlink
• IMG tag
• Location field.

HTML form

HTML forms provide the most versatile mechanism for inputting data to a Dispatcher application. Forms are easy to create and function effectively in virtually all Web browsers.

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 are included in the HTML files in the Broker package sample directory. They vary in level of complexity. Viewing the HTML code in these files and reading the sample application descriptions in the previous sections help you learn how to create forms. A complete listing of form requirements and components can be found in the HTML Syntax Reference section.

Hyperlink

It is also possible to create a hyperlink on an HTML page that invokes a Dispatcher application. This is done by using the standard anchor HTML syntax. Instead of linking to a file, the HREF points to the Broker. For example,

<A HREF="/cgi-bin/broker?_service=default&_program=sample.hello.sas">Say Hello</A>

creates a link that says Say Hello.

Notice the question mark that follows broker. The section of the URL after the question mark is called the query string. The query string contains the name/value pair data that is input to the application. Here, the two required fields _SERVICE and _PROGRAM are specified. More parameters can be specified in this fashion using the ampersand (&) as a separator between name/value pairs.

Important: The Web browser has strict rules about the format of the query string. Name/value pairs must be URL encoded. For example, spaces cannot be passed in the query string. They must be encoded as + or %20. See the HTML Syntax Reference section for more complete information.

IMG tag

Just as anchors and HREF are used to link HTML documents together, the IMG tag and SRC parameter embed graphic images in HTML pages. Typically, the image tag is used like this

<IMG SRC="mykids.gif">

and the browser loads the GIF file and inserts it into the Web page. However, the SRC parameter could simply point to a Dispatcher application which produces GIF output. When the Web browser loads the HTML page it encounters an IMG tag in the source code. At that point the browser automatically makes a separate request to load the graphic image. It makes no difference to the browser if the graphic that it loads comes from a file on the Web server or from dynamically generated Dispatcher output. For example,

<IMG SRC="/cgi-bin/broker?_service=default&_program=sample.grphics.sas">

will insert the sample graphics output into your HTML page. Now imagine that the underlying data were changing daily. Putting such an image tag on your page would display a new graph each day!

Location field

Most browsers have a location or address field across the top that displays the Web address of the page that you are currently viewing. You can run a Dispatcher program by simply typing in the URL and query string into this field. For example, typing this into the field

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

where myserver is the Web server you are using, will run the Hello World program. The ability to run programs without using a form is very useful when developing and debugging Dispatcher applications. By adding

&_DEBUG=131

to the end of the location above you can see some useful debugging information including the SAS log. And there was no need to edit any HTML or reload a form.

Important: The Web browser has strict rules about the format of the query string. Name/value pairs must be URL encoded. For example, spaces cannot be passed in the query string. They must be encoded as + or %20. See the HTML Syntax Reference section for more complete information.

Understanding Name/Value Pairs

The Browser passes parameters, data, and options from the HTML page to the Dispatcher through name/value pairs. You can pass name/value pair data via the URL or by inserting the information in fields such as the INPUT field on the HTML page. Here is an example of an HTML input field:

This code indicates that a radio button, one of several input types, appears on the HTML page and is labeled Bar Chart. The field name is bar and true is the value if the radio button is selected. The HTML page passes the name and value as NAME=VALUE to the Broker, and in the preceding example, this becomes bar=true.

The Dispatcher uses macro variables to surface name/value pair data to your programs. SCL programs are supplied with an SCL list as an additional mechanism for accessing the data. With a few exceptions, the macro variable names and list item names match the names supplied in the HTML code. The HTML names used to create the macro variable names must be valid SAS names and be expected by the program. The Dispatcher rejects nonvalid SAS names. Because the SAS rules for names are more restrictive than the rules for HTML names, Dispatcher application developers must follow the SAS naming rules for all fields:

• Use one to eight characters.
• Begin the name with a letter or an underscore.
• Continue the name with letters, underscores, or digits.

Multiple Value Pairs

There are some cases where multiple name/value pairs with the same name will be created. Because macro variables do not allow multiple values, the Broker must create a unique macro variable name for each value provided. It does this by adding numbers to the end of the name. Before explaining the details of how the Broker handles multiple value pairs, we will discuss what types of fields can cause multiple values to be created. The following input types can generate multiple values for one name:

checkboxes

A user can select multiple checkboxes from a group of boxes. All of the checkboxes may have the same HTML name, which can create multiple values for one name.

selection lists

A user can select multiple items from some selection lists. These lists will generate multiple values with the same name if more than one item is selected.

text entry fields

A user can enter free-form text. Only one value is passed from the browser to the Broker, but the Application Server cannot handle values longer than 200 characters or containing carriage returns. The Broker may split this value into multiple name/value pairs.

Multiple values received from selections

This example assumes that you have a group of four checkboxes, each named CBOX. The value associated with each box is one, two, three, and four, respectively. If the user selects all four boxes, part of the query string that is passed to the Broker would look like this:

  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

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 with the case of a single selection. This example also applies to a multiple selection list named CBOX containing the same four selected values.

Text passed from a text entry field

If the value passed from a text entry field contains more than the default number of characters or contains a carriage return, the Broker creates multiple name/value pairs

• when it encounters a carriage return.

  The first variable contains everything up to and including the return, and the second variable begins with the first character following the carriage return.

• at the end of the specified number of characters, identified using the special _FLDWDTH hidden field (or 80 if _FLDWDTH is not set).

  If a blank appears prior to the required break, the Broker breaks the string at the blank to avoid breaking a word into two halves.

• only if the name does not begin with an underscore. Values where the name begins with an underscore are not split and are truncated at 200 characters.

The _FLDWDTH field specifies the maximum length for any character value. Setting the value for this field in a hidden input tag will control the breaking of all text fields on that form.

Here's an example:

For more information on Dispatcher fields such as _FLDWDTH, refer to Special Dispatcher Fields.

Using Hidden Fields

Although hidden fields do not appear on the HTML form, you can use them to pass parameters to the Dispatcher program. For example, you could pass a list of variables to a Dispatcher program for processing. A single Dispatcher program could then be referenced by many HTML files. Another common usage of hidden fields is to pass name/value pairs from one form to the next. The input component to a complicated application can often have more than one form and more than one page. This usually 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. If your application uses JavaScript or Visual Basic Script, you may also find that hidden fields are convenient for capturing data generated by user interaction with screen widgets.