Receiving Input Component Data

The name/value pair data provided by the input component are sent to the program component and made available as macro variables. The Dispatcher creates these variables, assigns their values, and clears their values after the program has completed. The name/value pair data are also supplied in an SCL list to Dispatcher programs written in SCL.

Application developers must write their Dispatcher program to accept the proper macro variable names. The macro variable values can be obtained by direct reference (for example, &var) or by using one of the following:

• the SYMGET function of the DATA step
• the SYMGET, SYMGETC, and SYMGETN functions in SCL.

For example, if the HTML name/value pair for a text entry field is color=blue, all of the following store the value blue in the DATA step variable color:

   color="&color";

or

   color=%superq(color);

or

   color=symget('color');

The left side of each assignment statement is the DATA step variable. The right side shows three different techniques for extracting the macro variable value. All of these techniques return the 'safe' value of the input value. The Application Server will strip any unsafe characters (as defined by the UNSAFE option on PROC APPSRV). This means it is usually safe to use the &var reference in Version 8 Application Dispatcher programs, unlike in previous versions. Use the APPSRV_UNSAFE function to retrieve the full input value, including any 'unsafe' characters:

color=appsrv_unsafe('color');

Because all macro variables are a character data type, some extra processing is required in DATA step code if the value will be stored in a numeric variable. For example:

age=input(symget('age'),12.);

If the Dispatcher program is written in SCL, you have another option for accepting the variable values. An SCL list is passed to each Dispatcher program written in SCL. Therefore, each SCL program should contain the following statement:

   entry inputlist 8;

The input list contains named character items that correspond to the macro variables created. If your program is written in SCL, you can use either the input list or macro variables. To access the same name/value pair as above, a statement like this can be used:

   color=getnitemc(inputlist,'COLOR',1,1,'');

As with the macro variables, this SCL list is cleaned up by the Application Server when the Dispatcher program completes.

The Dispatcher automatically creates several variables based on the program request and various information in the Broker configuration file. These automatic variables are available to your program as macro variables and SCL list items. For a complete list of these automatic variables, see the sections Reserved or Special Variables and Exporting Environment Variables.