Creating Dispatcher Applications - Display a Data Set with Where Clause and Sum Variables

• The HTML Page
• The Dispatcher Program

The HTML Page

This application is very similar to the previous application which displays a data set. One important difference is the feature that allows the user to select one or more years' worth of data to display. This selection subsets the data in the resulting output. Allowing users to subset the displayed data makes an application much more useful. Two other options are available via checkboxes on the form. The user can select to display a total by sales and/or select to display observation numbers.

A selection list of years is created with the following HTML code:

<SELECT NAME="year" MULTIPLE>
<OPTION VALUE="1981"> 1981
<OPTION VALUE="1990"> 1990
<OPTION VALUE="1991"> 1991
<OPTION VALUE="1992"> 1992
<OPTION VALUE="1993"> 1993
<OPTION VALUE="1994"> 1994
</SELECT>

This is slightly different from the previous selection lists because it allows the user to select more than one value from the list. The keyword MULTIPLE added to the SELECT tag enables multiple selections.

The two check boxes are created with the following HTML code:

<INPUT TYPE="checkbox" NAME="sumvar" VALUE="sales" CHECKED>Total by Sales
<INPUT TYPE="checkbox" NAME="observ" VALUE="yes">Display Observation numbers

There are special concerns with handling multiple selection lists and check boxes in a Dispatcher program. The Dispatch Program section of this page will address them.

The entire HTML code for this application is contained in the the Broker package sample directory in a file named dataset2.html. The code produces a form that looks like this:

Two new selection lists have been added to the bottom of this form. Previously, the special Dispatcher variable _SERVICE was introduced and passed as a hidden field. On this form a selection list is used to set the value of _SERVICE. Another special Dispatcher variable is _DEBUG. This variable is typically omitted or passed as a hidden field in production applications. It is available in a selection list on this form because it is useful to set this variable when developing applications.

By examining the "Debugging level" list, you can see that _DEBUG can be used to display information about the application such as the time to process or the SAS log. To see the complete list of values for _DEBUG refer to Dispatcher Reference. For more detailed information on creating the input component of a Dispatcher application, see Input Component Details.

The Dispatcher Program

No changes need to be made in the Dispatcher program to incorporate the new selection lists for service and debug. The service value is treated the same by the Dispatcher whether it is a hidden field or not. The value of _DEBUG is recognized automatically by the Dispatcher and requires nothing be added to the Dispatcher program.

The first hurdle that this application presents are the check boxes. Check boxes were used before in the tabulate sample but were not explained. If a check box such as the observation numbers box is selected on the form, then a name/value pair such as observ=yes is passed to the Broker. However, if the check box is not selected, then the browser passes no name or value for that form element. This can cause a problem in the Dispatcher program. If a macro variable that does not exist is referenced in the program, SAS software displays a warning or error message. To avoid this, use the %global statement to declare any variables that have the possibility of not being passed by the browser. This includes check boxes, radio buttons where there is no initially selected button, and others depending on the browser and platform. For this program the following statement is used:

%global sumvar observ year0;

The global declaration will not clear or reset any values contained in these variables, it will simply make sure that these macro variables exist and are global in scope. If values were not passed, then these variables will be blank.

The next task this Dispatcher program must perform is creating a WHERE clause to subset the rows in the data set. Recall the selection list of years that allows multiple selections. If the user chose "1991", the name/value pair year=1991 is passed. The macro variable year will be used in the part of the Dispatcher program that generates a WHERE clause.

If the user chooses "1981", "1991", and "1993", the Dispatcher receives the following three name/value pairs

• year=1981
• year=1991
• year=1993

At first this looks like it might cause a problem because one name is used for three values. However, the Dispatcher handles multiple values in a special way. These three name/value pairs will actually produce the following macro variables in the SAS session.

• year=1981
• year0=3
• year1=1981
• year2=1991
• year3=1993

The Dispatcher has used a number suffix to produce unique variable names. This feature allows programs to accept and process multiple name/value pairs. The details of how multiple values are created and handled by the Application Dispatcher are explained more fully in Understanding Name/Value Pairs.

Now, a WHERE clause can be generated for an arbitrary number of years. Because the variable year0 contains the number of years selected, it can be used to control a do loop. Each loop can extract the selected years from the variables year1,year2, and so on. The complete source code for this program is contained in the Application Server package sample directory in a file named dataset2.sas. Here is the macro from that code, which generates the WHERE clause statement:

/* This macro code will build a WHERE clause */
%macro genwhr;
  %local i or;
  %global year year0;
  %if %length(%superq(year)) gt 0 %then
     %if %superq(year0) = %then %let year0=1;
     %let year1 = %superq(year);
     %do i = 1 %to %superq(year0);
         %let whrcls=&whrcls &or (year=%superq(year&i));
         %let or = or;
     %end;
  %end;
%mend;

This code accounts for the possibility that zero years may be selected, that only one year may be selected, and that multiple years may be selected. It is essential to realize that the year0 and other number-suffixed variables will only be created by the Dispatcher if multiple years are selected by the user. Notice the check for year having a zero length. This means no year was selected. In that case, the macro routine exits, and no WHERE clause is generated. Thus, selecting no years displays the full data set.

Next, notice the check for year0 having a blank value. If this is true but year is nonblank, then only a single year was selected. In that case, the macro sets year0 to a value of 1 so the do loop will only iterate once. Finally, the program makes a call to the Data Set Formatter, passing the generated WHERE clause to produce the desired HTML table.

Read the other example application sections to learn more or jump right to the details about the program component in Dispatcher Program Details.