Converting SAS/IntrNet Programs to SAS Stored Processes

Example

The following software makes up the environment for this example:

The Web server for the SAS/IntrNet portion of the example is Microsoft Internet Information Services (IIS) 6.0.
JBoss is the servlet container that is being used for this example. Other valid servlet containers include BEA WebLogic and IBM WebSphere.
SAS 9.2
SAS Stored Process Server (as opposed to the SAS Workspace Server)
Windows middle tier
Windows SAS server tier

About the Application Dispatcher Program

The Program Component

The example in this appendix uses ODS and the TABULATE procedure to display shoe sales data for a selected region. Here's the SAS code:

%global regionname;
      
ods listing close;
ods html body=_webout;

proc tabulate data = sashelp.shoes format = dollar14.;
title "Shoe Sales for &regionname";
   where (product =: 'Men' or product =: 'Women') & region="&regionname";
   table Subsidiary all, 
        (Product='Total Product Sales' all)*Sales=' '*Sum=' ';
   class Subsidiary Product;  
   var Sales;
   keylabel All='Grand Total' 
            Sum=' ';
run;

ods html close;

For the sake of illustration, assume that this SAS code is stored in the location C:\MySASFiles\intrnet\webtab1.sas.

The Input Component

The following HTML is the body for the input component, which is the physical HTML file. For the sake of illustration, assume that this HTML is stored in a file named webtab1.html.

<H1>Regional Shoe Sales</H1>
<p>Select a region in order to display shoe sales data for that 
region by subsidiary and style.  This sample program uses ODS and 
the TABULATE procedure.</p>

<HR>

<FORM ACTION="/sasweb/cgi-bin/broker.exe">
<INPUT TYPE="HIDDEN" NAME="_SERVICE" VALUE="default">
<INPUT TYPE="HIDDEN" NAME="_PROGRAM" VALUE="intrnet.webtab1.sas">

<b>Select a region:</b>  <SELECT NAME="regionname">
<OPTION VALUE="Africa">Africa
<OPTION VALUE="Asia">Asia
<OPTION VALUE="Central America/Caribbean">Central America/Caribbean
<OPTION VALUE="Eastern Europe">Eastern Europe
<OPTION VALUE="Middle East">Middle East
<OPTION VALUE="Pacific">Pacific
<OPTION VALUE="South America">South America
<OPTION VALUE="United States">United States
<OPTION VALUE="Western Europe">Western Europe
</SELECT>

<HR>
<INPUT TYPE="SUBMIT" VALUE="Execute">
<INPUT TYPE="CHECKBOX" NAME="_DEBUG" VALUE="131">Show SAS Log

</FORM>

The input component looks like the one shown in the following display.

Application Dispatcher Input Component

[Application Dispatcher Input Component]

You can select a region from the list and click Execute to display a table of sales data for that region. When you click Execute, Application Dispatcher executes the program and sends the results back to the Web browser. The results look like the program output shown in the following display.

Application Dispatcher Program Output

[Application Dispatcher Program Output]

The HTML form created the following URL for the results page, based on the default selections in the input form:

http://myserver/sasweb/cgi-bin/broker.exe?
_SERVICE=default&_PROGRAM=intrnet.webtab1.sas&regionname=Africa

The URL is typically built for you by the Web browser which uses fields in an HTML form. The HTML page uses the following FORM tag to submit the program to the Application Broker:

<FORM ACTION="/sasweb/cgi-bin/broker.exe">

The following hidden fields are used to create name/value pairs to complete the required syntax:

<INPUT TYPE="HIDDEN" NAME="_SERVICE" VALUE="default">
<INPUT TYPE="HIDDEN" NAME="_PROGRAM" VALUE="intrnet.webtab1.sas">

Notice that the value for _PROGRAM is set to intrnet.webtab1.sas. This first level indicates that the program is stored in a directory identified by the intrnet fileref. The next two levels (webtab1.sas) provide the name of the program that is executed.

Note: Several samples ship with Application Dispatcher, and you can use these samples to practice the conversion to stored processes. (Some of these samples have already been converted to stored process samples, and these samples are installed with SAS Integration Technologies.) You can execute the Application Dispatcher samples from the following URL: http://myserver/sasweb/IntrNet9/dispatch/samples.html [cautionend]

Converting the Application Dispatcher Program to a Stored Process

