SAS 9.1.3 Integration Technologies » Developer's Guide


SAS Stored Processes
Software Requirements
Creating Stored Processes
Input Parameters
Result Types
%STPBEGIN and %STPEND
Reserved Macro Variables
Stored Process Server Functions
Sessions
Samples
Debugging
Converting SAS/IntrNet Programs
Using Stored Processes
Building a Web Application
SAS Stored Process Web Application
Configuration
Input
HTTP Headers
Embedding Graphics
Chaining Stored Processes
Using Sessions
Debugging
IOM Direct Interface Stored Processes
SAS Stored Processes

SAS Stored Process Web Application

The SAS Stored Process Web Application is a Java Web application that can execute stored processes and return results to a Web browser. The SAS Stored Process Web Application is similar to the SAS/IntrNet Application Broker, and has the same general syntax and debug options. The SAS Stored Process Web Application is included with the SAS Web Infrastructure Kit, a component of SAS Integration Technologies.

To execute the SAS Stored Process Web Application, enter the application's URL in the Web browser. Either the default Welcome page or static data is displayed.

Here is an example of a URL for the SAS Stored Process Web Application:

   http://yourserver.com:8080/SASStoredProcess/do

In this example, if the Welcome.htm file is installed, then the Welcome page is displayed. The Welcome page might look like this:

SAS Stored Process Web Application welcome page

The Welcome page contains the following three links:

Stored Process Samples
Click this link to display a page of stored process samples that are installed with the SAS Web Infrastructure Kit. See the section about custom input forms for more information.
List Available Stored Processes
Click this link to display a page that contains a tree view of metadata repositories, folders, and stored processes. You can select a stored process in the tree view in order to view metadata for the stored process or to run the stored process. See the section about the stored process list and summary page for more information.
SAS Integration Technologies Documentation
Click this link to display the SAS Integration Technologies documentation library, which contains detailed documentation about each feature of the SAS Integration Technologies product. This link requires Internet access.

In the previous example, if the Welcome.htm file has not been installed, then static data is displayed. The static data might look like this:

   Stored Process Web Application

   Version 9.1 (Build 286)

Note that instead of navigating through this interface from the Welcome page, you can also use the _ACTION and _PROGRAM variables in the URL to open different pages.

Stored Process List and Summary Page

From the Welcome page, you can click the List Available Stored Processes link in order to display a page that is split into sections. (You can also append the _ACTION variable with a value of INDEX (_ACTION=INDEX) to the SAS Stored Process Web Application URL in order to display this page.) On the left is a tree view of metadata repositories, folders, and stored processes. If you drill down in the tree view and select a stored process, then a summary of that stored process is displayed on the right:

Stored process list and summary page

You can also display this summary page by specifying _ACTION=DATA&_PROGRAM=<stored-process-path> on the SAS Stored Process Web Application URL.

The following items are included on this page:

Path
specifies the path to the stored process metadata in the metadata repository. You can use this path as the value for the _PROGRAM variable.
Directory
specifies the source code repository, where the SAS code is located.
File name
specifies the name of the file that contains the SAS code.
SAS server type
specifies the type of server that is used to run the stored process (either a stored process server or a workspace server).
Creation date
specifies the date and time that the stored process metadata was first registered.
Last modified
specifies the date and time that the stored process metadata was last modified.
Keywords
specifies any keywords that are associated with the stored process. These keywords are part of the stored process metadata.
Description
contains a description of the stored process. This description is part of the stored process metadata.

Click Execute at the bottom of the summary to run the stored process. If there are no parameters or input forms, then the stored process will execute immediately and the results will be displayed. If there are parameters or input forms, then you will be taken to the custom input form or property page.

Custom Input Form

If you want the SAS Stored Process Web Application to display a custom input form for a stored process, then you can use any of the following methods:

  • On the Welcome page, click the Stored Process Samples link to display a page of stored process samples that are installed with the SAS Web Infrastructure Kit. Each of these samples has a link and a description. Click any of these links to display the custom input form for that stored process.
  • Use the _PROGRAM variable along with _ACTION=FORM in the URL to display the custom input form for a stored process. See Custom Input Forms for more information.
  • On the stored process summary page, click Execute at the bottom of the summary. If the stored process has a custom input form, then it will be displayed.

A custom input form might look like this:

Stored process custom input form

You can use the custom input form to execute the stored process. In this example, clicking Display SAS Output generates the following results:

Stored process results page

Property Page

A stored process property page can consist of one or more parameters pages and an execution options page. If there are no parameters pages, then the execution options page is displayed. However, if there are any parameters pages, then the top parameters page is displayed first. In order to display the property page for a stored process, you can do one of the following:

  • Use the _PROGRAM variable along with _ACTION=PROPERTIES in the URL to display the property page for a stored process. See Property Pages for more information.
  • On the stored process summary page, click Execute at the bottom of the summary. If the stored process does not have a custom input form, then the property page will be displayed.

Parameters Page

You can click Parameters in the menu on the left side of the property page to display the parameters page. If you have defined parameters groups, then the groups are shown as items in the menu on the left side of the property page. You can click each group name to display the parameters that are in that group. A parameters page without groups might look like this:

Stored process parameters page

