SAS 9.1.3 Integration Technologies » Developer's Guide

SAS Stored Processes
Software Requirements
Creating Stored Processes
Input Parameters
Result Types
%STPBEGIN and %STPEND
Reserved Macro Variables
Stored Process Server Functions
Sessions
Samples
Debugging
Converting SAS/IntrNet Programs
Using Stored Processes
Building a Web Application
SAS Stored Process Web Application
Configuration
Input
HTTP Headers
Embedding Graphics
Chaining Stored Processes
Using Sessions
Debugging
IOM Direct Interface Stored Processes
SAS Stored Processes

Reserved Macro Variables

Many reserved macro variables are reserved for special purposes in stored processes. Reserved names generally are prefixed with an underscore character. It is recommended that you do not use the underscore prefix for any application variables to avoid conflicts. Some reserved macro variables are created automatically for all stored processes running on a particular server. Some are created by specific stored process client or middle-tier interfaces and are not created or available when other clients call the stored process.

Variable Name Used By Description
_ABSTRACT %STPBEGIN/
%STPEND		 Text string briefly describing a package created by %STPBEGIN and %STPEND.
_ACTION Web Clients Specifies an action for the Web application to take. Possible values for this variable are as follows:
FORM
displays custom input form if one exists. If FORM is the only value for _ACTION, and no form is found, then an error is generated.
EXECUTE
executes the stored process.
PROPERTIES
displays the property page, which enables you to set input parameters and execution options and to execute the stored process.
BACKGROUND
executes the stored process in the background.
STRIP
removes null parameters. This value can only be used in combination with EXECUTE and BACKGROUND.
INDEX
displays a tree of all stored processes.
DATA
displays a summary of general stored process data.
Values for _ACTION are case insensitive. Multiple values can be combined (except when using INDEX or DATA). Two common combinations are:
_ACTION=FORM,PROPERTIES
displays a custom input form if one exists, otherwise displays the property page.
_ACTION=FORM,EXECUTE
displays a custom input form if one exists, otherwise executes the stored process.
_ADDRESSLIST_DATASET_LIBNAME, _ADDRESSLIST_DATASET_MEMNAME, _ADDRESSLIST_VARIABLENAME, _DATASET_OPTIONS %STPBEGIN/
%STPEND		 Specifies a data set containing email addresses when _RESULT is set to PACKAGE_TO_EMAIL.
_APSLIST Stored Process Server List of the names of all the parameters that were passed to the program.
_ARCHIVE_FULLPATH %STPBEGIN/
%STPEND		 Full path and name of an archive package created by %STPEND when _RESULT is set to PACKAGE_TO_ARCHIVE or PACKAGE_TO_REQUESTER. This value is set by %STPEND and is an output value only. Setting it before %STPEND has no effect.
_ARCHIVE_NAME %STPBEGIN/
%STPEND		 Name of the archive package to be created when _RESULT is set to PACKAGE_TO_ARCHIVE. If this value is not specified or is blank and _RESULT is set to PACKAGE_TO_ARCHIVE or PACKAGE_TO_REQUESTER, then the package is created with a new, unique name in the directory specified by _ARCHIVE_PATH. This value is set through the stored process service API and cannot be directly overridden by a client input parameter.
_ARCHIVE_PATH %STPBEGIN/
%STPEND		 Path of the archive package to be created when _RESULT is set to PACKAGE_TO_ARCHIVE or PACKAGE_TO_REQUESTER. This value is set through the stored process service API and cannot be directly overridden by a client input parameter. The special value TEMPFILE causes the archive package to be created in a temporary directory that exists only until the stored process completes executing and the client disconnects from the server.
_AUTHTYP Web Clients Specifies the name of the authentication scheme used to identify a Web client, for example, BASIC or SSL, or "null" (no authentication.) This variable is not set by default but can be enabled in the params.config file.
_CHANNEL %STPBEGIN/
%STPEND		 Specifies a subscriber channel when _RESULT is set to PACKAGE_TO_SUBSCRIBERS. See PACKAGE_PUBLISH for more information about channel names.
_COLLECTION_URL %STPBEGIN/
%STPEND		 URL of the WebDAV collection to be created when _RESULT is set to PACKAGE_TO_WEBDAV. See also _IF_EXISTS. This value is set through the stored process service API and cannot be directly overridden by a client input parameter.
_DEBUG Web Clients Debugging flags. For information about setting the default value of _DEBUG, see Setting the Default Value of _Debug.
_DESCRIPTION %STPBEGIN/
%STPEND		 Descriptive text embedded in a package created by %STPBEGIN and %STPEND.
_DOMAIN Web Clients Authentication domain for the SAS Stored Process Web Application.
_EMAIL_ADDRESS %STPBEGIN/
%STPEND		 Specifies destination e-mail addresses when _RESULT is set to PACKAGE_TO_EMAIL. Multiple addresses can be specified using the multiple value convention for stored process parameters.
_ENCODING %STPBEGIN/
%STPEND		 Sets the encoding for all ODS output.
_EXPIRATION_DATETIME %STPBEGIN/
%STPEND		 Expiration datetime embedded in a package created by %STPBEGIN and %STPEND. Must be specified in a valid SAS datetime syntax.
_FROM %STPBEGIN/
%STPEND		 Specifies the e-mail address of the sender when _RESULT is set to PACKAGE_TO_EMAIL.
_GOPT_DEVICE, _GOPT_HSIZE, _GOPT_VSIZE, _GOPT_XPIXELS, _GOPT_YPIXELS %STPBEGIN/
%STPEND		 Sets the corresponding SAS/GRAPH option. See the DEVICE, HSIZE, VSIZE, XPIXELS, and YPIXELS options in "Graphics Options and Device Parameters Dictionary" in the SAS/GRAPH Reference in SAS Help and Documentation for more information.
_GOPTIONS %STPBEGIN/
%STPEND		 Sets any SAS/GRAPH option documented in "Graphics Options and Device Parameters Dictionary" in the SAS/GRAPH Reference in SAS Help and Documentation. You must specify the option name and its value in the syntax used for the GOPTIONS statement. For example, set _GOPTIONS to ftext=Swiss htext=2 to specify the Swiss text font with a height of 2.
_GRAFLOC Web Clients URL for the location of SAS/GRAPH applets. This variable is set to /sasweb/graph for most installations.
_HTACPT Web Clients Specifies the MIME types accepted by the stored process client. This variable is not set by default but can be enabled in the params.config file.
_HTCOOK Web Clients Specifies all of the cookie strings the client sent with this request. This variable is not set by default but can be enabled in the params.config file.
_HTREFER Web Clients Specifies the address of the referring page. This variable is not set by default but can be enabled in the params.config file.
_HTTP_PASSWORD %STPBEGIN/
%STPEND		 Password used (with _HTTP_USER) to access the WebDAV server when _RESULT is set to PACKAGE_TO_WEBDAV. This value is set through the stored process service API and cannot be directly overridden by a client input parameter.
_HTTP_PROXY_URL %STPBEGIN/
%STPEND		 Proxy server used to access the WebDAV server when _RESULT is set to PACKAGE_TO_WEBDAV. This value is set through the stored process service API and cannot be directly overridden by a client input parameter.
_HTTP_USER %STPBEGIN/
%STPEND		 User name used (with _HTTP_PASSWORD) to access the WebDAV server when _RESULT is set to PACKAGE_TO_WEBDAV. This value is set through the stored process service API and cannot be directly overridden by a client input parameter.
_HTUA Web Clients Specifies the name of the user agent. This variable is not set by default but can be enabled in the params.config file.
_IF_EXISTS %STPBEGIN/
%STPEND		 Can be NOREPLACE, UPDATE, or UPDATEANY. See PACKAGE_PUBLISH options for more information.
_MESSAGE_QUEUE %STPBEGIN/
%STPEND		 Specifies a target queue when _RESULT is set to PACKAGE_TO_QUEUE. See PACKAGE_PUBLISH for more information about queue names. Multiple queues can be specified using the multiple value convention for stored process parameters.
_METAPERSON All Specifies the Person metadata name that is associated with the _METAUSER login variable. The value of this variable can be UNKNOWN. This variable cannot be modified by the client.
_METAUSER All Specifies the login username that is used to connect to the metadata server. This variable cannot be modified by the client.
_NAMESPACES %STPBEGIN/
%STPEND		 Applies to packages only. See PACKAGE_BEGIN for more information about this variable.
_NAMEVALUE %STPBEGIN/
%STPEND		 A list of one or more name/value pairs used for filtering when generating packages. See PACKAGE_BEGIN for more information about this variable.
_ODSDEST %STPBEGIN/
%STPEND		 Specifies the ODS destination. The default ODS destination is HTML if _ODSDEST is not specified. Valid values of _ODSDEST include the following:
  • CSV
  • CSVALL
  • TAGSETS.CSVBYLINE
  • HTML
  • LATEX
  • NONE (no ODS output is generated)
  • PDF
  • PS
  • RTF
  • SASREPORT
  • WML
  • XML
  • any tagset destination