Step 1: Copy the Source Program

To preserve the functionality of the original SAS/IntrNet example, copy the SAS program to a new location before modifying it. Copy the webtab1.sas program from C:\MySASFiles\intrnet to a location on the stored process server, such as C:\MySASFiles\storedprocesses.

Step 2: Modify the Program As Needed

Open the new copy of webtab1.sas to check for conversion considerations.

%global regionname;
      
ods listing close;
ods html body=_webout;

* PROC TABULATE code here;

ods html close;

Note that the program is already writing to _WEBOUT, so %STPBEGIN and %STPEND are not needed. However, replacing the ODS HTML statement with %STPBEGIN and %STPEND makes it easier to run the stored process from various clients. This replacement also enables you to run the code from a client like the SAS Stored Process Web Application and specify different values for _ODSDEST. For example, you can change the values of _ODSDEST and generate output as PDF, RTF, or PostScript, without making any SAS code changes.

For this example, delete the two ODS statements at the beginning of the code, and replace them with the following lines of code:
```
*ProcessBody;
%stpbegin;
```
Note: The *ProcessBody; comment is not necessary for this program because this example does not use a workspace server, but add it to your program as a best practice. Fewer changes are necessary if you ever want to run this stored process from a workspace server.

Replace the ODS statement at the end of the code with the following statement:
```
%stpend;
```
Check the list of conversion considerations. No further code changes are necessary for this program to run as a stored process. The stored process now consists of the following code:
```
%global regionname;

*ProcessBody;
%stpbegin;

* PROC TABULATE code here;

%stpend;
```
Save the changes and close webtab1.sas.

Step 3: Register the Stored Process in SAS Management Console

Note: Before you can register a stored process, a server must be defined for the stored process to run on. Converted SAS/IntrNet programs generally should be registered on a stored process server; workspace servers do not support streaming output or a number of other SAS/IntrNet compatibility features. If a stored process server is not already defined, then you can use the Server Manager in SAS Management Console to define a server. For more information about how to define a server, see the Help for the Server Manager. [cautionend]

To register a new stored process, complete the following steps:

From the Folder view in SAS Management Console, select the folder in which you would like to create the new stored process. For this example, create a /Converted Samples folder.

To create a new folder, navigate to where you want to put the new folder. Select Actions New Folder. The New Folder Wizard appears.
Select Actions New Stored Process. The New Stored Process Wizard appears.

In the New Stored Process Wizard, complete the following steps:

Enter the following information on the first page of the wizard:

Name: Regional Shoe Sales

Description: Converted from SAS/IntrNet program.

New Stored Process Wizard - Name Specification
Click Next.

On the next page of the wizard, specify the following information:

	SAS server: SASMain -- Logical Stored Process Server
	Source code repository: C:\MySASFiles\storedprocesses (A source code repository is a location on the application server that contains stored process source code. Click Manage if you need to add a new source code repository to the list. For more information about the source code repository, see the New Stored Process Wizard Help.)
	Source file: webtab1.sas
	Output: Streaming

New Stored Process Wizard - Execution Details

[New Stored Process Wizard - Execution Details]

Click Next.

The next page of the wizard is where you add parameters. Parameters are optional unless you plan to execute the stored process in other clients that need the metadata information in order to build a dialog box, or if you want to take advantage of the dynamic prompt page that is built by the SAS Stored Process Web Application. Parameters are also useful if you want to restrict input values or types of input. Do not define any parameters right now.
Click Finish to register the new stored process.

Note: After you have registered the stored process, use the Stored Process Properties dialog box to control access to the stored process. For more information, see the Help for the Stored Process Properties dialog box. [cautionend]

Step 4: Create a New JSP Page and Modify the HTML

To preserve the functionality of the original SAS/IntrNet example, copy the HTML file to a new location before modifying it.

Note: This example shows you how to use the input component from the Application Dispatcher program as a custom input form for the stored process. You will be able to use the _PROGRAM variable along with _ACTION=FORM in the URL to display the custom input form for the stored process. However, copying the HTML file is optional. You can run stored processes without a custom input form. [cautionend]

