Writing a Stored Process

Using the %STPBEGIN and %STPEND Macros

The %STPBEGIN and %STPEND macros provide standardized functionality for generating and delivering output from a stored process. This enables you to write stored processes that generate content in a variety of formats and styles with minimal programming effort. Here is a typical stored process that uses these macros:

 /* *****************************************************
 * Header comment documenting your
 * stored process and input parameters.
 * ************************************************** */
 %global input parameters;
 *ProcessBody;

 ... any pre-processing of input parameters ...

 %stpbegin;

 ... stored process body ...

 %stpend;

Note: You must include a semicolon at the end of the %STPBEGIN and %STPEND macro calls.

The %STPBEGIN macro initializes the Output Delivery System (ODS) to generate output from the stored process. The %STPEND macro terminates ODS processing and completes delivery of the output to the client or other destinations. The macros must be used as a matched pair for proper operation. Streaming output and package output are supported. These macros rely on many reserved macro variables to control their actions. For a more detailed description of each macro variable mentioned in the following sections, see Using Reserved Macro Variables.

Stored processes that do not use ODS to generate output should not use these macros or should set _ODSDEST to NONE to disable ODS initialization. In these cases, your stored process must explicitly create any output. [cautionend]

ODS Options

ODS options are specified by various global macro variables. These variables are normally set by input parameters, but can be modified by the stored process. The following variables affect ODS output:

_ENCODING
_GOPT_DEVICE
_GOPT_HSIZE
_GOPT_VSIZE
_GOPT_XPIXELS
_GOPT_YPIXELS
_GOPTIONS
_ODSDEST
_ODSOPTIONS
_ODSSTYLE
_ODSSTYLESHEET

The _ODSDEST variable is important because changing this variable enables your stored process to generate HTML, PDF, PostScript, or a variety of other formats, including user-written tagset destinations. Many variables allow you to override ODS options. You must remember to verify whether any options that are specified by the stored process or its clients are compatible with the output destinations that you plan to support.

Some ODS options (for example, BASE ) are set based on the result options. For more information, see Results. These options are generally transparent to the stored process author, but they can make it difficult to modify some ODS options in your stored process.

Overriding Input Parameters

Macro variables that are recognized by the %STPBEGIN macro can be set or modified by the stored process. This is usually done to deny or limit client choices for that variable. For example, a stored process that requires the use of a particular style might begin with the following statements:

 %global _ODSSTYLE;
 *ProcessBody;

 %let _ODSSTYLE=MyStyle;

 %stpbegin;

Any client-specified value for the _ODSSTYLE variable is ignored and the MyStyle style is always used. A more elaborate implementation might validate an input parameter against a list of supported values and log an error or choose a default value if the client input is not supported.

A stored process can modify the macro variables that are used by the %STPBEGIN macro at any time until %STPBEGIN is called. Modifying these reserved macro variables after %STPBEGIN has been called is not recommended.

Results

The %STPBEGIN and %STPEND macros implement several options for delivering results. For an introduction to the standard options for stored process results, see Setting Result Capabilities. In most cases, a stored process that uses these macros can support all the standard result types with no special coding. The _RESULT variable defines the result type. The following values are supported:

STATUS: returns only a completion status. An ODS destination is not opened, but the ODS LISTING destination is closed.
STREAM: returns the body or file output from ODS as a stream. This is the default result type if _RESULT is not set.

There are several values for _RESULT that generate packages. Packages can be delivered directly to the client and published to a more permanent location on the server file system, a WebDAV server, or other destinations. Package creation and delivery are controlled by many reserved macro variables. Here are the variables that are valid for all package destinations:

_ABSTRACT
_DESCRIPTION
_EXPIRATION_DATETIME
_NAMESPACES
_NAMEVALUE

Here are additional variables that are recognized for specific _RESULT settings:

PACKAGE_TO_ARCHIVE: creates an archive package on the server file system that contains the generated output. The _ARCHIVE_PATH and _ARCHIVE_NAME variables specify where the package is created. In addition, _ARCHIVE_FULLPATH is set by %STPEND to hold the full pathname of the created archive package.
PACKAGE_TO_REQUESTER: returns a package to the stored process client. It can also simultaneously create an archive package on the server file system if _ARCHIVE_PATH and _ARCHIVE_NAME are set. This option is valid only on the workspace server.
PACKAGE_TO_WEBDAV: creates a package as a collection on a WebDAV-compliant server. The location of the package is defined by _COLLECTION_URL or _PARENT_URL. Other relevant variables include _HTTP_PASSWORD, _HTTP_PROXY_URL, _HTTP_USER, and _IF_EXISTS.

