SAS 9.1.3 Integration Technologies » Developer's Guide

SAS BI Web Services

Writing SAS Programs for Web Services

To use the Web service to call your SAS code, you must configure your SAS code as a stored process. The stored process used with Web Services needs to conform to a few rules which enable the Web service to both receive data from the client and return data to the client.

You can author a stored process manually by using SAS or a text editor to write the code and then registering the program through SAS Management Console. Alternatively, you can use a program such as Enterprise Guide or another SAS code generator to author a stored process using the "point-and-click" method. Use the modifications below to make a stored process that can be used with SAS BI Web Services. Keep in mind that SAS BI Web Services can only return data; no images can be returned.

SAS programs are stored in external files that usually have a .SAS filename extension in directory-based operating environments. For z/OS, the files must be contained in a partitioned data set (PDS). SAS programs can contain a DATA step, procedures, and macro code.

The following list explains unique details about Web service stored processes:

The data returned by the stored process must be XML.
The %STPBEGIN or %STPEND macros are not used with Web service stored processes. These macros set up ODS statements for the stored process, but Web services do not use ODS.
Web service stored processes produce streaming results, which means that the SAS program writes output to _WEBOUT, typically by using the following LIBNAME statement:
```
   libname _WEBOUT xml xmlmeta=&_XMLSCHEMA;
```
The _XMLSCHEMA macro is unique to Web services. This macro is passed to the SAS program when it is invoked from the Web service. The _XMLSCHEMA macro is set to one of three values depending on the Content property that gets passed to the Execute call. The possible values for _XMLSCHEMA are Schema, SchemaData (which is the default), or Data. For example,
```
   libname _WEBOUT xml xmlmeta=SchemaData;
```
causes SAS to write both the XML schema and the data into the libref _WEBOUT. A libref uses a fileref of the same name when a source is not specified on the LIBNAME statement. For example,
```
   libname _WEBOUT xml xmlmeta=_XMLSCHEMA;
```
causes the libname, called _WEBOUT, to read from the fileref called _WEBOUT. For Web services, SAS defines the filerefs for _WEBOUT and the input parameter streams before invoking the SAS code.

Note: Applications should not try to write multiple data sets into a library when a schema is being created.
Input streams are unique to Web services. Input streams are filerefs that contain XML.

The following example code displays a stored process used as a Web service.

   libname instream xml;
   libname _WEBOUT xml xmlmeta=&_XMLSCHEMA;

   proc means data=instream.&tablename;
      output out=_WEBOUT.mean;
   run;

The first LIBNAME statement in the sample code defines the input stream. This code corresponds to the definition of the input stream in the Streaming Details dialog box in BI Manager. The name of the input stream is instream. In this example, the input stream provides the data to run PROC MEANS against.

The second LIBNAME statement in the sample code defines the output for the stored process as streaming output, or _WEBOUT. In BI Manager, Streaming is specified as the type of output on the Execution tab of the Stored Process Properties dialog box.

The &tablename in the sample code defines a parameter called tablename. In BI Manager, this parameter is specified through the Add Parameter dialog box, and can be modified using the Modify Parameter dialog box. In this example, tablename is a string parameter that specifies the name of the table to run PROC MEANS against.

Note: The dialog boxes mentioned in the previous example are available from both the Stored Process Properties dialog box and the New Stored Process Wizard, which are both part of BI Manager. For more information about using BI Manager to define metadata for stored processes, see the product Help.