Building a Web Application with SAS Stored Processes

Specifying Web Application Input

A Web application that uses stored processes must have a way of sending input parameters to the stored processes. Input parameters are typically generated by an HTML page and passed through the Stored Process Web Application or a user-written JSP to the stored process. Input parameters can be specified in the following:

fields in an HTML form. The user provides the required information and submits the request. The Web browser sends data from the form (including both user-entered data and hidden fields) to the server. HTML forms are generally used where user input is required to control the execution of the stored process.
a hypertext link in an anchor tag. The link URL includes parameter values that are passed to the server when the user selects the link. Hypertext links are generally used where the input parameters have fixed values (for example, as drill-down links in a table or image).
an inline image or other embedded link in the HTML page. This case also includes frames within an HTML frameset. In most cases, the Web browser fetches the embedded object when the user loads the HTML page. Fetching the embedded object can cause input parameters to be passed to a stored process.
URLs or forms that are created and submitted by JavaScript or a similar scripting technology in the Web browser.

The HTML page that uses these techniques can be a static HTML page or a dynamic page that is generated on demand by another stored process or by a Java Server Page (JSP). In all cases, the input parameters must follow the naming conventions and other basic rules that are described in Using Input Parameters. Reserved parameter names should be used only as recommended. For more information, see Using Reserved Macro Variables. Reserved parameter names should be used only as recommended.

The SAS Stored Process Web Application is set up to use the SanitizingRequestFilter to check for invalid requests. If an invalid input string (for example, <script>) is found in input parameters, then a status code 403 is returned to the Web browser. For more information about this filter, see the SAS Intelligence Platform: Web Application Administration Guide.

All of the previously mentioned techniques for specifying input parameters rely on URLs or HTML forms. The following sections discuss how parameters are passed in both cases. These sections assume the use of the Stored Process Web Application. JSPs will generally use similar conventions, but the details are determined by the author of the JSP.

Specifying Input Parameters in a URL

You can specify input parameters as a sequence of name/value pairs in a URL by using the query string syntax. For example, the following URL specifies two name/value pairs.

 http://yourserver/SASStoredProcess/do?
 _program=/WebApps/Sales/Weekly+Report&region=West

The URL specifies your server, an absolute path to your Stored Process Web Application, and the query string (following the question mark character). Each name in the query string is separated from the following value by an equal sign (=). Multiple name/value pairs are separated by ampersand characters (&). In this example, _program=/WebApps/Sales/Weekly+Report is the reserved input parameter that specifies the stored process that is to be executed. The second name/value pair (region=West ) is another input parameter to be passed to the stored process.

There are special rules for the formatting of name/value pairs in a URL. Special characters (such as most punctuation characters, including spaces) in a value must be URL-encoded. Spaces can be encoded as a plus sign (+) or %20. Other characters are encoded using the %nn convention, where nn is the hexadecimal representation of the character in the ASCII character set. In the previous example, the value /WebApps/Sales/Weekly+Report actually identifies the stored process named "Weekly Report". The space in the name is encoded as a plus sign (+). If your parameter values contain special characters, then it is important that they are URL-encoded. Use the URLENCODE DATA step function when creating URLs in a stored process.

URLs are typically used in an HTML tag attribute, and this might require extra encoding to be properly interpreted. The ampersand characters that are used in the URL query string can cause the Web browser to interpret them as HTML markup. The parameter &region=West is interpreted as ®ion=West in some Web browsers. Use HTML encoding to avoid this problem. The following example shows the correct HTML code:

 <A HREF="http://yourserver/SASStoredProcess/do?
 _program=/WebApps/Sales/Weekly+Report&amp;region=West">

The HTMLENCODE DATA step function can be used to encode the URL in a stored process. If we assume that the variable myurl contains a URL with various input parameters, then the following code creates an anchor tag in the variable atag that is properly encoded:

 atag = '<A HREF="' || htmlencode(myurl, 
 'lt gt amp quot') || '">';

Note that some Web browsers and Web servers might impose a limit on the total length of a URL. URLs with many parameter values that exceed this limit can be truncated without warning, which results in incomplete or inconsistent input data for your stored process. URL length limits are not well documented and might require experimentation with your particular configuration.

For information about specifying multiple values for an input parameter, see Input Parameters with Multiple Values.

Specifying Name/Value Pairs in an HTML Form

HTML forms provide the most versatile mechanism for sending input parameters to a stored process. 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 labels, input fields, selection lists, push buttons, and more. Here are some issues that are related to stored process input parameters in HTML forms:

