Using the %STPBEGIN and %STPEND Macros

Overview of %STPBEGIN and %STPEND

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;
 
 ... 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. Because the %STPBEGIN and %STPEND macros initialize the Output Delivery System (ODS), you should use them only if your stored process creates ODS output. For example, the macros are not necessary if the stored process is creating only a table. If you do use the macros, then you should set _ODSDEST to NONE to disable ODS initialization. In these cases, your stored process must explicitly create any output.

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 enable 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;
 
 %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, and only for stored processes that are compatible with 9.2.
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.

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 enable 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
  • _GENERATED_NAME
  • _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
  • _APPLIED_TEXT_VIEWER_NAME
  • _APPLIED_VIEWER_NAME
  • _ARCHIVE_NAME
  • _ARCHIVE_PATH
  • _COLLECTION_URL
  • _DATASET_OPTIONS
  • _EMAIL_ADDRESS
  • _FTP_PASSWORD
  • _FTP_USER
  • _FROM
  • _HTTP_PASSWORD
  • _HTTP_PROXY_URL
  • _HTTP_USER
  • _IF_EXISTS
  • _PARENT_URL
  • _PROCESS_VIEWER
  • _REPLYTO
  • _SENDER
  • _SUBJECT
  • _TARGET_VIEW_MIMETYPE
  • _TARGET_VIEW_NAME
  • _TEXT_VIEWER_NAME
  • _VIEWER_NAME
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_SHAREPOINT
creates a package and sends it to a Microsoft SharePoint server. Variables that control this option include the following:
  • _ARCHIVE_NAME
  • _ARCHIVE_PATH
  • _APPLIED_VIEWER_NAME
  • _COLLECTION_FOLDER
  • _COLLECTION_URL
  • _DEBUG_FILE
  • _GENERATED_NAME
  • _HTTP_PASSWORD
  • _HTTP_USER
  • _IF_EXISTS
  • _INITIALIZE_SITE
  • _LIST_NAME
  • _PARENT_FOLDER
  • _PARENT_URL
  • _SITE_URL
  • _TARGET_VIEW_MIMETYPE
  • _TARGET_VIEW_NAME
  • _VIEWER_NAME
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:
  • _APPLIED_TEXT_VIEWER_NAME
  • _APPLIED_VIEWER_NAME
  • _ARCHIVE_NAME
  • _ARCHIVE_PATH
  • _CHANNEL
  • _CHANNEL_STORE
  • _COLLECTION_URL
  • _CORRELATIONID
  • _FOLDER_PATH
  • _FROM
  • _FTP_PASSWORD
  • _FTP_USER
  • _HTTP_PASSWORD
  • _HTTP_PROXY_URL
  • _HTTP_USER
  • _IF_EXISTS
  • _PARENT_URL
  • _PROCESS_VIEWER
  • _REPLYTO
  • _SUBJECT
  • _TARGET_VIEW_MIMETYPE
  • _TARGET_VIEW_NAME
  • _TEXT_VIEWER_NAME
  • _VIEWER_NAME
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
  • _GENERATED_NAME
  • _HTTP_PASSWORD
  • _HTTP_PROXY_URL
  • _HTTP_USER
  • _IF_EXISTS
  • _PARENT_URL
  • _TARGET_VIEW_MIMETYPE
  • _TARGET_VIEW_NAME
  • _TEXT_VIEWER_NAME
  • _VIEWER_NAME
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.
Copyright © SAS Institute Inc. All rights reserved.