43
12
(using permanent result packages), it would be possible to create multiple output files from one execution of a stored
process. However, a discussion of this advanced topic is outside the scope of this paper.
Using macro conditional logic, it is, of course, possible to write one stored process program that would execute and
return one of the three result types, RTF, PDF, or HTML. While this is an easy macro programming task, it raises
several other issues. The issues revolve around how the end-users actually work and what the end-users are
allowed to control.
If you are a member of the client-centric school of thought, then, there is no need to control or override the
destination or result type, because each of the client applications allows the end-user to set the result type
(essentially _ODSDEST) for the stored process results returned to that client application.
On the other hand, the results-centric school of thought holds that the stored process was designed as part of a
corporate reporting system where other factors (regulatory requirements, corporate standards) dictate the result
type. Therefore, according to this school of thought, it is up to the stored process author to control what values of
_ODSDEST are used or to present the end-user with a limited set of choices for _ODSDEST. For example, when you
use the BODYTITLE option (which is a requirement for some pharmaceutical-related reports) it is valid only with the
RTF destination. If that program did not
have an override for _ODSDEST, and the program were submitted from SAS
Enterprise Guide, with the default result type set to HTML, the stored process would not run and the SAS log would
contain the following error message (highlighted).
3 +%global wantreg _odsoptions _odsstyle _odsstylesheet;
4 +
5 +*ProcessBody;
6 +
7 +%let _odsstyle=rtf;
8 +%let _odsstylesheet=;
9 +%let _odsoptions = bodytitle startpage=no keepn notoc_data;
10 +
11 +%stpbegin;
11 bodytitle startpage=no keepn notoc_data
_________ _________
22 202
ERROR 22-322: Syntax error, expecting one of the following: ;, (, ANCHOR, ARCHIVE, ATTRIBUTES,
BASE, BODY, CHARSET, CLOSE, CODE, CONTENTS, CSS, ENCODING, FILE, FRAME, GFOOTNOTE, GPATH,
GTITLE,
HEADTEXT, METATEXT, NEWFILE, NOGFOOTNOTE, NOGTITLE, PAGE, PARAMETERS, PATH,
RECORD_SEPARATOR, STYLE, STYLESHEET, TEXT, TRANTAB.
ERROR 202-322: The option or parameter is not recognized and will be ignored.
Both schools can be satisfied by designing a stored process that utilizes conditional macro programming. In the
program download, the DEMO5_MACRO.SAS program utilizes one macro to set the report options and another
macro program to run the report code.
Applications Development
SAS Global Forum 2007
007
78
13
DEMO5_MACRO.SAS
(SAS Macro logic added to DEMO1_TABLE.SAS)
Program Code
Comments
%global wantreg _odsoptions _odsdest _odsstyle
_odsstylesheet;
%macro setopt;
%if %upcase(&_odsdest) = RTF %then %do;
%let _odsstyle=rtf;
%let _odsstylesheet=;
%let _odsoptions=bodytitle startpage=no
nokeepn notoc_data;
%end;
%else %if %upcase(&_odsdest) = PDF %then %do;
%let _odsstyle=printer;
%let _odsstylesheet=;
%let _odsoptions=bookmarkgen=no compress=9
startpage=no;
%end;
%else %if %upcase(&_odsdest) = HTML %then %do;
%let _odsstyle=sasweb;
%let _odsstylesheet=;
%let _odsoptions= rs=none;
%end;
%else %if %upcase(&_odsdest)=TAGSETS.SASREPORT11
%then %do;
%let _odsstyle=normal;
%let _odsstylesheet=;
%let _odsoptions=;
%end;
options nodate nonumber missing='0'
orientation=landscape;
%mend setopt;
%macro RegRept;
/*
. . . SAS Code from DEMO1.HTML . . .
. . . for PROC SORT, PROC FORMAT, . . .
. . . PROC REPORT and PROC TABULATE . . .
*/
%mend RegRept;
*ProcessBody;
%setopt;
%stpbegin;
%RegRept;
%stpend;
Declare GLOBAL macro variables.
Define SETOPT macro program.
RTF settings for SAS Add-In for Microsoft
Office.
PDF settings for SAS Enterprise Guide or
Stored Process Web Application.
HTML settings for SAS Enterprise Guide, SAS
Add-In for Microsoft Office, Stored Process
Web Application.
XML SAS Report format for SAS Web Report
Studio and other client applications.
General SAS system options which may not
be used by all client applications.
End SETOPT macro definition.
Define REGREPT macro program.
SAS Report Code unchanged from
DEMO1_TABLE.SAS
End REGREPT macro definition.
Start the stored process-specific code with
*ProcessBody. Set the options before
%STPBEGIN, and then invoke the reporting
macro program. Finally, end the stored
process with %STPEND.
This program can be registered two different ways. If you register the program with just an input parameter for
REGION (DEMO5_MACRO stored process), you would use this version of the stored process to allow the end-user to
pick the result type using the client application options. On the other hand, if you registered the stored process with
input parameters for Region and Destination (DEMO5_MACRO_ALT stored process), you would use this alternative
stored process if you wanted to allow the end-use to pick the result type (_ODSDEST value) using the property sheet
interface.
Applications Development
SAS Global Forum 2007
007
29
14
STEPS 3-4: REGISTER THE STORED PROCESS METADATA AND TEST
The last topic connects Step 2 to Step 3 and Step4. An understanding of the reserved macro variables used by
%STPBEGIN and %STPEND is necessary for converting your legacy programs to stored processes. In the previous
examples, we focused primarily on the input parameters and the reserved macro variables; we did not talk about
registering the stored processes, explicitly, although each of the stored process was registered in the metadata to
use the Stored Process Server as the server for execution and to use Streaming output as the output type. However,
in order to successfully execute the stored process and return results to the client application, you also need an
understanding of the different output types that a stored process can return. Both of these requirements converge
when we talk about converting a SAS/GRAPH program to a stored process.
CONVERSION OF SAS/GRAPH PROGRAMS
When you convert a SAS/GRAPH program, you have several decisions to make that are unique to the production of
graphical output:
•
Information needed for Step 2 and program conversion:
o What device driver should be used to create my output?
o What graphics options need to be supplied in overrides to the %STPBEGIN macro call?
•
Information needed for Step 3 and metadata registration:
o What stored process output type do I choose?
The program DEMO1_GRAPH.SAS contains two PROC REPORT steps and one PROC GCHART step that uses
DEVICE=ACTXIMG to produce the output, as shown below (Figure 13):
Figure 13: Partial Report Results (SAS/GRAPH only)
Like ODS options, the reserved parameters for graphics options must be specified before %STPBEGIN. So the
conversion of the program is really no different from the ODS programs above. The conversion for the
DEMO6_GRAPH.SAS program is shown below.
Applications Development
SAS Global Forum 2007
007
38
15
Original Code
Modified Code
From DEMO1_GRAPH.SAS
Saved as DEMO6_GRAPH.SAS
ods html path='c:\temp\' (url=none)
file='demo1_graph.html'
style=analysis;
goptions device=actximg xpixels=640
ypixels=480;
. . . SAS Code. . .
ods html close;
%global wantreg _odsstyle _odsstylesheet
_odsoptions _gopt_device
_gopt_xpixels _gopt_ypixels;
*ProcessBody;
%let _odsstylesheet=;
%let _odsstyle=analysis;
%let _gopt_device=actximg;
%let _gopt_xpixels = 640;
%let _gopt_ypixels = 480;
%stpbegin;
goptions device=&_gopt_device
xpixels=&_gopt_xpixels
ypixels=&_gopt_ypixels;
. . . SAS Code. . .
%stpend;
Once the program is converted, the stored process is registered in the metadata with the following Execution
properties (same as for the previous stored processes) (Figure 14):
Figure 14: Execution Properties of DEMO6_GRAPH Stored Process
When the stored process executes in SAS Enterprise Guide, the output (Figure 16) looks the same as that shown in
Figure 13.
Here's where Step 4 in the conversion process pays off. When we test the stored process from within Microsoft
Word, it is immediately apparent from the big X in the Word document (Figure 15) that there was something wrong
with the image.
Applications Development
SAS Global Forum 2007
007
VB.NET PDF: Basic SDK Concept of XDoc.PDF You may add PDF document protection functionality into your VB.NET of PDF document, including editing PDF url links and quick navigation link in bookmark
pdf links; chrome pdf from link
13
16
Figure15: Stored Process Results in Microsoft Word When Output Type Is Streaming
Normally, if you have a simple text-based report (such as tabular results), the Streaming output type is fine.
However, one of the rules of streaming output is that only one content type can be delivered via the client-server
connection. SAS Enterprise Guide takes care of this issue with an option setting that forces Streaming output to be
Transient output (Figure 16). Web applications do not have this problem with streaming results because they use the
HTTP protocol where graphic output remains on the Web server machine until the client machine has received all
the text output. Then another HTTP request goes back to the server for the images, which represent a different
content-type.
Figure 16: Stored Process Results in SAS Enterprise Guide
Applications Development
SAS Global Forum 2007
007
25
17
Figure 17 shows the reason that the output looked fine in SAS Enterprise Guide and didn't look fine in Microsoft
Word. The output type of streaming works well with SAS Enterprise Guide. The "Force Streaming to Transient"
setting protects you from the consequences of setting Streaming as the stored process output type.
Figure17: Force Streaming to Transient Setting
This setting can be found on the Tools menu. If you select Tools
Æ
Options
and look at the default SAS Enterprise
Guide settings for a stored process, you will see a setting that forces Streaming output to be generated as Transient
output instead. If you turned off this setting (by deselecting it), then SAS Enterprise Guide would also have an X
indicating that there were problems with the graphical results.
STREAMING, TRANSIENT, AND PERMANENT PACKAGE RESULTS
The SAS Intelligence Platform can produce two other kinds of output from stored processes instead of Streaming
output. Transient output is returned immediately to the client application, and images are stored in a temporary
cache location on the client machine. When the client application closes, all the transient output files are cleared.
Permanent output is also returned immediately to the client application; however, a stored process that creates
Permanent output can either write that output to a permanent location on the server file system or can write the
output to a WebDAV repository.
Consider these two different ways to create Transient and Permanent packages using programs that we have
already seen (Figures 18 and 19):
Figure 18: Create Transient Package with DEMO7_GRAPH_TRANSIENT Stored Process
Applications Development
SAS Global Forum 2007
007
19
18
Figure 19: Create Permanent Package with DEMO7_PDF_PERM Stored Process
Note how the converted SAS programs were used as the source files for these stored processes. The
DEMO6_GRAPH.SAS program was used to produce Figure 20, and the DEMO4_PDF.SAS program was used to
produce Figure 21. The only change was the use of a different output type; the program code did not change.
The Permanent output is written not as an HTML or PDF file, but instead as a package of files (or in this case, just
one file) in a special container called a SAS Package, which is similar to a ZIP file or a TAR file. The SAS Package
container permanently stores separate files, which may or may not be the same file type. For an explanation of the
possible file types that you can put into a SAS Package, refer to the section "About Packages: Package Content" in
the SAS 9.1.3 Integration Technologies Developer's Guide (SAS Institute Inc. 2007(c)). For more information about
administering and configuring Xythos in order to publish output to a WebDAV server, refer to the section
"Implementing Authentication and Authorization for the Xythos WFS WebDAV Server" in the SAS
9.1.3 Integration
Technologies Server Administrator's Guide (SAS Institute Inc. 2007).
If you run the DEMO7_GRAPH_TRANSIENT stored process, then Microsoft Word results would now contain the
graphic image as shown in Figure 20:
Applications Development
SAS Global Forum 2007
007
11
19
Figure 20: Partial Stored Process Transient Results Shown in Microsoft Word Print Preview
If you run the DEMO7_PDF_PERM stored process, then you would see this output in SAS Enterprise Guide
(Figure 21):
Figure 21: Partial Stored Process Results Shown in SAS Enterprise Guide Project
An examination of the C:\TEMP directory (which is on the server file system for a single machine install of the SAS
Intelligence Platform on Windows) reveals an SPK file (Figure 22):
Figure 22: SAS Package on the Server File System
Applications Development
SAS Global Forum 2007
007
24
20
Using the SAS Package Reader to look inside the PDF_PKG.SPK file, you see the PDF file, as shown in Figure 23.
If you open the PDF file, it will look the same as the output in Figure 21. The SAS Package Reader will essentially
"unpack" the file into a temporary location, which is defined when you install the SAS Package Reader (Figure 23).
For more information about the SAS Package Reader (which is freely downloadable and distributable) refer to the
SAS Integration Technologies Software download Web site:
www.sas.com/apps/demosdownloads/setupcat.jsp?cat=SAS+Integration+Technologies.
Figure 23: Opening a SAS Package.SPK File with SAS Package Reader
Although this file was written to a directory on the server file system, it could just as easily have been e-mailed to a
distribution list or written to a WebDAV or to a personal repository.
CONCLUSION
This paper covered a broad range of topics beyond the basic concepts of using %STPBEGIN and %STPEND to turn a
SAS program into a stored process. We started with a discussion of basic stored process conversion and then
covered how to override ODS options and SAS/GRAPH options in the conversion process. The discussion of
SAS/GRAPH options and stored processes that returned graphical results led us into the realm of output types and
the difference between Streaming, Transient, and Permanent output types.
When you are dealing with legacy programs that use the Output Delivery System, once you understand how
reserved macro parameters for %STPBEGIN work, it is easy to convert your legacy ODS programs to execute as
stored processes. Further study of issues such as publishing to a WebDAV repository or writing a custom Web
application (from which you could call a stored process via URL) or using Transient and Permanent packages for
stored process output will make your stored processes even more flexible and powerful.
Applications Development
SAS Global Forum 2007
007
Documents you may be interested
Documents you may be interested