%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. A typical stored process using these macros follows:

   /* *****************************************************
    * 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. See the section on Reserved Macro Variables for a more detailed description of each macro variable mentioned in the following sections.

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 this case, 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. Note that there are many variables that allow you to override ODS options. You must remember to verify whether any options specified by the stored process or its clients are compatible with the output destinations you plan to support.

Note that some ODS options (for example, BASE) are set based on the result options. 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 recognized by %STPBEGIN 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:

   %global _ODSSTYLE;
   *ProcessBody;

   %let _ODSSTYLE=MyStyle;

   %stpbegin;

Any client specified value for _ODSSTYLE 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 is free to modify the macro variables consumed by %STPBEGIN 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. See the section on Result Types for an introduction to the standard options for stored process results. In most cases, a stored process using 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. Variables that are valid for all package destinations are as follows:

• _ABSTRACT
• _DESCRIPTION
• _EXPIRATION_DATETIME
• _NAMESPACES
• _NAMEVALUE

Additional variables are recognized for specific _RESULT settings, such as

PACKAGE_TO_ARCHIVE

creates an archive package on the server file system containing the generated output. The _ARCHIVE_PATH and (optionally) _ARCHIVE_NAME variables specify where the package is created. In addition, _ARCHIVE_FULLPATH is set by %STPEND to hold the full path name 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 (optionally) _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.

%STPBEGIN configures ODS to create output files in a temporary working directory. %STPEND then creates the package from all of the files found 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 created by ODS. The temporary directory and any contained files are automatically deleted when the stored process completes. No clean up is required in the stored process program.

Errors

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

Note that because these macros allow clients or stored processes to submit SAS language options (for example, see 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 (set the SAS OBS option 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 None as the 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

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

• _ARCHIVE_NAME
• _ARCHIVE_PATH
• _FTP_PASSWORD
• _FTP_USER
• _HTTP_PASSWORD
• _HTTP_PROXY_URL
• _HTTP_USER
• _LDAP_BINDDN
• _LDAP_BINDPW

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 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
• _LDAP_BINDDN
• _LDAP_BINDPW
• _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 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
• _LDAP_BINDDN
• _LDAP_BINDPW
• _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 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
• _LDAP_BINDDN
• _LDAP_BINDPW
• _PARENT_URL
• _REPLYTO
• _SUBJECT

Almost all of the package option variables previously listed have directly equivalent properties in the package publishing API. See the PACKAGE_PUBLISH documentation for more information about these properties. The property names are the same as the variable names with the underscore prefix removed.