54
6
If you look in the browser bar (instead of at the hits), you will see the following URL (Figure 7), which executed when
you clicked the Search button:
Figure 7: Expanded View of Google Search URL
In the above example, HL and Q are the names of parameters used by the Google SEARCH program. The
programmer who wrote the Google SEARCH program had to know that HL and Q were possible parameters that
would come from the HTML form interface (the page where you clicked the Search button was a form).
The stored process author has to know what parameters will come from the SAS Intelligence Platform client
interface. In a stored process program the name of the parameter is a SAS macro variable name, and the value of
the parameter is a SAS macro variable value. The input parameters that you use in your stored process must follow
the same rules as for SAS macro variables:
1. Macro variables can be accessed through normal macro syntax (&macvar) or through functions like
SYMGET, SYMGETC, or SYMGETN. Macro variables can be assigned values using CALL SYMPUT or %LET or
through PROC SQL, in addition to having values collected and set via the client application interface.
2. Parameter names can be no longer than 32 characters and must start with an alphabetic character or
underscore and can contain only alphanumeric characters or underscores.
For more information about server-specific rules related to input parameters, refer to the "Input Parameters" section
of the SAS 9.1.3 Integration Technologies Developer's Guide (SAS Institute Inc. 2007(a)).
In order for the user-supplied input parameters to be used by your stored process, you have to do a little more than
just reference them in your program and register them in the metadata. Your stored process has to be able to find
the input parameters in the macro global symbol table. This part of using input parameters is discussed next.
%STPBEGIN AND %STPEND MACRO PROGRAMS
The main part of the program conversion takes place when the %STPBEGIN; and %STPEND; macro invocation
statements replace the ODS invocation statements. In addition, although it is not required, the use of the
*ProcessBody; comment is recommended for maximum flexibility. On the workspace server, macro variables are
not initialized until the *ProcessBody comment is encountered. The macro variables used by
%STPBEGIN/%STPEND are already in the macro global symbol table. The user-defined input parameters also need to
be in the global symbol table. You will want to use a %GLOBAL statement to place any user-defined input parameters
in the right place.
The %STPBEGIN and %STPEND macro program calls replace the ODS HTML "sandwich"; they are a matched set and,
in concept, perform the same functions as ODS HTML OPEN and CLOSE statements. The %STPBEGIN macro
initializes the Output Delivery System to generate output from the stored process. The %STPEND macro ends ODS
processing and delivers the results to the client application that executed the stored process. These macro programs
use many reserved macro variables to control how they operate. Some of these macro variables are available for
you to test or even change. Generally, each of the client applications in the SAS Intelligence Platform has a
preferred ODS destination or result type. HTML is not the default result type for all of the SAS Intelligence Platform
applications, but, conceptually, the %STPBEGIN; call sets up the ODS environment for a client application in much
the same way that an ODS HTML OPEN statement sets up the ODS environment to create an HTML file.
There is an alternate, more advanced, invocation method for stored processes that is generally used with Web-
based client applications. This method is very similar to the kind of invocation (using FILE=_WEBOUT) that was used
with SAS/IntrNet
®
Application Dispatcher programs. A discussion of this advanced technique is outside the scope of
this paper. However, these conversion issues are discussed in the SAS Global Forum 2007 paper "Converting
SAS/IntrNet Programs to SAS Stored Processes" (Weinstein 2007).
OVERRIDING RESERVED MACRO VARIABLES USED FOR ODS OPTIONS
When your stored process is executed by one of the client applications, %STPBEGIN initializes the macro parameters
that are appropriate for the invoking client application. For example, the default result type or ODS destination for
SAS Enterprise Guide is HTML format, while the default result type for SAS
®
Web Report Studio is the SAS Report
Applications Development
SAS Global Forum 2007
007
70
7
(XML) format. The reserved macro variable, _ODSDEST, holds the name of the destination being used. Normally, you
do not need to change the _ODSDEST parameter if you want your stored process to generate the result type that is
the default for the client application or if you want your end-users to be able to select a result type using client
application selection methods. Consider a stored process written based on DEMO1_TABLE.SAS. The only changes
needed for the program are those shown below. You can download the full text of the modified code in the
DEMO2_HTML.SAS program from the Web site listed in the "Resources" section at the end of the paper.
Original Code
Modified Code
From DEMO1_TABLE.SAS
Saved as DEMO2_HTML.SAS
ods html file='c:\temp\demo1.html'
style=sasweb rs=none;
. . . SAS code . . .
ods _all_ close;
%global wantreg _odsoptions _odsstyle
_odsstylesheet;
*ProcessBody;
%let _odsoptions = rs=none;
%let _odsstyle = sasweb;
%let _odsstylesheet=;
%stpbegin;
. . . SAS Code . . .
%stpend;
The %GLOBAL statement ensures that all input parameters are declared, creating an empty macro variable for each
possible input parameter. This enables you to reference the macro variable in your stored process program, even if it
was not set by the stored process client application. If an input parameter value is not supplied by a client
application, declaring it in a %GLOBAL statement prevents unwanted WARNING messages and possible program
errors from occurring. This is why the WANTREG macro variable appears in the %GLOBAL statement. The other macro
variables, _ODSOPTIONS, _ODSSTYLE, and _ODSSTYLESHEET don't technically
need to be in the %GLOBAL
statement, since they are already set to global at the client interface side. I prefer to be explicit about their use so
that stored process maintenance is easier and subsequent programmers know that I intended to override these
reserved macro parameters in my code.
The other macro variables that appear in the %GLOBAL statement are macro variables that are reserved for use with
the %STPBEGIN macro. A list of all the reserved macro variables used in the demonstration programs can be found
in the Appendix. The most commonly used reserved macro variables are shown in Table 1.
ODS Task or Option
Equivalent Reserved Parameter Name
ODS Destination
_ODSDEST
FILE=
(or BODY=)
This ODS option is not used with %STPBEGIN/%STPEND for most clients. Each client
receives the output from the server that executed the stored process. Within each
client application there is a way to save the stored process results. There is an
alternate invocation method for stored processes in which you could specify
FILE=_WEBOUT; however, this invocation method is typically used only for Web-
based client applications (an advanced topic).
STYLE=
_ODSSTYLE sets the STYLE= option to an ODS style. The style name that you use
must be valid on the server running the stored process. Server sessions may not
persist from execution of one stored process to another, so if you create a style
template in one stored process with PROC TEMPLATE code, it may not be available
to a second stored process running on a different server session unless you write
the template to a permanently allocated template store on the appropriate server.
STYLESHEET=(URL=)
_ODSSTYLESHEET sets the Cascading Style Sheet (CSS) to be used in the creation
of output (generally, HTML-based output – may not be used by all client
applications). In most of our examples, we are turning OFF the use of Cascading
Style Sheets (CSS) by issuing a NULL %LET statement.
Other options
_ODSOPTIONS
A complete list of the reserved variables can be found in the "Reserved Macro Variables" section of the SAS
9.1.3
Integration Technologies Developer's Guide (SAS Institute Inc. 2007(b)).
Table 1: ODS Options and Equivalent Parameter Names
Applications Development
SAS Global Forum 2007
007
37
8
If you want to alter any of the reserved macro variables (such as _ODSSTYLE or _ODSOPTIONS) your modifying code
needs to appear before
the %STPBEGIN; macro program invocation. A stored process can modify the macro
variables used by the %STPBEGIN macro program at any time before %STPBEGIN; appears in the stored process
code because this is the point at which the %STPBEGIN macro is called. Changing these reserved macro variables
after %STPBEGIN has been invoked is not recommended.
The one ODS option from the original program that has not been converted is the FILE= option. The original
program created a file called DEMO1.HTML. The SAS Intelligence Platform application dynamically requests and
dynamically receives the stored process results in the open SAS Enterprise Guide project, Word document,
PowerPoint presentation, Excel workbook, or SAS Web Report Studio report. The person who invokes the stored
process has the ability to save the stored process results using the File pull-down menu of the client applications, so
the FILE= (or BODY=) option is not needed for this stored process.
Note how the %LET statements for _ODSSTYLE and _ODSOPTIONS precede the %STPBEGIN macro invocation
statement in the modified program. _ODSSTYLE is overriding a single ODS option, whose usage is predefined in the
%STPBEGIN macro program. There is no pre-defined reserved macro variable for the RS= option; therefore, the %LET
statement for _ODSOPTIONS must contain the full specification, RS=NONE.
After the program is converted, it must be registered in the metadata (this is Step 3). Using SAS Management
Console, the metadata for the stored process was registered with only the WANTREG parameter and the following
general properties and execution environment settings:
Name: demo2_html
Server: SAS Main – Logical Stored Process Server
Source Code Repository: S:\Workshop\winsas\sbisp
Source File: demo2_html.sas
Output Type: Streaming
The names of the servers, such as SASMain, are set by your system administrators. For simple tabular output that
returns results to the client application, the Stored Process Server and Streaming are good choices for Server and
Output Type, respectively. To reduce confusion, the stored process name is the same as the SAS program name,
although in a true production environment, you could just as easily have called this stored process something like
"Performance Report".
When the DEMO2_HTML stored process is executed for a SAS Enterprise Guide project and the end-user selected
Canada
for the WANTREG parameter, the partial output would be as shown in Figure 8.
Figure 8: Executing the Stored Process within a SAS Enterprise Guide Project
Applications Development
SAS Global Forum 2007
007
15
9
When the stored process consumer selects Run
Æ
demo2_html
, the consumer next sees the parameter property
sheet for the WANTREG parameter as shown in Figure 9.
Figure 9: SAS Enterprise Guide Interface (with value choices shown)
If the stored process consumer selects Canada
(which is highlighted because it is the default value), and then
selects Run
, the output is as shown in Figure 10.
Figure 10: Partial Output from DEMO2_HTML Stored Process
Applications Development
SAS Global Forum 2007
007
40
10
The program code for the RTF destination is modified in a similar manner, as shown below.
Original ODS RTF Statements
Modified Code
From DEMO1_TABLE.SAS
Saved as DEMO3_RTF.SAS
ods rtf file='c:\temp\demo1.rtf'
bodytitle
startpage=no keepn notoc_data;
. . . SAS code . . .
ods _all_ close;
%global wantreg _odsoptions _odsdest
_odsstyle _odsstylesheet;
*ProcessBody;
%let _odsdest=rtf;
%let _odsstyle=rtf;
%let _odsstylesheet=;
%let _odsoptions = bodytitle startpage=no
keepn notoc_data;
%stpbegin;
. . . SAS Code . . .
%stpend;
The stored process that returns RTF output can be submitted from SAS Enterprise Guide or from the SAS Add-In for
Microsoft Office, specifically from Microsoft Word. The output when viewed in Microsoft Word is shown in Figure 11.
Figure 11: Partial Output from DEMO3_RTF Stored Process
This stored process could also be submitted from the SAS
®
Information Delivery Portal or from a custom Web
application. It could also be executed via URL using the SAS Stored Process Web Application. The stored process
that returns RTF would not work, for example, if submitted from Microsoft Excel or SAS Web Report Studio. The
result type that you choose for _ODSDEST must be appropriate for the client application from which the stored
process will be executed.
The PDF version of the stored process presents some different issues. If the stored process returns PDF results, it
can be executed only from SAS Enterprise Guide or via the advanced Web-based methods. It is not appropriate to
try to return PDF results to the SAS Add-In for Microsoft Office, or for SAS Web Report Studio. To understand this
behavior, try to open a PDF file with Microsoft Word, Microsoft Excel, or Microsoft PowerPoint. If you try to open a
PDF file with Microsoft Word, for example, you are prompted about how the file should be converted (Figure 12).
Applications Development
SAS Global Forum 2007
007
Documents you may be interested
Documents you may be interested