The %STPBEGIN macro configures ODS to create output files in a temporary working directory. The %STPEND macro then creates the package from all of the files in this temporary directory. The temporary directory is defined by the _STPWORK variable. This variable should not be changed by the stored process, but new entries can be added to the output package by creating files in this directory. For example, the XML LIBNAME engine might be used to create one or more XML files that would be included in the package along with any output that was created by ODS. The temporary directory and any files that are contained in it are automatically deleted when the stored process completes. No cleanup is required in the stored process program.

Note: If the environment variable STPWORK is not set when the server is started, then STPBEGIN determines a temporary directory based on the operating system, and places that value in the _STPWORK reserved macro variable. If the environment variable STPWORK is set when the server is started, then STPBEGIN uses the directory specified as a starting point to create the temporary directory. For example, the STPWORK environment variable is set to /usrs/. STPBEGIN creates a temporary subdirectory under /usrs/ and places the full path to the temporary directory in the _STPWORK reserved macro variable. [cautionend]

Errors

Errors in the %STPBEGIN and %STPEND macros are reported in the _STPERROR macro variable. A value of 0 indicates that the macro completed successfully. A nonzero value indicates that an error occurred.

Because these macros allow clients or stored processes to submit SAS language options (for example, the _ODSOPTIONS variable), it is possible for the macros to fail in unusual ways. Invalid input parameters can cause the stored process to go into syntaxcheck mode (when the SAS OBS option is set to 0) or to terminate immediately.

Advanced Package Publishing

The %STPBEGIN and %STPEND macros support some package publishing options that are not recognized by the stored process metadata framework. These options are generally accessed by registering a stored process with no output type. This causes the stored process to be executed with _RESULT set to STATUS . The stored process can then set _RESULT to one of the following values:

PACKAGE_TO_ARCHIVE

provides several new options when used in this way. Archive packages can be created on HTTP servers that support updates and FTP servers. Variables that control this option include the following:

_ARCHIVE_NAME
_ARCHIVE_PATH
_FTP_PASSWORD
_FTP_USER
_HTTP_PASSWORD
_HTTP_PROXY_URL
_HTTP_USER

PACKAGE_TO_EMAIL

creates a package and mails it to one or more e-mail addresses. An actual archive package can be mailed, or the package can be created in a public location and a reference URL can be mailed. Variables that control this option include the following:

_ADDRESSLIST_DATASET_LIBNAME
_ADDRESSLIST_DATASET_MEMNAME
_ADDRESSLIST_VARIABLENAME
_ARCHIVE_NAME
_ARCHIVE_PATH
_COLLECTION_URL
_DATASET_OPTIONS
_EMAIL_ADDRESS
_FROM
_FTP_PASSWORD
_FTP_USER
_HTTP_PASSWORD
_HTTP_PROXY_URL
_HTTP_USER
_IF_EXISTS
_PARENT_URL
_REPLYTO
_SUBJECT

PACKAGE_TO_QUEUE

creates a package and sends it to one or more message queues. An actual archive package can be sent, or the package can be created in a public location and a reference URL can be sent. Variables that control this option include the following:

_ARCHIVE_NAME
_ARCHIVE_PATH
_CORRELATIONID
_FTP_PASSWORD
_FTP_USER
_HTTP_PASSWORD
_HTTP_PROXY_URL
_HTTP_USER
_MESSAGE_QUEUE

PACKAGE_TO_SUBSCRIBERS

creates a package and sends it to a subscriber channel. An actual archive package can be sent, or the package can be created in a public location and a reference URL can be sent. Variables that control this option include the following:

_ARCHIVE_NAME
_ARCHIVE_PATH
_CHANNEL
_CHANNEL_STORE
_COLLECTION_URL
_CORRELATIONID
_FROM
_FTP_PASSWORD
_FTP_USER
_HTTP_PASSWORD
_HTTP_PROXY_URL
_HTTP_USER
_IF_EXISTS
_PARENT_URL
_REPLYTO
_SUBJECT

PACKAGE_TO_WEBDAV

creates a package and sends it to a WebDAV-compliant server. Variables that control this option include the following:

_ARCHIVE_NAME
_ARCHIVE_PATH
_COLLECTION_URL
_HTTP_PASSWORD
_HTTP_PROXY_URL
_HTTP_USER
_IF_EXISTS
_PARENT_URL

Almost all of these package option variables have directly equivalent properties in the package publishing API. For more information about these properties, see the PACKAGE_PUBLISH documentation in the SAS Publishing Framework: Developer's Guide. The property names are the same as the variable names with the underscore prefix removed.

Top of Page