_ODSOPTIONS %STPBEGIN/
%STPEND		 Specifies options to be appended to the ODS statement. Do not use this macro to override options defined by a specific macro variable. For example, do not specify ENCODING=value in this variable because it conflicts with _ODSENCODING.

Note: NOGTITLE and NOGFOOTNOTE are appended to the ODS statement as default options. You can override this behavior by specifying GTITLE or GFOOTNOTE for _ODSOPTIONS.
_ODSSTYLE %STPBEGIN/
%STPEND		 Sets the ODS STYLE= option. You can specify any ODS style that is valid on your system.
_ODSSTYLESHEET %STPBEGIN/
%STPEND		 Sets the ODS STYLEHEET= option. To store a generated style sheet in a catalog entry and automatically replay it using the SAS Stored Process Web Application, specify myfile.css (url="myfile.css")
_PROGRAM All Name of the stored process. The value of _PROGRAM is frequently a path, such as 
   /Sales/Southwest/
      Quarterly Summary

In some cases _PROGRAM can also contain the metadata repository name or use a full URL syntax:

   //West/Sales/Southwest/
      Quarterly Summary
   sbip://West/Sales/Southwest/
      Quarterly Summary
      (StoredProcess)

If your stored process uses the value of _PROGRAM, then it should accept any of these variations.
_QRYSTR Web Clients Specifies the query string that is contained in the request URL after the path. This variable is not set by default but can be enabled in the params.config file.
_REPLAY Stored Process Server/Web Client A complete URL for use with programs that use the Output Delivery System (ODS). It is composed from the values of _THISSESSION and _TMPCAT. ODS uses this URL to create links that replay stored output when they are loaded by the user's Web browser. This variable is created by the stored process server and is not one of the symbols passed from the SAS Stored Process Web Application. The _REPLAY variable is set only if the _URL variable is passed in from the client or middle tier.
_REPLYTO %STPBEGIN/
%STPEND		 Specifies a designated e-mail address to which package recipients might respond when _RESULT is set to PACKAGE_TO_EMAIL.
_REPOSITORY Web Clients The metadata repository where the stored process is registered. This is the repository name defined in the InformationService configuration. It is usually the same as the metadata repository name seen in SAS Management Console, but the name might be different in some configurations. This value is normally set in the params.config file to define a default repository if the SAS Stored Process Web Application client does not specify a repository in the _PROGRAM variable.
_REQMETH Web Clients Specifies the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. This variable is not set by default but can be enabled in the params.config file.
_RESULT All Specifies the type of client result to be created by the stored process. See Result Types for more information. Possible values for this variable are as follows:
STATUS
no output to client.
STREAM
output is streamed to client through _WEBOUT fileref.
PACKAGE_TO_ARCHIVE
package is published to an archive file.
PACKAGE_TO_REQUESTER
package is returned to the client. The package can also be published to an archive file in this case.
PACKAGE_TO_WEBDAV
package is published to a WebDAV server.
The _RESULT value is set through the stored process service API and cannot be directly overridden by a client input parameter. The value can be overridden in the stored process program to use these additional values:
PACKAGE_TO_EMAIL
package published to one or more e-mail addresses.
PACKAGE_TO_QUEUE
package published to a message queue.
PACKAGE_TO_SUBSCRIBERS
package published to a subscriber channel.
See %STPBEGIN and %STPEND for more information about these options.
_RMTADDR Web Clients Specifies the Internet Protocol (IP) address of the client that sent the request. For many installations with a firewall between the client and the Web server or servlet container, this value is the firewall address instead of the Web browser client. This variable is not set by default but can be enabled in the params.config file.
_RMTHOST Web Clients Specifies the fully qualified name of the client that sent the request, or the IP address of the client if the name cannot be determined. For many installations with a firewall between the client and the Web server or servlet container, this value is the firewall name instead of the Web browser client. This variable is not set by default but can be enabled in the params.config file.
_RMTUSER Web Clients Specifies the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated. This variable is not set by default but can be enabled in the params.config file.
_SESSIONID Stored Process Server A unique identifier for the session. The _SESSIONID variable is created only if a session has been explicitly created.
_SRVNAME Web Clients Specifies the host name of the server that received the request.
_SRVPORT Web Clients Specifies the port number on which this request was received.
_SRVPROT Web Clients Specifies the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1. This variable is not set by default but can be enabled in the params.config file.
_SRVSOFT Web Clients Identifies the Web server software. This variable is not set by default but can be enabled in the params.config file.
_STPERROR %STPBEGIN/
%STPEND		 Global error variable. Set to 0 if %STPBEGIN and %STPEND complete successfully. Set to a non-zero numeric value if an error occurs.
_STPWORK %STPBEGIN/
%STPEND		 Specifies a temporary working directory to hold files that are published in a package. This variable is set by %STPBEGIN and is not modified by the stored process.
_SUBJECT %STPBEGIN/
%STPEND		 Specifies a subject line when _RESULT is set to PACKAGE_TO_EMAIL.
_THISSESSION Stored Process Server/Web Client A URL composed from the values of _URL and _SESSIONID. This variable is created by the stored process server and is used as the base URL for all URL references to the current session. The _THISSESSION variable is created only if the _URL variable is passed in and a session has been explicitly created.
_TMPCAT Stored Process Server A unique, temporary catalog name. This catalog can be used to store temporary entries to be retrieved later. In socket servers, the _TMPCAT catalog is deleted after a number of minutes specified in the variable _EXPIRE. This variable is created by the stored process server and is not one of the symbols passed from the SAS Stored Process Web Application.
_URL Web Clients Specifies the URL of the Web server middle tier used to access the stored process.
_USERNAME Web Clients Specifies the value for the user name obtained from Web client authentication.
_VERSION Web Clients Specifies the SAS Stored Process Web Application version and build number.
VAR All Reserved. Do not use this variable in a parameter definition.

Most of the reserved macro variables related to package publishing have an equivalent property or parameter in the Publishing Framework. See the documentation for PACKAGE_PUBLISH and PACKAGE_BEGIN for a more complete description of these variables.