If you want this Web page to be used as the default input form in the SAS Stored Process Web Application, then copy the webtab1.html file to a physical location under the JBoss folder. The exploded directory might be something like C:\Program Files\JBoss\server\SASServer1\deploy_sas
\sas.storedprocess9.2.ear\sas.storedprocess.war\input\Converted_Samples. (The physical location corresponds to the metadata location. This location is correct only if the new stored process is registered in the /Converted Samples folder in the metadata repository. Otherwise, the path will be different.)

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.

You can also copy the HTML file to a new directory under the IIS Web Server, or to a new directory under the JBoss folder with the SAS Stored Process Web Application. However, if you decide to do this, you should be aware that appending _ACTION=FORM to the URL to find the custom input form will not work.

Modify the HTML page to call the stored process instead of the SAS/IntrNet program.

Open webtab1.html in an HTML editor.
Change the value of the ACTION attribute in the FORM tag to http://myserver:8080/SASStoredProcess/do.
Remove the hidden field for _SERVICE.
Change the value of the hidden field for _PROGRAM to the metadata location, and name of the stored process: /Converted Samples/Regional Shoe Sales.
You can leave the _DEBUG check box with a value of 131. This is equivalent to the value LOG,TIME,FIELDS.
You can change the text that appears on the Web page. If you want to use images, then you need to move them to a location in the current directory or change the tag to point back to the old directory.

The body of the file now contains the following HTML:

<H1>Regional Shoe Sales</H1>
<p>Select a region in order to display shoe sales data for that 
region by subsidiary and style.  This sample program uses ODS and 
the TABULATE procedure.</p>

<HR>

<FORM ACTION="http://myserver:8080/SASStoredProcess/do">
<INPUT TYPE="HIDDEN" 
   NAME="_PROGRAM" VALUE="/Converted Samples/Regional Shoe Sales">

<b>Select a region:</b>  <SELECT NAME="regionname">
<OPTION VALUE="Africa">Africa
<OPTION VALUE="Asia">Asia
<OPTION VALUE="Central America/Caribbean">Central America/Caribbean
<OPTION VALUE="Eastern Europe">Eastern Europe
<OPTION VALUE="Middle East">Middle East
<OPTION VALUE="Pacific">Pacific
<OPTION VALUE="South America">South America
<OPTION VALUE="United States">United States
<OPTION VALUE="Western Europe">Western Europe
</SELECT>

<HR>
<INPUT TYPE="SUBMIT" VALUE="Execute">
<INPUT TYPE="CHECKBOX" NAME="_DEBUG" VALUE="131">Show SAS Log

</FORM>

Save the file as Regional Shoe Sales.jsp, and close it.

Note: If this JSP file is located somewhere other than in the SAS Stored Process Web Application directory, then you need to specify the complete URL to the stored process servlet, as follows, in the ACTION attribute in the FORM tag: http://myserver:8080/SASStoredProcess/do. Otherwise, this URL can be a relative link, as follows: /SASStoredProcess/do. If you do place the JSP file under the same directory as the SAS Stored Process Web Application, then you need to be careful to preserve the application if you later upgrade or redeploy the SAS Stored Process Web Application. [cautionend]

You should also convert any HTML pages that link to your stored process to use the SASStoredProcess URL syntax. For example, you might use the following URL to link to the Hello World sample program using the Application Broker:

http://myserver/cgi-bin/broker?
_service=default&_program=sample.webhello.sas

The URL specifies your Application Server, an absolute path to the Application Broker, and the query string (followed by the question mark character). The query string contains the name/value pair data that is input to the application. Each name is separated from the following value by an equal sign (=). Multiple name/value pairs are separated by an ampersand (&). The Web page that executes an Application Dispatcher program must pass the _SERVICE and _PROGRAM variables. In this example, the _SERVICE=DEFAULT pair specifies the service that handles this request, and the _PROGRAM=SAMPLE.WEBHELLO.SAS pair specifies the library, name, and type of request program to be executed.

For the SAS Stored Process Web Application, the URL in the preceding example would need to be changed. You might use the following URL if you want to run the program from the SAS Stored Process Web Application:

http://myserver:8080/SASStoredProcess/do?
_program =/Samples/Stored+Processes/Sample:+Hello+World

