Using Reserved Macro Variables

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:
Reserved Macro Variables
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:
BACKGROUND
executes the stored process in the background.
DATA
displays a summary of general stored process data.
EXECUTE
executes the stored process.
FORM
displays a custom input form if one exists. If FORM is the only value for _ACTION, and no form is found, then an error is generated. You can use the _FORM reserved macro variable in conjunction with _ACTION=FORM if you want to specify custom input forms.
INDEX
displays a tree of all stored processes. For _ACTION=INDEX, three HTML frames are created with the top frame being the banner frame.
LOGOFF
causes the Web application to terminate the active session and to display a logoff screen.
NEWWINDOW
displays results in a new window.
NOALERT
suppresses generation of alerts.
NOBANNER
displays results without adding a banner.
PROPERTIES
displays the prompt page, which enables you to set input parameters and execution options and to execute the stored process.
SEARCH
displays a search page that enables you to search for a stored process or stored process report. You can combine this value with values for the _MATCH, _FIELD, _COLUMNS, _TYPE, or _PATH variables in order to specify search parameters.
_ACTION (cont’d.)
Web Clients
STRIP
removes null parameters. This value can be used only in combination with the EXECUTE and BACKGROUND values.
TREE
displays a tree of all stored processes. You can combine this value with values for the _MATCH, _FIELD, _COLUMNS, _TYPE, or _PATH variables in order to specify display parameters for the tree view.
XML
can be combined with other _ACTION values to return XML data. You can use the following combinations:
_ACTION=TREE,XML
returns a stored process and stored process report tree list in XML.
_ACTION =DATA,XML
returns stored process data in XML.
_ACTION =PROPERTIES,XML
returns stored process prompts in XML.
_ACTION =SEARCH,XML
returns search results in XML.
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 prompt 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 that contains e-mail addresses when _RESULT is set to PACKAGE_TO_EMAIL.
_APPLIED_TEXT_VIEWER_NAME
_APPLIED_VIEWER_NAME
%STPBEGIN
%STPEND
Specifies the name of the rendered package view when _RESULT is set to PACKAGE_TO_SUBSCRIBERS or 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 Java 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 Java API. If the API cannot obtain the value for Client_Name, then the default value is StoredProcessService 9.3 (for example,
_CLIENT=StoredProcessService 9.3; JVM
1.5.0_12; Windows XP (x86) 5.1).
_COLLECTION_FOLDER
%STPBEGIN
%STPEND
Specifies both the parent folder and the collection folder together. This variable is relative to the list name when _RESULT is set to PACKAGE_TO_SHAREPOINT.
_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 Java API and cannot be directly overridden by a client input parameter.
_COLUMNS
Web Clients
Specifies which columns are to be displayed and the order in which they are presented. You can specify one or more of the following values: description, keywords, createDate (creation date), or modDate (modified date). The creation date and modified date are displayed as year-month-day. The default is the name column only.
_DEBUG
Web Clients
Specifies the debugging flags. For information about setting the default value of _DEBUG, see Setting the Default Value of _DEBUG.
_DEBUG_FILE
%STPBEGIN
%STPEND
Specifies the name of the file that contains debug wire trace output when _RESULT is set to PACKAGE_TO_SHAREPOINT.
_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.
_FIELD
Web Clients
Specifies which field to search for the match string. The possible fields are name, description, or keywords. The keywords field only matches complete keywords. The default field is the name field.
_FOLDER_PATH
%STPBEGIN
%STPEND
Specifies the folder path for the channel of interest when _RESULT is set to PACKAGE_TO_SUBSCRIBERS.
_FORM
Web Clients
Specifies the location of a custom input form JSP file for a stored process. This value is used only if _ACTION=FORM is also present. If the value starts with a slash (/), then the JSP file is assumed to be located relative to the Stored Process Web Application root. Otherwise, it is assumed to be a complete URL and a redirect is performed to that value.
_FROM
%STPBEGIN
%STPEND
Specifies the name or e-mail address of the sender when _RESULT is set to PACKAGE_TO_EMAIL. This value is the name or e-mail address that the e-mail appears to be from.
_GENERATED_NAME
%STPBEGIN
%STPEND
Returns the name of the package or the name of the folder that contains the package, whether this value was generated by SAS or specified by another variable. This variable is returned when _RESULT is set to PACKAGE_TO_ARCHIVE, PACKAGE_TO_SHAREPOINT, or PACKAGE_TO_WEBDAV.
_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 Java 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 Java 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 Java 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.
_INITIALIZE_SITE
%STPBEGIN
%STPEND
Enables an administrator to initialize a SharePoint site when _RESULT is set to PACKAGE_TO_SHAREPOINT.
_LIST_NAME
%STPBEGIN
%STPEND
Specifies a document library in the SharePoint site when _RESULT is set to PACKAGE_TO_SHAREPOINT.
_MATCH
Web Clients
Specifies a search string. If no string is specified, then everything is a match.
_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 Summary
the 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.
_MSOFFICECLIENT
SAS Add-In for Microsoft Office
Specifies the Microsoft application that is currently executing the stored process. Valid values for this macro variable are Excel, Word, PowerPoint, and Outlook.
_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:
  • CSV
  • CSVALL
  • TAGSETS.CSVBYLINE
  • HTML
  • LATEX
  • NONE (no ODS output is generated)
  • PDF
  • PS
  • RTF
  • SASREPORT
  • WML
  • XML
  • any tagset destination
