Converting SAS/IntrNet Programs to Stored Processes

Stored processes provide a conversion path for existing SAS/IntrNet applications, enabling them to take advantage of the SAS 9 BI Architecture. Many features are implemented in the stored process server and SAS Stored Process Web Application to minimize code changes required during a conversion. Existing SAS/IntrNet Application Dispatcher programs can usually be converted to streaming stored processes with minimal or no modifications. Conversion of existing programs requires the following steps:

1. Install and configure the SAS Web Infrastructure Kit, a component of SAS Integration Technologies that includes the SAS Stored Process Web Application used to emulate Application Dispatcher.

2. Modify the program as required to address the compatibility issues discussed in the Issues section.

3. Copy the program to a valid source code repository for a stored process server. SAS/IntrNet programs must be registered on a stored process server; workspace servers do not support streaming output or a number of other SAS/IntrNet compatibility features.

4. Register the stored process using BI Manager. Choose Streaming for the type of output. You do not need to register any parameter definitions.

5. Convert any HTML input forms or HTML pages that link to your stored process to use the SASStoredProcess URL syntax as described in the Issues section.

6. Run the stored process.

Note: SAS/IntrNet programs converted to stored processes using the techniques described here are intended to run in the SAS Stored Process Web Application. These stored processes might not run in other stored process clients (such as SAS Web Report Studio or SAS Add-In for Microsoft Office.) Each client application has its own requirements for stored process behavior.

Compatibility Features

• The SAS Stored Process Web Application (a component of the SAS Web Infrastructure Kit) provides the middle-tier equivalent of the Application Broker. The SAS Stored Process Web Application is a Java-based application and requires a servlet container host such as Apache Tomcat. See the SAS Web Infrastructure Kit installation instructions for other requirements.

• The SAS Stored Process Server (a component of SAS Integration Technologies) provides the equivalent of the Application Server. The typical stored process server configuration (a load-balanced cluster) is very similar in functionality to a SAS/IntrNet pool service. New servers are started as demand increases to provide a highly scalable system.

• Streaming output from a stored process is written to the _WEBOUT fileref. The underlying access method has changed, but the functionality is very similar. ODS, HTML Formatting Tool, DATA step, or SCL programs can continue to write output to _WEBOUT.

• The Application Server functions (APPSRVSET, APPSSRVGETC, APPSRVGETN, APPSRV_HEADER, APPSRV_SESSION, and APPSRV_UNSAFE) are supported in stored processes except as noted in the following issues. In many cases, there are equivalent STPSRV functions that are recommended for new programs.

• The _REPLAY mechanism is supported by the stored process server. The value of the _REPLAY URL has changed, but this does not affect most programs.

• The SAS/IntrNet sessions feature has been implemented by the stored process server. The same SAVE library, session macro variables, and session lifetime management functions are available.

Issues

There are a number of differences in the stored process server environment that might affect existing SAS/IntrNet programs. Use this list as a review checklist for your existing programs.

• HTTP headers cannot be written directly to _WEBOUT using a DATA step PUT statement or SCL fwrite function. You must use the STPSRV_HEADER (or APPSRV_HEADER) functions to set header values. Automatic header generation cannot be disabled with appsrvset("automatic headers", 0).

  The Location header record does not currently work with stored processes because the HTTP status code cannot be set.

• Unsafe processing is different for stored processes — there is no UNSAFE option. Unsafe characters are quoted instead of removed from the input parameters, so you can safely use the &VAR syntax without worrying about unsafe characters. The following examples work without using the APPSRV_UNSAFE function.

     %if &MYVAR eq %nrstr(A&P) %then do something...;
  

  Another example:

     data _null_;
        file _webout;
        put "MYVAR=&MYVAR";
        run;
  

  APPSRV_UNSAFE works in the stored process server and still returns the complete, unquoted input value. This change might cause subtle behavioral differences if your program relies on the SAS/IntrNet unsafe behavior.

• The stored process server cannot directly execute SOURCE, MACRO, or SCL catalog entries. You must write a wrapper .sas source code file that executes the catalog entry.

• The _REPLAY macro variable does not have the same syntax in stored processes as it did in Application Dispatcher. References to &_REPLAY are not recommended for SAS/IntrNet programs, but can be used in stored processes. The DATA step function symget('_REPLAY') does not return a usable URL in a stored process and should be replaced with "&_REPLAY". For example,

     url = symget('_REPLAY') || ...url parameters...
  

  should be changed to

     url = "&_REPLAY" || ...url parameters...
  

• _SERVICE, _SERVER, and _PORT do not exist for stored processes. You must review any code that uses these macro variables. Usually, they are used to create drill-down URLs or forms. In many cases, this code does not require any change; input values for these variables are ignored.

• _PROGRAM refers to a stored process path, and not a three or four-level program name. Any programs that create drill-down links or forms with _PROGRAM must generally be modified to use the stored process path.

• There is no REQUEST TIMEOUT functionality in SAS Stored Processes. appsrvset('request timeout') is not supported.

• The Application Server functions APPSRV_AUTHCLS, APPSRV_AUTHDS, and APPSRV_AUTHLIB are not supported in stored processes. There are no STPSRV functions that are equivalent to these Application Server functions.

• Stored processes do not support automatic user exit programs such as REQUEST INIT, REQUEST TERM, REQUEST LOGIN, SESSION INIT, SESSION TERM, and SESSION INVSESS. SAS/IntrNet applications that rely on these features will require modifications to implement equivalent functionality. In most cases, all relevant stored process source code must be changed to explicitly call user exits when necessary. There is no support for REQUEST LOGIN or SESSION INVSESS functionality in the SAS Stored Process Web Application, although similar functionality can be implemented in a custom Web interface.

• If you are writing to _WEBOUT using PUT statements while ODS has _WEBOUT open, when you execute the code the PUT statement data might be out of sequence with the data generated by ODS. This problem occurs because both your code and ODS are opening the same fileref at the same time. For example, the following code might not always work as expected:

     ods listing close;
     ods html body=_webout path=&_tmpcat
        (url=&_replay) Style=Banker;
     ... other code ...
     data _null_;
        file _webout;
        put '<p align="center">&#160;</p>' ;
        put '<p align="center"><b>Test.
           If you see this in order, it worked.</b></p>';
        run;
     ... other code ...
     ods html close;
  

  This code might work in some SAS/IntrNet programs, but it can cause data order problems even in SAS/IntrNet. This code is more likely to fail in a stored process. This problem can be fixed by inserting your PUT statements before you open ODS, closing ODS while you write directly to the fileref, or using the ODS HTML TEXT="string" option to write data. The following code is an example of how you can both close ODS while you write directly to the fileref, and insert your PUT statements before you open ODS:

     ods html body=_webout (no_bottom_matter)...;
     ... other code ...
     ods html close;
   
     data _null_;
        file _webout;
        put '<p align="center">&#160;</p>' ;
        put '<p align="center"><b>Test.
           If you see this in order, it worked.</b></p>';
        run;
   
     ods html body=_webout (no_top_matter)...;
     ... other code ...
     ods html close;
  

  The following code is an example of how you can use the ODS HTML TEXT="string" option to write data:

     ods listing close;
     ods html body=_webout path=&_tmpcat
        (url=&_replay) Style=Banker;
     ... other code ...
     ods html text='<p align="center">&#160;</p>' ;
     ods html text='<p align="center"><b>Test.
        If you see this in order, it worked.</b></p>';
     ... other code ...
     ods html close;