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 normally 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 created and submitted by JavaScript or a similar scripting technology in the Web browser.

The HTML page using these techniques can be a static HTML page or a dynamic page 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 described in the Input Parameters section. Reserved parameter names should be used only as recommended.

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 generally will 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 URL

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

specifies two name/value pairs. 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 equals (=). Multiple name/value pairs are separated by ampersands (&). In this example, _program=/WebApps/Sales/Weekly+Report is the reserved input parameter that specifies the stored process 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 (most punctuation characters, including spaces) in a value must be URL encoded. Spaces can be encoded as a plus (+) 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 (+). If your parameter values might contain special characters, 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 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 browsers. Use HTML encoding to avoid this problem. For example, use

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

instead of

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

The HTMLENCODE DATA step function can be used to encode the URL in a stored process. If we assume the variable myurl contains a URL with various input parameters, then the following code:

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

creates an anchor tag in the variable atag that is properly encoded.

Note that some 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, resulting 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.

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. Any HTML reference book will document forms and provide numerous examples. A few issues related to stored process input parameters in HTML forms are discussed below.

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 discussed in the previous section. The GET method enables the user to bookmark a specific stored process execution, including all input parameters, but might be limited in the total length of all parameters. Web servers typically log all requested URLs and this method causes all input parameters to be included in the Web server log (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 does not allow the execution to be bookmarked in a browser.

Hidden fields are name/value pairs in a form that do not appear as buttons, selection lists, or other visible fields in the HTML page. Hidden fields are frequently used to hold fixed input parameters that do not require user input. For example,

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

specifies the stored process to be executed by this form. Note that 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 less than (<), greater than (>), ampersand (&), or quotation marks (").

Custom Input Forms

The SAS Stored Process Web Application will look 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:

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

Your browser will be forwarded to

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

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: ' " : * ? < > | 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, see Custom Input Form.

Custom input forms are provided with most of the sample stored processes that are included in the SAS Web Infrastructure Kit.

As a best practice, custom input form JSP files should be deployed from the Stored Process Web Application install area. For the previous Shoe Sales by Region example, in a Windows environment, this would be:

   <install root>\Web\Portal2.0.1\SASStoredProcess\
      input\Samples\Stored_Processes

The path to the custom input form is determined by the location of the stored process entry in metadata. For example, a stored process located in the repository as

   /Reports/East Region/Sales Summary 2005

would have a custom input form maintained and deployed from this location:

   <install root>\Web\Portal2.0.1\SASStoredProcess\
      input\Reports\East_Region

with the file name, Sales_Summary_2005.jsp. Custom input forms should be deployed as part of the SASStoredProcess.war file. The SASStoredProcess.war file is built and deployed by the SAS Web Infrastructure Kit redeployment process (see Re-Create and Redeploy the Portal Web Application in the SAS Intelligence Platform: Web Application Administration Guide).

Property Pages

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

If you are unsure whether a stored process has a custom input form, you can specify _ACTION=FORM,PROPERTIES on the Web application URL. This causes the Web application to display the custom input form if it exists or display the property page if the input form does not exist. This is the default action for a stored process accessed from the SAS Information Delivery Portal.