This sample parameters page shows four parameters: Date (a date type parameter), Color (a color type parameter), Comment (a multi-line text type parameter), and Name (a string type parameter). Parameters must be defined in the stored process metadata for them to be visible in a property page. The stored process metadata is where the label, type, default value, and constraints for a parameter are defined. Parameter constraints can specify any of the following:

  • a list of values, number of selections allowed, and whether additional values are allowed for date, color, file name, and string parameters.
  • string length for string and multi-line text parameters.
  • a range of values, and the way in which values are incremented for float and integer parameters.

The metadata also indicates whether each parameter is required, modifiable, or visible, and whether each parameter is for expert users only. The asterisks (*) beside Date and Name in the previous example indicate that these are required parameters, which means that the stored process cannot execute until values are provided for these parameters. In this example, all of the parameters are also visible and modifiable.

The parameter type determines how that parameter is displayed in the property page. You can have any of the following types of parameters in this page:

Boolean
displays the parameter label and two radio boxes. You must choose whether the value should be true or false. The default value is false.
Color
displays the parameter label and either a drop-down list, or a text box and a browse [...] button. You can use the text box or drop-down list to specify or select values in the form CXrrggbb, where rr, gg, and bb are two-digit hexadecimal numbers. Any characters that you specify are case-insensitive. You can also click the browse button to display the Choose a Color dialog box, where you can click available colors, specify values, and preview the resulting color.
Date
displays the parameter label and either a drop-down list, or a text box and an browse [...] button. You can use the text box or drop-down list to specify or select values for Date parameters. Date values can be specified with any legal Java date syntax for your locale or with ddmmmyyyy where dd is a one or two digit day, mmm is the English month abbreviation, and yyyy is the four digit year. You can also click the browse button to display the Choose a Date dialog box, where you can click to select a date in the calendar.
File Name
displays a text box or drop-down list where you can enter or select a file name.
Float
displays a text box where you can enter a floating number.
Integer
displays a text box where you can enter an integer.
Multi-line Text
displays a text box, with a scroll bar, where you can enter multiple lines of text.

Note: Multi-line text parameters are not supported for stored processes on workspace servers.
String
displays a text box or drop-down list, where you can enter or select a string.

Execution Options Page

You can click Execution Options in the menu on the left side of the property page in order to view the execution options page, which might look like this:

Stored process execution options page

The following execution options are available by default:

Display results in a new window?
specifies whether to open a new browser window to display the stored process results.
Output type
specifies what kind of output object to deliver. The options are HTML, Rich Text, PDF, and PostScript.
ODS style
specifies the ODS style to use when displaying ODS output.
Graphic device
specifies the type of graphic to generate. The options are GIF, JPEG, ActiveX, Java, ActiveX image, Java image, and SAS EMF.
Show SAS log?
specifies whether to show the SAS log with the stored process results.
Show execution time?
specifies whether to show the amount of time used to process the request. A message like this appears under the stored process results:
   This request took n.nn seconds of real time.
Show execution trace?
specifies whether to set _DEBUG=TRACE for the stored process. See Debugging in the SAS Stored Process Web Application for more information about this debug option.
HTTP method
specifies which HTTP method to use, either GET or POST. See Specifying Name/Value Pairs in an HTML Form for more information about these methods.
Process blank parameter values?
specifies whether parameter values that include blank values are passed to the stored process. If you select No, then blank parameter values are ignored.
Run in the background?
specifies that when the stored process is executed, control is returned to the browser. This option is only available for stored processes with non-streaming results. Running a stored process in the background causes an alert to be created. Your alerts (and any results from the stored process) can be viewed from the Alerts portlet in the SAS Information Delivery Portal. For more information, see Adding and Administering SAS Stored Processes in the "Adding Content to the Portal" chapter in the SAS Intelligence Platform: Web Application Administration Guide.

Click Execute in the menu on the left side of the property page to execute the stored process. If you choose to run a stored process in the background, then you will see a message similar to the following text:

   Stored Process //Repository/path/stored process 
      submitted for background processing.

When executing a stored process using the Web application or Information Delivery Portal, the execution options page will be displayed unless a JSP file exists for the stored process. If you want to customize the execution options page, you can hide or customize some of the options.

To hide or customize an execution option, add an input parameter with a name that corresponds to the execution option. For example, the input parameter named _ODSDEST corresponds to the Output type execution option.

The following table contains a list of the execution options you can hide or customize, and the properties of the input parameters you need to add in order to hide or customize them. This must be done for each individual stored process. For each of these input parameters, specify the type as String. You should select Visible if you are customizing the execution option, but deselect this check box if you are hiding the execution option. You can specify any label for the input parameters.

Execution Option
to Customize
SAS Variable Name
of Input Parameter
Default Value of Input Parameter
Output type _ODSDEST <blank, or any valid ODS destination>
ODS style _ODSSTYLE <blank, or any valid ODS style>
Graphics device _GOPT_DEVICE <blank, or any valid SAS/GRAPH device driver>
Show SAS Log
Show execution time
Show execution trace
_DEBUG <blank, or any valid value for the debugging flag>

You can completely eliminate the execution options page by creating a JSP file for the stored process. See Custom Input Forms for more information.

Error Page

If there is an error while the stored process is running, then you will get an error message with a button that you can click to show the SAS log.

Error page

In order to disable the Show SAS Log button, you can set the Web application initialization parameter DebugMask to disable debug logging.

For more information about customizing the SAS Stored Process Web Application, see SAS Stored Process Web Application Configuration. For more information about Web application input, see Web Application Input.