Writing a Stored Process |
Many macro variables are reserved for special purposes in stored processes. Reserved names generally are prefixed with an underscore character. To avoid conflicts, do not use the underscore prefix for any application variables. Some reserved macro variables are created automatically for all stored processes that are 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.
The following table shows the reserved macro variables that can be used in your stored processes:
Variable Name | Used By | Description |
---|---|---|
_ABSTRACT |
%STPBEGIN
%STPEND |
Is the text string that briefly describes a package that was 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:
|
|
||
|
|
Values for _ACTION are case insensitive. Multiple values can be combined
(except when using INDEX or DATA). Two common combinations are:
|
_ADDRESSLIST_DATASET_LIBNAME, _ADDRESSLIST_DATASET_MEMNAME, _ADDRESSLIST_VARIABLENAME, _DATASET_OPTIONS |
%STPBEGIN
%STPEND |
Specifies a data set that contains e-mail addresses when _RESULT is set to PACKAGE_TO_EMAIL . |
_APSLIST | Stored Process Server | Specifies the list of the names of all the parameters that were passed to the program. |
_ARCHIVE_FULLPATH |
%STPBEGIN
%STPEND |
Specifies the full path and name of an archive package that was 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 setting %STPEND has no effect. |
_ARCHIVE_NAME |
%STPBEGIN
%STPEND |
Specifies the 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 that is 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 |
Specifies the 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 that is 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. For more information, see Web Application Properties. |
_BASEURL | Web Clients | Overrides the default value for _URL. This macro variable is used mainly with _REPLAY to return to the correct location. |
_CHANNEL |
%STPBEGIN
%STPEND |
Specifies a subscriber channel when _RESULT is set to PACKAGE_TO_SUBSCRIBERS . For more information about channel names, see PACKAGE_PUBLISH in the SAS Publishing Framework: Developer's Guide. |
_CLIENT | All |
Identifies the client and version number, as follows:
_CLIENT=Client_Name; JVM java_version; operating_environment (operating_environment_architecture) operating_environment_version The Client_Name is automatically obtained through the Stored Process Service API. If the API cannot obtain the value for Client_Name, then the default value is StoredProcessService 9.2 (for example, _CLIENT=StoredProcessService 9.2; JVM 1.5.0_12; Windows XP (x86) 5.1). |
_COLLECTION_URL |
%STPBEGIN
%STPEND |
Specifies the 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 | Specifies the debugging flags. For information about setting the default value of _DEBUG, see Setting the Default Value of _DEBUG. |
_DESCRIPTION |
%STPBEGIN
%STPEND |
Descriptive text that is embedded in a package that was created by %STPBEGIN and %STPEND. |
_DOMAIN | Web Clients | Specifies the 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 |
Specifies the expiration datetime that is embedded in a package that was 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. For more information, 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. |
_GOPTIONS |
%STPBEGIN
%STPEND |
Sets any SAS/GRAPH option that is 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 that is 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 | Specifies the 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 that are accepted by the stored process client. This variable is not set by default but can be enabled. For more information, see Web Application Properties. |
_HTCOOK | Web Clients | Specifies all of the cookie strings that the client sent with this request. This variable is not set by default but can be enabled. For more information, see Web Application Properties. |
_HTREFER | Web Clients | Specifies the address of the referring page. This variable is not set by default but can be enabled. For more information, see, Web Application Properties. |
_HTTP_PASSWORD |
%STPBEGIN
%STPEND |
Specifies the password that is 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 |
Specifies the Proxy server that is 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 |
Specifies the user name that is 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. For more information, see Web Application Properties. |
_IF_EXISTS |
%STPBEGIN
%STPEND |
Can be NOREPLACE, UPDATE, or UPDATEANY. For more information, see the PACKAGE_PUBLISH options in the SAS Publishing Framework: Developer's Guide. |
_MESSAGE_QUEUE |
%STPBEGIN
%STPEND |
Specifies a target queue when _RESULT is set to PACKAGE_TO_QUEUE . For more information about queue names, see the PACKAGE_PUBLISH documentation in the SAS Publishing Framework: Developer's Guide. Multiple queues can be specified using the multiple value convention for stored process parameters. |
_METAFOLDER | All |
Contains the name or path of the folder for the stored process that
is being executed. For example, for the stored process:
_PROGRAM=/Sales/Southwest/ Quarterly Summarythe value of _METAFOLDER would be: _METAFOLDER=/Sales/Southwest/. |
_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 user name that is used to connect to the metadata server. This variable cannot be modified by the client. |
_NAMESPACES |
%STPBEGIN
%STPEND |
Applies to packages only. For more information about this variable, see the PACKAGE_BEGIN documentation in the SAS Publishing Framework: Developer's Guide. |
_NAMEVALUE |
%STPBEGIN
%STPEND |
Specifies a list of one or more name or value pairs that are used for filtering when generating packages. For more information about this variable, see the PACKAGE_BEGIN documentation in the SAS Publishing Framework: Developer's Guide. |
_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:
|
_ODSOPTIONS |
%STPBEGIN
%STPEND |
Specifies options that are to be appended to the ODS statement. Do not
use this macro to override options that are 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 by using the SAS Stored Process Web Application, specify myfile.css (url="myfile.css") . |
_PATH | Web Clients |
Specifies the starting level for the _ACTION=INDEX display. The value
of _PATH is a folder name, such as
/Sales/Southwest. |
_PROGRAM | All |
Specifies the name of the stored process. The value of _PROGRAM is a
path, such as
/Sales/Southwest/Quarterly Summary. |
_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. For more information, see Web Application Properties. |
_REPLAY | Stored Process Server; Web Clients |
Specifies a complete URL for use with programs that use the Output Delivery
System (ODS). This URL consists of 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 that is 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.
If you are using the _REPLAY macro variable with Microsoft Office, then you will build a URL that uses the _OUTPUTAPP= parameter. Supported values for the _OUTPUTAPP= parameter include EXCEL, WORD, and POWERPOINT. For example, if you specify _OUTPUTAPP=EXCEL in the URL, then the content type for the replayed output is application/vnd.ms-excel. If you need to specify the name of the file that the _REPLAY macro variable returns, then you can use the _CONTDISP parameter in the URL. The value of this parameter will be echoed back as a Content-disposition header. |
_REPLYTO |
%STPBEGIN
%STPEND |
Specifies a designated e-mail address to which package recipients might respond when _RESULT is set to PACKAGE_TO_EMAIL . |
_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. For more information, see Web Application Properties. |
_RESULT | All |
Specifies the type of client result that is to be created by the stored
process. For more information, see Setting Result Capabilities.
Possible values for this variable are as follows:
|
_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. For more information, see Web Application Properties. |
_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. For more information, see, Web Application Properties. |
_RMTUSER | Web Clients | Specifies the login ID of the user making this request if the user has been authenticated, or indicates null if the user has not been authenticated. This variable is not set by default but can be enabled. For more information, see Web Application Properties. |
_SESSIONID | Stored Process Server | Specifies 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 that 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. For more information, see Web Application Properties. |
_SRVSOFT | Web Clients | Identifies the Web server software. This variable is not set by default but can be enabled. For more information, see, Web Application Properties. |
_STATUS_MESSAGE | Web Clients | Returns the value of the SAS macro variable to the client after the stored process has been executed. This macro variable is useful for returning debugging information or informational messages (for example, when packages are created that are not displayed). |
_STPERROR |
%STPBEGIN
%STPEND |
Specifies a global error variable. This variable is set to 0 if %STPBEGIN and %STPEND complete successfully. This variable is set to a nonzero 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 | Specifies a URL that is 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 | Specifies 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 that are specified in the variable _EXPIRE. This variable is created by the stored process server and is not one of the symbols that is passed from the SAS Stored Process Web Application. |
_URL | Web Clients | Specifies the URL of the Web server middle tier that is used to access the stored process. |
_USERNAME | Web Clients | Specifies the value for the user name that is obtained from Web client authentication. |
_VERSION | Web Clients | Specifies the SAS Stored Process Web Application version and build number. |
Most of the reserved macro variables that are related to package publishing have an equivalent property or parameter in the Publishing Framework. For a description of these variables, see the documentation for PACKAGE_PUBLISH and PACKAGE_BEGIN in the SAS Publishing Framework: Developer's Guide.
Copyright © 2010 by SAS Institute Inc., Cary, NC, USA. All rights reserved.