The URL specifies your stored process server, an absolute path to the SAS Stored Process Web Application (instead of the Application Broker), and the query string. Notice that /cgi-bin/broker? has been replaced with the stored process Web application equivalent: /SASStoredProcess/do?. The _SERVICE name/value pair is not used with stored processes, and _PROGRAM is the reserved input parameter that specifies the metadata location and the name of the stored process to be executed.

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 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 /Samples/Stored+Processes/Sample:+Hello+World actually identifies the stored process named Sample: Hello World. The space in the name is encoded as a plus sign (+). If your parameter values contain special characters, then they should be URL-encoded.

Step 5: Execute the Stored Process Using the New JSP Page

You can use _ACTION=FORM in the URL in order to display the custom input form. For example, type the following URL in a Web browser:
```
http://myserver:8080/SASStoredProcess/do?
_program=/Converted+Samples/Regional+Shoe+Sales&_action=form
```
Your Web browser is forwarded to the following URL, which displays the modified custom input form:
```
http://myserver:8080/SASStoredProcess/input/Converted_Samples/
Regional_Shoe_Sales.jsp?_program=/Converted Samples/Regional Shoe Sales
```
Note: Be sure to start JBoss first.
Select the default region (Africa) and click Execute.

The JSP page executes the stored process by using the following generated URL:
```
http://myserver:8080/SASStoredProcess/do?
_PROGRAM=/Converted Samples/Regional Shoe Sales&regionname=Africa
```
The results look like the results from the Application Dispatcher program as shown in the following display:

Stored Process Results

Adding a Parameter to the Stored Process Definition

Step 1: Modify the Stored Process Metadata Definition

Parameter definitions are not required if you are converting a SAS/IntrNet program to a stored process. If macro variables in the program are used to substitute parameter values in the program, you can define the macro variables as parameters to the stored process. If you define the value as a parameter, it means that other clients can use the metadata to create a dialog box that prompts for the parameter, or you can use the dynamic prompt page that is built by the SAS Stored Process Web application. If you do not define the parameter, it means that the program must use defaults in the code if you want to execute the stored process in other clients. If you intend to use the stored process in other clients, then you should define parameters in the metadata.

In webtab1.html and webtab1.sas, the REGIONNAME macro variable is substituted into the PROC TABULATE code. Because the HTML form uses a drop-down list, you can count on a valid value always being passed to the program from that Web page. If you want to make sure this stored process runs correctly in other clients (or if you want to use the dynamic prompt page that was built by the SAS Stored Process Web Application), then you need to define a parameter that returns a macro variable named REGIONNAME with a valid list of regions.

To add the REGIONNAME parameter, complete the following steps:

In SAS Management Console, open the Stored Process Properties dialog box for the Regional Shoe Sales stored process.
On the Parameters tab, click New Prompt.
On the General tab of the New Prompt dialog box, specify the following information:

Name: regionname

Displayed text: Select a region

Options: Requires a non-blank value

New Prompt Dialog Box: General Tab

In the Prompt Type and Values tab of the New Prompt dialog box, specify the following information:

	Prompt type: Text
	Method for populating prompt: User selects values from a static list
	Number of values: Single value
	List of values: Africa Asia Central America/Caribbean Eastern Europe Middle East Pacific South America United States Western Europe

For the List of Values table, click Add to add each value. Click the radio button for Default next to Africa. For more information about these fields, see the help for this dialog box.

New Prompt Dialog Box: Prompt Type and Values Tab

[Constraints Dialog Box]

Click OK in the New Prompt dialog box, and then click OK in the Stored Process Properties dialog box.

Step 2: Execute the Stored Process Using the Dialog Box

To view the parameter that you added to the stored process metadata definition, execute the stored process using the SAS Stored Process Web Application dialog box instead of the custom input form. The dialog box uses the parameter that you defined in the New Stored Process Wizard when you registered the stored process metadata. To access the dialog box for this stored process, type the following URL in a Web browser:

http://myserver:8080/SASStoredProcess/do?
_PROGRAM=/Converted Samples/Regional Shoe Sales&_action=properties

SAS Stored Process Web Application: Dialog Box

[SAS Stored Process Web Application - Property Sheet]

Select the default region (Africa) and click Execute. You see the same results (the table of shoe sales for Africa that was shown in Step 5: Execute the Stored Process Using the New JSP Page) displayed in a separate Web browser window.

Top of Page

	Name: Regional Shoe Sales
	Description: Converted from SAS/IntrNet program.

	Name: regionname
	Displayed text: Select a region
	Options: Requires a non-blank value