All the Above: Building a Multi-Selection HTML Form in a SAS Viya Job

[#1]

Imagine you want to run a SAS Viya job that filters results based on several user-selected regions, product categories, or customer types. A drop-down that only allows one value to be selected won’t cut it — you need a multi-selection input. In this article, I’ll discuss how to set up and process multi-select prompt controls in SAS Viya jobs using a HTML input form.

Defining the HTML Form

In an HTML form, allowing multiple selections is simple. All you need to do is add the multiple attribute to the select tag. Consider the following example:

…

<select name="selectMake" id="selectMake" data-colname="make"    

     data-library="sashelp" data-table="cars" multiple size="6">

</select>

…

By adding the multiple attribute, the control allows the user to select more than one make of car by CTRL+clicking on each value. The size attribute specifies how many values should be visible in the control at once:

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

Understanding How Selections are Passed to the Job

Because macro variables can’t hold more than a single value, when you have a parameter that contains multiple values, multiple macro variables are passed to the job definition. Consider the example from above, where the user selected three makes of car. Six macro variables are created and passed to the job definition, all based on the name of the parameter:

Macro Variable	Value	Explanation
selectMake	Acura	First value
selectMake0	3	Number of values
selectMake1	Acura	First value
selectMake2	BMW	Second value
selectMake3	Buick	Third value
selectMake_COUNT	3	Number of values

The base macro variable (e.g., selectMake) contains the first selected value. The version ending in 0 and _COUNT indicates the total number of values. Then selectMake1, selectMake2, and selectMake3 contain each selected value in sequence.

Handling Multiple Selection Values

Having the selected values separated across multiple different macro variables is not especially useful when writing SAS code. In order to use multiple parameter values in a filtering WHERE statement or a VAR statement, you need to transform them. SAS provides a macro program called %PARAM_LIST that does this by converting the parameter list generated by a multiple-value prompt into a single macro variable.

The %PARAM_LIST macro has four arguments:

• mvar=: the name of the macro variable corresponding to the prompt name
• outvar=: the name of the resulting macro variable
• dlm=: the delimiter used in the output list
• quote=: whether to wrap each value in quotes

The PARAM_LIST macro is not an autocall macro included automatically with SAS. Rather, you will need to define it either in the job definition or separately, and then in include it in the job definition. You can find the source code for the macro definition here.

Let’s consider an example. I have the following code, which generates a simple report of the five most expensive cars of a selected make:

proc sort data=sashelp.cars out=cars_sort;
  where make in (&Make_List);
  by descending MSRP;
run;

title "Top Five Most Expensive";
proc print data=cars_sort(obs=5);
run;
title;

This code filters the data based on the value of the &MAKE_LIST macro variable. Because I’m using the IN operator in a WHERE statement, the &MAKE_LIST macro variable must contain the Make values must be a list of quoted values separated by commas, like:

"Acura", "BMW", "Buick"

Knowing that, I can use the %PARAM_LIST macro to process the input parameters and generate a correctly structured &MAKE_LIST macro variable.

%param_list(mvar=selectMake, outvar=make_list, dlm=%str(,), quote=y);

The MVAR argument specifies the name of the input macro variable that corresponds to the prompt name from the HTML form. The OUTVAR argument specifies the name of the macro variable that contains the converted parameter list. Then, the DLM argument specifies what character should be used to delimit values in the converted parameter list. Finally, the QUOTE argument species whether or not to quote the individual values in the list.

When the code runs, the macro will generate the &MAKE_LIST macro variable, containing the selected values, individually quoted, and separated by commas. The job generates the following results:

Conclusion

Multi-selection controls open the door for more dynamic and user-friendly SAS Viya jobs. By correctly setting up your HTML form and using %PARAM_LIST, you can transform multiple input values into a format your SAS code can easily use. With this approach, your jobs become more flexible, more reusable, and better aligned with real-world user needs.

Tips and Tricks

• You can also create multi-select controls JSON-based step prompt forms, using the List Control.
• If your HTML job results appear unformatted, read here for information about to fix it.
• Be careful of how the converted parameter list macro variable is used in your code. Think about what delimiter needs to be used, and whether the values should be quoted. For instance, when using the IN operator in a WHERE statement, you’ll need a comma delimiter and each value to be individually quoted, but in a VAR statement specifying column names, you won’t.
• Use the size attribute in the select tag to make sure users can see enough options without scrolling.

Find more articles from SAS Global Enablement and Learning here.