_ODSDOC
%STPBEGIN
%STPEND
Contains the two-level name of the ODS Document file that was created by the STP procedure.
_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 that 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").
_PARENT_FOLDER
%STPBEGIN
%STPEND
Specifies the parent folder of a generated collection name when _RESULT is set to PACKAGE_TO_SHAREPOINT. This variable is relative to the list name.
_PATH
Web Clients
Specifies the starting level for the _ACTION=INDEX display. The value of _PATH is a folder name, such as
/Sales/Southwest
.
If this variable is used with _ACTION=SEARCH, then _PATH limits searching to the specified path and below.
_PROCESS_VIEWER
%STPBEGIN
%STPEND
Specifies a character string of yes to indicate that the rendered view is delivered in e-mail when _RESULT is set to PACKAGE_TO_EMAIL or PACKAGE_TO_SUBSCRIBERS.
_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 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 is 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.
_REPORT
All
Specifies the name of the stored process report. The value of _REPORT is a path, such as
/myfolder/myreport
.
_REPOSITORY
Web Clients
Specifies the metadata repository where the stored process is registered. The default repository value is METASERVER if _REPOSITORY is not specified.
_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:
STATUS
no output to the client.
STREAM
output is streamed to the 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. This option is valid only on the workspace server, and only for stored processes that are compatible with 9.2.
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_SHAREPOINT
package published to SharePoint.
PACKAGE_TO_SUBSCRIBERS
package published to a subscriber channel.
For more information about these options, see Using the %STPBEGIN and %STPEND Macros.
_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.
_SECUREUSERNAME
Web Clients
Contains the value for the user name that is obtained from Web client authentication. The _SECUREUSERNAME macro variable is created when the application server executes a stored process. The value for _SECUREUSERNAME is written into the _username macro variable if _username doesn't already contain a value.
_SENDER
%STPBEGIN
%STPEND
Specifies the e-mail address of the sender when _RESULT is set to PACKAGE_TO_EMAIL . A valid e-mail address should be specified. This address receives any bounced or undeliverable e-mail. This value is the actual e-mail address that the e-mail is sent from.
_SESSIONID
Stored Process Server
Specifies a unique identifier for the session. The _SESSIONID variable is created only if a session has been explicitly created.
_SITE_URL
%STPBEGIN
%STPEND
Specifies the transfer protocol (HTTP or HTTPS), the host name, and the SharePoint site when _RESULT is set to PACKAGE_TO_SHAREPOINT.
_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.
_TARGET
Web Clients
Specifies the fixed HTML form target value to use in displays that are generated by the SAS Stored Process Web Application. Use _blank to always force a new window.
_TARGET_VIEW_MIMETYPE
%STPBEGIN
%STPEND
Specifies the MIME type of the rendered view when _RESULT is set to PACKAGE_TO_EMAIL, PACKAGE_TO_SHAREPOINT, PACKAGE_TO_SUBSCRIBERS, or PACKAGE_TO_WEBDAV
_TARGET_VIEW_NAME
%STPBEGIN
%STPEND
Specifies the name of the rendered view when _RESULT is set to PACKAGE_TO_EMAIL, PACKAGE_TO_SHAREPOINT, PACKAGE_TO_SUBSCRIBERS, or PACKAGE_TO_WEBDAV
_TEXT_VIEWER_NAME
%STPBEGIN
%STPEND
Specifies the name of a text viewer template that formats package content for viewing in e-mail when _RESULT is set to PACKAGE_TO_EMAIL, PACKAGE_TO_SUBSCRIBERS, or PACKAGE_TO_WEBDAV.
_THISSESSION
Stored Process Server
Web Clients
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.
_TYPE
Web Clients
Indicates what type of object to search for. You can specify storedprocess or report (stored process report) to limit the search to one of these object types. The default is to search for both.
_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.
_VIEWER_NAME
%STPBEGIN
%STPEND
Specifies the name of the HTML viewer template to be applied when _RESULT is set to PACKAGE_TO_EMAIL, PACKAGE_TO_SHAREPOINT, PACKAGE_TO_SUBSCRIBERS, or PACKAGE_TO_WEBDAV.
_WELCOME
Web Clients
Specifies an initial page to display in the Web application. If the value starts with a slash (/), then the Welcome page is relative to the Web application root context, and the Web browser is forwarded to that page. Otherwise, a redirect command is sent to the Web browser for the specified page.
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.