The ACTION attribute of the <FORM> tag generally points to the Stored Process Web Application or a JSP that will execute the stored process. The METHOD attribute of the <FORM> tag can be set to GET or POST.
The GET method causes the Web browser to construct a URL from all of the field values in the form. The URL will be exactly like the URLs that were discussed in the previous section. The GET method enables the user to bookmark a specific stored process execution, including all input parameters, but the total length of all parameters might be limited. Web servers typically log all requested URLs, and this method causes all input parameters to be included in the Web server log, which can be a possible security issue.
The POST method uses a special post protocol for sending the parameters to the server. The POST method allows an unlimited number of input parameters and usually hides them from the Web server log, but this method does not allow the execution to be bookmarked in a Web browser.

Hidden fields are name/value pairs in a form that do not appear as buttons, selection lists, or other visible fields on the HTML page. Hidden fields are frequently used to hold fixed input parameters that do not require user input. For example, the following code specifies the stored process to be executed by this form.

 <INPUT TYPE="hidden"
 NAME="_program" VALUE="/WebApps/Sales/Weekly Report">

The space in the stored process name is not encoded as in the previous URL section. Values in hidden fields and other field types should not be URL-encoded, but might still need to be HTML-encoded if they contain HTML syntax characters such as a less than sign (<), a greater than sign (>), an ampersand (&), or quotation marks (").

Specifying Custom Input Forms

The SAS Stored Process Web Application looks for a custom input form if you add the parameter _ACTION=FORM to the Web application URL. Custom input forms are JSPs under the input folder in the SASStoredProcess directory. For example, the Shoe Sales by Region sample stored process can be accessed with the following code:

 http://yourserver/SASStoredProcess/do?
 _program=/Samples/Stored+Processes/
 Sample:+Shoe+Sales+by+Region&_action=form

Your Web browser will be forwarded as shown here:

 
 http://yourserver/SASStoredProcess
 /input/Samples/Stored_Processes/
 Sample__Shoe_Sales_by_Region.jsp?
 _program=/Samples/Stored+Processes/
 Sample:+Shoe+Sales+by+Region

Note: If a custom input form with zero length is found, then the form will be skipped and the stored process will execute immediately. [cautionend]

In order to create the input form path and name, all names in the stored process path (both folders and the stored process itself in the _PROGRAM parameter) are converted to an equivalent file system path for a JSP file. The following special characters in a folder or stored process name are converted to underscore characters: ' " ;: * ? < >\ | tabs and blank spaces.

For example:

 /Samples/John's Test Area/Test: Hello World (English) V1.0

would be converted to:

 <webapp-home>/input/Samples/John_s_Test_Area/
 Test__Hello_World_(English)_V1.0.jsp

For more information about the SAS Stored Process Web Application and custom input forms, including a sample form, see Custom Input Form.

Custom input forms are provided with most of the sample stored processes that are included in the SAS Web Infrastructure Platform. Custom input form JSP files should be deployed from the Stored Process Web Application configuration area. Consider a stored process with the following name and location:

 /Reports/East Region/Sales Summary 2005

This stored process has a custom input form with the filename Sales_Summary_2005.jsp. It is maintained and deployed from the following location:

 <configuration-directory>\Web\Common\SASServer1\SASStoredProcess9.2\CustomContent\wars\
   sas.storedprocess\ input\Reports\East_Region

Custom input forms should be deployed as part of the sas.storedprocess.war file. The sas.storedprocess.war file is built and deployed by the SAS Web Infrastructure Platform redeployment process.

Note: The SAS Stored Process Web Application is delivered in an EAR file and can be run directly from the EAR file or from the exploded directory. For more information about how to explode the EAR file, see the SAS Intelligence Platform: Web Application Administration Guide. [cautionend]

Specifying Prompt Pages

Prompt pages provide a parameter input page for stored processes that do not have custom input forms. The prompt page is accessed by adding the parameter _ACTION=PROPERTIES to the Web application URL. Parameters must be defined in the stored process metadata in order for them to be visible in a prompt page. For more information about the SAS Stored Process Web Application and prompt pages, see Using the SAS Stored Process Web Application Pages.

If you are unsure whether a stored process has a custom input form, you can specify _ACTION=FORM,PROPERTIES,EXECUTE on the Web application URL. This is the default action for a stored process accessed from the SAS Information Delivery Portal. This action causes the Web application to do the following:

display the custom input form if it exists
display the prompt page if the input form does not exist and the stored process has prompts defined
execute the stored process if there is no custom input form and there are no prompts defined

Top of Page