SAS® Integration Technologies: Developer's Guide Dev Sp4 2

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 899 [warning: Documents this large are best viewed by clicking the View PDF Link!]

SAS®9.1.3Integration Technologies
Developer’s Guide, Fifth Edition
The correct bibliographic citation for this manual is as follows: SAS Institute Inc. 2006. SAS® 9.1.3 Integration
Technologies: Developer’s Guide, Fifth Edition. Cary, NC: SAS Institute Inc.
SAS 9.1.3 Integration Technologies: Developer’s Guide, Fifth Edition
Copyright © 2006, SAS Institute Inc., Cary, NC, USA
All rights reserved. Produced in the United States of America.
For a Web download or e-book: Your use of this publication shall be governed by the terms established by the
vendor at the time you acquire this publication.
U.S. Government Restricted Rights Notice. Use, duplication, or disclosure of this software and related
documentation by the U.S. government is subject to the Agreement with SAS Institute and the restrictions set forth in
FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987).
SAS Institute Inc., SAS Campus Drive, Cary, North Carolina 27513.
1st printing, November 2006
SAS Publishing provides a complete selection of books and electronic products to help customers use SAS software
to its fullest potential. For more information about our e-books, e-learning products, CDs, and hard-copy books, visit
the SAS Publishing Web site at support.sas.com/pubs or call 1-800-727-3228.
SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS
Institute Inc. in the USA and other countries. ® indicates USA registration.
Other brand and product names are registered trademarks or trademarks of their respective companies.
Table of Contents
SAS® Integration Technologies: Developer's Guide....................................................................................................1
SAS Stored Processes.......................................................................................................................................................3
Stored Process Software Requirements.........................................................................................................................4
Creating Stored Processes...............................................................................................................................................7
Input Parameters...........................................................................................................................................................10
Result Types....................................................................................................................................................................14
%STPBEGIN and %STPEND.....................................................................................................................................16
Reserved Macro Variables............................................................................................................................................21
Stored Process Server Functions..................................................................................................................................29
STPSRVGETC...............................................................................................................................................................30
STPSRVGETN...............................................................................................................................................................31
STPSRVSET...................................................................................................................................................................33
STPSRV_HEADER.......................................................................................................................................................35
STPSRV_SESSION.......................................................................................................................................................37
STPSRV_UNQUOTE2..................................................................................................................................................38
Sessions............................................................................................................................................................................39
Stored Process Samples.................................................................................................................................................42
Debugging Stored Processes..........................................................................................................................................47
Converting SAS/IntrNet Programs to Stored Processes............................................................................................49
Using Stored Processes..................................................................................................................................................52
Building a Web Application..........................................................................................................................................54
SAS Stored Process Web Application..........................................................................................................................55
SAS Stored Process Web Application Configuration.................................................................................................63
SAS® Integration Technologies: Developer's Guide
i
Table of Contents
Web Application Input..................................................................................................................................................67
HTTP Headers................................................................................................................................................................71
Embedding Graphics.....................................................................................................................................................75
Chaining Stored Processes............................................................................................................................................79
Using Sessions: A Sample Web Application................................................................................................................83
Debugging in the SAS Stored Process Web Application............................................................................................92
Implementing a Repository...........................................................................................................................................94
Creating a Stored Process.............................................................................................................................................95
Invoking a Stored Process.............................................................................................................................................97
Publishing Stored Process Results................................................................................................................................98
Working with Results in the Client Application.......................................................................................................100
SAS BI Web Services...................................................................................................................................................101
Using Web Services......................................................................................................................................................102
Deciding Between .NET and Java..............................................................................................................................103
Writing SAS Programs for Web Services..................................................................................................................104
Discover Method..........................................................................................................................................................106
Execute Method............................................................................................................................................................111
Securing SAS BI Web Services...................................................................................................................................113
Securing SAS BI Web Services for .NET with WSE 2.0..........................................................................................114
Securing SAS BI Web Services for Java....................................................................................................................121
Sample PROC MEANS Using SAS BI Web Services...............................................................................................122
Publishing Framework................................................................................................................................................126
About Packages: Package Content.............................................................................................................................128
SAS® Integration Technologies: Developer's Guide
ii
Table of Contents
Package Rendering......................................................................................................................................................129
Package Transports.....................................................................................................................................................131
Archived Packages.......................................................................................................................................................132
Subscription Channels.................................................................................................................................................134
About Events................................................................................................................................................................135
Package Publishing......................................................................................................................................................137
Publishing Using the SAS Publisher GUI..................................................................................................................138
Publishing Programmatically Using SAS..................................................................................................................141
Publishing Using a Third−Party Client Application................................................................................................142
Package Retrieval.........................................................................................................................................................143
URL Retrieval..............................................................................................................................................................145
Viewer Processing........................................................................................................................................................146
When To Use a Viewer................................................................................................................................................147
How to Create a Viewer...............................................................................................................................................148
How to Apply a Viewer................................................................................................................................................153
<SASINSERT> Tag.....................................................................................................................................................155
Substitution Syntax......................................................................................................................................................156
<SASTABLE> Tag.......................................................................................................................................................160
<SASREPEAT> Tag....................................................................................................................................................162
<SASECHO> Tag........................................................................................................................................................164
Using the <SASINSERT> and <SASTABLE> Tags: Examples..............................................................................165
Sample HTML Viewer.................................................................................................................................................166
Rendered View in E−mail............................................................................................................................................167
SAS® Integration Technologies: Developer's Guide
iii
Table of Contents
SAS Program with an HTML Viewer........................................................................................................................169
Sample Viewer Template.............................................................................................................................................171
Daily Purchase Summary............................................................................................................................................173
SAS Publisher...............................................................................................................................................................174
Package Items...............................................................................................................................................................175
SAS Publisher Requirements......................................................................................................................................176
How SAS Publisher Works.........................................................................................................................................177
Publishing Destination Types......................................................................................................................................178
Starting SAS Publisher................................................................................................................................................179
Publishing a Package...................................................................................................................................................180
Publishing a Package, and Saving and Viewing Publish Code................................................................................181
Defining Package Content (What to Publish)............................................................................................................183
Adding an Item (Specify Item to Insert)....................................................................................................................184
Adding a SAS Data Set to a Package..........................................................................................................................186
Adding a SAS Database, SAS Catalog, or SQL View to a Package........................................................................188
Adding ODS Output to a Package..............................................................................................................................189
Adding an External File to a Package........................................................................................................................192
Adding a Reference to a Package...............................................................................................................................193
Adding a Viewer to a Package....................................................................................................................................194
Specifying Package Destination (Where to Publish).................................................................................................195
Specifying Name/Value Pairs......................................................................................................................................200
Configuring Channels..................................................................................................................................................203
Specifying Package Format (How to Publish)...........................................................................................................204
SAS® Integration Technologies: Developer's Guide
iv
Table of Contents
Using SAS Publisher with SAS/Warehouse Administrator.....................................................................................209
SAS Subscription Manager.........................................................................................................................................210
Overview.......................................................................................................................................................................211
SAS Subscription Manager Requirements................................................................................................................212
Logging On...................................................................................................................................................................213
Subscription Manager Interface.................................................................................................................................214
Channels........................................................................................................................................................................216
Subscribing to a Channel............................................................................................................................................217
Unsubscribing from a Channel...................................................................................................................................218
Viewing Channel Details.............................................................................................................................................219
Searching Channels......................................................................................................................................................220
Subscriptions................................................................................................................................................................221
Viewing Your Subscriptions.......................................................................................................................................222
Viewing Subscription Details......................................................................................................................................223
Defining or Modifying Your Default Subscription Properties................................................................................224
Defining Unique Subscription Properties..................................................................................................................225
Restoring a Subscription to Your Default Subscription Properties........................................................................226
Subscriber Groups.......................................................................................................................................................227
Viewing Your Group Memberships...........................................................................................................................228
SAS Package Reader....................................................................................................................................................229
SAS Package.................................................................................................................................................................230
Overview.......................................................................................................................................................................231
SAS Package Reader Requirements...........................................................................................................................232
SAS® Integration Technologies: Developer's Guide
v
Table of Contents
Package Reader Interface...........................................................................................................................................233
Accessing a SAS Package............................................................................................................................................236
Listing One or More Packages....................................................................................................................................237
Listing Package Entries...............................................................................................................................................238
Viewing Package Properties........................................................................................................................................239
Viewing Package Entry Properties.............................................................................................................................240
Viewing an Entry in a Web Browser..........................................................................................................................241
Viewing SAS Data Sets................................................................................................................................................242
Saving a Package Entry...............................................................................................................................................244
SAS Package Retriever................................................................................................................................................245
SAS Package Retriever Requirements.......................................................................................................................246
Invoking SAS Package Retriever................................................................................................................................247
Obtaining a Package from an Archive.......................................................................................................................248
Advanced Archive Properties.....................................................................................................................................249
Obtaining a Package from a Queue............................................................................................................................251
Advanced Queue Properties........................................................................................................................................252
Obtaining a Package from WebDAV.........................................................................................................................253
Advanced WebDAV Properties..................................................................................................................................254
Selecting Package Entries for Retrieval and Storage...............................................................................................255
Retrieving and Storing a Package Entry...................................................................................................................257
Retrieving and Storing a Data Set..............................................................................................................................258
Retrieving and Storing a Catalog, MDDB, or SQLView Entry...............................................................................260
Retrieving and Storing a Binary File Entry..............................................................................................................261
SAS® Integration Technologies: Developer's Guide
vi
Table of Contents
Storing a Binary CSV File Entry................................................................................................................................262
Retrieving and Storing an HTML File Entry............................................................................................................263
HTML and Viewer Encoding Property.....................................................................................................................266
Storing a Companion File............................................................................................................................................267
Retrieving and Storing a Text File Entry..................................................................................................................268
Retrieving and Storing a Viewer File Entry..............................................................................................................269
Removing the Package from the Transport Location..............................................................................................270
Publish Package Interface...........................................................................................................................................272
Publish/Retrieve Encoding Behavior.........................................................................................................................273
INSERT_CATALOG...................................................................................................................................................275
INSERT_DATASET....................................................................................................................................................277
INSERT_FDB...............................................................................................................................................................280
INSERT_FILE.............................................................................................................................................................282
INSERT_HTML...........................................................................................................................................................284
INSERT_MDDB...........................................................................................................................................................288
INSERT_PACKAGE...................................................................................................................................................290
INSERT_REF...............................................................................................................................................................292
INSERT_SQLVIEW....................................................................................................................................................294
INSERT_VIEWER......................................................................................................................................................296
PACKAGE_BEGIN.....................................................................................................................................................298
PACKAGE_END.........................................................................................................................................................301
PACKAGE_PUBLISH................................................................................................................................................302
Publish to an Archive...................................................................................................................................................306
SAS® Integration Technologies: Developer's Guide
vii
Table of Contents
Publish to E−mail.........................................................................................................................................................308
Publish to Queues.........................................................................................................................................................313
Publish to Subscribers.................................................................................................................................................316
Publish to a WebDAV−Compliant Server.................................................................................................................322
LDAP Channel Store Syntax......................................................................................................................................326
SAS Metadata Repository Channel Store Syntax.....................................................................................................327
COMPANION_NEXT.................................................................................................................................................328
ENTRY_FIRST............................................................................................................................................................330
ENTRY_NEXT.............................................................................................................................................................332
PACKAGE_DESTROY..............................................................................................................................................334
PACKAGE_FIRST......................................................................................................................................................335
PACKAGE_NEXT.......................................................................................................................................................337
PACKAGE_TERM......................................................................................................................................................339
RETRIEVE_CATALOG.............................................................................................................................................340
RETRIEVE_DATASET..............................................................................................................................................341
RETRIEVE_FDB.........................................................................................................................................................343
RETRIEVE_FILE.......................................................................................................................................................344
RETRIEVE_HTML.....................................................................................................................................................345
RETRIEVE_MDDB.....................................................................................................................................................348
RETRIEVE_NESTED.................................................................................................................................................349
RETRIEVE_PACKAGE.............................................................................................................................................351
RETRIEVE_REF.........................................................................................................................................................355
RETRIEVE_SQLVIEW..............................................................................................................................................356
SAS® Integration Technologies: Developer's Guide
viii
Table of Contents
RETRIEVE_VIEWER................................................................................................................................................357
Filtering Packages and Package Entries....................................................................................................................358
Example: Publishing in the Data Step........................................................................................................................360
Example: Publishing in a Macro................................................................................................................................364
Example: Publishing with the FTP Access Method..................................................................................................367
Publish Event Interface (CALL Routines)................................................................................................................370
EVENT_BEGIN...........................................................................................................................................................371
EVENT_BODY............................................................................................................................................................375
EVENT_PUBLISH......................................................................................................................................................377
EVENT_END...............................................................................................................................................................383
XML Specification for Generic Events......................................................................................................................384
XML Specification for SASPackage Events..............................................................................................................386
Examples of Generated Events...................................................................................................................................390
Application Messaging Overview...............................................................................................................................393
Supported Messaging Interface Versions..................................................................................................................395
Configuring WebSphere MQ with the WebSphere MQ Explorer..........................................................................396
Polling Message Queues from the Object Spawner..................................................................................................403
Configuring Multiple Clients To Read From a Single Queue.................................................................................406
Configuring WebSphere MQ to Trigger SAS: An Example....................................................................................410
Sample Trigger Programs...........................................................................................................................................417
WebSphere MQ Functional Interface........................................................................................................................423
Writing WebSphere MQ Applications.......................................................................................................................424
WebSphere MQ Coding Examples.............................................................................................................................427
SAS® Integration Technologies: Developer's Guide
ix
Table of Contents
WebSphere MQ CALL Routines................................................................................................................................465
WebSphere MQ CALL Routines................................................................................................................................466
MQCONN.....................................................................................................................................................................467
MQDISC.......................................................................................................................................................................468
MQOPEN......................................................................................................................................................................469
MQCLOSE...................................................................................................................................................................471
MQPUT.........................................................................................................................................................................472
MQPUT1.......................................................................................................................................................................474
MQGET........................................................................................................................................................................476
MQCMIT......................................................................................................................................................................478
MQBACK.....................................................................................................................................................................479
MQINQ.........................................................................................................................................................................480
MQSET.........................................................................................................................................................................486
MQPMO.......................................................................................................................................................................487
MQGMO.......................................................................................................................................................................490
MQOD...........................................................................................................................................................................493
MQMD..........................................................................................................................................................................495
MQMAP........................................................................................................................................................................500
MQSETPARMS...........................................................................................................................................................502
MQGETPARMS..........................................................................................................................................................503
MQRMH.......................................................................................................................................................................504
MQFREE......................................................................................................................................................................508
MSMQ Functional Interface.......................................................................................................................................509
SAS® Integration Technologies: Developer's Guide
x
Table of Contents
Writing MSMQ Applications......................................................................................................................................510
MSMQ Code Samples..................................................................................................................................................511
MSMQ CALL Routines...............................................................................................................................................529
MSMQ CALL Routines...............................................................................................................................................530
MSMQCREATEQUEUE............................................................................................................................................531
MSMQDELETEQUEUE............................................................................................................................................534
MSMQOPENQUEUE.................................................................................................................................................535
MSMQCLOSEQUEUE...............................................................................................................................................537
MSMQPATHTOFORMAT........................................................................................................................................538
MSMQINSTTOFORMAT..........................................................................................................................................540
MSMQHNDLTOFORMAT........................................................................................................................................541
MSMQSENDMSG.......................................................................................................................................................542
MSMQRECEIVEMSG...............................................................................................................................................546
MSMQCREATECURSOR.........................................................................................................................................551
MSMQCLOSECURSOR............................................................................................................................................552
MSMQBEGINTRANS................................................................................................................................................553
MSMQCOMMITTRANS...........................................................................................................................................554
MSMQABORTTRANS...............................................................................................................................................555
MSMQRELEASETRANS...........................................................................................................................................556
MSMQLOCATE..........................................................................................................................................................557
MSMQGETQPROP....................................................................................................................................................561
MSMQSETQPROP.....................................................................................................................................................564
MSMQGETQSEC.......................................................................................................................................................566
SAS® Integration Technologies: Developer's Guide
xi
Table of Contents
MSMQSETQSEC........................................................................................................................................................568
MSMQGETSCONTEXT............................................................................................................................................570
MSMQFREESCONTEXT..........................................................................................................................................571
MSMQMAP..................................................................................................................................................................572
MSMQSETPARMS.....................................................................................................................................................574
MSMQGETPARMS....................................................................................................................................................575
MSMQFREE................................................................................................................................................................576
Common Messaging Interface....................................................................................................................................577
Writing Applications Using the Common Messaging Interface..............................................................................578
Using TIB/Rendezvous with the SAS Common Messaging Interface.....................................................................581
TIB/Rendezvous Coding Example..............................................................................................................................583
TIB/Rendezvous Certified Messaging Coding Examples.........................................................................................586
Using a Repository with Application Messaging.......................................................................................................593
Using the SAS Registry with the Common Messaging Interface.............................................................................594
Using an LDAP Server with the Common Messaging Interface.............................................................................598
Common Messaging Interface CALL Routines........................................................................................................603
SAS CALL Routines for the Common Messaging Interface...................................................................................604
SETALIAS....................................................................................................................................................................605
SETMAP.......................................................................................................................................................................607
SETMODEL.................................................................................................................................................................609
GETALIAS...................................................................................................................................................................613
GETMAP......................................................................................................................................................................615
GETMODEL................................................................................................................................................................617
SAS® Integration Technologies: Developer's Guide
xii
Table of Contents
DELETEALIAS...........................................................................................................................................................619
DELETEMAP..............................................................................................................................................................621
DELETEMODEL........................................................................................................................................................622
INIT...............................................................................................................................................................................624
TERM............................................................................................................................................................................626
OPENQUEUE..............................................................................................................................................................627
CLOSEQUEUE............................................................................................................................................................631
SENDMESSAGE.........................................................................................................................................................633
RECEIVEMESSAGE..................................................................................................................................................642
PARSEMESSAGE.......................................................................................................................................................647
BEGINTRANSACTION.............................................................................................................................................649
Commit..........................................................................................................................................................................650
Abort.............................................................................................................................................................................651
FREETRANSACTION...............................................................................................................................................652
GETATTACHMENT..................................................................................................................................................653
ACCEPTATTACHMENT..........................................................................................................................................656
GETQUEUEPROPS....................................................................................................................................................658
Attachment Layout for Websphere MQ and MSMQ...............................................................................................661
Attachment Layout for TIB/Rendezvous...................................................................................................................665
Attachment Error Handling.......................................................................................................................................674
Developing Java Clients...............................................................................................................................................677
Java Client Installation and JRE Requirements.......................................................................................................678
Java Client Security.....................................................................................................................................................679
SAS® Integration Technologies: Developer's Guide
xiii
Table of Contents
Using the IOM Server..................................................................................................................................................680
Using the Java Connection Factory............................................................................................................................682
Connecting with Directly Supplied Server Attributes..............................................................................................685
Connecting with Server Attributes Read from a SAS Metadata Server................................................................687
Connecting with Server Attributes Read from an LDAP Server............................................................................690
Connecting with Server Attributes Read from the Information Service................................................................692
Java Connection Factory Language Service Example.............................................................................................694
Logging Java Connection Factory Activity...............................................................................................................695
Using Failover...............................................................................................................................................................697
Using Load Balancing..................................................................................................................................................698
Using Connection Pooling...........................................................................................................................................699
Pooling with Directly Supplied Server Attributes....................................................................................................701
Pooling with Server Attributes Read from a Metadata Server...............................................................................705
Pooling with Server Attributes Read from the Information Service......................................................................706
Returning Connections to the Java Connection Factory.........................................................................................708
Using Java CORBA Stubs for IOM Objects.............................................................................................................710
Null References.............................................................................................................................................................711
Exception Handling......................................................................................................................................................712
Output Parameters......................................................................................................................................................713
Generic Object References..........................................................................................................................................714
IOM Objects that Support More Than One Stub.....................................................................................................715
Events and Connection Points....................................................................................................................................716
Datetime Values............................................................................................................................................................719
SAS® Integration Technologies: Developer's Guide
xiv
Table of Contents
Getting a JDBC Connection Object...........................................................................................................................720
Using the Java Workspace Factory............................................................................................................................721
Connecting with Directly Supplied Server Properties..............................................................................................722
Connecting with Server Properties Read from an LDAP Server............................................................................727
Java Workspace Factory Language Service Example..............................................................................................732
Returning a Workspace to the Java Workspace Factory........................................................................................733
SAS Foundation Services.............................................................................................................................................735
Connection Service.......................................................................................................................................................736
Discovery Service.........................................................................................................................................................737
Event Broker Service...................................................................................................................................................738
Information Service.....................................................................................................................................................739
Logging Service............................................................................................................................................................740
Publish Service.............................................................................................................................................................741
Security Service............................................................................................................................................................742
Session Service..............................................................................................................................................................743
Stored Process Service.................................................................................................................................................744
User Service..................................................................................................................................................................745
Developing Windows Clients.......................................................................................................................................746
Client Requirements....................................................................................................................................................747
Client Installation.........................................................................................................................................................748
Windows Client Security.............................................................................................................................................750
Selecting a Windows Programming Language.........................................................................................................755
Programming with Visual Basic.................................................................................................................................756
SAS® Integration Technologies: Developer's Guide
xv
Table of Contents
Programming in the .NET Environment...................................................................................................................766
Using VBScript.............................................................................................................................................................779
Programming with Visual C++...................................................................................................................................784
Using the SAS Object Manager..................................................................................................................................786
Creating an Object.......................................................................................................................................................788
SAS Object Manager Interfaces.................................................................................................................................791
Using a Metadata Server with the SAS Object Manager.........................................................................................792
Metadata Configuration Files.....................................................................................................................................794
SAS Object Manager Error Reporting......................................................................................................................796
SAS Object Manager Code Samples..........................................................................................................................798
Using Connection Pooling...........................................................................................................................................801
Choosing SAS Integration Technologies or COM+ Pooling....................................................................................803
Using SAS Integration Technologies Pooling............................................................................................................804
Using COM+ Pooling..................................................................................................................................................807
Pooling Samples............................................................................................................................................................810
Using the SAS IOM Data Provider............................................................................................................................811
Using the Workspace Manager...................................................................................................................................812
Launching IOM Servers..............................................................................................................................................813
Administering the SAS Workspace Manager...........................................................................................................815
SASWorkspaceManager Interfaces...........................................................................................................................816
Error Reporting...........................................................................................................................................................819
Using Workspace Pooling............................................................................................................................................821
Code Samples................................................................................................................................................................828
SAS® Integration Technologies: Developer's Guide
xvi
Table of Contents
Directory Services........................................................................................................................................................832
Directory Services Overview.......................................................................................................................................833
Directory Services and Integration Technologies.....................................................................................................838
Application Interfaces..................................................................................................................................................840
LDAP CALL Routine Interface..................................................................................................................................841
LDAPS_ADD................................................................................................................................................................842
LDAPS_ATTRNAME.................................................................................................................................................844
LDAPS_ATTRVALUE...............................................................................................................................................846
LDAPS_CLOSE...........................................................................................................................................................848
LDAPS_DELETE........................................................................................................................................................849
LDAPS_ENTRY...........................................................................................................................................................850
LDAPS_FREE..............................................................................................................................................................852
LDAPS_MODIFY........................................................................................................................................................853
LDAPS_OPEN.............................................................................................................................................................855
LDAPS_SETOPTIONS...............................................................................................................................................857
LDAPS_SEARCH........................................................................................................................................................859
Adding a Directory Entry to an LDAP Server..........................................................................................................861
Searching an LDAP Directory....................................................................................................................................863
LDAP SCL Interface...................................................................................................................................................865
_ADD.............................................................................................................................................................................866
_CLOSE........................................................................................................................................................................868
_DELETE.....................................................................................................................................................................869
_MODIFY.....................................................................................................................................................................870
SAS® Integration Technologies: Developer's Guide
xvii
Table of Contents
_OPEN...........................................................................................................................................................................872
_SETOPTIONS............................................................................................................................................................875
_SEARCH.....................................................................................................................................................................877
SAS® Integration Technologies: Developer's Guide
xviii
SAS® Integration Technologies: Developer's Guide
This Developer's Guide provides guidance and reference materials for performing the various types of development
tasks that might be required for an Integration Technologies implementation, including:
using the Stored Processes interface to enable client applications to execute SAS programs that are stored
centrally on a server. Instructions are provided for the following tasks:
creating a SAS program that can execute as a stored process♦ implementing a repository for stored processes♦ creating a client application that invokes a stored process and which processes the results of a stored
process
♦
using the Publishing Framework to publish the results of a stored process♦
•
using SAS BI Web Services to enable client applications to obtain metadata about and execute SAS Stored
Processes using the XML for Analysis (XMLA) Version 1.1 interface.
•
using the Publishing Framework to implement proactive delivery of information to users throughout the
enterprise. Instructions and reference documentation are provided for the following tasks:
using SAS CALL routines and third−party programs to publish and retrieve packages of digital
content by way of archive locations, channels, e−mail, message queues, and WebDAV−compliant
servers
♦
using SAS CALL routines to publish electronic events♦ creating viewer templates to format package content for display♦ using the SAS Publisher, SAS Package Reader, and SAS Package Retriever applications to publish
and retrieve packages
♦
using the SAS Subscription Manager to manage users' subscriptions to publication channels
Note: Subscription Manager will not be supported in future releases of SAS Integration Technologies.
The Subscription Manager functionality will be delivered via a new interface that will continue to
allow users to manage their own channel subscriptions.
♦
•
using the CALL routines in the Application Messaging Interface to incorporate messaging services into your
SAS programs. Instructions and reference documentation are provided for the following interfaces:
IBM WebSphere MQ Interface♦ Microsoft Message Queuing Services (MSMQ) Interface♦ Common Messaging Interface, which supports TIBCO TIB/Rendezvous as well as WebSphere MQ
and MSMQ.
♦
•
using the IOM Java client interface to write applets, stand−alone applications, servlets, and Enterprise
JavaBeans that interact with IOM servers. This interface supports industry standards such as CORBA and
Java Database Connectivity (JDBC). Instructions and reference documentation are provided for the following
tasks:
installing SAS Java client components♦ using the Connection Factory to connect a Java client to an IOM server♦ using Java CORBA stubs for IOM objects and JDBC connection objects to exploit SAS analytical and
reporting functions in the IOM server
♦
returning a connection to the Connection Factory♦ encrypting messages that are exchanged with IOM servers♦
Instructions are also provided for using the Workspace Factory to access an IOM server.
•
SAS® Integration Technologies: Developer's Guide 1
using the IOM Windows client to write Microsoft Windows applications that interact with IOM servers. The
Microsoft Component Object Model (COM), on which the Windows client interface is based, is built into the
Windows operating system and into all of the leading programming language products. Instructions and
reference documentation are provided for the following tasks:
installing SAS Windows client components♦ implementing security through the use of server user IDs, client user IDs, and encryption♦ developing client applications in the Visual Basic, C++, and VBScript environments♦ using the Object Manager or Workspace Manager to access an IOM server♦ using the SAS IOM Data Provider to access SAS data sets on IOM servers in conformance with
Microsoft's OLE DB specification
♦
•
using the Directory Services to incorporate LDAP directory services functions into your SAS programs.
Instructions and reference documentation are provided for the following tasks:
using LDAP CALL routines to add, delete, modify, and search entries on an LDAP server♦ using the LDAPSERVICES class of the SAS Component Language (SCL) to add, delete, modify, and
search entries on an LDAP server
♦
•
For high level overviews of the Integration Technologies features, refer to the SAS Integration Technologies Technical
Overview. For guidance in performing the system administration tasks associated with Integration Technologies, refer
to the SAS Integration Technologies: Administrator's Guide, the SAS Integration Technologies: Server Administrator's
Guide or the SAS Integration Technologies: Administrator's Guide (LDAP version).
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
SAS® Integration Technologies: Developer's Guide 2
SAS Stored Processes
A stored process is a SAS program that is stored on a server and can be executed as required by requesting
applications. You can use stored processes for Web reporting, analytics, building Web applications, delivering
packages to clients or to the middle tier, and publishing results to channels or repositories. Stored processes can also
access any SAS data source or external file and create new data sets, files, or other data targets supported by SAS.
The ability to store your SAS programs on the server provides an effective method for change control management.
For example, instead of embedding the SAS code into client applications, you can centrally maintain and manage this
code from the server. This gives you the ability to change your SAS programs and at the same time ensure that every
client that invokes a stored process will always get the latest version available.
The stored process concept becomes even more powerful when you consider that these SAS programs can be invoked
from multiple client contexts. For example, you might deploy Java applets and Windows−based applications that
invoke your stored processes. If your strategy is to use a multi−tiered architecture, you can use Enterprise JavaBeans
(EJB) technology, for example, to invoke the same stored processes from an application server.
Using stored processes also enhances security and application integrity because the programs that access your
sensitive data are contained on the server instead of being widely distributed with the client applications.
There are two different types of stored processes. A limited form of stored processes, IOM Direct Interface Stored
Processes, was introduced in Version 8. This type of stored process operates on a SAS Workspace Server and
produces packages only. IOM Direct Interface Stored Processes are still fully supported. However, the focus of this
documentation is on SAS Stored Processes. SAS Stored Processes are new with SAS Integration Technologies 9, and
they can be used with either a SAS Workspace Server (to produce packages) or a SAS Stored Process Server (to
produce packages or streaming results).
You must use a SAS Metadata Server to administer SAS Stored Processes. To make a stored process accessible to
client applications, you must allocate a storage location that your server can access. Then, use BI Manager to create
metadata that describes the stored process and its location. BI Manager stores this metadata on the SAS Metadata
Server so that it can be accessed by client applications.
Note: BI Manager is available beginning with SAS Foundation Services 1.2. If you have not upgraded to this release,
then you can use Stored Process Manager to register and manage stored processes. BI Manager replaces Stored
Process Manager. For more information about using BI Manager to create and maintain the metadata defining a stored
process, see the Help in SAS Management Console.
SAS Stored Processes
SAS Stored Processes 3
Stored Process Software Requirements
General Requirements
To manage and execute SAS Stored Processes for any client environment, you must have the following components
installed:
SAS System software• SAS Management Console• BI Manager plug−in (a component of SAS Foundation Services)•
Client−Specific Requirements
Stored processes can be accessed from many different client environments. Software requirements vary depending on
the client environment.
To use SAS Stored Processes in a Web application environment, the following components are recommended:
Java Runtime Environment (JRE) or Java Development Kit (JDK)• Servlet container• SAS Web Infrastructure Kit or SAS Information Delivery Portal•
To use SAS Stored Processes in a Java application, the following components are required:
Java Development Kit (JDK)• Servlet container (for servlets or JSPs only)• SAS Foundation Services•
To access SAS Stored Processes from Microsoft Office, the following component is required:
SAS Add−In for Microsoft Office•
To access SAS Stored Processes from a Web services client, install one of the following components:
SAS BI Web Services for Java• SAS BI Web Services for .NET•
To author SAS Stored Processes in a task oriented user interface, install the following component:
SAS Enterprise Guide•
You can install all of the components on a single system or install them across multiple systems. A development
system might have all of the components on a single desktop system while a production system might have SAS
installed on one or more systems, a servlet container on another system, and client software installed on multiple
client desktop systems. See the product documentation for the individual components for specific requirements on
host platforms.
Stored Process Software Requirements 4
Components
SAS System software
Install SAS 9.1 on your designated SAS server. You must install Base SAS and SAS Integration Technologies
to run stored processes. SAS/GRAPH software is required to run some of the sample stored processes. Install
any other products that are used by your stored processes. You must also configure a SAS Metadata Server in
order to create and use stored processes. You must configure one or more stored process servers or workspace
servers to execute stored processes.
SAS Management Console
Install SAS Management Console on any system with network access to your SAS server.
SAS Foundation Services
You must install the BI Manager plug−in component of SAS Foundation Services on the same system where
you have installed SAS Management Console. This plug−in enables you to register and administer stored
processes from within SAS Management Console.
You also must install the SAS Foundation Services on systems where you develop Java applications that
access stored processes.
Java Runtime Environment (JRE)
The Java interface to SAS Stored Processes requires the Java 2 Runtime Environment (JRE), Standard
Edition. See the installation instructions for SAS Foundation Services for information about the specific
version required for your operating environment. Some development environments and servlet containers
include a copy of the appropriate version of the Java 2 JRE. If you need a copy, you can download it from the
Third−Party software CD in the SAS Installation Kit.
If you are developing Java applications or creating Java Server Pages (JSPs), then you also need the Java 2
Software Development Kit (SDK), which includes a copy of the Java 2 JRE.
Java Development Kit (JDK)
Java developers or servlet containers executing Java Server Pages (JSPs) require the Java 2 Software
Development Kit (SDK), Standard Edition. See the installation instructions for SAS Foundation Services for
information about the specific version required for your operating environment. Some development
environments and servlet containers include a copy of the appropriate version of the Java 2 SDK. If you need
a copy, you can download it from the Third−Party software CD in the SAS Installation Kit.
Servlet Container
A servlet container is a Java server that can act as a middle−tier access point to SAS Stored Processes. A
servlet container can be used to host the SAS Web Infrastructure Kit, SAS Information Delivery Portal, or
user−written servlets or Java Server Pages. See the respective product documentation for specific servlet
container requirements for the SAS Web Infrastructure Kit or SAS Information Delivery Portal software.
Servlet containers used for user−written servlets or JSPs must include a JRE version compatible with the SAS
9.1 requirements for the operating environment. The Apache Tomcat servlet container is available at no cost
from the Apache Jakarta project's Web site at http://jakarta.apache.org/.
SAS Web Infrastructure Kit and SAS Information Delivery Portal
The SAS Web Infrastructure Kit is installed on a servlet container and includes the SAS Stored Process Web
Application. This Web application enables you to execute stored processes from a Web browser or other Web
client. The SAS Information Delivery Portal includes the SAS Web Infrastructure Kit and provides the same
Web access to stored processes.
SAS Add−In for Microsoft Office
The SAS Add−In for Microsoft Office must be installed on a client Windows system to execute stored
processes from Microsoft Office on that system. The SAS Integration Technologies client for Windows must
also be installed on the same system.
SAS BI Web Services for Java
SAS® Integration Technologies: Developer's Guide
Stored Process Software Requirements 5
SAS BI Web Services for Java requires that several other components be installed, including the SAS Web
Infrastructure Kit. Refer to the installation instructions for SAS BI Web Services for Java for more
information about required components.
SAS BI Web Services for .NET
SAS BI Web Services for .NET requires the Microsoft IIS Web server.
SAS Enterprise Guide
SAS Enterprise Guide is a Microsoft Windows client application that can be installed on any system with
network access to your SAS server.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Stored Process Software Requirements 6
Creating Stored Processes
A stored process is a SAS program that is hosted on a server and described by metadata. Stored processes can be
written by anyone who is familiar with the SAS programming language or with the aid of a SAS code generator such
as SAS Enterprise Guide. The basic steps to creating a stored process are as follows:
Writing the Stored Process1. Choosing or Defining a Server2. Registering the Metadata3.
Writing the Stored Process
Almost any SAS program can be a stored process. A stored process can be written using the SAS program editor, SAS
Enterprise Guide, or any text editor. The following program is a typical stored process:
*ProcessBody;
%stpbegin;
title "Shoe Sales By Region and Product";
footnote;
proc report data=sashelp.shoes nowindows;
column region product sales;
define region / group;
define product / group;
define sales / analysis sum;
break after region / ol summarize suppress skip;
run;
%stpend;
The program begins with a standard comment that initiates input parameter processing, if any. The %STPBEGIN and
%STPEND macros initialize the Output Delivery System (ODS) and deliver the output (in this case, a report) to the
client. This stored process is capable of generating multiple output formats including HTML, XML, PDF, CSV, and
custom tagsets and then delivering the output through various techniques including streaming output, a client package,
a server−side archive package, or a WebDAV collection.
Note: You should not use the %STPBEGIN and %STPEND macros if your stored process does not use ODS or if
your stored process writes directly to the _WEBOUT fileref.
Choosing or Defining a Server
You must choose a server to host your stored process. Servers are defined in metadata and are actually logical server
definitions that can represent one or more physical server processes. There are many options including pre−started
servers, servers started on demand, and servers distributed across multiple hardware systems. You can use the Server
Manager in SAS Management Console to create or modify server definitions. For more information about server
configurations, see SAS Integration Technologies: Server Administrator's Guide.
Because the logical server description in metadata hides the server implementation details, a stored process can be
moved to or associated with any appropriate server without modifying the stored process. Moving a stored process
from one server to another requires only changing the metadata association and moving the source code if necessary.
Note that a stored process is the combination of a SAS program, the server that hosts that program, and the metadata
that describes and associates the two. It is not possible to create a stored process that is associated with more than one
Creating Stored Processes 7
server, although it is possible to create stored processes that share the same SAS program, or source code file.
Stored processes can be hosted by two types of servers: SAS Stored Process Servers and SAS Workspace Servers. The
two servers are similar, but have different capabilities and are targeted at different use cases.
Stored Process Server
The stored process server is a multi−user server. A single server process can be shared by many clients. The
recommended load−balancing configuration enables client requests to be serviced by multiple server processes across
one or more hardware systems. This approach provides a high−performance, scalable server, but imposes some
restrictions. Because the same server handles requests from multiple users, it cannot easily impersonate that user to
perform security checks. By default, the server runs under a single, shared user identity (defined in metadata) for all
requests. All security checks based on client identity must be performed in the stored process. For more information
about stored process server security, refer to the section about Planning Security on Workspace and Stored Process
Servers.
The stored process server implements several features that are not available on the workspace server, including
streaming output, sessions, and multiple−value input parameters. Stored process Web services are only supported on
the stored process server.
Workspace Server
The workspace server is a single−user server. A new server process is started for each client. This approach is not as
scalable as the load−balanced stored process server, but it has a major security advantage. Each server is started under
the client user identity and is subject to host operating environment permissions and rights for that client user. The
workspace server also provides additional functionality, including data access and execution of client−submitted SAS
code. For more information about workspace server security, refer to the section about Planning Security on
Workspace and Stored Process Servers.
Some features available on the stored process server are not available on the workspace server, as described in the
previous section. Information map stored processes are supported only on the workspace server.
Using Source Code Repositories
Stored processes are stored in external files with a .sas extension. The .sas file must reside in a directory that is
registered with the server that executes the stored process. These directories are known as source code repositories.
Source code repositories are managed using BI Manager. After you choose a server for your stored process in BI
Manager, you are presented with a list of available source code repositories. You can choose an existing source code
repository or click Manage to add or modify source code repositories.
For z/OS, the program can be contained in an HFS .sas file or in a member of a partitioned data set (PDS). Source
code repositories can be either HFS directories or a partitioned data set.
Registering the Stored Process Metadata
After you write the stored process and define or choose a server, you must register the metadata using BI Manager.
(SAS Enterprise Guide users can perform the same steps within the Enterprise Guide application.) The New Stored
Process Wizard can be used to create new stored processes, or you can use the Stored Process Properties dialog box in
BI Manager to modify existing stored processes. BI Manager enables you to specify and manage the following
information for stored processes:
SAS® Integration Technologies: Developer's Guide
Creating Stored Processes 8
Folder specifies a collection of stored processes. The folders are defined in metadata and do not correspond to any
physical location. The folder hierarchies used for stored processes can also hold SAS reports, information
maps, and administrative metadata. You can create and modify folders using BI Manager.
Name specifies the stored process name, which acts as both a display label and as part of the URI for the stored
process.
Description
specifies an optional text description of the stored process.
Keywords
specifies an optional list of keywords to associate with the stored process. Keywords are arbitrary text strings
typically used for searching or to indicate specific capabilities. For example, the keyword XMLA Web
Service is used to indicate a stored process that can be executed by SAS BI Web Services.
SAS server
specifies the server that executes the stored process.
Source Code Repository and Source Code File
specifies the directory and source code file containing the stored process.
Input specifies an optional list of input streams. Input streams can be used to send data that are too large to be
passed in parameters from the client to the executing stored process.
Output specifies the stored process result type.
Parameters
specifies an optional definition of parameters.
Authorization
specifies access controls for the stored process. Currently only the ReadMetadata and WriteMetadata
permissions are honored. A user must have ReadMetadata permission to execute the stored process.
WriteMetadata permission is required to modify the stored process definition.
You are now ready to use the stored process from a variety of clients including the SAS Stored Process Web
Application, the SAS Information Delivery Portal, the SAS Add−In for Microsoft Office, SAS Enterprise Guide, and
user−written Java applications and JSPs.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Creating Stored Processes 9
Input Parameters
Most stored processes require information from the client to perform their intended function. This information can be
in the form of presentation options for a report, selection criteria for data to be analyzed, names of data tables to be
used or created, or an unlimited number of other possibilities. Input parameters are the most common way to deliver
information from a client to a stored process.
Input parameters are defined as name/value pairs. They appear in a stored process program as global macro variables.
For example, if you have a stored process that analyzes monthly sales data, you might accept MONTH and YEAR as
input parameters. The stored process program might be:
*ProcessBody;
%stpbegin;
title "Product Sales for &MONTH, &YEAR";
proc print data=sales;
where Month eq "&MONTH" and Year eq &YEAR;
var productid product sales salesgoal;
run;
%stpend;
Because input parameters are simply macro variables, they can be accessed through normal macro substitution syntax
(&param−name) or through any other SAS functions that access macro variables (SYMGET, SYMGETC, or
SYMGETN). Parameters follow the same rules as SAS macro variables. Names must start with an alphabetic character
or underscore and can contain only alphanumeric characters or underscores. The name can be no more than 32
characters long and is case−insensitive. Values can contain any character except a null character and can be up to
65534 characters in length on the stored process server. Values are limited to approximately 5950 bytes in length and
cannot contain non−printing characters (including line feeds or carriage returns) on the workspace server.
Each stored process client interface provides one or more methods to set input parameters. The Stored Process Service
API provides a direct programming interface to set name/value pairs. The SAS Stored Process Web Application
allows name/value pairs to be specified directly on a URL or indirectly through posting HTML form data. The SAS
Add−In for Microsoft Office provides a property sheet interface to specify parameters.
There are many reserved parameters that are created by the server or the stored process client interface. See Reserved
Macro Variables for a list of these variables.
Standard Header for Parameters
Parameters are not initialized in the same way for the stored process server and the workspace server. The stored
process server sets parameter values before the stored process begins to execute. This means the first line of code in
the stored process can access any input parameter macro variable. The workspace server does not set input parameters
into macro variables until it reaches a *ProcessBody; comment line in the stored process:
*ProcessBody;
A stored process that does not contain this line will never receive input parameters when executed on a workspace
server.
It is recommended that you begin all stored processes (regardless of the server types) with %GLOBAL declarations for
Input Parameters 10
all of your input parameters followed by the *ProcessBody; comment:
/* *****************************************************
* Standard header comment documenting your
* stored process and input parameters.
* ************************************************** */
%global parmone parmtwo parmthree;
%global parmfour;
*ProcessBody;
... remainder of the stored process ...
The %GLOBAL declarations create an empty macro variable for each possible input parameter and enable you to
reference the macro variable in the stored process even if it was not set by the stored process client. If you do not
declare input parameters in a %GLOBAL statement, then any references to an unset input parameter will result in
WARNING messages in the SAS log.
Defining Parameters
Most stored process client interfaces allow a client to pass any input parameter. There is no requirement to define
parameters before executing the stored process, but there are many advantages to describing parameters in stored
process metadata:
Parameter definitions can specify labels and descriptive text. This information can be used by client interfaces
to present a more attractive and informative user interface. Other presentation options include grouping
parameters and expert flags.
•
Default values can be specified. The default value is used if the parameter value is not specified by the client.• Default values can optionally be flagged as non−modifiable to allow a fixed parameter value to always be
passed into a stored process. This can be useful when using an existing program that accepts many input
parameters. You can register a new, simpler stored process that has some fixed value parameters and fewer
client specified parameters.
You can also register multiple stored processes for a single program. Each stored process definition can pass
in unique fixed parameter values to the executing program to force a particular operation or otherwise affect
the execution of the stored process.
•
Parameters can be flagged as required. A stored process will not run unless the client specifies these
parameters.
•
Parameters can be limited to a specific type such as Boolean, Integer, or Float. Defining a parameter type
causes certain client user interfaces (such as the SAS Add−In for Microsoft Office) to present more
appropriate input controls. All interfaces will reject stored process requests with input parameters that do not
match the specified type.
•
Parameter values can be limited by constraints. Constraints can specify enumerated lists or ranges of valid
values for a parameter. Note that constraints are currently only supported by the SAS Add−In for Microsoft
Office interface. Other stored process interfaces do not enforce constraints.
•
Parameter metadata for a stored process can be added or modified using BI Manager.
Note: Multi−line text parameters are not supported for stored processes on workspace servers.
SAS® Integration Technologies: Developer's Guide
Input Parameters 11
Special Character Quoting
Input parameter values are specified by the stored process client at run time. The author of a stored process has little
control over the values a client can specify. Setting the values directly into SAS macro variables would allow clients
to insert executable macro code into a stored process and could lead to unexpected behavior or unacceptable security
risks. For example, if an input parameter named COMP was set to "Jones&Comp." and passed directly into the
macro variable, any references to &COMP in the stored process program would lead to an invalid recursive macro
reference. To avoid this problem, stored process parameters are masked with SAS macro quoting functions before
being set into macro variables. In the previous example, the parameter COMP would be set with the equivalent of:
%let COMP=%nrstr(Jones&Comp.);
The stored process can then freely use &COMP without special handling for unusual input values. Special characters
that are masked for input parameters are the ampersand (&), apostrophe ('), percent sign (%), quotation marks ("), and
semicolon (;).
There might be special cases where you want to unmask some or all of the special characters in an input parameter.
The STPSRV_UNQUOTE2 function unmasks only matched apostrophe (') or quotation mark (") characters. This can
be useful for passing in parameters that are used as SAS options. The %UNQUOTE macro function unquotes all
characters in an input parameter, but you should only use this function in very limited circumstances. You should
carefully analyze the potential risk from unexpected client behavior before unquoting input parameters. Remember
that stored processes can be executed from multiple clients and some client interfaces perform little or no checking of
input parameter values before they are passed to the stored process.
Note: An input parameter to a stored process executing on a workspace server cannot contain both apostrophe (') and
quotation mark (") characters. Attempting to set such an input parameter will result in an error.
Multiple Values
Parameters with multiple values (or alternatively, multiple input parameters with the same name) can be useful in
some stored processes. For example, an HTML input form used to drive a stored process might contain a group of
four check boxes, each named CBOX. The value associated with each box is optOne, optTwo, optThree, and optFour.
The HTML for these check boxes might be
<input type="CHECKBOX" name="CBOX" value="optOne">
<input type="CHECKBOX" name="CBOX" value="optTwo">
<input type="CHECKBOX" name="CBOX" value="optThree">
<input type="CHECKBOX" name="CBOX" value="optFour">
If you select all four boxes and submit the form to the SAS Stored Process Web Application, then the query string
looks like
&CBOX=optOne&CBOX=optTwo&CBOX=optThree&CBOX=optFour
Macro variables cannot hold more than one value. The two types of servers that execute stored processes handle this
problem in different ways.
Note: Stored processes running on a workspace server have access only to the last value specified for the parameter.
All other values are lost.
SAS® Integration Technologies: Developer's Guide
Input Parameters 12
The stored process server uses a macro variable naming convention to pass multiple values to the stored process. A
numeric suffix is added to the parameter name to distinguish between values. The number of values is set in
<param−name>0, the first value is set in <param−name>1, and so on. In the previous example, the following
macro variables are set as follows:
CBOX = optOne
CBOX0 = 4
CBOX1 = optOne
CBOX2 = optTwo
CBOX3 = optThree
CBOX4 = optFour
Note that the original parameter macro variable (CBOX) is always set to the first parameter value.
Any client application can generate multiple value parameters. The typical uses for multiple values are check box
groups in HTML input forms and selection lists that allow multiple selection.
Hiding Passwords and Other Sensitive Data from the SAS Log
The SAS log exposes programs and input parameters, which could pose a security issue. There are some actions you
can take to hide passwords and other sensitive data from the SAS log. Password values are hidden from the SAS log
for any input parameters with _PASSWORD anywhere in the parameter name (for example, ABC_PASSWORD,
_PASSWORDABC). You can disable the SAS log with the DebugMask Web application initialization parameter.
You can also use the prefix _NOLOG_ with macro variables to hide request variable values.
The _NOLOG_ feature enables you to create special macro variables that can be sent to the stored process server
without publishing the macro variable values in the SAS log. The special macro variables must start with the prefix
_NOLOG_. The prefix is case insensitive. For example:
http://yourserver/SASStoredProcess/do?
&_program=/WebApps/Sales/Employee+Salary&_nolog_salary=secretpw
If _NOLOG_SALARY is displayed in the SAS logs, it shows
_NOLOG_SALARY=XXXXXXXX;
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Input Parameters 13
Result Types
A stored process is a SAS program and can produce any kind of output that a valid SAS program can produce. Output
could include data sets, external files, e−mail messages, SAS catalogs, packages, and many other objects. In some
cases, output (or a "result") is delivered to the client application executing the stored process. In other cases, the output
is generated only on the server. When creating a stored process, you must describe any output that is returned to the
client. There are four types of client output.
The simplest result type is None. The client receives no output from the stored process. The stored process is
still able to create or update data sets, external files or other objects, but this output remains on the server.
This result type is indicated by the input parameter _RESULT set to STATUS, because only the program
status is returned to the client.
•
Streaming output delivers a data stream, such as an HTML page or XML document, to the client. This result
type is indicated by _RESULT set to STREAM. The data stream can be textual or binary data and is visible to
the stored process program as the _WEBOUT fileref. Any data written to the _WEBOUT fileref is streamed
back to the client application. Streaming output is supported only on the stored process server. Stored
processes executing on a workspace server cannot use streaming output.
•
Transient package output returns a temporary package to the client. The package can contain multiple entries,
including SAS data sets, HTML files, image files, or any other text or binary files. The package exists only as
long as the client is connected to the server. This result type is a convenient way to deliver multiple output
objects (such as an HTML page with associated GIF or PNG images) to a client application. Transient
package output is available on both stored process and workspace servers, but the implementations differ. On
the stored process server, transient package output is indicated by _RESULT set to PACKAGE_TO_ARCHIVE
and the input parameter _ARCHIVE_PATH set to TEMPFILE. On the workspace server, transient package
output is indicated by _RESULT set to PACKAGE_TO_REQUESTER.
•
Permanent package output creates a package in a permanent location on a WebDAV server or in the server
file system. The package is immediately accessible to the stored process client, but is also permanently
accessible to any client with access to WebDAV or the server file system. This result type is a convenient way
to publish output for permanent access.
Output to WebDAV is indicated by _RESULT set to PACKAGE_TO_WEBDAV. The input parameter
_COLLECTION_URL contains the target location. The input parameters _HTTP_USER and
_HTTP_PASSWORD might be set if the WebDAV server is secured and credentials are available.
_HTTP_PROXY_URL is set if an HTTP proxy server is required to access the WebDAV server. Output to
the server file system is indicated by _RESULT set to PACKAGE_TO_ARCHIVE. The input parameters
_ARCHIVE_PATH and _ARCHIVE_NAME contain the target repository and filename, respectively.
•
Note that although the result type is chosen when you define a stored process, the result type can be changed by the
client application through calls to the Stored Process Service API. Where possible, it is recommended that you write
stored processes to support any appropriate client result type. This enables a client application to select the result type
most appropriate for that application. The program can determine the desired client result type by examining the
_RESULT input parameter. The %STPBEGIN and %STPEND macros include support for any of the four result
types. The following stored process is capable of generating streaming, transient package, or permanent package
output. (It can also be run with _RESULT set to STATUS, but this would produce no useful result.)
*ProcessBody;
%stpbegin;
proc print data=SASHELP.CLASS noobs;
var name age height;
run;
%stpend;
Result Types 14
The input parameters mentioned previously are set by the stored process client APIs and are reserved parameters.
They cannot be overridden by passing in new values through the normal parameter interface. Special API methods are
provided to set the result type and associated parameters for a stored process. See Reserved Macro Variables for more
information about specific input parameters.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Result Types 15
%STPBEGIN and %STPEND
The %STPBEGIN and %STPEND macros provide standardized functionality for generating and delivering output
from a stored process. This enables you to write stored processes that generate content in a variety of formats and
styles with minimal programming effort. A typical stored process using these macros follows:
/* *****************************************************
* Header comment documenting your
* stored process and input parameters.
* ************************************************** */
%global input parameters;
*ProcessBody;
... any pre−processing of input parameters ...
%stpbegin;
... stored process body ...
%stpend;
Note: You must include a semicolon at the end of the %STPBEGIN and %STPEND macro calls.
The %STPBEGIN macro initializes the Output Delivery System (ODS) to generate output from the stored process.
The %STPEND macro terminates ODS processing and completes delivery of the output to the client or other
destinations. The macros must be used as a matched pair for proper operation. Streaming output and package output
are supported. These macros rely on many reserved macro variables to control their actions. See the section on
Reserved Macro Variables for a more detailed description of each macro variable mentioned in the following sections.
Stored processes that do not use ODS to generate output should not use these macros or should set _ODSDEST to
NONE to disable ODS initialization. In this case, your stored process must explicitly create any output.
ODS Options
ODS options are specified by various global macro variables. These variables are normally set by input parameters,
but can be modified by the stored process. The following variables affect ODS output:
_ENCODING• _GOPT_DEVICE• _GOPT_HSIZE• _GOPT_VSIZE• _GOPT_XPIXELS• _GOPT_YPIXELS• _GOPTIONS• _ODSDEST• _ODSOPTIONS• _ODSSTYLE• _ODSSTYLESHEET•
The _ODSDEST variable is important because changing this variable enables your stored process to generate HTML,
PDF, postscript, or a variety of other formats, including user written tagset destinations. Note that there are many
variables that allow you to override ODS options. You must remember to verify whether any options specified by the
%STPBEGIN and %STPEND 16
stored process or its clients are compatible with the output destinations you plan to support.
Note that some ODS options (for example, BASE) are set based on the result options. These options are generally
transparent to the stored process author, but they can make it difficult to modify some ODS options in your stored
process.
Overriding Input Parameters
Macro variables recognized by %STPBEGIN can be set or modified by the stored process. This is usually done to
deny or limit client choices for that variable. For example, a stored process that requires the use of a particular style
might begin with the following:
%global _ODSSTYLE;
*ProcessBody;
%let _ODSSTYLE=MyStyle;
%stpbegin;
Any client specified value for _ODSSTYLE is ignored and the MyStyle style is always used. A more elaborate
implementation might validate an input parameter against a list of supported values and log an error or choose a
default value if the client input is not supported.
A stored process is free to modify the macro variables consumed by %STPBEGIN at any time until %STPBEGIN is
called. Modifying these reserved macro variables after %STPBEGIN has been called is not recommended.
Results
The %STPBEGIN and %STPEND macros implement several options for delivering results. See the section on Result
Types for an introduction to the standard options for stored process results. In most cases, a stored process using these
macros can support all the standard result types with no special coding. The _RESULT variable defines the result
type. The following values are supported:
STATUS
returns only a completion status. An ODS destination is not opened, but the ODS LISTING destination is
closed.
STREAM
returns the body or file output from ODS as a stream. This is the default result type if _RESULT is not set.
There are several values for _RESULT that generate packages. Packages can be delivered directly to the client and
published to a more permanent location on the server file system, a WebDAV server or other destinations. Package
creation and delivery are controlled by many reserved macro variables. Variables that are valid for all package
destinations are as follows:
_ABSTRACT• _DESCRIPTION• _EXPIRATION_DATETIME• _NAMESPACES• _NAMEVALUE•
Additional variables are recognized for specific _RESULT settings, such as
SAS® Integration Technologies: Developer's Guide
%STPBEGIN and %STPEND 17
PACKAGE_TO_ARCHIVE
creates an archive package on the server file system containing the generated output. The _ARCHIVE_PATH
and (optionally) _ARCHIVE_NAME variables specify where the package is created. In addition,
_ARCHIVE_FULLPATH is set by %STPEND to hold the full path name of the created archive package.
PACKAGE_TO_REQUESTER
returns a package to the stored process client. It can also simultaneously create an archive package on the
server file system if _ARCHIVE_PATH and (optionally) _ARCHIVE_NAME are set. This option is valid
only on the workspace server.
PACKAGE_TO_WEBDAV
creates a package as a collection on a WebDAV−compliant server. The location of the package is defined by
_COLLECTION_URL or _PARENT_URL. Other relevant variables include _HTTP_PASSWORD,
_HTTP_PROXY_URL, _HTTP_USER, and _IF_EXISTS.
%STPBEGIN configures ODS to create output files in a temporary working directory. %STPEND then creates the
package from all of the files found in this temporary directory. The temporary directory is defined by the _STPWORK
variable. This variable should not be changed by the stored process, but new entries can be added to the output
package by creating files in this directory. For example, the XML LIBNAME engine might be used to create one or
more XML files that would be included in the package along with any output created by ODS. The temporary
directory and any contained files are automatically deleted when the stored process completes. No clean up is required
in the stored process program.
Errors
Errors in the %STPBEGIN and %STPEND macros are reported in the _STPERROR macro variable. A value of 0
indicates the macro completed successfully. A non−zero value indicates an error occurred.
Note that because these macros allow clients or stored processes to submit SAS language options (for example, see the
_ODSOPTIONS variable) it is possible for the macros to fail in unusual ways. Invalid input parameters can cause the
stored process to go into syntaxcheck mode (set the SAS OBS option to 0) or to terminate immediately.
Advanced Package Publishing
The %STPBEGIN and %STPEND macros support some package publishing options that are not recognized by the
stored process metadata framework. These options are generally accessed by registering a stored process with None
as the output type. This causes the stored process to be executed with _RESULT set to STATUS. The stored process
can then set _RESULT to one of the following values:
PACKAGE_TO_ARCHIVE
PACKAGE_TO_ARCHIVE provides several new options when used in this way. Archive packages can be
created on HTTP servers that support updates, FTP servers, and LDAP servers. Variables that control this
option include
_ARCHIVE_NAME◊ _ARCHIVE_PATH◊ _FTP_PASSWORD◊ _FTP_USER◊ _HTTP_PASSWORD◊ _HTTP_PROXY_URL◊ _HTTP_USER◊ _LDAP_BINDDN◊ _LDAP_BINDPW◊
SAS® Integration Technologies: Developer's Guide
%STPBEGIN and %STPEND 18
PACKAGE_TO_EMAIL
creates a package and mails it to one or more e−mail addresses. An actual archive package can be mailed, or
the package can be created in a public location and a reference URL mailed. Variables that control this option
include the following:
_ADDRESSLIST_DATASET_LIBNAME◊ _ADDRESSLIST_DATASET_MEMNAME◊ _ADDRESSLIST_VARIABLENAME◊ _ARCHIVE_NAME◊ _ARCHIVE_PATH◊ _COLLECTION_URL◊ _DATASET_OPTIONS◊ _EMAIL_ADDRESS◊ _FROM◊ _FTP_PASSWORD◊ _FTP_USER◊ _HTTP_PASSWORD◊ _HTTP_PROXY_URL◊ _HTTP_USER◊ _IF_EXISTS◊ _LDAP_BINDDN◊ _LDAP_BINDPW◊ _PARENT_URL◊ _REPLYTO◊ _SUBJECT◊
PACKAGE_TO_QUEUE
creates a package and sends it to one or more message queues. An actual archive package can be sent, or the
package can be created in a public location and a reference URL sent. Variables that control this option
include the following:
_ARCHIVE_NAME◊ _ARCHIVE_PATH◊ _CORRELATIONID◊ _FTP_PASSWORD◊ _FTP_USER◊ _HTTP_PASSWORD◊ _HTTP_PROXY_URL◊ _HTTP_USER◊ _LDAP_BINDDN◊ _LDAP_BINDPW◊ _MESSAGE_QUEUE◊
PACKAGE_TO_SUBSCRIBERS
creates a package and sends it to a subscriber channel. An actual archive package can be sent, or the package
can be created in a public location and a reference URL sent. Variables that control this option include the
following:
_ARCHIVE_NAME◊ _ARCHIVE_PATH◊ _CHANNEL◊ _CHANNEL_STORE◊ _COLLECTION_URL◊ _CORRELATIONID◊ _FROM◊ _FTP_PASSWORD◊
SAS® Integration Technologies: Developer's Guide
%STPBEGIN and %STPEND 19
_FTP_USER◊ _HTTP_PASSWORD◊ _HTTP_PROXY_URL◊ _HTTP_USER◊ _IF_EXISTS◊ _LDAP_BINDDN◊ _LDAP_BINDPW◊ _PARENT_URL◊ _REPLYTO◊ _SUBJECT◊
Almost all of the package option variables previously listed have directly equivalent properties in the package
publishing API. See the PACKAGE_PUBLISH documentation for more information about these properties. The
property names are the same as the variable names with the underscore prefix removed.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
%STPBEGIN and %STPEND 20
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.
Reserved Macro Variables 21
_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
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 22
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
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 23
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•
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 24
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
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 25
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.
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 26
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.
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 27
_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.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Reserved Macro Variables 28
Stored Process Server Functions
Stored process server functions are DATA step functions that you use to define character, numeric, and alphanumeric
strings to generate output in the desired format. The following list of SAS Stored Process Server functions can be used
to return the correct character, numeric, or alphanumeric value of a parameter setting.
STPSRVGETC• STPSRVGETN• STPSRVSET• STPSRV_HEADER• STPSRV_SESSION• STPSRV_UNQUOTE2•
Note: You can also use APPSRV syntax from the Application Dispatcher in place of these functions. See the
Application Dispatcher documentation for more information.
SAS Stored Processes
Stored Process Server Functions 29
STPSRVGETC
Returns the character value of a server property
Syntax
Arguments
Details
Examples
Syntax
VALUE = STPSRVGETC( valuecode )
Note: The APPSRVGETC function can be used in place of STPSRVGETC. This feature is provided in order to
enable you to convert existing SAS/IntrNet programs to stored processes.
Arguments
valuecode
is the character string name of the property.
Details
The STPSRVGETC function takes one character string property and returns a character string result.
Examples
SAS Statements Results
sencoding=stpsrvgetc('Default
Output Encoding');
put sencoding=;
sencoding=WLATIN1
version=stpsrvgetc('version');
put version=;
version=SAS Stored Processes
Version 9.1 (Build 18)
SAS Stored Processes
STPSRVGETC 30
STPSRVGETN
Returns the numeric value of a server property
Syntax
Arguments
Details
Examples
Syntax
VALUE = STPSRVGETN( valuecode )
Note: The APPSRVGETN function can be used in place of STPSRVGETN. This feature is provided in order to
enable you to convert existing SAS/IntrNet programs to stored processes.
Arguments
valuecode
is the character string name of the property.
Details
The STPSRVGETN function takes one character string property and returns a numeric string result.
Examples
SAS Statements Results
dsesstimeout=stpsrvgetn('default
session timeout');
put dsesstimeout=;
dsesstimeout=900
sessmaxtimeout=stpsrvgetn('maximum
session timeout');
put sessmaxtimeout=;
sessmaxtimeout=3600
session=stpsrvgetn('session
timeout');
put session=;
session=900
maxconreqs=stpsrvgetn('maximum
concurrent requests');
put maxconreqs=;
maxconreqs=1
deflrecl=stpsrvgetn('default
output lrecl');
put deflrecl=;
deflrecl=65535
version=stpsrvgetn('version');
put version=;
version=9.1
STPSRVGETN 31
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
STPSRVGETN 32
STPSRVSET
Sets the value of a server property
Syntax
Arguments
Details
Examples
Syntax
RC = STPSRVSET( valuecode, newvalue )
Note: The APPSRVSET function can be used in place of STPSRVSET. This feature is provided in order to enable
you to convert existing SAS/IntrNet programs to stored processes. The following Application Dispatcher properties
are not supported by the SAS Stored Process Server: REQUIRE COOKIE, REQUEST TIMEOUT, and
AUTOMATIC HEADERS.
Arguments
valuecode
is the character string name of the property.
newvalue
is the numeric string name of the property.
The following table lists the valid properties for valuecode and provides a description of each.
Valuecode Description
PROGRAM
ERROR specifies the return code when there is an error. This can be set to any value.
SESSION
TIMEOUT specifies the number of seconds that elapse before a session expires. The default session
timeout is 900 (15 minutes).
Details
The STPSRVSET function takes one character string property and one numeric string property and returns a numeric
string result. The return code is zero for success, non−zero for failure.
Examples
SAS Statements
rc=stpsrvset('session timeout',900);
rc=stpsrvset('program error',256);
STPSRVSET 33
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
STPSRVSET 34
STPSRV_HEADER
The DATA step function used to add or modify a header
Syntax
Arguments
Details
Examples
Syntax
OLD−HEADER = STPSRV_HEADER(Header Name,Header Value);
Note: The APPSRV_HEADER function can be used in place of STPSRV_HEADER. This feature is provided in
order to enable you to convert existing SAS/IntrNet programs to stored processes.
Arguments
Header Name
is the name of the header to set or reset.
Header Value
is the new value for the header.
See HTTP Headers for a list of commonly used HTTP headers.
Details
The STPSRV_HEADER function enables automatic header generation. You can add a header to the default list or
modify an existing header from the list. When you modify the value of an existing header, the old value becomes the
return value of the function.
The automatic HTTP header generation feature recognizes Output Delivery System (ODS) output types and generates
appropriate default content−type headers. If no content type is specified with STPSRV_HEADER, ODS is not used
and no HTTP header is written to _WEBOUT, and a default Content−type: text/html header is generated.
Examples
SAS Statements Resulting Headers
No calls to stpsrv_header Content−type: text/html
/* add expires header */
rc = stpsrv_header('Expires','Thu,
18 Nov 1999 12:23:34 GMT');
Content−type: text/html
Expires: Thu, 18 Nov 1999
12:23:34 GMT
/* add expires header */
rc = stpsrv_header('Expires','Thu,
18 Nov 1999 12:23:34 GMT');
Content−type: text/html
Expires: Thu, 18 Nov 1999
12:23:34 GMT
STPSRV_HEADER 35
/* add pragma header*/
rc = stpsrv_header('Cache−control',
'no−cache');
Cache−control: no−cache
/* add expires header */
rc = stpsrv_header('Expires','Thu,
18 Nov 1999 12:23:34 GMT');
/* add pragma header*/
rc = stpsrv_header('Cache−control',
'no−cache');
...
/* remove expires header, rc
contains old value */
rc = stpsrv_header('Expires','');
Content−type: text/html
Cache−control: no−cache
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
STPSRV_HEADER 36
STPSRV_SESSION
Creates or deletes a session
Syntax
Arguments
Details
Examples
Syntax
RC = STPSRV_SESSION( 'command' , <timeout> )
Note: The APPSRV_SESSION function can be used in place of STPSRV_SESSION. This feature is provided in
order to enable you to convert existing SAS/IntrNet programs to stored processes.
Arguments
command
is the command to be performed. Allowed values are "CREATE" and "DELETE".
timeoutis the optional session timeout in seconds. This property is valid only when you specify a value of "CREATE"
for the command property.
Details
The STPSRV_SESSION function creates or deletes a session. The function returns zero for a successful completion.
A non−zero return value indicates an error condition.
Examples
SAS Statements
rc=stpsrv_session('create', 600);
rc=stpsrv_session('delete');
SAS Stored Processes
STPSRV_SESSION 37
STPSRV_UNQUOTE2
Unmasks quotation mark characters in an input parameter
Syntax
Arguments
Details
Example
Syntax
call STPSRV_UNQUOTE2( paramname )
Arguments
paramname
is the character string name of the parameter.
Details
The STPSRV_UNQUOTE2 call routine takes the name of an input parameter (or any global macro variable) and
unmasks matched pairs of single or double quotation marks. The call routine does not return a value; instead it
modifies the specified macro variable. This call routine can be used to selectively remove quotation marks from stored
process input parameters so that they can be used in statements that require quotation mark characters.
Example
This call routine is typically called with %SYSCALL in open macro code, as follows:
/* MYGOPTIONS is an input parameter and might contain quotation
marks, for example: dashline='c000000000000000'x */
%SYSCALL STPSRV_UNQUOTE2(MYGOPTIONS);
/* Quote characters are now interpreted as expected */
goptions &MYGOPTIONS;
...
SAS Stored Processes
STPSRV_UNQUOTE2 38
Sessions
The Web is a stateless environment. A client request to a server knows nothing of any preceding requests. This creates
a simple environment for client and server developers, but it is difficult for application programmers. Often,
programmers want to carry information from one request to the next. This is known as maintaining state. Sessions
provide a convenient way to maintain state across multiple stored process requests.
A session is the data that is saved from one stored process execution to the next. It consists of macro variables and
library members (data sets and catalogs) that the stored process has explicitly saved. The session data is scoped so that
all users have independent sessions. See Using Sessions for a sample Web application that uses sessions.
Creating a Session
The stored process must explicitly create a session with the STPSRV_SESSION function, as follows:
In macro
%let rc=%sysfunc(stpsrv_session(create));
In DATA step or SCL
rc=stpsrv_session('create');
Creating a session will set the global macro variables _SESSIONID and _THISSESSION and create the SAVE
session library.
Using the Session
A session saves all global macro variables whose names begin with SAVE_. For example, the statements
%global save_mytext;
%let save_mytext="Text to be saved
for the life of the session";
cause the macro variable save_mytext to be available in subsequent stored processes that share the same session.
Data sets and catalogs can also be saved across program requests using the SAVE library. Data sets and catalogs that
are created in or copied to this library are available to all future stored processes that execute in the same session.
Creating a session causes the automatic variables _THISSESSION and _SESSIONID to be set. Sample values for
these variables are as follows:
0010 %let rc=%sysfunc(stpsrv_session(create));
0011 %put _SESSIONID=&_SESSIONID;
_SESSIONID=7CF645EB−6E23−4853−8042−BBEA7F866B55
0012 %put _THISSESSION=&_THISSESSION;
_THISSESSION=/SASStoredProcess/do?_sessionid=
7CF645EB−6E23−4853−8042−BBEA7F866B55
These variables can be used to construct URLs or HTML forms that execute another stored process in the same
session. For example,
%let rc=%sysfunc(stpsrv_session(create));
data _null;
Sessions 39
file _webout;
put '<HTML>';
put '<BODY>';
put '<H1>Session Test Page</H1>';
/* Link to another stored process in the same session */
put '<A HREF="' "&_THISSESSION"
'&_PROGRAM=/Test/Test2">Test</A>';
put '</BODY>';
put '</HTML>';
run;
Note: The _THISSESSION variable is not identical to the _THISSESSION variable used in SAS/IntrNet. If you are
converting an existing SAS/IntrNet program to a stored process, any references to symget('_THISSESSION')
should generally be replaced with "&_THISSESSION". See Converting SAS/IntrNet Programs for more
information.
Deleting the Session
Sessions expire after a period of inactivity. The default expiration time is 15 minutes. The expiration time can be
changed using the STPSRVSET function, as follows
In macro
%let rc=%sysfunc(stpsrvset(session timeout,300));
In DATA step or SCL
rc=stpsrvset('session timeout',300);
where the timeout is specified in seconds. If the session is not accessed for the length of the timeout, the server will
delete the session, the associated SAVE library, and all associated macro values. Any further attempts to access the
session will result in an invalid or expired session error.
Sessions can be explicitly destroyed using the STPSRV_SESSION function, as follows:
In macro
%let rc=%sysfunc(stpsrv_session(delete));
In DATA step or SCL
rc=stpsrv_session('delete');
Submitting this code does not immediately destroy the session. The session is only marked for deletion at the
completion of the stored process. For this reason, a stored process cannot delete a session and create a new session.
Limitations
Stored process sessions are supported only by the stored process server. Stored processes executing on a workspace
server cannot create or access sessions.
A session exists in the server process where it was created. All stored processes that access that session must execute
in the same server process. Load balancing and other execution dispatching features are typically ignored when using
sessions that might have an impact on application performance and scalability. Sessions are not recommended for
applications with small amounts of state information; use a client−based method for maintaining state instead.
SAS® Integration Technologies: Developer's Guide
Sessions 40
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Sessions 41
Stored Process Samples
The following samples demonstrate how a stored process generates different types of output using the %STPBEGIN
and %STPEND macros. All of the samples are based on the following stored process:
*ProcessBody;
%STPBEGIN;
title 'Age analysis by sex';
footnote;
proc sort data=sashelp.class out=class; by sex age; run;
proc gchart data=class;
vbar3d age / group=sex
discrete
nozero
shape=cylinder
patternid=group;
run; quit;
title;
proc print data=class;
by sex age;
id sex age;
var name height weight;
run;
%STPEND;
This code generates a bar chart and a table. The exact format and appearance of the output depends upon various input
parameters. For these samples, assume the following input parameters were specified:
Variable Value Comments
_ODSDEST HTML Default destination. Not required.
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg Generates a PNG image file. Available only on Windows
platforms.
_GOPT_XPIXELS 384 Image width in pixels
_GOPT_YPIXELS 288 Image height in pixels
Note: See the section on Reserved Macro Variables for a more detailed description of each macro variable mentioned
in the previous table and in the following sections.
Streaming Output
Streaming output is generally used when you are executing a stored process from a Web−based application using the
SAS Stored Process Web Application or when you are returning a single output file with no embedded links to
companion files such as images. Because the stored process was registered with a result type of Streaming, the
following input parameters are passed to the stored process:
Variable Value
_RESULT STREAM
_ODSDEST HTML
Stored Process Samples 42
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
The HTML output from the stored process is streamed to the client though the server−created _WEBOUT fileref. The
PNG image file is streamed through a separate replay connection to the server, as described in the section on
Embedding Graphics.
Creating a Transient Package
Transient packages are a convenient way to deliver a collection of multiple output files to a client application.
Transient packages are implemented in different ways for the stored process server and the workspace server as
described in the following sections.
Stored Process Server
A stored process registered with a result type of Transient result package on a stored process server is
executed with _RESULT set to PACKAGE_TO_ARCHIVE and _ARCHIVE_PATH set to TEMPFILE. The input
parameters are as follows:
Variable Value
_RESULT PACKAGE_TO_ARCHIVE
_ARCHIVE_NAME TEMPFILE
_ODSDEST HTML
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
Workspace Server
The same stored process registered on a workspace server is executed with _RESULT set to
PACKAGE_TO_REQUESTER and no value for _ARCHIVE_PATH. The input parameters are as follows:
Variable Value
_RESULT PACKAGE_TO_REQUESTER
_ODSDEST HTML
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
SAS® Integration Technologies: Developer's Guide
Stored Process Samples 43
Creating a Permanent Package Archive
Permanent packages are published to a permanent location where they can be accessed at a later time. Permanent
packages are also immediately available to the stored process client through the same interfaces used for a transient
package. This sample assumes that the stored process was registered with the following metadata, in addition to the
parameters already listed:
Metadata Field Value
Output type Permanent result package
File system Selected
Archive path c:\My Packages
Archive name AgeAnalysis.spk
Again, implementation differs between the stored process server and the workspace server. _RESULT is set to
PACKAGE_TO_ARCHIVE or PACKAGE_TO_REQUESTOR, respectively. The input parameters are as follows:
Variable Value
_RESULT PACKAGE_TO_ARCHIVE or PACKAGE_TO_REQUESTER
_ARCHIVE_PATH C:\My Packages
_ARCHIVE_NAME AgeAnalysis.spk
_ODSDEST HTML
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
The archive package is created at C:\My Packages\AgeAnalysis.spk, and the variable
_ARCHIVE_FULLPATH is set by %STPEND.
Creating a Permanent Package on a WebDAV Server
Permanent packages can also be published to WebDAV servers by specifying the appropriate options when registering
the stored process. This sample assumes that the stored process was registered with the following metadata, in
addition to the parameters already listed:
Metadata Field Value
Output type Permanent result package
DAV location Selected
Server http://server1.abc.com/
Base path /dav
Base path /reports
SAS® Integration Technologies: Developer's Guide
Stored Process Samples 44
Create new instance Selected
The input parameters are as follows:
Macro Variable Name Value
_RESULT PACKAGE_TO_WEBDAV
_PARENT_URL http://server1.abc.com/dav/reports
_ODSDEST HTML
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
The package is created in a uniquely named collection under http://server1.abc.com/dav/reports.
Publishing a Package to E−Mail
As discussed in the section on Advanced Package Publishing, packages can be published to other destinations with
minor modifications to the stored process. Adding two lines to the stored process such as
*ProcessBody;
%let _RESULT=PACKAGE_TO_EMAIL;
%let _ARCHIVE_PATH=TEMPFILE;
%STPBEGIN;
title 'Age analysis by sex';
footnote;
proc sort data=sashelp.class out=class; by sex age; run;
proc gchart data=class;
vbar3d age / group=sex
discrete
nozero
shape=cylinder
patternid=group;
run; quit;
title;
proc print data=class;
by sex age;
id sex age;
var name height weight;
run;
%STPEND;
and registering the stored process with None as the result type enables you to publish a package to e−mail addresses.
Additional input parameters specify the e−mail address, a subject line, and a reply−to address, as follows:
Variable Value
_RESULT STATUS (is modified in the stored process)
_EMAIL_ADDRESS DeptManagers@abc.com
SAS® Integration Technologies: Developer's Guide
Stored Process Samples 45
_REPLYTO ReportAdmin@abc.com
_SUBJECT Age Analysis Report
_ODSDEST HTML
_ODSSTYLE SASWeb
_GOPT_DEVICE ActxImg
_GOPT_XPIXELS 384
_GOPT_YPIXELS 288
The package is created and mailed to the DeptManagers@abc.com address. If you make slight modifications to
the input parameters, then you can publish the package to a WebDAV location and mail a reference to the package to
one or more e−mail addresses.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Stored Process Samples 46
Debugging Stored Processes
There are two techniques for debugging stored processes:
Examining the SAS Log• Using SAS Options•
Examining the SAS Log
The client interfaces provided to stored processes usually include a mechanism for retrieving the SAS log from a
stored process. For example, passing an input parameter _DEBUG=LOG to the SAS Stored Process Web Application
causes the SAS log to be returned with the stored process output. The SAS log is directly accessible from the Stored
Process Service API. Assuming your installation is configured correctly, most run−time stored process errors will
appear in the SAS log.
If you are unable to access the SAS log from the client interface, you might be able to access the SAS log from the
server log files. The server administrator controls the level of server logging enabled and the location of the server log
files. Server log options vary depending on the server type.
The stored process server enables you to capture the SAS log for each stored process in the server log with the
APPLEVEL option. The APPLEVEL option can be specified in the Object Server Parameters field in the Server
Manager definition for the server in SAS Management Console. The following table describes the supported values
for the APPLEVEL option:
APPLEVEL
Value Logging Behavior
0 Summary. The stored process server only logs an identifying build statement and error conditions.
1Default. The stored process server logs APPLEVEL=0 messages, minimal processing statements,
as well as the SAS log for each stored process that completes with an error status.
2Full. The stored process server logs APPLEVEL=1 messages, except that the SAS log is included
for every stored process executed on the server.
3Debug. The stored process server logs verbose processing statements as well as the APPLEVEL=2
messages. Not recommended except for special debugging circumstances.
The workspace server also supports the APPLEVEL option, but does not log the same information. The logging
behavior in the previous table is supported only by the stored process server. Client−side access is generally
recommended for the SAS log. The IOMLEVEL=2 option can be enabled in cases where debugging must be
performed from server logs, but this option is not recommended for production servers. The log output with this
option is very verbose and might affect server performance.
Using SAS Options
There are several SAS options that can help you debug problems in your stored processes. If you can return the SAS
log to your browser, activating some of these options can make that log more useful. If you are debugging a stored
process that contains macro code, you should supply one or more of these options at the beginning of your stored
process: MPRINT, SYMBOLGEN, MLOGIC, MERROR.
Debugging Stored Processes 47
If, for security reasons, you have disabled the display of submitted source code in your stored process using the
NOSOURCE option when you are debugging, you should enable this feature by supplying the SOURCE option. You
can then see your submitted SAS code in the log that is returned to your browser. After you are finished debugging,
you can revert to using NOSOURCE if your security model requires it.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Debugging Stored Processes 48
Converting SAS/IntrNet Programs to Stored Processes
Stored processes provide a conversion path for existing SAS/IntrNet applications, enabling them to take advantage of
the SAS 9 BI Architecture. Many features are implemented in the stored process server and SAS Stored Process Web
Application to minimize code changes required during a conversion. Existing SAS/IntrNet Application Dispatcher
programs can usually be converted to streaming stored processes with minimal or no modifications. Conversion of
existing programs requires the following steps:
Install and configure the SAS Web Infrastructure Kit, a component of SAS Integration Technologies that
includes the SAS Stored Process Web Application used to emulate Application Dispatcher.
1.
Modify the program as required to address the compatibility issues discussed in the Issues section.2. Copy the program to a valid source code repository for a stored process server. SAS/IntrNet programs must be
registered on a stored process server; workspace servers do not support streaming output or a number of other
SAS/IntrNet compatibility features.
3.
Register the stored process using BI Manager. Choose Streaming for the type of output. You do not need
to register any parameter definitions.
4.
Convert any HTML input forms or HTML pages that link to your stored process to use the SASStoredProcess
URL syntax as described in the Issues section.
5.
Run the stored process.6.
Note: SAS/IntrNet programs converted to stored processes using the techniques described here are intended to run in
the SAS Stored Process Web Application. These stored processes might not run in other stored process clients (such
as SAS Web Report Studio or SAS Add−In for Microsoft Office.) Each client application has its own requirements for
stored process behavior.
Compatibility Features
The SAS Stored Process Web Application (a component of the SAS Web Infrastructure Kit) provides the
middle−tier equivalent of the Application Broker. The SAS Stored Process Web Application is a Java−based
application and requires a servlet container host such as Apache Tomcat. See the SAS Web Infrastructure Kit
installation instructions for other requirements.
•
The SAS Stored Process Server (a component of SAS Integration Technologies) provides the equivalent of
the Application Server. The typical stored process server configuration (a load−balanced cluster) is very
similar in functionality to a SAS/IntrNet pool service. New servers are started as demand increases to provide
a highly scalable system.
•
Streaming output from a stored process is written to the _WEBOUT fileref. The underlying access method has
changed, but the functionality is very similar. ODS, HTML Formatting Tool, DATA step, or SCL programs
can continue to write output to _WEBOUT.
•
The Application Server functions (APPSRVSET, APPSSRVGETC, APPSRVGETN, APPSRV_HEADER,
APPSRV_SESSION, and APPSRV_UNSAFE) are supported in stored processes except as noted in the
following issues. In many cases, there are equivalent STPSRV functions that are recommended for new
programs.
•
The _REPLAY mechanism is supported by the stored process server. The value of the _REPLAY URL has
changed, but this does not affect most programs.
•
The SAS/IntrNet sessions feature has been implemented by the stored process server. The same SAVE
library, session macro variables, and session lifetime management functions are available.
•
Converting SAS/IntrNet Programs to Stored Processes 49
Issues
There are a number of differences in the stored process server environment that might affect existing SAS/IntrNet
programs. Use this list as a review checklist for your existing programs.
HTTP headers cannot be written directly to _WEBOUT using a DATA step PUT statement or SCL fwrite
function. You must use the STPSRV_HEADER (or APPSRV_HEADER) functions to set header values.
Automatic header generation cannot be disabled with appsrvset("automatic headers", 0).
The Location header record does not currently work with stored processes because the HTTP status code
cannot be set.
•
Unsafe processing is different for stored processes — there is no UNSAFE option. Unsafe characters are
quoted instead of removed from the input parameters, so you can safely use the &VAR syntax without
worrying about unsafe characters. The following examples work without using the APPSRV_UNSAFE
function.
%if &MYVAR eq %nrstr(A&P) %then do something...;
Another example:
data _null_;
file _webout;
put "MYVAR=&MYVAR";
run;
APPSRV_UNSAFE works in the stored process server and still returns the complete, unquoted input value.
This change might cause subtle behavioral differences if your program relies on the SAS/IntrNet unsafe
behavior.
•
The stored process server cannot directly execute SOURCE, MACRO, or SCL catalog entries. You must write
a wrapper .sas source code file that executes the catalog entry.
•
The _REPLAY macro variable does not have the same syntax in stored processes as it did in Application
Dispatcher. References to &_REPLAY are not recommended for SAS/IntrNet programs, but can be used in
stored processes. The DATA step function symget('_REPLAY') does not return a usable URL in a stored
process and should be replaced with "&_REPLAY". For example,
url = symget('_REPLAY') || ...url parameters...
should be changed to
url = "&_REPLAY" || ...url parameters...
•
_SERVICE, _SERVER, and _PORT do not exist for stored processes. You must review any code that uses
these macro variables. Usually, they are used to create drill−down URLs or forms. In many cases, this code
does not require any change; input values for these variables are ignored.
•
_PROGRAM refers to a stored process path, and not a three or four−level program name. Any programs that
create drill−down links or forms with _PROGRAM must generally be modified to use the stored process path.
•
There is no REQUEST TIMEOUT functionality in SAS Stored Processes. appsrvset('request
timeout') is not supported.
•
The Application Server functions APPSRV_AUTHCLS, APPSRV_AUTHDS, and APPSRV_AUTHLIB are
not supported in stored processes. There are no STPSRV functions that are equivalent to these Application
Server functions.
•
Stored processes do not support automatic user exit programs such as REQUEST INIT, REQUEST TERM,•
SAS® Integration Technologies: Developer's Guide
Converting SAS/IntrNet Programs to Stored Processes 50
REQUEST LOGIN, SESSION INIT, SESSION TERM, and SESSION INVSESS. SAS/IntrNet applications
that rely on these features will require modifications to implement equivalent functionality. In most cases, all
relevant stored process source code must be changed to explicitly call user exits when necessary. There is no
support for REQUEST LOGIN or SESSION INVSESS functionality in the SAS Stored Process Web
Application, although similar functionality can be implemented in a custom Web interface.
If you are writing to _WEBOUT using PUT statements while ODS has _WEBOUT open, when you execute
the code the PUT statement data might be out of sequence with the data generated by ODS. This problem
occurs because both your code and ODS are opening the same fileref at the same time. For example, the
following code might not always work as expected:
ods listing close;
ods html body=_webout path=&_tmpcat
(url=&_replay) Style=Banker;
... other code ...
data _null_;
file _webout;
put '<p align="center">&#160;</p>' ;
put '<p align="center"><b>Test.
If you see this in order, it worked.</b></p>';
run;
... other code ...
ods html close;
This code might work in some SAS/IntrNet programs, but it can cause data order problems even in
SAS/IntrNet. This code is more likely to fail in a stored process. This problem can be fixed by inserting your
PUT statements before you open ODS, closing ODS while you write directly to the fileref, or using the ODS
HTML TEXT="string" option to write data. The following code is an example of how you can both close
ODS while you write directly to the fileref, and insert your PUT statements before you open ODS:
ods html body=_webout (no_bottom_matter)...;
... other code ...
ods html close;
data _null_;
file _webout;
put '<p align="center">&#160;</p>' ;
put '<p align="center"><b>Test.
If you see this in order, it worked.</b></p>';
run;
ods html body=_webout (no_top_matter)...;
... other code ...
ods html close;
The following code is an example of how you can use the ODS HTML TEXT="string" option to write data:
ods listing close;
ods html body=_webout path=&_tmpcat
(url=&_replay) Style=Banker;
... other code ...
ods html text='<p align="center">&#160;</p>' ;
ods html text='<p align="center"><b>Test.
If you see this in order, it worked.</b></p>';
... other code ...
ods html close;
•
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Converting SAS/IntrNet Programs to Stored Processes 51
Using Stored Processes
SAS Stored Processes can be used in many different client applications. The following list gives a brief overview of
each so that you can determine which client best suits your needs.
SAS Add−In for Microsoft Office
The SAS Add−In for Microsoft Office is a Component Object Model (COM) add−in that extends Microsoft
Office by enabling you to dynamically execute stored processes and embed the results in Microsoft Word
documents, Microsoft Excel spreadsheets, and Microsoft PowerPoint presentations. Additionally, within
Excel you can use the SAS add−in to access and view SAS data sources or any data source that is available
from your SAS server, and analyze SAS or Excel data by using analytic tasks. For more information, refer to
the SAS Add−In for Microsoft Office Online Help, which is located within the product.
SAS BI Web Services
SAS BI Web Services provide a Web service interface to SAS Stored Processes. Web services can be hosted
on a Java servlet container or Windows IIS. SAS BI Web Services implement the Discover and Execute Web
methods specified by the XML for Analysis standard. The Discover method returns the metadata for a stored
process, and the Execute method calls the SAS Stored Process Server to invoke a stored process.
SAS Data Integration Studio
SAS Data Integration Studio enables its administrators to publish jobs as stored processes. SAS Data
Integration Studio can generate code that converts a job into a stored process, which is saved to a file and can
be executed later by the SAS Stored Process Server. Metadata about the stored process is saved in the current
metadata repository. Refer to the SAS Data Integration Studio product Help for more information.
SAS Enterprise Guide
SAS Enterprise Guide provides an integrated solution for authoring, editing, and testing stored processes. You
can create stored processes from existing or new SAS code and create stored processes automatically from
SAS Enterprise Guide tasks. Metadata registration and source code management are handled from one
interface. SAS Enterprise Guide also has the capability to execute stored processes, which enables you to
modify and test your stored process without leaving the SAS Enterprise Guide environment. Refer to the SAS
Enterprise Guide product Help for more information.
SAS Information Delivery Portal
The SAS Information Delivery Portal provides integrated Web access to SAS reports, stored processes,
information maps, and channels. If you have installed the SAS Information Delivery Portal, you can make
stored processes available to be executed from the portal without the need for additional programming. The
SAS Information Delivery Portal includes the SAS Stored Process Web Application.
SAS Information Map Studio
Stored processes can be used to implement information map data sources. Stored processes can use the full
power of SAS procedures and the DATA step to generate or update the data in an information map. Refer to
the SAS Information Map Studio product Help for more information about stored process information maps.
SAS Stored Process Web Application
The SAS Stored Process Web Application is a Java Web application that can execute stored processes and
return results to a Web browser. The SAS Stored Process Web Application is similar to the SAS/IntrNet
Application Broker and has the same general syntax and debug options as the Application Broker. See the
Building Web Applications section for examples of this component. The SAS Stored Process Web
Application is included with the SAS Web Infrastructure Kit, a component of SAS Integration Technologies.
SAS Web Report Studio
You can use SAS Web Report Studio to execute stored processes and to include stored processes or stored
process results in a report. Refer to the SAS Web Report Studio product Help for more information.
Stored Process Service
The Stored Process Service is a Java application programming interface (API) that enables you to execute
stored processes from a Java program. This API is commonly used in JSP pages, but can also be used from
Using Stored Processes 52
servlets, custom tagsets and other Java applications. The Stored Process Service API is part of SAS
Foundation Services; you must deploy SAS Foundation Services in order to use the Stored Process Service
API. For more information, see the Stored Process Service package description in the Foundation Services
class documentation in the SAS Integration Technologies: Developer's Guide.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Using Stored Processes 53
Building a Web Application
Stored processes are frequently used in Web−based applications. While almost any stored process can be executed
through a Web interface, the typical Web application design might require special techniques. This section and the
following sections document special issues you might encounter when building a Web application.
Web applications are typically implemented by streaming output stored processes. Streaming output stored processes
deliver their output through the _WEBOUT fileref. You can write directly to the _WEBOUT fileref using PUT
statements or use the Output Delivery System (ODS) to generate output. The example code throughout this section
demonstrates both approaches. Streaming output is only supported by the stored process server: the workspace server
is not an appropriate host for many Web applications.
Web applications can be implemented using the SAS Stored Process Web Application, the Stored Process Service API
or a combination of both. The SAS Stored Process Web Application is a Java middle−tier application that executes
stored processes on behalf of a Web client. Only SAS and HTML programming skills are required; no Java
programming is required. Most of the examples in the remainder of this section assume the use of the SAS Stored
Process Web Application. The Stored Process Service API enables the Java developer to embed stored processes
within a Java Web application.
SAS Stored Processes
Building a Web Application 54
SAS Stored Process Web Application
The SAS Stored Process Web Application is a Java Web application that can execute stored processes and return
results to a Web browser. The SAS Stored Process Web Application is similar to the SAS/IntrNet Application Broker,
and has the same general syntax and debug options. The SAS Stored Process Web Application is included with the
SAS Web Infrastructure Kit, a component of SAS Integration Technologies.
To execute the SAS Stored Process Web Application, enter the application's URL in the Web browser. Either the
default Welcome page or static data is displayed.
Here is an example of a URL for the SAS Stored Process Web Application:
http://yourserver.com:8080/SASStoredProcess/do?
In this example, if the Welcome.htm file is installed, then the Welcome page is displayed. The Welcome page might
look like this:
The Welcome page contains the following three links:
Stored Process Samples
Click this link to display a page of stored process samples that are installed with the SAS Web Infrastructure
Kit. See the section about custom input forms for more information.
List Available Stored Processes
Click this link to display a page that contains a tree view of metadata repositories, folders, and stored
processes. You can select a stored process in the tree view in order to view metadata for the stored process or
to run the stored process. See the section about the stored process list and summary page for more
information.
SAS Integration Technologies Documentation
Click this link to display the SAS Integration Technologies documentation library, which contains detailed
documentation about each feature of the SAS Integration Technologies product. This link requires Internet
access.
In the previous example, if the Welcome.htm file has not been installed, then static data is displayed. The static data
might look like this:
Stored Process Web Application
SAS Stored Process Web Application 55
Version 9.1 (Build 286)
Note that instead of navigating through this interface from the Welcome page, you can also use the _ACTION and
_PROGRAM variables in the URL to open different pages.
Stored Process List and Summary Page
From the Welcome page, you can click the List Available Stored Processes link in order to display a page that is split
into sections. (You can also append the _ACTION variable with a value of INDEX (_ACTION=INDEX) to the SAS
Stored Process Web Application URL in order to display this page.) On the left is a tree view of metadata repositories,
folders, and stored processes. If you drill down in the tree view and select a stored process, then a summary of that
stored process is displayed on the right:
You can also display this summary page by specifying _ACTION=DATA&_PROGRAM=<stored−process−path>
on the SAS Stored Process Web Application URL.
The following items are included on this page:
Path
specifies the path to the stored process metadata in the metadata repository. You can use this path as the value
for the _PROGRAM variable.
Directory
specifies the source code repository, where the SAS code is located.
File name
specifies the name of the file that contains the SAS code.
SAS server type
specifies the type of server that is used to run the stored process (either a stored process server or a workspace
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 56
server).
Creation date
specifies the date and time that the stored process metadata was first registered.
Last modified
specifies the date and time that the stored process metadata was last modified.
Keywords
specifies any keywords that are associated with the stored process. These keywords are part of the stored
process metadata.
Description
contains a description of the stored process. This description is part of the stored process metadata.
Click Execute at the bottom of the summary to run the stored process. If there are no parameters or input forms, then
the stored process will execute immediately and the results will be displayed. If there are parameters or input forms,
then you will be taken to the custom input form or property page.
Custom Input Form
If you want the SAS Stored Process Web Application to display a custom input form for a stored process, then you
can use any of the following methods:
On the Welcome page, click the Stored Process Samples link to display a page of stored process samples that
are installed with the SAS Web Infrastructure Kit. Each of these samples has a link and a description. Click
any of these links to display the custom input form for that stored process.
•
Use the _PROGRAM variable along with _ACTION=FORM in the URL to display the custom input form for
a stored process. See Custom Input Forms for more information.
•
On the stored process summary page, click Execute at the bottom of the summary. If the stored process has a
custom input form, then it will be displayed.
•
A custom input form might look like this:
You can use the custom input form to execute the stored process. In this example, clicking Display SAS Output
generates the following results:
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 57
Property Page
A stored process property page can consist of one or more parameters pages and an execution options page. If there
are no parameters pages, then the execution options page is displayed. However, if there are any parameters pages,
then the top parameters page is displayed first. In order to display the property page for a stored process, you can do
one of the following:
Use the _PROGRAM variable along with _ACTION=PROPERTIES in the URL to display the property page
for a stored process. See Property Pages for more information.
•
On the stored process summary page, click Execute at the bottom of the summary. If the stored process does
not have a custom input form, then the property page will be displayed.
•
Parameters Page
You can click Parameters in the menu on the left side of the property page to display the parameters page. If you have
defined parameters groups, then the groups are shown as items in the menu on the left side of the property page. You
can click each group name to display the parameters that are in that group. A parameters page without groups might
look like this:
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 58
This sample parameters page shows four parameters: Date (a date type parameter), Color (a color type parameter),
Comment (a multi−line text type parameter), and Name (a string type parameter). Parameters must be defined in the
stored process metadata for them to be visible in a property page. The stored process metadata is where the label, type,
default value, and constraints for a parameter are defined. Parameter constraints can specify any of the following:
a list of values, number of selections allowed, and whether additional values are allowed for date, color, file
name, and string parameters.
•
string length for string and multi−line text parameters.• a range of values, and the way in which values are incremented for float and integer parameters.•
The metadata also indicates whether each parameter is required, modifiable, or visible, and whether each parameter is
for expert users only. The asterisks (*) beside Date and Name in the previous example indicate that these are required
parameters, which means that the stored process cannot execute until values are provided for these parameters. In this
example, all of the parameters are also visible and modifiable.
The parameter type determines how that parameter is displayed in the property page. You can have any of the
following types of parameters in this page:
Boolean
displays the parameter label and two radio boxes. You must choose whether the value should be true or
false. The default value is false.
Color
displays the parameter label and either a drop−down list, or a text box and a browse [...] button. You can use
the text box or drop−down list to specify or select values in the form CXrrggbb, where rr, gg, and bb are
two−digit hexadecimal numbers. Any characters that you specify are case−insensitive. You can also click the
browse button to display the Choose a Color dialog box, where you can click available colors, specify values,
and preview the resulting color.
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 59
Date
displays the parameter label and either a drop−down list, or a text box and an browse [...] button. You can use
the text box or drop−down list to specify or select values for Date parameters. Date values can be specified
with any legal Java date syntax for your locale or with ddmmmyyyy where dd is a one or two digit day,
mmm is the English month abbreviation, and yyyy is the four digit year. You can also click the browse button
to display the Choose a Date dialog box, where you can click to select a date in the calendar.
File Name
displays a text box or drop−down list where you can enter or select a file name.
Float
displays a text box where you can enter a floating number.
Integer
displays a text box where you can enter an integer.
Multi−line Text
displays a text box, with a scroll bar, where you can enter multiple lines of text.
Note: Multi−line text parameters are not supported for stored processes on workspace servers.
String
displays a text box or drop−down list, where you can enter or select a string.
Execution Options Page
You can click Execution Options in the menu on the left side of the property page in order to view the execution
options page, which might look like this:
The following execution options are available by default:
Display results in a new window?
specifies whether to open a new browser window to display the stored process results.
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 60
Output type
specifies what kind of output object to deliver. The options are HTML, Rich Text, PDF, and PostScript.
ODS style
specifies the ODS style to use when displaying ODS output.
Graphic device
specifies the type of graphic to generate. The options are GIF, JPEG, ActiveX, Java, ActiveX image, Java
image, and SAS EMF.
Show SAS log?
specifies whether to show the SAS log with the stored process results.
Show execution time?
specifies whether to show the amount of time used to process the request. A message like this appears under
the stored process results:
This request took n.nn seconds of real time.
Show execution trace?
specifies whether to set _DEBUG=TRACE for the stored process. See Debugging in the SAS Stored Process
Web Application for more information about this debug option.
HTTP method
specifies which HTTP method to use, either GET or POST. See Specifying Name/Value Pairs in an HTML
Form for more information about these methods.
Process blank parameter values?
specifies whether parameter values that include blank values are passed to the stored process. If you select No,
then blank parameter values are ignored.
Run in the background?
specifies that when the stored process is executed, control is returned to the browser. This option is only
available for stored processes with non−streaming results. Running a stored process in the background causes
an alert to be created. Your alerts (and any results from the stored process) can be viewed from the Alerts
portlet in the SAS Information Delivery Portal. For more information, see Adding and Administering SAS
Stored Processes in the "Adding Content to the Portal" chapter in the SAS Intelligence Platform: Web
Application Administration Guide.
Click Execute in the menu on the left side of the property page to execute the stored process. If you choose to run a
stored process in the background, then you will see a message similar to the following text:
Stored Process //Repository/path/stored process
submitted for background processing.
When executing a stored process using the Web application or Information Delivery Portal, the execution options
page will be displayed unless a JSP file exists for the stored process. If you want to customize the execution options
page, you can hide or customize some of the options.
To hide or customize an execution option, add an input parameter with a name that corresponds to the execution
option. For example, the input parameter named _ODSDEST corresponds to the Output type execution option.
The following table contains a list of the execution options you can hide or customize, and the properties of the input
parameters you need to add in order to hide or customize them. This must be done for each individual stored process.
For each of these input parameters, specify the type as String. You should select Visible if you are customizing the
execution option, but deselect this check box if you are hiding the execution option. You can specify any label for the
input parameters.
Default Value of Input Parameter
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 61
Execution Option
to Customize SAS Variable Name
of Input Parameter
Output type _ODSDEST <blank, or any valid ODS destination>
ODS style _ODSSTYLE <blank, or any valid ODS style>
Graphics device _GOPT_DEVICE <blank, or any valid SAS/GRAPH device driver>
Show SAS Log
Show execution time
Show execution trace _DEBUG <blank, or any valid value for the debugging flag>
You can completely eliminate the execution options page by creating a JSP file for the stored process. See Custom
Input Forms for more information.
Error Page
If there is an error while the stored process is running, then you will get an error message with a button that you can
click to show the SAS log.
In order to disable the Show SAS Log button, you can set the Web application initialization parameter DebugMask
to disable debug logging.
For more information about customizing the SAS Stored Process Web Application, see SAS Stored Process Web
Application Configuration. For more information about Web application input, see Web Application Input.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application 62
SAS Stored Process Web Application Configuration
The SAS Stored Process Web Application can be customized for your site through various configuration files and
servlet initialization parameters.
Configuration Files
The following table describes the external files that are read by the SAS Stored Process Web Application.
File Description
Params.config
contains stored process input parameters that are set before any client parameters are
processed. The parameters are defined in the form name=value on a separate line with a '#'
character in column one indicating a comment. Continuation lines can be specified with a '\'
character at the end of a line. See the section about Web Application Properties for properties
that can be substituted into input parameters in the params.config file. Parameters defined in
the params.config file cannot be overridden.
Resources.properties contains name/value pairs for locale−defined output strings. This file is normally not altered.
Welcome.htm specifies an optional page to display when the SAS Stored Process Web Application is invoked
with no parameters.
Initialization Parameters
The following table describes the initialization parameters that are available. Initialization parameters are values that
are set when the SAS Stored Process Web Application is started. These parameters control various Web Application
processing options. Initialization parameters are defined in the SAS Stored Process Web Application initialization area
of the SAS Stored Process Web Application server.
Initialization
Parameter Description
AuthMechanism
specifies how users are authenticated when logging into the SAS Stored Process Web
Application. This parameter is set to Trusted for Web authentication. If the AuthMechanism
parameter is set to Trusted, then the Web server must set the remote user value or an error will
be returned. See Changing to Trusted Web Authentication in the SAS Intelligence Platform: Web
Application Administration Guide for a description of Web authentication.
Debug specifies default _DEBUG values.
DebugMask specifies the _DEBUG values that users are allowed to set. The default is to allow all keywords.
Valid names can be specified as a comma−separated list.
InputEncoding specifies the default input character encoding, for example, utf−8.
OutputEncoding specifies the default output character encoding, for example, utf−8.
ParamsFile specifies the file that contains the preset input parameters. The default preset file name is
Params.config in the SAS Stored Process Web Application root context directory.
PrivilegedUser specifies a stored process privileged user for pooled workspaces.
SessionTimeout specifies the number of seconds that elapse before a servlet session expires. The default session
SAS Stored Process Web Application Configuration 63
timeout is 900 (15 minutes).
WelcomePage
specifies an HTML page to display if no parameters are entered in the URL. The value that you
specify should be a fully expanded file specification. The default file name is Welcome.htm in the
SAS Stored Process Web Application root context directory. If the welcome file cannot be read,
the SAS Stored Process Web Application version and build number are displayed.
Web Application Properties
Various reserved values, or properties, are available to be passed as input parameters to stored processes executed by
the SAS Stored Process Web Application. To pass a property to every stored process executed by the SAS Stored
Process Web Application, add a line of the form name=$reserved_name to the params.config file. For example,
to add request cookie information as an input parameter, add the following line to params.config:
_HTCOOK=$servlet.cookies
The input parameter _HTCOOK is then created, containing the HTTP header cookie data. _HTCOOK is added to the
input parameters for the stored process.
Note: Any unresolved values result in the corresponding parameter being set to a zero length string.
Reserved Name Recommended
SAS Variable
Name Description
servlet.auth.type _AUTHTYP
specifies the name of the authentication scheme used to protect the
SAS Stored Process Web Application, for example, BASIC or SSL,
or null if the SAS Stored Process Web Application was not
protected.
servlet.character.encoding specifies the name of the character encoding used in the body of the
request.
servlet.content.length specifies the length, in bytes, of the request body and made available
by the input stream, or −1 if the length is not known.
servlet.content.type specifies the MIME type of the body of the request, or null if the
type is not known.
servlet.context.path specifies the portion of the request URL that indicates the context of
the request.
servlet.cookies _HTCOOK specifies all of the cookie strings the client sent with this request.
servlet.header specifies the HTTP request header as received by the SAS Stored
Process Web Application.
servlet.header.accept _HTACPT specifies the MIME types accepted by the stored process client.
servlet.header.referer _HTREFER specifies the address of the referring page.
servlet.header.user−agent _HTUA specifies the name of the user agent.
servlet.header.<name>specifies a particular HTTP request header line as received by the
SAS Stored Process Web Application, where <name> is the header
keyword name.
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application Configuration 64
servlet.info specifies any information about the SAS Stored Process Web
Application, such as author, version, and copyright.
servlet.jsessionid specifies the Java servlet session ID.
servlet.locale specifies the preferred locale that the client will accept content in,
based on the Accept−Language header.
servlet.method _REQMETH specifies the name of the HTTP method with which this request was
made, for example, GET, POST, or PUT.
servlet.name specifies the name of this SAS Stored Process Web Application
instance.
servlet.path specifies the part of the request URL that calls the SAS Stored
Process Web Application.
servlet.path.info specifies any extra path information associated with the URL the
client sent when it made this request.
servlet.path.translated specifies any extra path information after the SAS Stored Process
Web Application name but before the query string, and translates it
to a real path.
servlet.protocol _SRVPROT specifies the name and version of the protocol the request uses in the
form protocol/majorVersion.minorVersion, for example, HTTP/1.1.
servlet.query.string _QRYSTR specifies the query string that is contained in the request URL after
the path.
servlet.remote.addr _RMTADDR specifies the Internet Protocol (IP) address of the client that sent the
request.
servlet.remote.host _RMTHOST 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.
servlet.remote.user _RMTUSER specifies the login of the user making this request, if the user has
been authenticated, or null if the user has not been authenticated.
servlet.request.uri _URL specifies the part of this request's URL from the protocol name up to
the query string in the first line of the HTTP request.
servlet.root specifies the SAS Stored Process Web Application root context
directory.
servlet.scheme specifies the name of the scheme used to make this request, for
example, HTTP, HTTPS, or FTP.
servlet.secure returns true or false indicating whether this request was made using
a secure channel, such as HTTPS.
servlet.server.name _SRVNAME specifies the host name of the server that received the request.
servlet.server.port _SRVPORT specifies the port number on which this request was received.
servlet.server.software _SRVSOFT specifies the Web server software.
servlet.user.name _USERNAME specifies the value for the user name obtained from the browser
authentication.
servlet.user.password specifies the value for the password obtained from the browser
authentication.
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application Configuration 65
servlet.version _VERSION specifies the SAS Stored Process Web Application version and build
number.
There are numerous system properties (for example, user.name) that can be obtained. Setting _DEBUG to ENV will
show all the available values.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
SAS Stored Process Web Application Configuration 66
Web Application Input
A Web application that uses stored processes must have a way of sending input parameters to the stored processes.
Input parameters are normally generated by an HTML page and passed through the Stored Process Web Application
or a user written JSP to the stored process. Input parameters can be specified in the following:
fields in an HTML form. The user provides the required information and submits the request. The Web
browser sends data from the form (including both user entered data and hidden fields) to the server. HTML
forms are generally used where user input is required to control the execution of the stored process.
•
a hypertext link in an anchor tag. The link URL includes parameter values that are passed to the server when
the user selects the link. Hypertext links are generally used where the input parameters have fixed values, for
example, as drill−down links in a table or image.
•
an inline image or other embedded link in the HTML page. This case also includes frames within an HTML
frameset. In most cases, the Web browser fetches the embedded object when the user loads the HTML page.
Fetching the embedded object can cause input parameters to be passed to a stored process.
•
URLs or forms created and submitted by JavaScript or a similar scripting technology in the Web browser.•
The HTML page using these techniques can be a static HTML page or a dynamic page generated on demand by
another stored process or by a Java Server Page (JSP). In all cases, the input parameters must follow the naming
conventions and other basic rules described in the Input Parameters section. Reserved parameter names should be used
only as recommended.
All of the previously mentioned techniques for specifying input parameters rely on URLs or HTML forms. The
following sections discuss how parameters are passed in both cases. These sections assume the use of the Stored
Process Web Application. JSPs generally will use similar conventions, but the details are determined by the author of
the JSP.
Specifying Input Parameters in a URL
You can specify input parameters as a sequence of name/value pairs in a URL by using the query string syntax. For
example, the URL
http://yourserver/SASStoredProcess/do?
_program=/WebApps/Sales/Weekly+Report&region=West
specifies two name/value pairs. The URL specifies your server, an absolute path to your Stored Process Web
Application and the query string (following the question mark character). Each name in the query string is separated
from the following value by an equals (=). Multiple name/value pairs are separated by ampersands (&). In this
example, _program=/WebApps/Sales/Weekly+Report is the reserved input parameter that specifies the
stored process to be executed. The second name/value pair (region=West) is another input parameter to be passed
to the stored process.
There are special rules for the formatting of name/value pairs in a URL. Special characters (most punctuation
characters, including spaces) in a value must be URL encoded. Spaces can be encoded as a plus (+) or %20. Other
characters are encoded using the %nn convention, where nn is the hexadecimal representation of the character in the
ASCII character set. In the previous example, the value /WebApps/Sales/Weekly+Report actually identifies
the stored process named "Weekly Report". The space in the name is encoded as a plus (+). If your parameter values
might contain special characters, it is important that they are URL encoded. Use the URLENCODE DATA step
function when creating URLs in a stored process.
Web Application Input 67
URLs are typically used in an HTML tag attribute and this might require extra encoding to be properly interpreted.
The ampersand characters used in the URL query string can cause the Web browser to interpret them as HTML
markup. The parameter &region=West is interpreted as &reg;ion=West in some browsers. Use HTML
encoding to avoid this problem. For example, use
<A HREF="http://yourserver/SASStoredProcess/do?
_program=/WebApps/Sales/Weekly+Report&amp;region=West">
instead of
<A HREF="http://yourserver/SASStoredProcess/do?
_program=/WebApps/Sales/Weekly+Report&region=West">
The HTMLENCODE DATA step function can be used to encode the URL in a stored process. If we assume the
variable myurl contains a URL with various input parameters, then the following code:
atag = '<A HREF="' || htmlencode(myurl,
'lt gt amp quot') || '">';
creates an anchor tag in the variable atag that is properly encoded.
Note that some browsers and Web servers might impose a limit on the total length of a URL. URLs with many
parameter values that exceed this limit can be truncated without warning, resulting in incomplete or inconsistent input
data for your stored process. URL length limits are not well documented and might require experimentation with your
particular configuration.
Specifying Name/Value Pairs in an HTML Form
HTML forms provide the most versatile mechanism for sending input parameters to a stored process. A form
definition begins with the <FORM> tag and ends with the </FORM> tag. Between these two tags, other HTML tags
define the various components of the form, including labels, input fields, selection lists, push buttons, and more. Any
HTML reference book will document forms and provide numerous examples. A few issues related to stored process
input parameters in HTML forms are discussed below.
The ACTION attribute of the <FORM> tag generally points to the Stored Process Web Application or a JSP that will
execute the stored process. The METHOD attribute of the <FORM> tag can be set to GET or POST:
The GET method causes the Web browser to construct a URL from all of the field values in the form. The
URL will be exactly like the URLs discussed in the previous section. The GET method enables the user to
bookmark a specific stored process execution, including all input parameters, but might be limited in the total
length of all parameters. Web servers typically log all requested URLs and this method causes all input
parameters to be included in the Web server log (a possible security issue).
•
The POST method uses a special post protocol for sending the parameters to the server. The POST method
allows an unlimited number of input parameters and usually hides them from the Web server log, but does not
allow the execution to be bookmarked in a browser.
•
Hidden fields are name/value pairs in a form that do not appear as buttons, selection lists, or other visible fields in the
HTML page. Hidden fields are frequently used to hold fixed input parameters that do not require user input. For
example,
<INPUT TYPE="hidden"
NAME="_program" VALUE="/WebApps/Sales/Weekly Report">
SAS® Integration Technologies: Developer's Guide
Web Application Input 68
specifies the stored process to be executed by this form. Note that the space in the stored process name is not encoded
as in the previous URL section. Values in hidden fields and other field types should not be URL encoded, but might
still need to be HTML encoded if they contain HTML syntax characters such as less than (<), greater than (>),
ampersand (&), or quotation marks (").
Custom Input Forms
The SAS Stored Process Web Application will look for a custom input form if you add the parameter
_ACTION=FORM to the Web application URL. Custom input forms are JSPs under the input folder in the
SASStoredProcess directory. For example, the Shoe Sales by Region sample stored process can be accessed
with:
http://yourserver/SASStoredProcess/do?
_program=/Samples/Stored+Processes/
Sample:+Shoe+Sales+by+Region&_action=form
Your browser will be forwarded to
http://yourserver/SASStoredProcess
/input/Samples/Stored_Processes/
Sample__Shoe_Sales_by_Region.jsp?
_program=/Samples/Stored+Processes/
Sample:+Shoe+Sales+by+Region
In order to create the input form path and name, all names in the stored process path (both folders and the stored
process itself in the _PROGRAM parameter) are converted to an equivalent file system path for a JSP file. The
following special characters in a folder or stored process name are converted to underscore characters: ' " : * ? < > |
and blank spaces.
For example,
/Samples/John's Test Area/Test: Hello World (English) V1.0
would be converted to
<webapp−home>/input/Samples/John_s_Test_Area/
Test__Hello_World_(English)_V1.0.jsp
For more information about the SAS Stored Process Web Application and custom input forms, see Custom Input
Form.
Custom input forms are provided with most of the sample stored processes that are included in the SAS Web
Infrastructure Kit.
As a best practice, custom input form JSP files should be deployed from the Stored Process Web Application install
area. For the previous Shoe Sales by Region example, in a Windows environment, this would be:
<install root>\Web\Portal2.0.1\SASStoredProcess\
input\Samples\Stored_Processes
The path to the custom input form is determined by the location of the stored process entry in metadata. For example,
a stored process located in the repository as
SAS® Integration Technologies: Developer's Guide
Web Application Input 69
/Reports/East Region/Sales Summary 2005
would have a custom input form maintained and deployed from this location:
<install root>\Web\Portal2.0.1\SASStoredProcess\
input\Reports\East_Region
with the file name, Sales_Summary_2005.jsp. Custom input forms should be deployed as part of the
SASStoredProcess.war file. The SASStoredProcess.war file is built and deployed by the SAS Web Infrastructure Kit
redeployment process (see Re−Create and Redeploy the Portal Web Application in the SAS Intelligence Platform:
Web Application Administration Guide).
Property Pages
Property pages provide a parameter input page for stored processes that do not have custom input forms. The property
page is accessed by adding the parameter _ACTION=PROPERTIES to the Web application URL. Parameters must be
defined in the stored process metadata for them to be visible in a property page. For more information about the SAS
Stored Process Web Application and property pages, see Property Page.
If you are unsure whether a stored process has a custom input form, you can specify
_ACTION=FORM,PROPERTIES on the Web application URL. This causes the Web application to display the
custom input form if it exists or display the property page if the input form does not exist. This is the default action for
a stored process accessed from the SAS Information Delivery Portal.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Web Application Input 70
HTTP Headers
Stored process streaming output is always accompanied by an HTTP header. The HTTP header consists of one or
more header records that identify the content type of the output and can provide other information such as encoding,
caching, and expiration directives. A streaming stored process client is free to use or ignore the HTTP header as
desired. The SAS Stored Process Web Application forwards the HTTP client on to the Web browser (or other HTTP
client).
HTTP headers are defined by the HTTP protocol specification (RFC 2616), which can be found at the World Wide
Web Consortium. Each header record is a single text line consisting of a name and a value separated by a colon (:).
The following is an example of records in an HTTP header:
Content−type: text/html; encoding=utf−8
Expires: Wed, 03 Nov 2004 00:00:00 GMT
Pragma: nocache
You can set any HTTP record for your stored process output by calling the STPSRV_HEADER function. The
following DATA step function calls generate the previous example header records:
old = stpsrv_header("Content−type",
"text/html; encoding=utf−8");
old = stpsrv_header("Expires",
"Wed, 03 Nov 2004 00:00:00 GMT");
old = stpsrv_header("Pragma", "nocache");
You can also call this function directly from SAS macro code outside a DATA step. Note that string parameters are
not enclosed in quotation marks and macro characters such as semicolon (;) must be masked in this case:
%let old = %sysfunc(stpsrv_header(Content−type,
text/html%str(;) encoding=utf−8);
%let old = %sysfunc(stpsrv_header(Expires,
Wed, 03 Nov 2004 00:00:00 GMT));
%let old = %sysfunc(stpsrv_header(Pragma, nocache));
Commonly Used Headers
The following are few commonly used HTTP header records:
Content−type• Expires• Pragma• Set−Cookie•
Note: The Location header record does not currently work with stored processes because the HTTP status code
cannot be set.
Content−type
The Content−type header record is generated automatically for you. The value is set based on the ODS destination
that you use in your stored process. The value is determined by looking up the ODS destination in the file types
section of the SAS and, if appropriate, the Windows registry. If you do not use ODS to generate the output,
HTTP Headers 71
Content−type defaults to text/html. Use the STPSRV_HEADER function if you want to override the default
value. Override the value of Content−type when you want to do any of the following:
specify the encoding of the data. This might be important in Web applications where the client (typically a
Web browser) might expect a different encoding than the stored process output. Examples:
Content−type: text/xml; encoding=utf−8
Content−type: text/plain; encoding=iso−8859−1
Content−type: text/html; encoding=windows−1252
•
direct the output to a specific content handler. For example, HTML output can be directed to Microsoft Excel
(in later versions of Microsoft Office) by setting the Content−type to application/vnd.ms−excel.
•
override the default text/html value. This typically occurs if you are using ODS custom tagsets or you are
not using ODS at all to generate the output.
•
Commonly used Content−type values include the following:
Content−type Description
application/octet−stream Unformatted binary data.
image/gif GIF (Graphics Interchange Format) images.
image/jpeg JPEG (Joint Photographic Expert Group) format images.
image/png PNG (Portable Network Graphics) format images.
text/html HTML (Hypertext Markup Language).
text/plain Plain unformatted text.
text/xml XML (eXtensible Markup Language).
text/x−comma−separated−values Spreadsheet data.
Content−type values are also known as MIME types. For a list of all official MIME types, see the IANA registry.
An unregistered MIME type or subtype can be used; the value should be preceded with x−.
Expires
Web clients frequently cache HTML and other content. Accessing the same URL might return the cached content
instead of causing the output to be regenerated by the server. This is often desirable and reduces server and network
loads, but can lead to unexpected or stale data. The Expires header record enables you to control how long a Web
client will cache the content.
The Expires header record requires that the expiration time be specified in Greenwich Mean Time (GMT) and in a
particular format. A SAS picture format can be used to create this value. Use PROC FORMAT to create a custom
format:
proc format;
picture httptime (default=29)
other='%a, %0d %b %Y %0H:%0M:%0S GMT'
(datatype=datetime);
run;
This format can be created one time and saved in a global format library, or you can create it dynamically as needed in
your stored process. The format generates a date in the form
SAS® Integration Technologies: Developer's Guide
HTTP Headers 72
Sun, 24 AUG 2003 17:13:23 GMT
DATA step functions can then be used to set the desired expiration time, adjust to GMT and format, as shown in the
following examples:
/* Expire this page in six hours */
data _null_;
exptime = datetime() + '6:00:00't;
old = stpsrv_header('Expires',
put(exptime − gmtoff(), httptime. ));
run;
/* Expire this page at the beginning of next
week (Sunday, 00:00 local time) */
data _null_;
exptime = intnx('dtweek', datetime(), 1);
old = stpsrv_header('Expires',
put(exptime − gmtoff(), httptime. ));
run;
Specifying an expiration time in the past causes caching to be disabled for your output. It is recommended that you
also use the Pragma: nocache header record in this case. Specify an expiration time far in the future if you want
your content to be cached indefinitely.
Pragma
The Pragma header record is used to specify information not formally defined in the HTTP specification. The most
commonly used value is nocache. This value disables Web client caching of content for most Web browsers.
Set−Cookie
The Set−Cookie header record sends a cookie to the Web client to maintain client−side state. The format is
Set−Cookie: name=value; name2=
value2; ...; expires=date;
path=path; domain=domain_name; secure
where EXPIRES, PATH, DOMAIN, and SECURE are all optional. The date must be specified in the HTTP GMT
format described in the section on the Expires header record.
For example:
old = stpsrv_header("Set−Cookie",
"CUSTOMER=WILE_E_COYOTE; path=/SASStoredProcess/do; " ||
"expires=Wed, 06 Nov 2002 23:12:40 GMT");
The next time your application is run, any matching cookies are returned in the _HTCOOK environment variable,
assuming this variable has been enabled in your SAS Stored Process Web Application environment. You must parse
the cookie string to retrieve the information that you saved in the cookie. Use the scan DATA step function to split
the name/value pairs on the semicolon (;) delimiters; then split the name/value pairs on the equals sign (=) delimiter.
Most Web browsers support cookies, but some users disable them due to privacy concerns, site policies, or other
issues. If you use cookies, explain to your users why you need them and if they must be enabled to use your
application. Some Web clients might not support cookies at all.
SAS® Integration Technologies: Developer's Guide
HTTP Headers 73
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
HTTP Headers 74
Embedding Graphics
Web pages frequently contain embedded graphic images. For static images, an <IMG> tag is enough to embed the
image:
<IMG SRC="mykids.gif">
Dynamically generated images, such as charts that vary over time or due to input parameters, are more complicated.
Stored processes can generate graphics in addition to HTML output. The following stored process creates a bar chart
followed by a tabular report:
/* Sales by Region and Product */
*ProcessBody;
%stpbegin;
title "Sales by Region and Product";
legend1 label=none frame;
proc gchart data=sashelp.shoes;
hbar3d region / sumvar=sales
sum space=.6
subgroup=product
shape=cylinder
patternid=subgroup
legend=legend1;
label product='Shoe Style';
run;
proc report data=sashelp.shoes;
column region product sales;
define region / group;
define product / group;
define sales / analysis sum;
break after region / ol summarize suppress skip;
run;
%stpend;
Depending on input parameters, this stored process might produce the following:
Embedding Graphics 75
Note that no special code was added to handle the image. ODS and the stored process framework takes care of the
details of delivering both the HTML and the image to the Web browser. This code will handle different image types,
through the _GOPT_DEVICE input parameter supported by the %STPBEGIN macro. The image is delivered to the
Web browser in different ways depending on the chosen graphics device. JAVA and ACTIVEX images are generated
by embedding an <OBJECT> tag in the generated HTML containing the attributes and parameters necessary to invoke
the viewer and display the graphic. There is no <IMG> tag in this case. Other commonly used drivers (GIF, JPEG,
PNG, ACTXIMG, and JAVAIMG) do use the <IMG> tag. The following code is an HTML fragment generated by the
previous stored process using the GIF image driver:
<IMG SRC="/SASStoredProcess/do?_sessionid=
7CF645EB−6E23−4853−8042−BBEA7F866B55
&_program=replay&entry=
STPWORK.TCAT0001.GCHART.GIF">
The image URL in the <IMG> tag is actually a reference to the SAS Stored Process Web Application using the
special stored process named REPLAY. The REPLAY stored process takes two parameters, _SESSIONID and
ENTRY. _SESSIONID is new, unique value each time the original stored process is executed. ENTRY is the name of
a temporary SAS catalog entry containing the generated image. Image replay uses a special, lightweight version of the
stored process sessions feature to hold image files temporarily until the Web browser retrieves them.
You can use the REPLAY stored process to replay entries other than embedded images, such as CSS stylesheets,
JavaScript include files, PDF files, and HTML or XML files to be displayed in a pop−up window, frame or
<IFRAME>. The special macro variable _TMPCAT contains the name of the temporary catalog used for REPLAY
SAS® Integration Technologies: Developer's Guide
Embedding Graphics 76
entries and the variable _REPLAY contains the complete URL used to reference the REPLAY stored process (except
the actual entry name). The _TMPCAT catalog remains on the server only for a limited time. If the catalog is not
accessed within a timeout period (typically 15 minutes), the catalog and its contents are deleted.
Direct Graphic Output
In some cases, you might want to generate image output directly from a stored process with no HTML container. This
might be useful if you want to include a dynamically generated graphic in static HTML pages or HTML generated by
an unrelated stored process. For example,
/* Sales by Product − pie chart stored process
*
* XPIXELS and YPIXELS input parameters are required */
/* assume we want a new image generated
* each time the image is viewed −
* disable browser caching of this image */
%let old=%sysfunc(stpsrv_header(Pragma, nocache));
/* need test here in case XPIXELS
* or YPIXELS are not defined */
/* set up graph display options */
goptions gsfname=_webout gsfmode=replace
dev=png cback=cxE0E0E0 xpixels=&XPIXELS
ypixels=&YPIXELS ftext=swiss;
pattern1 color=yellow;
pattern2 color=cyan;
pattern3 color=green;
pattern4 color=black;
pattern5 color=red;
pattern6 color=blue;
/* create a simple pie chart */
proc gchart data=sashelp.shoes;
pie3d product/sumvar=sales;
run;
quit;
This stored process expects XPIXELS and YPIXELS to be passed as input parameters. A typical IMG tag to invoke
this stored process might be
<IMG SRC="/SASStoredProcess/do?_program=
/WebApps/Utilities/Sales+by+Product&XPIXELS=
400&YPIXELS=300">
which results in
SAS® Integration Technologies: Developer's Guide
Embedding Graphics 77
Note: There is a defect in some Web browser versions that ignores the NOCACHE and Expires directives in the
HTTP header. This defect causes the browser to re−use the previously generated image from its cache even if the
HTTP header directed that no caching was to occur. This might happen when embedding an image in an HTML page
or when directly entering an image URL in the Web browser. The old image might be updated by manually
performing a browser REFRESH or RELOAD, but it is difficult to work around this problem without manual
intervention.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Embedding Graphics 78
Chaining Stored Processes
Only the simplest stored process Web applications contain a single Web page. With the addition of a second and
subsequent pages, you face the problem of passing information from one page to another. It is also typical to have an
application that contains more than a single stored process. This means that you must find a way to connect the stored
processes that compose your application and make sure that all of the data collected along the way is available in the
appropriate places.
It is good programming practice to design applications so that they do not request the same information multiple
times. Because HTTP is a stateless environment, each request is separate from all other requests. If a user enters a
phone number on the first page of an application and submits the form, that phone number is available as an input
parameter to the first stored process. After that stored process completes, the input parameters are lost unless they are
explicitly saved. If the second or third stored process in the application needs to know the specified phone number, the
application must ask for the phone number again. There are several ways to solve this problem. You can store data
values in the following locations:
on the client in hidden form fields or URL parameters• on the client in cookies• on the server using sessions.•
Passing Data Through Form Fields or URL Parameters
Storing data on the client in hidden fields or URL parameters is the simplest technique. To do this, you must
dynamically generate all of the HTML pages in your application except for the initial page. Because each page
functions as a mechanism for transporting data values from the previous stored process to the next stored process, it
cannot be static HTML stored in a file.
Usually, the application takes the following steps:
The first HTML page is a welcome or login screen for the application. After the user enters any required
information, the first stored process is executed by submitting a form or clicking on a link.
1.
The first stored process performs any necessary validation on the submitted parameters and any required
application initialization.
2.
The first stored process writes an HTML page to the _WEBOUT output stream. This HTML page might be an
initial report or it might be the next navigation page in the application. Links in this page typically execute
another stored process and pass user identity, user preferences, application state or any other useful
information through hidden form fields or URL parameters.
3.
Each succeeding link in the application executes another stored process and passes any required information
through the same technique.
4.
Each hidden field in the second form can contain one name/value data pair passed from the first form. You should use
unique names for all of the data values in the entire application. In this way you can pass all of the application data
throughout the entire application.
When you dynamically generate the second form, you can write out the name of the second stored process in the
hidden field _PROGRAM. Because the first stored process contains the logic to determine the second stored process,
this is referred to as chaining stored processes. A stored process can chain to multiple stored processes depending on
the link a user chooses or on data entered by the users. The stored process can even chain back to itself.
Chaining Stored Processes 79
Example
The MyWebApp application starts with a static HTML welcome page.
<!−− Welcome page for MyWebApp −−>
<HTML>
<HEAD><TITLE>Welcome to MyWebApp
</TITLE></HEAD>
<BODY><H1>Welcome to MyWebApp</H1>
<FORM ACTION="/SASStoredProcess/do">
Please enter your first name:
<INPUT TYPE="text" NAME="FNAME"><BR>
<INPUT TYPE="hidden" NAME="_program"
VALUE="/WebApps/MyWebApp/Ask Color">
<INPUT TYPE="submit" VALUE="Run Program">
</FORM>
</BODY></HTML>
This page prompts the user for a first name and passes the value as the FNAME input parameter to the
/WebApps/MyWebApp/Ask Color stored process, as follows:
/* Ask Color stored process
*
* This stored process prompts for the user's favorite
* and passes it to the Print Color stored process.
*/
data _null_;
file _webout;
put '<HTML>';
put '<H1>Welcome to MyWebApp</H1>';
/* Create reference back to the Stored Process
Web Application from special automatic
macro variable _URL. */
put "<FORM ACTION='&_URL'>";
/* Specify the stored process to be executed using
the _PROGRAM variable. */
put '<INPUT TYPE="hidden" NAME="_program" ' ||
'VALUE="/WebApps/MyWebApp/Print Color">';
/* Pass first name value on to next program.
The value is user entered text, so you must
encode it for use in HTML. */
fname = htmlencode("&FNAME", 'amp lt gt quot');
put '<INPUT TYPE="hidden" NAME="fname" VALUE="'
fname +(−1) '"><BR>';
put 'What is your favorite color?';
put '<SELECT SIZE=1 NAME="fcolor">';
put '<OPTION VALUE="red">red</OPTION>';
put '<OPTION VALUE="green">green</OPTION>';
put '<OPTION VALUE="blue">blue</OPTION>';
put '<OPTION VALUE="other">other</OPTION>';
put '</SELECT><BR>';
put '<INPUT TYPE="submit" VALUE="Run Program">';
put '</FORM>';
put '</HTML>';
run;
SAS® Integration Technologies: Developer's Guide
Chaining Stored Processes 80
This stored process simply creates an HTML form prompting the user for more information. The reserved macro
variable _URL is used to refer back to the SAS Stored Process Web Application. This enables you to move the Web
application without modifying each stored process. The _PROGRAM variable specifies the stored process that will
process the contents of the form when it is submitted. In order to keep the FNAME that was entered in the initial page,
place it in the form as a hidden field. Because the value was entered by the user, it must be encoded using the
HTMLENCODE function in case it contains any character that might be interpreted as HTML syntax. The form
prompts the user for a color choice and chains to a new stored process named Print Color, as follows:
/* Print Color stored process
*
* This stored process prints the user's
* first name and favorite color.
*/
data _null_;
file _webout;
put '<HTML>';
fname = htmlencode("&FNAME");
put 'Your first name is <b>'
fname +(−1) '</b>';
put '<BR>';
put "Your favorite color is
<b>&FCOLOR</b>";
put '<BR>';
put '</HTML>';
run;
The Print Color stored process prints the values of the variables from both the first and second forms, illustrating
that the data has been correctly passed throughout the entire application.
A variation of this technique uses URL parameters instead of hidden form fields. An alternate implementation of the
Ask Color stored process might be as follows:
/* Ask Color stored process
*
* This stored process prompts for the user's favorite
* and passes it to the Print Color stored process.
*/
data _null_;
file _webout;
put '<HTML>';
put '<H1>Welcome to MyWebApp</H1>';
/* Build a URL referencing the next stored process.
* Use URLENCODE to encode any special characters in
* any parameters. */
length nexturl $500;
nexturl = "&_URL?_program=
/WebApps/MyWebApp/Print Color" ||
'&fname=' || urlencode("&FNAME");
put 'What is your favorite color?';
put '<UL>';
put '<LI><A HREF="' nexturl +(−1)
'&color=red">red</A><LI>';
put '<LI><A HREF="' nexturl +(−1)
'&color=green">green</A><LI>';
put '<LI><A HREF="' nexturl +(−1)
'&color=blue">blue</A><LI>';
SAS® Integration Technologies: Developer's Guide
Chaining Stored Processes 81
put '<LI><A HREF="' nexturl +(−1)
'&color=other">other</A><LI>';
put '</UL>';
put '</HTML>';
run;
This stored process generates a separate URL link for each color choice. The end result is the same as the first
implementation of Ask Color: the Print Color stored process is executed with both FNAME and COLOR
input parameters.
The technique of passing data by using hidden fields or URL parameters has the following advantages:
simple to perform• easy to debug• state is maintained indefinitely• allows stored processes to be distributed across multiple servers•
The major disadvantages of this technique are the necessity to use dynamically generated HTML for all pages in the
application and the security and visibility of the data. The data in hidden fields is readily visible to the client by
viewing the HTML source (and is directly visible in the URL when using GET method forms). The data is easily
changed by the user and falsified or inconsistent data can be submitted to the application. Sensitive data should be
validated in each new stored process, even if it is passed from generated hidden fields.
Passing Data Through Cookies
HTTP cookies are packets of information that are stored in the client Web browser. They are shuttled back and forth
with the application requests. In a general sense, they are quite similar to hidden form fields, but they are
automatically passed with every request to the application. Cookies have the advantage of being nearly invisible to the
user. They contain a built−in expiration mechanism, and they are slightly more secure than hidden fields. They also
work seamlessly across multiple stored process servers and Web applications and are preserved even if your
application uses static HTML pages. See the HTTP Header documentation for more information about setting and
using cookies. You must enable HTTP cookies in your Web application configuration.
HTTP cookies can be complex to generate and parse. You must carefully consider names, paths and domains to
ensure your cookie values do not conflict with other applications installed on the same Web server. HTTP cookies
might also be disabled by some clients due to privacy concerns.
Passing Data Through Sessions
Sessions provide a simple way to save state on the server. Instead of passing all of the saved information to and from
the Web client with each request, a single session key is passed and the data is saved on the server. Applications must
use all dynamically generated HTML pages, but the hidden fields or URL parameters are much simpler to generate. In
addition, sessions provide a method to save much larger amounts of state information including temporary data sets or
catalogs. Sessions have the disadvantage of binding a client to a single server process, which can affect the
performance and scalability of a Web application. Sessions are not recommended for simple applications that pass
small amounts of data from one stored process to another. See the sessions documentation for more information.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Chaining Stored Processes 82
Using Sessions: A Sample Web Application
The following sample Web application demonstrates some of the features of stored process sessions. The sample
application is an online library. Users can log on, select one or more items to check out of the library, and request by
e−mail that the selected items be delivered. The sample code shows how to create a session and then create, modify,
and view macro variables and data sets in that session. See the section about Sessions for more information.
Sample Data
This sample requires a LIB_INVENTORY data set in the SAMPDAT library that is used for other SAS Integration
Technology samples. You can create the data set in Windows using the following code. You can also use the code in
other operating environments by making the appropriate modifications to the SAMPDAT LIBNAME statement.
libname SAMPDAT 'C:\My Demos\Library';
data SAMPDAT.LIB_INVENTORY;
length type $10 desc $80;
input refno 1−5 type 7−16 desc 17−80;
datalines4;
17834 BOOK SAS/GRAPH Software: Reference
32345 BOOK SAS/GRAPH Software: User's Guide
52323 BOOK SAS Procedures Guide
54337 BOOK SAS Host Companion for UNIX Environments
35424 BOOK SAS Host Companion for OS/390 Environment
93313 AUDIO The Zen of SAS
34222 VIDEO Getting Started with SAS
34223 VIDEO Introduction to AppDev Studio
34224 VIDEO Building Web Applications with
SAS Stored Processes
70001 HARDWARE Cellphone − Model 5153
70002 HARDWARE Video Projector − Model 79F15
;;;;
Main Aisle Stored Process
The main aisle page is generated by the Main Aisle stored process. This page acts as a welcome page if new users. A
session is created the first time a user executes this stored process.
/* Main Aisle of the Online Library */
data _null_;
file _webout;
if libref('SAVE') ne 0 then
rc = stpsrv_session('create');
put '<HTML>';
put '<HEAD><TITLE>Online Library
Main Aisle</TITLE></HEAD>';
put;
put '<BODY vlink="#004488" link="#0066AA"
bgcolor="#E0E0E0">';
put '<H1>Online Library Main Aisle</H1>';
put;
put 'Select one of the following
areas of the library:';
Using Sessions: A Sample Web Application 83
put '<UL>';
length hrefroot $400;
hrefroot = symget('_THISSESSION') ||
'&_PROGRAM=/WebApps/Library/';
put '<LI><A HREF="' hrefroot +(−1)
'Aisles&type=Book">Book Aisle</A></LI>';
put '<LI><A HREF="' hrefroot +(−1)
'Aisles&type=Video">Video Aisle</A></LI>';
put '<LI><A HREF="' hrefroot +(−1)
'Aisles&type=Audio">Audio Aisle</A></LI>';
put '<LI><A HREF="' hrefroot +(−1)
'Aisles&type=Hardware">Hardware Aisle</A></LI>';
put '<LI><A HREF="' hrefroot +(−1)
'Shopping Cart">View my shopping cart</A></LI>';
put '<LI><A HREF="' hrefroot +(−1)
'Logout">Logout</A></LI>';
put '</UL>';
put '</BODY>';
put '</HTML>';
run;
The main aisle page consists of a list of links to specific sections of the Online Library.
Each link in this page is built using the _THISSESSION macro variable. This variable includes both the _URL value
pointing back to the Stored Process Web Application and the _SESSIONID value identifying the session.
Aisles Stored Process
The library is divided into aisles for different categories of library items. The pages for each aisle are generated by one
shared Aisles stored process. The stored process accepts a TYPE input variable that determines which items to
display.
/* Aisles − List items in a specified aisle.
The aisle is specified by the TYPE variable. */
libname SAMPDAT 'C:\My Demos\Library';
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 84
/* Build a temporary data set that contains the
selected type, and add links for selecting
and adding items to the shopping cart. */
data templist;
if libref('SAVE') ne 0 then
rc = stpsrv_session('create');
set SAMPDAT.LIB_INVENTORY;
where type="%UPCASE(&type)";
length select $200;
select = '<A HREF="' || symget("_THISSESSION") ||
'&_program=/WebApps/Library/Add+Item&REFNO=' ||
trim(left(refno)) || '&TYPE=' || "&TYPE" ||
'">Add to cart</A>';
run;
ods html body=_webout(nobot) rs=none;
title Welcome to the &type Aisle;
proc print data=templist noobs label;
var refno desc select;
label refno='RefNo' desc='Description' select='Select';
run;
ods html close;
data _null_;
file _webout;
put '<P>';
put 'Return to <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Main+Aisle'
'">main aisle</A><BR>';
put 'View my <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Shopping+Cart'
'">shopping cart</A><BR>';
put '</BODY>';
put '</HTML>';
run;
The stored process selects a subset of the LIB_INVENTORY data set using a WHERE clause, and then uses PROC
PRINT to create an HTML table. A temporary data set is created that contains the selected items in order for an
additional column to be generated that has an HTML link for users to add the item to their shopping cart.
In this stored process, both ODS and a DATA step are used to generate HTML. The ODS HTML statement includes
the NOBOT option that indicates that more HTML will be appended after the ODS HTML CLOSE statement. The
navigation links are then added using a DATA step.
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 85
Add Item Stored Process
The Add Item stored process is run when the user clicks the Add to cart link in the aisle item table. The specified
item is copied from the LIB_INVENTORY data set to a shopping cart data set in the session library (SAVE.CART).
The session and the data set will remain accessible to all programs in the same session until the session is deleted or it
times out.
/* Add Item − Add a selected item to the shopping cart.
This stored process uses REFNO and TYPE input
variables to identify the item. */
libname SAMPDAT 'C:\My Demos\Library';
/* Perform REFNO and TYPE verification here. */
/* Append the selected item. */
proc append base=SAVE.CART data=SAMPDAT.LIB_INVENTORY;
where refno=&refno;
run;
/* Print the page. */
data _null_;
file _webout;
put '<HTML>';
put '<HEAD><TITLE>Selected Item Added to
Shopping Cart</TITLE></HEAD>';
put '<BODY vlink="#004488" link="#0066AA"
bgcolor="#E0E0E0">';
put "<H1>Item &refno Added</H1>";
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 86
put 'Return to <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Aisles'
'&TYPE=' "&TYPE" '">' "&TYPE aisle</A><BR>";
put 'Return to <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Main+Aisle'
'">main aisle</A><BR>';
put 'View my <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Shopping+Cart'
'">shopping cart</A><BR>';
put '</BODY>';
put '</HTML>';
run;
The program prints an information page that has navigation links.
Shopping Cart Stored Process
The Shopping Cart stored process displays the contents of the shopping cart.
/* Shopping Cart − Display contents of the shopping cart
* (SAVE.CART data set). */
%macro lib_cart;
%let CART=%sysfunc(exist(SAVE.CART));
%if &CART %then %do;
/* This program could use the same technique as the
LIB_AISLE program in order to add a link to each
line of the table that removes items from the
shopping cart. */
/* Print the CART contents. */
ods html body=_webout(nobot) rs=none;
title Your Selected Items;
proc print data=SAVE.CART noobs label;
var refno desc;
label refno='RefNo' desc='Description';
run;
ods html close;
%end;
%else %do;
/* No items in the cart. */
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 87
data _null_;
file _webout;
put '<HTML>';
put '<HEAD><TITLE>No items
selected</TITLE></HEAD>';
put '<BODY vlink="#004488" link="#0066AA"
bgcolor="#E0E0E0">';
put '<H1>No Items Selected</H1>';
put;
run;
%end;
/* Print navigation links. */
data _null_;
file _webout;
put '<P>';
if &CART then do;
put '<FORM ACTION="' "&_url" '">';
put '<INPUT TYPE="HIDDEN" NAME="_program"
VALUE="/WebApps/Library/Logout">';
put '<INPUT TYPE="HIDDEN" NAME="_sessionid"
VALUE="' "&_sessionid" '">';
put '<INPUT TYPE="HIDDEN" NAME="CHECKOUT"
VALUE="YES">';
put '<INPUT TYPE="SUBMIT"
VALUE="Request these items">';
put '</FORM><P>';
end;
put 'Return to <A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Main+Aisle'
'">main aisle</A><BR>';
put '<A HREF="' "&_THISSESSION"
'&_PROGRAM=/WebApps/Library/Logout'
'&CHECKOUT=NO">Logout</A><BR>';
put '</BODY>';
put '</HTML>';
run;
%mend;
%lib_cart;
The contents of the shopping cart are displayed using a PROC PRINT statement. The page also includes a request
button and navigation links. The request button is part of an HTML form. In order to connect to the same session,
include the _SESSIONID value in addition to the normal _PROGRAM value. These values are usually specified as
hidden fields. This program also has a hidden CHECKOUT field that is initialized to YES in order to indicate that the
user is requesting the items in the cart.
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 88
Logout Stored Process
The Logout stored process checks the user out of the Online Library. If the CHECKOUT input variable is YES, then
all of the items in the user's shopping cart are requested via e−mail.
/* Logout − logout of Online Library application.
Send e−mail to the library@abc.com account with
requested item if CHECKOUT=YES is specified. */
%macro lib_logout;
%global CHECKOUT;
/* Define CHECKOUT in case it was not input. */
%if %UPCASE(&CHECKOUT) eq YES %then %do;
/* Checkout − send an e−mail request to the library.
See the documentation for the email access method
on your platform for more information on the
required options. */
/* ***************** disabled for demo *************
filename RQST EMAIL 'library@abc.com'
SUBJECT='Online Library Request for &_USERNAME';
ods listing body=RQST;
title Request for &_USERNAME;
proc print data=SAVE.CART label;
var refno type desc;
label refno='RefNo' type='Type'
desc='Description';
run;
ods listing close;
* *********************************************** */
data _null_;
file _webout;
put '<HTML>';
put '<HEAD><TITLE>Library
Checkout</TITLE></HEAD>';
put '<BODY vlink="#004488" link="#0066AA"
bgcolor="#E0E0E0">';
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 89
put '<H1>Library Checkout</H1>';
put;
put 'The items in your shopping cart have
been requested.';
put '<P>Requested items will normally
arrive via interoffice';
put 'mail by the following day. Thank you
for using the Online Library.';
put '<P><A HREF="' "&_URL"
'?_PROGRAM=/WebApps/Library/Main+Aisle"
>Click here</A>';
put 'to re−enter the application.';
put '</BODY>';
put '</HTML>';
run;
%end;
%else %do;
/* Logout without requesting anything. */
data _null_;
file _webout;
put '<HTML>';
put '<HEAD><TITLE>Logout</TITLE></HEAD>';
put '<BODY vlink="#004488" link="#0066AA"
bgcolor="#E0E0E0">';
put '<H1>Library Logout</H1>';
put;
put '<P>Thank you for using the Online Library.';
put '<P><A HREF="' "&_URL"
'?_PROGRAM=/WebApps/Library/Main+Aisle"
>Click here</A>';
put 'to re−enter the application.';
put '</BODY>';
put '</HTML>';
run;
%end;
%mend;
%lib_logout;
/* User is finished − delete the session. */
%let rc=%sysfunc(stpsrv_session(delete));
An information page is displayed if the user chooses to request the shopping cart items.
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 90
A simple logout screen is displayed if the user selects the Logout link.
Note: Logging out is not required. All sessions have an associated timeout (the default is 15 minutes). If the session is
not accessed for the duration of the timeout, the session and all temporary data in the session will be deleted. In this
sample, the SAVE.CART data set would be automatically deleted when the session timeout is reached. You can
change the session timeout using the STPSRVSET('session timeout',seconds) function inside the program.
SAS Stored Processes
SAS® Integration Technologies: Developer's Guide
Using Sessions: A Sample Web Application 91
Debugging in the SAS Stored Process Web Application
After the SAS Stored Process Web Application has been installed, it can be tested by invoking it directly from a Web
browser. To execute the SAS Stored Process Web Application, enter the Web application URL in the Web browser,
and either the default Welcome page or static version data gets returned.
For example, if the SAS Stored Process Web Application URL entered is
http://yourserver.com:8080/SASStoredProcess/do?
then you either get the data from the Welcome.htm page if it has been installed, or a display similar to
Stored Process Web Application
Version 9.1 (Build 286)
If an error is returned, then the installation was not completed successfully or the URL that was entered is incorrect.
The reserved macro variable _DEBUG provides you with several diagnostic options. Using this variable is a
convenient way to debug a problem, because you can supply the debug values by using the Web browser to modify
your HTML or by editing the URL in your browser location field. For example, to see the installed environment for
the SAS Stored Process Web Application, the URL can be entered with _DEBUG=ENV appended. A table is
returned, which contains the system values for the SAS Stored Process Web Application environment.
List of Valid Debug Keywords
You can activate the various debugging options by passing the _DEBUG variable to the SAS Stored Process Web
Application. Keywords are used to set the debug options. Multiple keywords can be specified separated by commas or
spaces. For instance,
_DEBUG=TIME,TRACE
Some debug flags might be locked out at your site for security reasons. Verify with your administrator which flags are
locked out at your site. The following chart is a list of valid debug keywords:
Keyword Description
FIELDS Displays the stored process input parameters.
TIME Returns the processing time for the stored process.
DUMP Displays output in hexadecimal.
LOG Returns the SAS log file. This is useful for diagnosing problems in the SAS code.
TRACE Traces execution of the stored process. This is helpful for diagnosing the SAS Stored Process Web
Application communication process. You can also use this option to see the HTTP headers that the server
returns.
LIST Lists known stored processes.
ENV Displays the SAS Stored Process Web Application environment parameters.
Debugging in the SAS Stored Process Web Application 92
Some debug options, such as showing the SAS log, showing the stored process execution time, and tracing stored
process execution, are available from the Execution Options page of the SAS Stored Process Web Application.
Setting the Default Value of _DEBUG
Web application initialization parameters can be used to set default values for the _DEBUG parameter or to limit the
allowable values. Any of the valid keywords listed in the previous table can be specified as a comma−separated list
for the Debug initialization parameter. These values become the default debug values for each request. The
initialization parameter DebugMask can be used to specify a list of _DEBUG values that are disallowed. Refer to the
section about Web Application Configuration for more information about initialization parameters.
IOM Direct Interface Stored Processes
SAS® Integration Technologies: Developer's Guide
Debugging in the SAS Stored Process Web Application 93
Implementing a Repository
Implementing a repository for your stored processes is simple. You first need to allocate a storage location that your
servers can access to hold your stored processes. This storage location, or repository, is implemented as a file system
directory with the stored processes instances represented as files, by name, with a .sas extension if appropriate for the
file system. Clients invoke the stored process utilizing this file name minus the .sas extension.
Once you have created the repository, you can catalogue its existence using the Administrator utility if you want to
manage your stored process definitions in an LDAP directory. This is not required in order to utilize the facility but
can be useful for resource management and discovery purposes. In this case, a repository is defined with information
about the file system location and IOM server associations to gain access to the file system from a distributed client.
The individual stored process instances are assigned a logical name and a set of properties are defined including the
implementation file name, any name/value parameter pairs, and descriptive labels.
IOM Direct Interface Stored Processes
Implementing a Repository 94
Creating a Stored Process
A SAS language stored process is a normal SAS program with an additional feature that enables you to customize its
execution. This feature enables the invoking application to supply name/value parameters at the time that the stored
process is invoked. For example, if you have a stored process that analyzes monthly sales data, you could create a
MONTH variable in the stored process. Then at execution time, to analyze the May sales data, you would supply a
name/value pair of MONTH=MAY.
The following is an example of a stored process:
%let tempdir = ;
%let source = ;
%let intable = ;
%let svar = ;
%let filter = ;
%let outtitle = ;
*ProcessBody;
libname datain "&source";
proc sql;
create table xQuery as
select product, &svar
from datain.&intable
where &filter;
proc sort data=xQuery;
by &svar;
proc print data=xQuery;
by &svar;
filename outgif "c:\Temp\&tempdir\xQuery.gif";
goptions reset=all;
goptions device=gif gsfname=outgif gsfmode=replace;
title1 f=swiss &outtitle;
proc gchart data=xQuery;
hbar3d product/sumvar=&svar patternid=midpoint;
run;
As you can see in the example above, SAS Macro Language variables implement the stored process's execution
parameters within the source body. The macro variables are initialized to default values in the prologue section of the
stored process. The *ProcessBody comment is a marker that identifies the end of the prologue. This marker is
required syntax that delineates the boundary between the default parameter prologue and the source body, where
invocation parameters are applied.
The remainder of the stored process is an ordinary SAS program−−in this case, a general purpose analysis routine that
both prints the results and graphs them in a three−dimensional horizontal bar chart.
When the stored process is executed, the IOM StoredProcessService applies the client−provided name/value
parameters that override the default values of the macro variables.
Creating a Stored Process 95
IOM Direct Interface Stored Processes
SAS® Integration Technologies: Developer's Guide
Creating a Stored Process 96
Invoking a Stored Process
Using the IOM StoredProcessService to invoke a stored process from a client application is straightforward. You first
define the location of the repository. You do this by setting the Repository property of the StoredProcessService.
For example, if you are using file system objects to implement the repository and have allocated a UNIX directory of
/SASPrograms/StoredProcesses to hold your programs, the following Visual Basic code sets the repository property of
the StoredProcessService.
Dim sp as SAS.StoredProcessService
Set sp = obWS.LanguageService.StoredProcessService
sp.Repository = "file:/SASPrograms/StoredProcesses"
Note: This assumes that you already have a reference (obWS in this case) to a Workspace object. Please see Working
With Object Variables and Creating a Workspace for details on how to obtain this reference.
Then, to execute a stored process on the server, you invoke the Execute method and pass the filename of the stored
process as well as any required name/value parameters to be used in this execution of the stored process.
For example, if the stored process shown in the example above was in a file named SP01, you might invoke it using
the following Visual Basic code:
sp.Execute "SP01", "tempdir=scratch
source=salesdata intable=monthly _
svar=sales filter=MONTH=MAY
outtitle=Monthly Sales Data"
IOM Direct Interface Stored Processes
Invoking a Stored Process 97
Publishing Stored Process Results
At this point, if you have read the section, Invoking a Stored Process, and you have seen how the IOM
StoredProcessService is used to invoke the stored process on the server, you may be wondering what happens to the
results. This is where packages come into play.
One of the main features of SAS Integration Technologies is the Publishing Framework. Central to the publishing
framework is the ability to create or collect data, including SAS output, in the form of packages.
One of the ways in which you can create packages is with the Publish Package Interface. This is a library of SAS
CALL routines that you can use within your stored processes to create a package and then publish it to various
delivery transports including an e−mail address(es), a message queue, subscribers to a predefined channel, a
WebDAV−Compliant server, and to an archive. (See the Publish Package Interface for more details.)
An additional method of delivering a published package is to send it back to the requesting application. This transport
is sometimes referred to as the To_Requester transport because that is the value of the parameter in the
PACKAGE_PUBLISH CALL routine that controls how the package is delivered.
Follow these basic steps to use the Publish Package Interface:
Initialize the package. For example, the following SAS language code initializes a package:
packageId=0;
rc=0;
PkgDesc = "package contains a printed report
and graph for the May Sales Data.";
nameValue='';
CALL PACKAGE_BEGIN(packageId, desc, nameValue, rc);
1.
Add one or more entries to the package. The following example uses the SAS Output Delivery System (ODS)
to generate HTML files that are subsequently inserted into the package. Note that the statements below for
PROC SQL, PROC SORT, and PROC PRINT are from the example stored process that is used in Creating a
Stored Process.
ItemDesc='HTML output for May Sales Data';
nameValue = '';
filename f '/users/f.html';
filename c '/users/c.html';
filename b '/users/b.html';
filename p '/users/p.html';
ods html frame=f contents=c(url='c.html')
body=b(url='b.html') page=p(url='p.html');
proc sql;
create table xQuery as
select &svar
from datain.&intable
where &filter;
proc sort data=xQuery;
by &svar;
proc print data=xQuery;
by &svar;
ods html close;
2.
Publishing Stored Process Results 98
/* The statement below inserts the
resulting HTML into the package */
CALL INSERT_HTML(packageId, 'fileref:b', "b.html",
'fileref:f', "f.html", 'fileref:c', "c.html",
'fileref:p', "p.html", ItemDesc, nameValue, rc);
You can add additional items to the package as needed. The example below adds another item; in this case,
the GIF file that was produced from SAS/GRAPH from the example stored process that is used in Creating a
Stored Process.
filename = 'filename:c:\Temp\&tempdir\xQuery.gif';
filetype ='binary';
desc = 'Graph of the SP01 results in GIF format.';
nameValue = '';
mimetype = 'Image/gif';
CALL INSERT_FILE(packageId, filename, filetype,
mimetype, desc, nameValue, rc);
Publish the package. The following SAS language code shows an example of publishing the package back to
the requesting application:
call package_publish(packageId,
"TO_REQUESTER", rc, "", "");
3.
Release the package resources. This is the last step of the publish process using the Publish Package interface.
It frees the SAS system resources that were associated with the package that was just published. The
following SAS language code shows an example of how to use this CALL routine:
call package_end(packageId, rc);
4.
IOM Direct Interface Stored Processes
SAS® Integration Technologies: Developer's Guide
Publishing Stored Process Results 99
Working with Results in the Client Application
If your stored process publishes the package back to the requesting application as discussed in Publishing the Results,
then you will need to use the ExecuteWithResults method that is a part of the StoredProcessService. This method
causes the IOM server to return to the client application a reference to the package that was created in the stored
process.
The following Visual Basic code shows how this method is used:
Dim sp as SAS.StoredProcessService
Dim rp as SAS.ResultPackage
Set sp = obWS.LanguageService.StoredProcessService
sp.Repository = "file:/SASPrograms/StoredProcesses"
sp.ExecuteWithResults "SP01", "tempdir=scratch
source=salesdata intable=monthly _ svar=sales
filter=MONTH=MAY outtitle=Monthly Sales Data", _ rp
Note: The ExecuteWithResults method is used instead of the Execute method.
You can then use the returned reference to the package, rp in this case, to manipulate the package with the methods
that are available for the IOM ResultPackage object. This object has methods available to list and view the package
entries as well as the package metadata. Please see the ResultPackage Object for the complete reference
documentation for this object.
SAS BI Web Services
Working with Results in the Client Application 100
SAS BI Web Services
A Web service is an interface that enables communication between distributed applications. Web services enable
cross−platform integration by enabling applications written in various programming languages to communicate using
a standard Web−based protocol, typically the Simple Object Access Protocol (SOAP). This functionality makes it
possible for businesses to bridge the gaps between different applications and systems.
There are two implementations of SAS BI Web Services: one written in Java that requires a servlet container, and
another written in C# using the .NET framework. For information about the differences between SAS BI Web
Services for .NET and SAS BI Web Services for Java, see Deciding Between .NET and Java.
The SAS BI Web Services interface is based on the XML for Analysis (XMLA) Version 1.1 specification. XMLA is a
standard specification developed by several companies for use as a Web service interface to access online analytical
processing (OLAP) and data−mining functions. For the first release of SAS BI Web Services, a client application can
use this interface to invoke and get metadata about SAS Stored Processes. Support for OLAP technology is under
development for future releases of SAS BI Web Services.
The following figure shows how Web services work. A client, such as a Web application or desktop application, starts
out by obtaining the Web Service Description Language (WSDL) from the Web service. The WSDL describes the
methods available, endpoint (where to call the Web service), and the format of the XML required to call the Web
service.
Web service clients and servers transport XML data using a data envelope called a SOAP envelope. Any client that
can send and receive SOAP messages can access Web services. SAS supports SOAP bindings over HTTP. The client
sends XML requests and parameters in a SOAP envelope to the Web service, telling the Web service to either
Discover or Execute stored processes.
Discover() and Execute() are the two methods that are specified for XMLA. The Discover method consists of
middle−tier code that calls the SAS Metadata Server to get the requested metadata. The Execute method consists of
middle−tier code that calls the SAS Stored Process Server to invoke stored processes.
During execution, the requested stored process is executed by a SAS Stored Process Server. Usually any number of
simple string parameters are passed to the stored process, and a stream of XML data is returned. The input parameters
to the stored process can be nothing or a combination of simple string parameters and any number of XML streams.
The output from a stored process called by a SAS BI Web Service is always an XML stream.
SAS BI Web Services
SAS BI Web Services 101
Using Web Services
Before you can use Web services, you need to follow these steps on the server side:
Decide whether you want to use SAS BI Web Services for .NET or SAS BI Web Services for Java. Install
SAS BI Web Services and the SAS Metadata Server.
1.
Write a SAS program to use as a stored process with Web services.2. Define a stored process server.3. Define a stored process using BI Manager. Use XMLA Web Service as a keyword when defining a stored
process to be called by a SAS BI Web Service. Also, when defining a stored process to be called by a SAS BI
Web Service, specify Streaming as the stored process output type.
Note: BI Manager is available beginning with SAS Foundation Services 1.2. If you have not upgraded to this
release, then you can use Stored Process Manager to register and manage stored processes. BI Manager
replaces Stored Process Manager. For more information about using BI Manager or Stored Process Manager,
see the Help in SAS Management Console.
4.
On the client side, follow these steps to use Web services:
Locate the WSDL.1. Write the code for the client application that uses either the Discover method or Execute method to call the
Web service.
2.
Run the code.3.
The SAS code that implements the Web service, the metadata, and the client code that calls the Web service must all
be synchronized. The following table shows how to synchronize these three items:
SAS Program Metadata Client Code
Name The name of the file
containing the SAS code. Matches the name of the SAS Stored
Process with the name of the file.
<StoredProcess name=
'MyStoredProcess'>
Input Data Reads XML from the
fileref.
libname instream
xml;
The name of the fileref, which must
match the name of the input stream.
<Stream name='instream'>
<XMLDataFromClientHere...
</Stream>
Input
Parameters Macros.
&tablename
The parameter name is specified in the
metadata. Parameters are treated as
strings regardless of the type specified
in the metadata.
<Parameter
name='tablename'>
myParam</Parameter>
Output Data Writes output to the
_WEBOUT fileref as
XML.
libname _WEBOUT
xml xmlmeta=
&_XMLSCHEMA;
Designates the output as 'Streaming'. Uses the returned XML.
SAS BI Web Services
Using Web Services 102
Deciding Between .NET and Java
There are some differences between SAS BI Web Services for .NET and SAS BI Web Services for Java. Following
are some frequently asked questions that you can use to help you decide which version is the right one for you to
install, and some differences that exist for the Web service client.
Installation and Administration Differences
What operating environment are you using?
SAS BI Web Services for .NET can only be installed in the Windows XP, Windows 2000, and
Windows 2003 operating environments.
♦
SAS BI Web Services for Java can be installed in any operating environment that can understand
Java.
♦
•
How do you want to administer the Web services?
SAS BI Web Services for .NET are administered using IIS.♦ SAS BI Web Services for Java are administered using Apache Tomcat or BEA Weblogic. If you
install SAS BI Web Services for Java, you will also need to have a Java Virtual Machine for an
application server.
♦
•
SAS BI Web Services for .NET and SAS BI Web Services for Java also differ in the way they handle logging and
configuration. SAS BI Web Services for .NET use .NET logging, and SAS BI Web Services for Java use SAS
Foundation Services for logging.
Client Differences
Web service clients cannot generally identify differences between SAS BI Web Services for .NET and SAS BI Web
Services for Java. As long as the client adheres to the usage rules for Web services, the client should be able to use
either platform.
One difference for the Web service client is how you get the WSDL. If you use SAS BI Web Services for .NET, you
get the WSDL by using a URL that ends with sasxmla.asmx?WSDL. If you use SAS BI Web Services for Java,
you get the WSDL by using a URL that ends with xmla.wsdl. In both cases, the actual endpoint is specified in the
WSDL file.
Another difference for the Web service client is how the path is returned for the name of the stored process
(DataSourceName). SAS BI Web Services for Java return a BIP URL. SAS BI Web Services for .NET return a simple
path. In both cases, you get the name of the stored process to invoke by using the Discover method of the same Web
service.
SAS BI Web Services
Deciding Between .NET and Java 103
Writing SAS Programs for Web Services
To use the Web service to call your SAS code, you must configure your SAS code as a stored process. The stored
process used with Web Services needs to conform to a few rules which enable the Web service to both receive data
from the client and return data to the client.
You can author a stored process manually by using SAS or a text editor to write the code and then registering the
program through SAS Management Console. Alternatively, you can use a program such as Enterprise Guide or
another SAS code generator to author a stored process using the "point−and−click" method. Use the modifications
below to make a stored process that can be used with SAS BI Web Services. Keep in mind that SAS BI Web Services
can only return data; no images can be returned.
SAS programs are stored in external files that usually have a .SAS filename extension in directory−based operating
environments. For z/OS, the files must be contained in a partitioned data set (PDS). SAS programs can contain a
DATA step, procedures, and macro code.
The following list explains unique details about Web service stored processes:
The data returned by the stored process must be XML.• The %STPBEGIN or %STPEND macros are not used with Web service stored processes. These macros set up
ODS statements for the stored process, but Web services do not use ODS.
•
Web service stored processes produce streaming results, which means that the SAS program writes output to
_WEBOUT, typically by using the following LIBNAME statement:
libname _WEBOUT xml xmlmeta=&_XMLSCHEMA;
•
The _XMLSCHEMA macro is unique to Web services. This macro is passed to the SAS program when it is
invoked from the Web service. The _XMLSCHEMA macro is set to one of three values depending on the
Content property that gets passed to the Execute call. The possible values for _XMLSCHEMA are Schema,
SchemaData (which is the default), or Data. For example,
libname _WEBOUT xml xmlmeta=SchemaData;
causes SAS to write both the XML schema and the data into the libref _WEBOUT. A libref uses a fileref of
the same name when a source is not specified on the LIBNAME statement. For example,
libname _WEBOUT xml xmlmeta=_XMLSCHEMA;
causes the libname, called _WEBOUT, to read from the fileref called _WEBOUT. For Web services, SAS
defines the filerefs for _WEBOUT and the input parameter streams before invoking the SAS code.
Note: Applications should not try to write multiple data sets into a library when a schema is being created.
•
Input streams are unique to Web services. Input streams are filerefs that contain XML.•
The following example code displays a stored process used as a Web service.
libname instream xml;
libname _WEBOUT xml xmlmeta=&_XMLSCHEMA;
proc means data=instream.&tablename;
output out=_WEBOUT.mean;
run;
Writing SAS Programs for Web Services 104
The first LIBNAME statement in the sample code defines the input stream. This code corresponds to the definition of
the input stream in the Streaming Details dialog box in BI Manager. The name of the input stream is instream. In
this example, the input stream provides the data to run PROC MEANS against.
The second LIBNAME statement in the sample code defines the output for the stored process as streaming output, or
_WEBOUT. In BI Manager, Streaming is specified as the type of output on the Execution tab of the Stored Process
Properties dialog box.
The &tablename in the sample code defines a parameter called tablename. In BI Manager, this parameter is
specified through the Add Parameter dialog box, and can be modified using the Modify Parameter dialog box. In this
example, tablename is a string parameter that specifies the name of the table to run PROC MEANS against.
Note: The dialog boxes mentioned in the previous example are available from both the Stored Process Properties
dialog box and the New Stored Process Wizard, which are both part of BI Manager. For more information about using
BI Manager to define metadata for stored processes, see the product Help.
SAS BI Web Services
SAS® Integration Technologies: Developer's Guide
Writing SAS Programs for Web Services 105
Discover Method
The Discover method retrieves information, such as stored process metadata or a list of available data sources, from
the SAS Metadata Repository. The Discover method returns a list of all the stored processes that have the keyword
"XMLA Web Service" on the SAS Metadata Server. The SAS Stored Process Server is not invoked to service the
Discover call.
The syntax for the Discover method follows:
Discover (
[in] RequestType As EnumString,
[in] Restrictions As Restrictions,
[in] Properties As Properties,
[out] Result As Rowset)
RequestType
RequestType is a required parameter for the Discover method. The value of RequestType is an enumeration value that
corresponds to a return rowset. The RequestType parameter specifies the type of information to be returned by the
Discover request.
There are two main request types that are normally used with SAS BI Web Services: DISCOVER_DATASOURCES
and STOREDPROCESS_PARAMETERS. DISCOVER_DATASOURCES and
STOREDPROCESS_PARAMETERS both return a list of the stored processes that can be invoked.
DISCOVER_DATASOURCES is a standard XMLA request type that returns a list of available data sources for the
server or Web service so that you can select a data source with which to connect. The information returned by the
DISCOVER_DATASOURCES request type includes the name and a description of the data source, a URL to connect
to the data source, the name and data type of the provider, and the type of security mode that the data source uses, as
well as any additional information that is needed to connect to the data source. STOREDPROCESS_PARAMETERS
is a request type specific to SAS, and this request type returns a list of all the available stored processes along with a
list of the parameters that are specified in each stored process.
Other request types that might be useful with SAS BI Web Services are DISCOVER_PROPERTIES and
DISCOVER_SCHEMA_ROWSETS. DISCOVER_SCHEMA_ROWSETS returns a list of all the available request
types along with their enumeration values and other information. See the Properties section for more information
about what the DISCOVER_PROPERTIES request type returns.
Note: Although the SAS XMLA Stored Process provider supports the DISCOVER_KEYWORDS,
DISCOVER_LITERALS, and DISCOVER_ENUMERATORS request types, these request types are not useful for
calling stored processes.
See the XML for Analysis Specification for more information about standard XML for Analysis request types.
DISCOVER_DATASOURCES
The SAS BI Web Service returns one data source for each stored process that has been defined in the metadata for use
with Web services.
For each returned stored process, the returned rowset contains:
Discover Method 106
DataSourceName
specifies the name of the stored process, as specified in BI Manager. For example,
/Samples/Stored Processes/
Sample: MEANS Procedure Web Service
DataSourceDescription
specifies the description of the stored process, as specified in BI Manager. For example,
(PROC MEANS Stored Process that can be invoked by
the SAS BI Web Services for Java/.Net mid−tier.)
URL
specifies the URL to invoke the XMLA methods. This is usually the same as the URL that is used to invoke
this Discover method. For example,
http://yourserver/xmla/SASSPSProvider/sasxmla.asmx
DataSourceInfo
specifies which data source to use. The SAS Stored Process Server data source is "Provider=SASSPS;".
ProviderName
specifies the provider behind the data source. For the SAS Stored Process Server, this is the "SAS XML for
Analysis Stored Process Provider".
ProviderType
specifies the type of provider that is behind the data source. The Stored Process Service only supports "TDP"
(Tabular Data Provider).
AuthenticationMode
specifies the authentication required for the given data source (that is, indicates whether a user name and
password are required). SAS BI Web Services for .NET only return "Authenticated" if a user name and
password are required. SAS BI Web Services for Java always return "Authenticated," meaning that you are
required to authenticate to the SAS Metadata Repository whether you pass in credentials or only use default
credentials that are configured by the administrator.
STOREDPROCESS_PARAMETERS
STOREDPROCESS_PARAMETERS is a custom request type that is only used by the SAS Stored Process Service
provider. It returns metadata describing the parameters that are necessary to call the stored process. A stream
parameter is always a required parameter and it never has a default. This does not mean that you are required to have a
stream parameter for each stored process, but it means that any stream parameters defined for the stored process must
be provided when the stored process is called using the Execute method.
For each returned stored process, the returned rowset contains:
StoredProcessName
specifies the name of the stored process.
Parameters
specifies a container that includes all of the parameters for the stored process.
Parameter
specifies a container that includes all of the details for a stored process parameter.
Name
specifies the name of the stored process parameter.
Description
specifies the description of the stored process parameter.
Type
SAS® Integration Technologies: Developer's Guide
Discover Method 107
specifies the parameter type. The possible parameter types are specified in BI Manager. Note that all
parameters are passed to SAS as macro variables, so the SAS program does not know the parameter type
specified in the metadata.
Required
specifies whether the stored process parameter is required.
Default
specifies a default value for the stored process parameter.
Streams
specifies a container that includes all of the input streams for the stored process.
Stream
specifies a container that includes all of the details for a stored process input stream.
The following is an example of the response for a stored process that takes a single string and a single stream as input:
<row xmlns="urn:schemas−sas−com:xml−analysis:rowset">
<StoredProcessName>
/BIP Tree/copyintoout</StoredProcessName>
<Parameters>
<Parameter>
<Name>inputname</Name>
<Description>A simple string that we are
passing as a parameter.</Description>
<Required>true</Required>
<Default />
<Type>String</Type>
</Parameter>
</Parameters>
<Streams>
<Stream>
<Name>DataName</Name>
<Description>This stream does allow
multi−pass reads, so you do not have to
use an XMLMap.</Description>
</Stream>
</Streams>
</row>
Restrictions
You can use the Restrictions parameter to filter which results get returned from a call to the Discover method. The
restriction name specifies a column in a rowset that you desire to restrict. The restriction value specifies which data to
restrict in the column. Use the DISCOVER_SCHEMA_ROWSETS request type to get restriction information about
the rowsets that are available in each request type. The DISCOVER_SCHEMA_ROWSETS request type returns a list
of all the request types supported by the provider, along with restriction information and descriptions for each request
type.
The Restrictions parameter is required in the Discover method, but it can be empty. Invalid values for restrictions are
ignored.
The following RestrictionList element restricts a call to Discover STOREDPROCESS_PARAMETERS based on the
name of the stored process:
<RestrictionList
xmlns="urn:schemas−microsoft−com:xml−analysis">
SAS® Integration Technologies: Developer's Guide
Discover Method 108
<StoredProcessName>
/Samples/Stored Processes/
Sample: MEANS Procedure Web Service
</StoredProcessName>
</RestrictionList>
See the rowset tables in "XML for Analysis Rowsets” in the XML for Analysis Specification for more information
about restricting columns.
Properties
The Properties parameter enables you to specify properties of the Discover method, such as the return format of the
result set or the timeout value.
Use the DISCOVER_PROPERTIES request type to get information about properties that are available for each
request type and the values that are associated with those properties. The DISCOVER_PROPERTIES request type
returns information about both standard and provider−specific properties. The returned information includes the name,
description, data type, access, and current value of each property. The information also shows whether each property
is required.
The following table contains a list of properties and property information, including sample values, that the
DISCOVER_PROPERTIES request type returns. The value of PropertyType for each of these properties is string.
PropertyName PropertyDescription PropertyAccessType Value
Content specifies the content of the XML result:
None, Schema, Data, or Both. ReadWrite SchemaData
StateSupport specifies the support for state maintenance
offered by the provider: None or Sessions. Read Sessions
UserName specifies the user name to use for database
authentication. ReadWrite
Password specifies the password to use for database
authentication. Write
Domain specifies the domain to use for database
authentication. ReadWrite
ProviderName specifies the name of the XML for Analysis
provider. Read SAS XML for Analysis
StoredProcess Provider
ProviderVersion specifies the version of the XML for
Analysis provider. Read 1.0
Format specifies the format of the XML result:
Tabular or Multidimensional. Read Tabular
DataSourceInfo specifies the identifying information that is
required to retrieve data from a data source. ReadWrite Provider=SASSPS
Timeout specifies the number of seconds until a
request fails due to a timeout. Read
SAS® Integration Technologies: Developer's Guide
Discover Method 109
See "XML for Analysis Properties" in the XML for Analysis Specification for more information about standard XML
for Analysis properties.
You can list properties in any order. The Properties parameter is required in the Discover method. The only call to the
Discover method that can have empty properties is DISCOVER_DATASOURCES. All other request types require at
least DataSourceInfo to be specified, such as:
<PropertyList
xmlns="urn:schemas−microsoft−com:xml−analysis">
<DataSourceInfo>
Provider=SASSPS
</DataSourceInfo>
</PropertyList>
To cause a call to Discover to execute under a specific user's identity, a UserName and Password property can be
included in the PropertyList element, such as:
<PropertyList xmlns="urn:schemas−microsoft−com:xml−analysis">
<DataSourceInfo>
Provider=SASSPS
</DataSourceInfo>
<UserName>username</UserName>
<Password>password</Password>
</PropertyList>
If you choose to include the UserName or Password properties, it is important to ensure that access to your Web
service is secure and encrypted. For more information, see Securing SAS BI Web Services.
Result
The Result parameter is required. This parameter specifies the result set that the provider returns. The information that
is returned can vary according to which values are used in the RequestType, Restrictions, and Properties parameters.
SAS BI Web Services
SAS® Integration Technologies: Developer's Guide
Discover Method 110
Execute Method
Client applications of the Web service call the Execute method to run a SAS Stored Process.
When an application calls the Execute method, the following actions occur. The Web service does the following:
receives the call and validates the SOAP request against the WSDL.• validates the Command against the Command schema.• searches in the SAS Metadata Server to find the SAS server to connect to that can service the request. If the
user name and password are provided in the Properties parameter, then they are used to connect to the SAS
Metadata Server. The credentials to use when connecting to the SAS Stored Process Server are obtained from
the metadata.
•
invokes the SAS code that represents the stored process on the SAS Stored Process Server.• checks the value of the SYSCC macro in SAS. If SYSCC is non−zero, then the Web service throws a SOAP
fault and includes the value of SYSMSG in the fault.
•
returns all data that was written to _WEBOUT.•
Syntax
The syntax for the Execute method follows:
Execute (
[in] Command As Command,
[in] Properties As Properties,
[out] Result As Resultset)
Command
The Execute method takes the Command and Properties parameters as input. Both of these parameters are in XML.
The following code shows the command passed to the Execute method:
<StoredProcess name="MyStoredProcess">
<Stream name="DataName"> <myXML>data</myXML> </Stream>
<Parameter name="InputName">myData</Parameter>
</StoredProcess>
When the previous code is passed to Execute(), the SAS code will have a macro defined whose name corresponds to
the String parameter:
%LET InputName=ThisIsTheValue
The SAS code will also have a libref assigned that corresponds to the name of the Data parameter:
libname DataName;
The SAS program should write output to the pre−assigned fileref _WEBOUT. Most applications will do this by using
the XML LIBNAME engine, as follows:
libname _WEBOUT xml xmlmeta=&_XMLSCHEMA;
Execute Method 111
data _WEBOUT.a;
Properties
The Properties parameter enables you to specify properties of the Execute method. Properties describe how to invoke
the Command parameter. Calling applications specify the SASSPS (Stored Process Service) Provider to be used in
DataSourceInfo, as shown in the following example:
<PropertyList>
<DataSourceInfo>
Provider=SASSPS;
</DataSourceInfo>
</PropertyList>
Use the DISCOVER_PROPERTIES request type in the Discover method to get information about properties that are
available for each request type and the values that are associated with those properties. The
DISCOVER_PROPERTIES request type returns information about both standard and provider−specific properties.
The returned information includes the name, description, data type, access, and current value of each property. The
information also shows whether each property is required.
See "XML for Analysis Properties" in the XML for Analysis Specification for more information about standard XML
for Analysis properties.
You can list properties in any order. The Properties parameter is required in the Discover method, but it can be empty.
The Properties parameter must be specified for the Execute method, and must include at least the DataSourceInfo
property.
Note: After you have selected a data source from the DISCOVER_DATASOURCES rowset, set the DataSourceInfo
property in the Properties parameter, which is sent to the server using the Command parameter by the Execute
method. Do not attempt to write in your own value for the DataSourceInfo property, only use a value from the
DISCOVER_DATASOURCES rowset.
To cause a call to Execute to run under a specific user's identity, a UserName and Password property can be included
in the PropertyList element, such as:
<PropertyList xmlns="urn:schemas−microsoft−com:xml−analysis">
<DataSourceInfo>
Provider=SASSPS
</DataSourceInfo>
<UserName>username</UserName>
<Password>password</Password>
</PropertyList>
If you choose to include the UserName or Password properties, it is important to ensure that access to your Web
service is secure and encrypted. For more information, see Securing SAS BI Web Services.
Result
The Result parameter is required. This parameter specifies the result set that the provider returns. The information that
is returned can vary according to which values are used in the Command and Properties parameters.
SAS BI Web Services
SAS® Integration Technologies: Developer's Guide
Execute Method 112
Securing SAS BI Web Services
A default installation of SAS BI Web Services for Java or .NET is not highly secure. All requests and responses are
sent as cleartext, and if a user wants to authenticate as a specific user, then they must send a user name and password
as cleartext as part of the Properties element. Whenever user names and passwords must be sent as cleartext, SSL
should be enabled to provide transport layer security. See the following links for more information about enabling
SSL:
The Tomcat 4 Servlet−JSP Container: SSL Configuration HOW−TO• Managing WebLogic Security: Configuring SSL• How To Enable SSL for All Customers Who Interact with Your Web Site in Internet Information Services•
With SAS 9.1.3 Service Pack 4, SAS BI Web Services for Java can be secured using trusted Web server
authentication. This provides a way for SAS BI Web Services for Java to identify the calling user using basic Web
server authentication. See Securing SAS BI Web Services for Java for more information.
SAS BI Web Services for .NET can be secured using Web Services Enhancements 2.0 for Microsoft .NET, which
enables support for the latest security and interoperability standards for Web services. For detailed information about
using Web Services Enhancements 2.0, WS−Security, and WS−Policy to secure SAS BI Web Services, see Securing
SAS BI Web Services for .NET with WSE 2.
The current release of SAS BI Web Services for Java does not support WS−Security or WS−Policy.
SAS BI Web Services
Securing SAS BI Web Services 113
Securing SAS BI Web Services for .NET with WSE 2.0
Web Services Enhancements for Microsoft .NET (WSE) is a tool that provides developers with advanced Web
services capabilities, and enables developers to secure SAS BI Web Services for .NET. WSE is a supported add−on to
Microsoft Visual Studio .NET and the Microsoft .NET Framework. You can use WSE to secure SAS BI Web Services
for .NET by performing the following tasks:
modifying the Web.config file to enable WSE• adding a new policy file that indicates the security policy required by SAS BI Web Services• modifying client applications to use WSE, and to also use a security policy that matches the Web service•
You can use the tools that are provided with WSE to configure SAS BI Web Services to authenticate users by using a
Kerberos security context token, and to encrypt all transmissions using Kerberos encryption.
Configuration Steps
Install WSE 2.01. Launch WSE 2.0 Configuration Utility2. Configure SAS BI Web Services for .NET to use WSE 2.03. Configure Policy for SAS BI Web Services for .NET4. Configure Microsoft .NET Client to use WSE 2.05. Configure Policy for Microsoft .NET Client6. Update Client Code7. Test the New Security Policy8.
Install WSE 2.0
You can download Web Service Enhancements 2.0 from the Web Services and Other Distributed
Technologies Developer Center on the Microsoft Web site. This documentation was written using WSE 2.0
Service Pack 3. It is recommended that you get the latest version of WSE 2.0 in order to ensure that you have
all the latest features and bug fixes.
1.
Launch WSE Settings 2.0 Tool
The WSE Settings 2.0 tool can modify an application configuration file to enable WSE 2.0, as well as
configure the options that are available with WSE 2.0. To use the WSE Settings 2.0 tool from the Start menu,
select Start All Programs Microsoft WSE 2.0 Configuration Editor.
2.
Configure SAS BI Web Services for .NET to use WSE 2.0
Select File Open, and then open the Web.config file for the installation of SAS BI Web Services for .NET
that you are modifying. By default, the Web.config file is located here:
C:\Inetpub\wwwroot\SASWS\Web.config
On the General tab, select Enable this project for Web Services Enhancements. Also, select Enable
Microsoft Web Services Enhancement Soap Extensions.
3.
Securing SAS BI Web Services for .NET with WSE 2.0 114
Configure Policy for SAS BI Web Services for .NET
On the Policy tab, select Enable Policy and use the default file name policyCache.config. Under Edit
Application Policy, click Add. In the Add or Rename Endpoint URI dialog box, accept the default of
<DefaultEndpoint>. This causes the policy to apply to any endpoint and operation that is defined for
SAS BI Web Services for .NET. Click OK to launch the WSE Security Setting Tool.
Click Next to proceed to the Choose the Type of Application page. Select Secure a service application. You
can leave Use Secure Conversation unselected. If you want to use secure conversation, then you will need to
supply an X.509 certificate. Click Next to continue.
4.
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 115
On the Message Settings page, accept the default settings to sign the request and encrypt the response. This
simplifies the configuration so that no X.509 certificates are required. If you prefer to encrypt the request or
sign the response, then you will need to supply an X.509 certificate. Click Next to continue.
On the Client Authentication Token page, select Kerberos. A Kerberos token is an authentication token that
is used by Windows to authenticate clients with remote servers. To use the Kerberos token option, both the
client and server must be in a Windows Server 2000 or later Active Directory domain.
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 116
If the client and server machines are not in the same domain, then you can select the Username token type in
order to create a token in the client code. This configuration is not covered here, but you can find more
information on the Username token in the Web Services Enhancements 2.0 documentation.
Click Next to continue to the Kerberos Token Claims page. Specify the name of the machine that the service
is on, and add users or roles that are allowed access to the Web service.
Click Next to view the confirmation page, and click Finish to save the changes to the policy.
While you are testing various security settings, it is helpful to look at the input and output trace files that can
be enabled on the Diagnostics tab of the configuration utility.
When you are finished making changes to the configuration file, select File Save to save the changes to the
Web.config file and to create a new policyCache.config file.
Configure Microsoft .NET Client to use WSE 2.0
If you are using Visual Studio .NET, then you can launch the WSE Settings 2.0 tool from Visual Studio .NET.
In Solution Explorer, right−click on the client project and select WSE Settings 2.0 to launch the WSE
Settings 2.0 tool.
5.
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 117
Alternatively, you can use the WSE Settings 2.0 tool that was launched previously to open the configuration
file (Web.config, App.config, or AppName.exe.config) for the application that calls SAS BI Web Services for
.NET. If the application doesn't have a configuration file, then you will need to create one. For more
information about configuration files, see Application Configuration Files in the MSDN Library.
On the General tab, select Enable this project for Web Services Enhancements. If this is an ASP.NET
application and the Web service should also use WSE 2.0, then you can also select Enable Microsoft Web
Services Enhancement Soap Extensions.
On the TokenIssuing tab, make sure that Auto Issue Security Context Token is selected. This will
automatically issue a SecurityContextToken for the currently logged−on user to use when authenticating with
SAS BI Web Services for .NET.
Configure Policy for Microsoft .NET Client
The configuration of the policy on the client is nearly identical to the configuration of the server policy. The
only differences are as follows:
When prompted to secure a service application or a client application, select Secure a client
application.
♦
The path to the policyCache.config file might be slightly different. Visual Studio .NET will set an
appropriate path for the policyCache.config file automatically. If you aren't using Visual Studio .NET,
then be sure to specify a path that is relative to the location of the executable file.
♦
If you are accessing Web services from the client application other than SAS BI Web Services for
.NET, then you will need to provide a specific endpoint URI when you configure the policy instead of
using the default value of <DefaultEndpoint>.
♦
6.
Update Client Code7.
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 118
Visual Studio .NET Project
After WSE is enabled in a Visual Studio .NET project, you should right−click the Web Reference for SAS BI
Web Services for .NET and select Update Web Reference to force the proxy class to be re−generated with
the new WSE features. Rebuild the project for the changes to take effect.
You will see a new class available in the proxy namespace called SASAnalysisWse. This is the class that
you should use to call SAS BI Web Services for .NET. Replace all instances of SASAnalysis with
SASAnalysisWse in order to start using WSE in the client project.
Microsoft .NET Framework Project
If you don't have Visual Studio .NET, you will need to generate a new Web service proxy class using the
WseWsdl2.exe tool. By default, this tool is located in the WSE 2.0 installation folder in the Tools\Wsdl
folder. The command will be similar to the following:
"C:\Program Files\Microsoft WSE\v2.0\
Tools\Wsdl\WseWsdl2.exe"
http://localhost/SASWS/sasxmla.asmx?
WSDL localhost.cs
You will need to modify the code to use the new generated proxy, because the proxy class that is generated by
WseWsdl2.exe is different from the proxy class that is generated by the standard wsdl.exe tool that ships with
the Microsoft .NET Framework.
Test the New Security Policy
At this point, the installation of SAS BI Web Services should be secured by Kerberos authentication and
encryption, and only users who are specified in the policy configuration should be able to access the Web
service. Verify the security policy as follows:
Enable input and output message tracing on the Diagnostics tab in the WSE Settings 2.0 tool.1. Execute the client.2. View the log files to confirm that the request was signed and the response was encrypted.3.
8.
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 119
SAS BI Web Services
SAS® Integration Technologies: Developer's Guide
Securing SAS BI Web Services for .NET with WSE 2.0 120
Securing SAS BI Web Services for Java
In order for SAS BI Web Services for Java to look up stored processes in the SAS Metadata Server, it must first
authenticate to a metadata server. A Web service can pass a set of credentials to the SAS Metadata Server to use for
authentication. This is defined as SAS Metadata Server host authentication because the host running the SAS
Metadata Server will perform the authentication. Otherwise, a Web service can enable a Web container to perform the
authentication against an incoming client's credentials via basic authentication semantics, and then connect to the SAS
Metadata Server in a trusted configuration. This is defined as trusted authentication because the Web container
performs the authentication against an incoming client's credentials and the middle tier connects to the SAS Metadata
Server using a set of trusted credentials. The Web container then performs trusted authentication on behalf of the
authenticated Web user.
For host authentication (auth_mechanism=host), the client's credentials must be specified in the SOAP message
body as UserName, Password, and Domain properties. Alternatively, you can specify default or guest credentials
as the following configuration properties: default_user, default_password, and default_domain.
These credentials are used to authenticate to a SAS Metadata Server to determine what stored processes a user can run
as well as how and where they are executed.
For trusted authentication (auth_mechanism=trusted), a Web container will perform basic authentication. You
will need to add privileged users to the webuserRole role (or to the webuserGroup group, if you are using BEA
WebLogic). After the Web tier has successfully authenticated an incoming client, the client's principal name is then
used to connect to the SAS Metadata Server in a trusted configuration. For trusted authentication to succeed, a SAS
Metadata Server user login must exist for this client with the appropriate user ID and trusted authentication domain
(trusted_domain). See Changing to Trusted Web Authentication in the SAS Intelligence Platform: Web
Application Administration Guide for additional instructions on setting up a trusted configuration.
SAS BI Web Services
Securing SAS BI Web Services for Java 121
Sample PROC MEANS Using SAS BI Web Services
The following sample shows how to write, define, and invoke a sample stored process that can be used with SAS BI
Web Services.
Write the Stored Process
The following SAS code is a sample stored process called stpwsmea.sas. This program is installed with SAS
Integration Technologies; by default it is located in C:\Program Files\SAS\SAS 9.1\inttech\sample.
%put &tablename;
libname _WEBOUT xml xmlmeta = &_XMLSCHEMA;
libname instream xml;
proc means data=instream.&tablename;
output out=_WEBOUT.mean;
run;
libname _WEBOUT clear;
libname instream clear;
Define the Metadata
The stored process must be defined in a SAS Metadata Repository that is used by SAS BI Web Services to determine
how and where to run the stored process. Stored process metadata is defined using BI Manager. The tables in this
section show the values for each field in BI Manager.
Note: If you have previously installed the SAS Stored Process sample metadata as part of the SAS Configuration
Wizard or the Web Infrastructure Kit installation, you might not need to re−create the metadata for the "Sample:
MEANS Procedure Web Service" sample stored process. The sample metadata should already be available from the
Samples\Stored Processes folder in BI Manager. If you do not have the sample metadata, you can define the
metadata for the stored process on your SAS Metadata Server using the following steps.
Open SAS Management Console and connect to the appropriate metadata repository.1. From the SAS Management Console navigation tree, select the folder under BI Manager in which you would
like to create the new stored process. (If you would like to first create a new folder, you can select the location
in the navigation tree in which you want to add the new folder, and then select Actions New Folder from
the menu bar to open the New Folder Wizard. Follow the wizard instructions to create the new folder.)
2.
After you select the folder in which you want to add a new stored process, select Actions New Stored
Process from the menu bar. The New Stored Process Wizard displays.
3.
In the Name window of the New Stored Process Wizard, enter the following values in their corresponding
fields for the sample Web service:
Field Value
Name Sample: MEANS Procedure Web Service
Keywords XMLA Web Service
4.
Sample PROC MEANS Using SAS BI Web Services 122
Note: To add the keyword, click Add to open the Add Keyword dialog box, then enter the name of the
keyword. Click OK to return to the Name window.
Using the Name window to add a description for the stored process is optional.
Click Next to go to the Execution window.5. In the Execution window of the New Stored Process Wizard, enter the following values in their corresponding
fields for the sample Web service:
Field Value
SAS server Main − Logical Stored Process Server
Source code repository C:\Program Files\SAS\SAS 9.1\inttech\sample
Source code file stpwsmea.sas
Output Streaming
6.
In the Execution window of the New Stored Process Wizard, click Streams to open the Input Stream Details
window. Then click Add to open the Add Input Stream dialog box, where you must define the input stream.
In this example, the input stream is named instream. Click OK to save the input stream definition.
Note: You must also select the Supports multi−pass reads check box in the Add Input Stream dialog box.
Otherwise, an XMLMap would need to be specified on the XML LIBNAME statement to define the XML
schema for instream.
7.
Click OK in the Streaming Details window to return to the Execution window; then click Next to open the
Parameters window.
8.
In the Parameters window of the New Stored Process Wizard, click Add to open the Add Parameter window.
In the Add Parameter window, enter the following values in their corresponding fields for the sample Web
service:
Field Value
Label tablename
SAS variable name tablename
Boolean properties Modifiable, Visible, and Required (are selected)
Type String
Default value InData
9.
Click OK to return to the Parameters window.10. Review your stored process information and click Finish to define the metadata for the stored process.11.
Invoke the Stored Process
SOAP Request
The stored process we just created can be invoked by SAS BI Web Services for Java and .NET middle−tier clients. A
Web service client invokes the middle−tier Web service with an Execute() command. The SOAP request body, or
client code, follows:
<soap−env:Body>
<Execute>
<Command>
SAS® Integration Technologies: Developer's Guide
Sample PROC MEANS Using SAS BI Web Services 123
<StoredProcess
name="/Samples/Stored Processes/Sample:
MEANS Procedure Web Service">
<Parameter name="tablename">InData</Parameter>
<Stream name="instream">
<Table>
<InData>
<Column1>1</Column1>
<Column2>20</Column2>
<Column3>99</Column3>
</InData>
<InData>
<Column1>50</Column1>
<Column2>200</Column2>
<Column3>9999</Column3>
</InData>
<InData>
<Column1>100</Column1>
<Column2>2000</Column2>
<Column3>1000000</Column3>
</InData>
</Table>
</Stream>
</StoredProcess>
</Command>
<Properties>
<PropertyList>
<DataSourceInfo>Provider=SASSPS;</DataSourceInfo>
</PropertyList>
</Properties>
</Execute>
</soap−env:Body>
SOAP Response
After you run the client code, the resulting SOAP response body is as follows:
<soap−env:Body>
<ExecuteResponse>
<return>
<root>
<TABLE>
<MEAN>
<_TYPE_> 0 </_TYPE_>
<_FREQ_> 3 </_FREQ_>
<_STAT_> N </_STAT_>
<COLUMN3> 3 </COLUMN3>
<COLUMN2> 3 </COLUMN2>
<COLUMN1> 3 </COLUMN1>
</MEAN>
<MEAN>
<_TYPE_> 0 </_TYPE_>
<_FREQ_> 3 </_FREQ_>
<_STAT_> MIN </_STAT_>
<COLUMN3> 99 </COLUMN3>
<COLUMN2> 20 </COLUMN2>
<COLUMN1> 1 </COLUMN1>
</MEAN>
<MEAN>
<_TYPE_> 0 </_TYPE_>
SAS® Integration Technologies: Developer's Guide
Sample PROC MEANS Using SAS BI Web Services 124
<_FREQ_> 3 </_FREQ_>
<_STAT_> MAX </_STAT_>
<COLUMN3> 1000000 </COLUMN3>
<COLUMN2> 2000 </COLUMN2>
<COLUMN1> 100 </COLUMN1>
</MEAN>
<MEAN>
<_TYPE_> 0 </_TYPE_>
<_FREQ_> 3 </_FREQ_>
<_STAT_> MEAN </_STAT_>
<COLUMN3> 336699.333 </COLUMN3>
<COLUMN2> 740 </COLUMN2>
<COLUMN1> 50.3333333 </COLUMN1>
</MEAN>
<MEAN>
<_TYPE_> 0 </_TYPE_>
<_FREQ_> 3 </_FREQ_>
<_STAT_> STD </_STAT_>
<COLUMN3> 574456.555 </COLUMN3>
<COLUMN2> 1094.89726 </COLUMN2>
<COLUMN1> 49.5008417 </COLUMN1>
</MEAN>
</TABLE>
</root>
</return>
</ExecuteResponse>
</soap−env>
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Sample PROC MEANS Using SAS BI Web Services 125
Publishing Framework
The Publishing Framework feature of SAS Integration Technologies provides a complete and robust publishing
environment for enterprise−wide information delivery. The Publishing Framework consists of SAS CALL routines,
application programming interfaces (APIs), and graphical user interfaces that enable both users and applications to
publish SAS files (including data sets, catalogs, and database views), other digital content, and system−generated
events to a variety of destinations including the following:
E−mail addresses• message queues• publication channels and subscribers• WebDAV−compliant servers• archive locations.•
The Publishing Framework also provides tools that enable both users and applications to receive and process
published information. For example, users can receive packages with content, such as charts and graphs, that is ready
for viewing; and SAS programs can receive packages with SAS data sets that might in turn trigger additional analyses
on that data.
The functions of the Publishing Framework include channel definition, subscription management, package publishing,
package retrieval, package viewing, and event publishing.
Channel Definition and Subscription Management
The Publishing Framework enables you to define SAS publication channels, which are conduits for publishing
particular categories of information. You can set up a channel for a particular topic, organizational group, user
audience, or any other category. Once publication channels have been defined, authorized users can subscribe to them
and automatically receive information whenever it is published to those channels.
If your organization has installed the SAS Information Delivery Portal, users can manage their subscriptions from
within the portal. The portal enables users to select channels to subscribe to, specify the desired delivery transport
(such as an e−mail address or message queue), and specify filters that indicate which information is to be included or
excluded.
For more information about defining channels and managing subscriptions, refer to Administering the Publishing
Framework in the SAS Integration Technologies: Administrator's Guide. If you are using an LDAP directory server as
your metadata repository, refer to Administering the Publishing Framework in the SAS Integration Technologies:
Administrator's Guide (LDAP Version).
Package Publishing
The Publishing Framework enables you to create packages containing one or more information entities, including
SAS data sets, SAS catalogs, SAS databases, and almost any other type of digital content. You can also define viewers
that will make the information entities easier to display.
After creating a package, you can publish the package and its associated viewers to one or more channels. This causes
the information to be delivered to each user who has subscribed to those channels, if the package and its contents meet
the subscriber's filtering criteria. In addition to channels, you can publish packages directly to one or more E−mail
addresses, message queues, WebDAV−compliant servers, and archive locations.
Publishing Framework 126
To create and publish packages, you can use any of the following methods:
use the SAS Publisher user interface, which is provided as part of Base SAS• use the publish CALL routines to create packages and publish them from within a SAS program• use the APIs that are provided with Integration Technologies to create packages and publish them from within
a third−party application.
•
You can also use SAS Enterprise Guide or the SAS Information Delivery Portal to create and publish packages via the
Publishing Framework.
Package Retrieval and Viewing
The Publishing Framework provides the SAS Package Retriever, which is a graphical user interface to enable users to
extract and save information from packages that have been published through the Publishing Framework. The SAS
Package Reader user interface enables users to display the contents of packages. If the SAS Information Delivery
Portal has been installed, users can view published information from the portal.
In addition, you can use CALL routines to extract and process published information from within SAS programs; and
APIs are provided to enable third− party programs to extract and process published information.
Event Publishing
SAS Integration Technologies 9 includes the Publish Event Interface. This interface consists of CALL routines that
enable you to write SAS programs, including stored processes, that create and publish events. Events can be generated
and published explicitly, or they can be generated implicitly as part of the publication of a package. Implicit event
generation occurs when packages are published to a channel that has event subscribers defined.
Events are published as well−formed XML documents. They can be published to HTTP servers, message queues, or
to publication channels and their associated subscribers. You can develop custom applications that receive and process
events generated by the Publishing Framework.
Publishing Framework Documentation
For information about how to perform publishing tasks, or how to incorporate publishing tasks into your SAS
programs or applications, refer to the topics in the table of contents at left.
For information about how to administer publication channels and subscriber information, refer to Administering the
Publishing Framework in the SAS Integration Technologies: Administrator's Guide. If you are using an LDAP
directory server as your metadata repository, refer to Administering the Publishing Framework in the SAS Integration
Technologies: Administrator's Guide (LDAP Version).
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Publishing Framework 127
About Packages: Package Content
Package: Definition
A package is a container for knowledge, or digital content, that is generated or collected for delivery to a consumer.
Knowledge takes the form of package entries, which can be either of two types:
SAS results• unstructured content.•
SAS Results
A category of package entry type is SAS results, which can take the form of any of the following:
SAS catalog• SAS data set• SAS database (such as FDB and MDDB)• SAS SQL view.•
Note: A package that contains only SAS results is referred to as a result set package.
Unstructured Content
Unstructured content is any package entry that is created external to SAS. Supported unstructured content types
include the following:
binary file (such as Excel, GIF, JPG, PDF, PowerPoint, and Word)• HTML file (including ODS output)• reference string (such as URL)• text file (such as a SAS program)• viewer file (such as an HTML or plain text template that formats SAS file items for viewing in e−mail).•
File Name Extensions for Package Entry Types
Each entry in a package is implicitly contained in a file whose file name extension reflects the entry type. Knowing
file name extensions might be useful when retrieving packages from the archive and WebDAV transports.
Default file name extensions follow:
.csv − Comma separated values
.ref − Reference
.sac − SAS Catalog
.sad − SAS Dataset
.sam − SAS MDDB
.sav − SAS SQL View
.spk − Nested archive
Publishing Framework
About Packages: Package Content 128
Package Rendering
When determining how to render packages, the publisher should consider the following:
the company's business requirements• the configuration of the business enterprise (for example, hardware, software, business processes, and
communications protocols)
•
the package content (structured and unstructured data)• the transport (such as archive, channel, e−mail, message queue, or Web) that is used to deliver the package.•
The following scenarios depict business factors that might affect how a package is rendered:
Consumer Need Publisher Solution
Access to packages, but
have limited system
storage resources
Render the package as an archive.
Access to package
without having SAS
software installed
Render the package as an archive and
attach the archive to e−mail for access
using SAS Package Reader.
Only executive−level
summaries (for example,
text reports, graphics, and
Web links)
Render the package as unstructured content
to known consumers via e−mail or to
unknown consumers via
subscription−based channels.
Access to SAS results, but
do not want to access the
package for continued
processing
Apply a template to the SAS data package
entry for viewing in e−mail and on the
Web.
Access to SAS results, but
do not have Web access
or do not use HTML
Apply a template in plain−text format to
the SAS results for viewing in e−mail.
Direct access to SAS
results for continued data
processing
Deliver SAS results package entries to
message queues or archives to enable
programmatic access to SAS data.
To span a broad
professional range
(executive, manager,
programmer, and
knowledge worker)
Apply name/value metadata to the package
and package entries to enable consumers to
filter packages or package entries for
relevancy.
Before the publisher can begin the publishing process, the administrator must first configure the publishing
environment, which might include archives, channels, subscribers, and subscriptions. For details, see Administering
the Publishing Framework in the SAS Integration Technologies: Administrator's Guide. If you are using an LDAP
Package Rendering 129
directory server as your metadata repository, see Administering the Publishing Framework in the SAS Integration
Technologies: Administrator's Guide (LDAP Version).
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Package Rendering 130
Package Transports
The destination (or transport) for delivering a package is defined in the Where to Publish tab of the SAS Publisher
GUI or programmatically in a SAS application using PACKAGE_PUBLISH CALL routines.
Transports are the following:
Archive
a single binary collection of all the items in a package. An archived package is also referred to as an SPK file,
which is short for SAS Package.
Channel
a conduit through which the defined transport (either e−mail or message queue) delivers package items to the
subscriber of the channel. The subscriber defines the preferred transport using personal subscription
properties.
E−mail
mechanism for delivering selected package items to identified recipients.
Message Queue
in application messaging, a place where the publisher can send a message (or a package) that can be retrieved
by another program for continued processing.
WebDAV−Compliant Server
an acronym for Web Distributed Authoring and Versioning. Whereas the traditional transports (archive,
channel, e−mail, and message queue) are repositories for published package data that can be retrieved and
reprocessed in a synchronous fashion, a WebDAV−compliant server facilitates concurrent access to and
update of package data on the Internet.
Publishing Framework
Package Transports 131
Archived Packages
An archive is a location to which an archived package is delivered or stored. An archival location can contain only
archived packages. An archive is a single binary collection of all of the items in a package. Archived packages are also
referred to as SPK files, which is short for SAS Package. The consumer can use the stand−alone product SAS Package
Reader subsequently to uncompress, or unzip, and use the file. SAS Package Retriever can be used to access the
package from the archive and to store the package elsewhere.
Archiving a Package
Publishing a package to an archive provides the following advantages:
You conserve disk resources.• The package stays in a static location, allowing consumers, persons or programs, to retrieve the package at
their convenience
•
The SAS data package entries are available to consumers who do not have SAS software installed on their
systems.
•
After the administrator has configured archive paths (and optionally configured channels that have default archive
paths), the publisher can publish packages directly to an archive. The publisher can use the following methods to
publish an archive:
using SAS Publisher GUI• publishing programmatically using SAS• using a third−party client application.•
Configuring Archives
The administrator configures archives under the following conditions:
to support package archiving, which is the process of collecting all package entries into a single binary file• to use as a repository for archived packages that contain data that consumers can access at their convenience.•
If the organization chooses to implement archiving in the publishing environment, the administrator must configure
the following objects:
Archival paths
enable publishers to select from a list of predefined paths to which they can publish a package as an archived
file to an archive. The administrator can define paths as directory locations or LDAP URLs. The administrator
must know about an LDAP server environment and LDAP metadata storage in order to specify archival paths.
Default archive path for each configured channel
can be associated with a channel to which subscribers can subscribe. Channels that are configured for access
to all subscribers are made available for subscription in SAS Subscription Manager, SAS Management
Console, and the SAS Information Delivery Portal. Likewise, restricted channels do not appear in the channels
list for subscribers who are not configured to access them. Consumers are notified of a package delivery to an
archive by way of subscription to a channel that has a default archive location that is associated with it.
For detailed instructions on setting up archives, see Administering the Publishing Framework in the SAS Integration
Technologies: Administrator's Guide. If you are using an LDAP directory server as your metadata repository, see
Archived Packages 132
Administering the Publishing Framework in the SAS Integration Technologies: Administrator's Guide (LDAP
Version).
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Archived Packages 133
Subscription Channels
A channel is a conduit for sending information from a publisher to all users subscribed to the channel. Whereas
publishing to e−mail is identity−centered (the publisher delivers packages to recipients whose identities are known),
publishing to channels is subject−centered, allowing both the publisher and the consumer to concentrate on the subject
of the package rather than on the recipients for the package.
Creating Channels
The administrator must create a channel for each distinct topic or audience. For example, users of a particular
application might want a channel for discussion and data exchange, while the programmers of that application might
want another channel to discuss technical problems and future enhancements. Although the topic is the same
application, the discussion about the topic will be different. Therefore, two separate channels would probably best
serve the needs of the two groups of users.
A channel can be created within a SAS Metadata Repository or an LDAP Repository. The administrator uses SAS
Management Console to create a channel object with the specified attributes in the SAS Metadata Repository. If
LDAP is used as the metadata repository, the administrator uses the Integration Technologies Administrator
application.
Creating Subscribers
The administrator must create a subscriber for each potential user of a channel. Subscribers must be defined before
subscriptions to channels can be created.
Creating Subscriptions
The association of a subscriber to a channel is a subscription. A subscription enables the information that is published
to a channel to be delivered to the interested (subscribed) subscribers.
Subscriptions can be created by either the administrator or the subscriber. The administrator can create subscriptions
when a publishing environment is initially configured. Individual subscribers can create personal subscriptions after
the publishing environment has been configured.
For information about configuring channels, subscribers, and subscriptions, Administering the Publishing Framework
in the SAS Integration Technologies: Administrator's Guide. If you are using an LDAP directory server as your
metadata repository, refer to Administering the Publishing Framework in the SAS Integration Technologies:
Administrator's Guide (LDAP Version).
Publishing Framework
Subscription Channels 134
About Events
Version 9 of the Publishing Framework supports the generation and publication of events. In this context, an event is
an action or occurrence that can be detected by a computer program. The Publishing Framework creates events using
well−formed XML specifications that contain the name of the event, a set of associated properties, and a message
body.
The Publishing Framework provides two methods for publishing an event:
Explicit event publication. This feature enables a SAS program to generate any type of event and publish it
using HTTP, message queuing, or a publication channel.
•
Implicit event publication. This feature enables a channel's subscribers to be designated as "event"
subscribers. The Publishing Framework then automatically notifies event subscribers whenever new
information is published to the channel.
•
Using Explicit Event Publication
Explicit event publication enables a SAS program to generate an event of any kind and publish it explicitly. First, the
event is defined using the CALL routines EVENT_BEGIN and EVENT_BODY. The CALL routine
EVENT_PUBLISH is used to generate the event and publish it using HTTP, message queuing, or a publication
channel. The event is generated using a well−formed XML specification for generic events. The CALL routine
EVENT_END is then used to free all resources associated with the event.
For details about using the event CALL routines, refer to the Event Publish CALL Routines documentation. For
details about the format used to generate explicit events, refer to the XML Specification for Generic Events.
Note: The SAS Publisher user interface does not currently support explicit event generation, and the Publishing
Framework does not currently support event retrieval. However, custom programs can be developed to provide this
functionality.
To collect and process events that the Publishing Framework generates, you can develop customized programs using
the Event Broker service. The Event Broker is one of the Foundation Services provided with Integration
Technologies. For more information, see com.sas.services.events.broker in the Foundation Services class
documentation.
Using Implicit Event Publication
With Version 9 of the Publishing Framework, the PACKAGE_PUBLISH CALL routine and the SAS Publisher
interface automatically generate a SASPackage event whenever a package is published to a channel. The SASPackage
event is captured as a well−formed XML document that describes the package. For details, see the XML Specification
for SASPackage Events.
Subscribers to the channel who are designated as "event" subscribers then receive the event via their chosen transport
methods. This feature enables subscribers to be aware that new information has been published to the channel.
To designate a subscriber as an event subscriber, use the Publishing Framework plug−in of SAS Management
Console. For details, see the Publishing Framework section of the SAS Integration Technologies: Administrator's
Guide.
About Events 135
Note: If you are using LDAP (instead of a SAS Metadata Server) as your metadata repository, you will need to
develop custom programs to designate subscribers as event subscribers. The Subscription Manager interface does not
currently support this function.
To collect and process events that the Publishing Framework generates, you can develop customized programs using
the Event Broker service. The Event Broker is one of the Foundation Services provided with Integration
Technologies. For more information, see com.sas.services.events.broker in the Foundation Services class
documentation.
XML Specifications for Events
The Publishing Framework uses well−formed XML specifications to generate events. For detailed information, see
the following topics:
the XML Specification for Generic Events, which is used for explicit event publishing• the XML Specification for SASPackage Events, which is used for implicit event publishing• Examples of Generated Events using both of these specifications•
Publishing Framework
SAS® Integration Technologies: Developer's Guide
About Events 136
Package Publishing
The following activities are performed in order to publish a package:
Entries are inserted into the package.1. The transport for delivering the package to the consumer is defined.2. Other properties are defined that are specific to the transport or the rendering of the package.3. The package is published.4.
The following scenarios depict how the package publishing method can depend on your role in the business enterprise
or your experience as a programmer:
Type of Publisher Package Publishing Method
Novice user or someone
who prefers to use a GUI Publish by using the SAS Publisher GUI.
SAS programmer Publish programmatically by using the
Publish Package CALL routines.
Programmer who uses a
language other than SAS Publish by writing a third−party client
application.
Publishing Framework
Package Publishing 137
Publishing Using the SAS Publisher GUI
SAS Publisher can be used to define the following basic information for publishing a package:
Items to include in the package are defined in the What to Publish tab:
The destination (or transport) for delivering the package is defined in the Where to Publish tab:
Other package properties, such as the package's rendering as an archived file (or SPK package), are defined in the
How to Publish tab:
Publishing Using the SAS Publisher GUI 138
The Viewers tab is available when you are working with the e−mail, channel, and WebDAV transports. Use this tab to
specify a particular viewer template file and to indicate the reference type of the viewer.
Use the Publish Options tab to specify additional options or properties based on the destination type.
SAS® Integration Technologies: Developer's Guide
Publishing Using the SAS Publisher GUI 139
After the package has been defined, an appropriate action is taken, such as publishing the package (clicking the OK
(Publish Package) button):
For complete details about how to use the SAS Publisher GUI to publish a package, see SAS Publisher.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Publishing Using the SAS Publisher GUI 140
Publishing Programmatically Using SAS
The Interface to the Publish Package CALL Routines can be used to write a SAS program to publish a package:
A package and its properties are defined using the PACKAGE_BEGIN CALL routine.
Example:
CALL PACKAGE_BEGIN(pid, desc, nameValue, rc);
1.
Items are inserted in the package using an appropriate CALL routine.
CALL routines fall into two categories of item types:
SAS results:
INSERT_CATALOG
INSERT_DATASET
INSERT_MDDB
INSERT_SQLVIEW
♦
unstructured content:
INSERT_FILE
INSERT_HTML
INSERT_REF
INSERT_VIEWER
♦
Example:
Call INSERT_DATASET(pid, libname, memname, description, NameValue, rc);
2.
The destination (or transport) for delivering the package is defined using the PACKAGE_PUBLISH CALL
routine.
CALL routines for supported transports are as follows:
TO_ARCHIVE♦ TO_EMAIL♦ TO_QUEUE♦ TO_SUBSCRIBERS♦ TO_WEBDAV♦
Example:
publishType = "TO_ARCHIVE"
.
.
.
CALL PACKAGE_PUBLISH (pid, publishType, rc, properties, archivePath,
archiveName);
3.
The end of the package is defined using the PACKAGE_END CALL routine.
Example:
CALL PACKAGE_END(pid, rc);
4.
For complete details about how to use the Publish Package CALL routines to publish a package, see Publish Package
Interface.
Publishing Framework
Publishing Programmatically Using SAS 141
Publishing Using a Third−Party Client Application
The publisher can write a third−party client application that uses SAS Integration Technologies to access Integrated
Object Model (IOM) servers.
The Integrated Object Model provides distributed object interfaces for conventional SAS features. This enables the
publisher to develop component−based applications that integrate SAS features into the enterprise application.
Client development in the Java environment enables the publisher to write applets, stand−alone applications, servlets,
and even Enterprise JavaBeans that interact with IOM servers. By supporting industry standards (such as Java
Database Connectivity (JDBC) and CORBA), the Integration Technologies software enables the publisher to take
advantage of existing programming skills and tool sets for writing client applications. For more information, see
Developing Java Clients.
Client development in the Windows environment is based on the Microsoft Component Object Model (COM).
Because COM support is built into the operating system and in all the leading programming language products, the
publisher can integrate SAS (and existing SAS programs) into client applications. Integration Technologies software
provides the type libraries that are necessary to use the IOM server with Visual Basic and Visual C++. For more
information, see Developing Windows Clients.
Publishing Framework
Publishing Using a Third−Party Client Application 142
Package Retrieval
After a package is created, the transport, or destination, and other properties control how the package is delivered to
the consumer.
Packages can be retrieved from these destinations:
Archive• E−mail• Message Queue• WebDAV−Compliant Server•
Archive
An archive is a single binary collection of all the items in a package. An archived package is also referred to as an
SPK (SAS Package) file. Depending on your needs and on whether you have SAS installed, you can choose from the
following products to access an archived package:
You can use the stand−alone product SAS Package Reader to uncompress, or unzip, and use SPK files. SAS
Package Reader can be used to read packages whether or not the consumer has SAS installed.
•
The consumer can use SAS Package Retriever to access an archived package and to store it elsewhere for
continued use. SAS must be installed in order to use the SAS Package Retriever.
•
If SAS is installed, then you can also use the Publish Package CALL routines in order to write SAS programs,
including stored processes, that create, populate, publish, and retrieve packages.
•
If SAS is not installed, then you can use third−party client software in order to write a third−party client
application that uses SAS Integration Technologies to access Integrated Object Model (IOM) servers. The
Integrated Object Model provides distributed object interfaces for conventional SAS features. This enables
you to develop component−based applications that integrate SAS features into the enterprise application.
•
For more information about configuring and publishing to an archive, see Archived Packages.
E−mail
When the publisher publishes a package via e−mail, the package is delivered to a list of recipients which is submitted
to SAS software for processing. Choosing e−mail gives the publisher authority over who receives the package. The
recipient, however, requires no knowledge about the publishing environment from which the package was sent, nor
must the recipient subscribe to a delivery channel. Also, recipients do not have to be SAS users. A recipient who has
not installed SAS can use SAS Package Reader or a Web browser in order to read the package.
Message Queue
A message queue is a named location to which the publisher can publish a package for subsequent retrieval and
continued processing. Although e−mail is suited for delivering reports and views of data to a limited audience, a
message queue is best used for collecting package data entries for continued processing and publishing in
time−critical environments. Publishing to a queue, and retrieval from a queue, are entirely independent activities. The
publishing software (SAS Publisher or programmatic software) and the retrieval software (SAS Package Retriever or
programmatic software) communicate asynchronously without any knowledge of the location of the other software, or
even whether the other software is running.
Package Retrieval 143
You can use the following products to access a package on a message queue:
The consumer can use SAS Package Retriever to access a package on the queue and to store it elsewhere for
continued use. SAS must be installed in order to use the SAS Package Retriever.
•
If SAS is installed, then you can also use the Publish Package CALL routines in order to write SAS programs,
including stored processes, that create, populate, publish, and retrieve packages.
•
If SAS is not installed, then you can use third−party client software in order to write a third−party client
application that uses SAS Integration Technologies to access Integrated Object Model (IOM) servers. The
Integrated Object Model provides distributed object interfaces for conventional SAS features. This enables
you to develop component−based applications that integrate SAS features into the enterprise application.
•
WebDAV−Compliant Server
Whereas the traditional transports (archive, channel, e−mail, and message queue) are repositories for published
package data that can be retrieved and reprocessed in a synchronous fashion, package delivery to a
WebDAV−compliant server facilitates concurrent access to and update of package data on the Internet.
WebDAV is an acronym for Web Distributed Authoring and Versioning. WebDAV is not only a delivery mechanism,
but also a core technology that extends the HTTP network protocol, enabling distributed Web authoring tools to be
broadly interoperable. WebDAV extends the capability of the Web from that of a primarily read−only service, to a
writable, collaborative medium.
You can use the following products to access a package on a WebDAV server:
The consumer can use SAS Package Retriever to access a package on the WebDAV server and to store it
elsewhere for continued use. SAS must be installed in order to use the SAS Package Retriever.
•
If SAS is installed, then you can also use the Publish Package CALL routines in order to write SAS programs,
including stored processes, that create, populate, publish, and retrieve packages.
•
If SAS is not installed, then you can use third−party client software in order to write a third−party client
application that uses SAS Integration Technologies to access Integrated Object Model (IOM) servers. The
Integrated Object Model provides distributed object interfaces for conventional SAS features. This enables
you to develop component−based applications that integrate SAS features into the enterprise application.
•
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Package Retrieval 144
URL Retrieval
E−mail supports the delivery only of a reference to a URL that is accessible from a Web browser. Here is an example
of an e−mail message in which the URL reference is identified:
Clicking the link automatically invokes the consumer's configured Web browser and the URL package entry is
presented for viewing in the Web browser window.
Publishing Framework
URL Retrieval 145
Viewer Processing
SAS Integration Technologies provides a viewer facility that combines the robust text rendering capabilities of HTML
and plain text with the efficiency of e−mail delivery. This facility enables you to create and apply a viewer, which is a
template that contains formatting directives for rendering a specific view to an entire package or to selected package
entries.
The viewer facility consists of a set of tagging extensions to HTML, which you can use to create a unique template
according to the specific package data that is being rendered. For example, you can write formatting directives to
stream package entries (such as a text file or a URL reference) or to extract SAS data file entries for presentation in
e−mail. A viewer creates a presentation quality look and feel to package data entries for distribution to a view−only
audience.
A primary benefit of applying viewers to packages is that e−mail recipients can now view package entries that
otherwise would not be viewable. For example, an archive that contains a SAS data set can be attached to e−mail, but
is not viewable in e−mail unless a viewer is applied. The viewer renders the SAS data set as a populated table.
Furthermore, a viewer facilitates publishing in the traditional sense using, for example, an electronic newsletter. An
electronic newsletter template that is coded in HTML or plain text format can dynamically build your content, which
can consist of links to Web sites for up−to−date information about topics of interest to its readers.
Publishing Framework
Viewer Processing 146
When To Use a Viewer
A viewer is useful under the following conditions:
Publishing to the E−mail Transport
You want to publish a result−set package for delivery to consumers who use a view−only transport (such as e−mail).
Because a SAS data set is not viewable in e−mail, an HTML or text viewer is needed to format the SAS data for a
view−only presentation.
Publishing to Channel Subscribers
If you are publishing to a channel, the transports that are used by subscribers are unknown to you. Therefore, you
might decide to format the entire package with the aid of a viewer to ensure maximum viewability for the broadest
consumer audience. The viewer is applied to a package that is published only to subscribers who use e−mail delivery.
The viewer is not applied to a package that is published to subscribers who specify delivery to message queues.
Extracting and Formatting SAS Data
With a viewer, you can extract specific package items and variables from a SAS data set entry and distribute to
subscribers who use e−mail. Subscribers who use e−mail receive the package entries that the viewer extracts and
formats. Subscribers who use queues receive the full package.
Formatting an Entire Package
Besides formatting a SAS data set package entry, you can also use a viewer to format other entries in the package
(such as another HTML file, a text file, a binary file, or a reference) as input streams. Applying a viewer to the entire
package provides a comprehensive presentation for viewing purposes only.
Publishing an Electronic Newsletter
A popular form of package output is an electronic newsletter. The basic template that imposes the look and feel of the
document can contain static text or HTML coding. However, you can code the dynamic information (in the form of
news articles or SAS data) as links to Web sites whose source data is continuously refreshed.
Publishing an Executive Level Summary
Delivery of SAS result sets and other text and graphical information via e−mail has the greatest value for an executive
level consumer. The executive might have a requirement to view the data (for example in the form of summary tables)
and to read text but might not necessarily need access to the raw data for continued processing, extraction, and
delivery throughout the enterprise.
Publishing Framework
When To Use a Viewer 147
How to Create a Viewer
The publisher (or the person who creates the viewer template) must have a thorough understanding of the contents of
the package in order to successfully create the template. You choose the appropriate viewer tags in order to design a
template that formats the rendered view of the package.
The Sample Package
This sample package contains four entries, in the following order:
SAS data set1. text file2. Reference URL3. HTML file.4.
This package also contains the following description:
AlphaliteAirways Sales Force Briefing
The SAS Data Set
Here is an example of a SAS data set that contains six observations, each containing four variables: FNAME,
LNAME, YEARS, and TERRITORY.
John Smith 32 NE
Gary DeStephano 20 SE
Arthur Allen 40 MW
Jean Forest 3 NW
Tony Votta 30 SW
Dakota Smith 3 HA
The Basic Viewer
The file that contains the viewer template contains code that is surrounded by tagsSASINSERT> open tag and end
with the </SASINSERT> closing tag.
The viewer contains sections that format each package entry using the appropriate technique.
Extracting and formatting a variable from a SAS data set into a list1. Extracting and formatting an entire SAS data set into a table2. Streaming a text file and a reference URL3. Filtering package entries.4.
For a single, comprehensive viewer that contains all of the preceding examples, see Sample HTML Viewer.
Extracting and Formatting a Variable from a SAS Data Set into a List
Delivery of a single variable from all observations in a SAS data set is well suited to an unordered list.
Here is the first section from the sample template that formats a single variable from a SAS data set into a list.
How to Create a Viewer 148
<!−−Section 1: Formatting a Data Set
Variable in an HTML List−−>
<SASINSERT>
<h2>Congratulations!</h2>
$(entry=1 attribute=description)
<ul>
<SASTABLE ENTRY=1>
<li>$(VARIABLE=fname)</li>
</SASTABLE>
</ul>
</SASINSERT>
The ENTRY=1 attribute is necessary to identify the SAS data set as the first entry in the package. The description
attribute extracts the description of the package.
The <UL> HTML tag specifies an unordered list after which the <SASTABLE> tag with the ENTRY=1 option are
necessary to identify the SAS data set as the first entry in the package. The <LI> HTML tag is used with variable
substitution syntax to identify that the variable fname is to be extracted from the SAS data file and formatted as a list
entry in the rendered view. Implicit in the <SASTABLE> construct is looping. Each observation in the data set is read
and formatted until the end of file is reached.
The following SAS HTML tags are used in this example:
SASINSERT Tag• Substitution Syntax• SASTABLE Tag.•
This section of the template is rendered for viewing in e−mail as follows:
Congratulations!
AlphaliteAirways Sales Force Briefing
John• Gary• Arthur• Jean• Tony• Dakota•
Extracting and Formatting a SAS Data Set into a Table
Delivery of multiple variables or all variables from the observations in a SAS data set is well suited to a tabular
presentation.
Here is an example of a template that extracts three of four variables from a SAS data set into a table.
<!−−Section 2: Formatting a SAS Data
Set into a Table−−>
<SASINSERT>
<h2>Record Sales from these Salespeople</h2>
$(entry=1 attribute=description)
<table border cellspacing=0 cellpadding=5
SAS® Integration Technologies: Developer's Guide
How to Create a Viewer 149
rules=groups>
<thead>
<tr>
<th>First Name</th>
<th>Last Name</th>
<th>Territory</th>
</tr>
</thead>
<tbody>
<SASTABLE ENTRY=1>
<tr>
<td> $(Variable=fname)</td>
<td> $(Variable=lname)</td>
<td> $(Variable=territory)</td>
</tr>
</tbody>
</SASTABLE>
</table>
</SASINSERT>
The ENTRY=1 attribute is necessary to identify the SAS data set as the first entry in the package. The description
attribute extracts the description of the entry from the package. Standard HTML table tags set up the tabular
framework that defines a row with three columns of header text and accompanying tabular data. The <TD> tag is used
with the variable substitution syntax to identify the following variables for extraction and insertion into the table:
fname, lname, and territory. Implicit in the <SASTABLE> construct is looping. Each observation in the data set is
read and formatted until the end of file is reached.
The following SAS HTML tags are used in this example:
SASINSERT Tag• Substitution Syntax• SASTABLE Tag.•
This section of the template is rendered for viewing in e−mail as follows:
Record Sales from these Salespeople
AlphaliteAirways Sales Force Briefing
First Name Last Name Territory
John Smith NE
Gary DeStephano SE
Arthur Allen MW
Jean Forest NW
Tony Votta SW
Dakota Smith HA
SAS® Integration Technologies: Developer's Guide
How to Create a Viewer 150
Streaming a Text File and a Reference URL
The viewer template might also include the entire contents of a text file, another HTML file, a reference URL, or a
binary file.
Here is the third section from the sample template that inserts a text file and a reference URL into the viewer.
<!−−Section 3: Inserting a Text File
and a Reference URL−−>
<SASINSERT>
<h2>Letter of Congratulations</h2>
<p>Below is a copy of the letter that was sent
to each recipient of the top sales award.</p>
$(entry=2 attribute=stream)
<p>
See <a href="$(entry=3 attribute=stream)">
for detailed sales figures.</p>
</SASINSERT>
The <H2> tag defines a descriptive heading for the text document and the reference URL. The ENTRY=2 attribute
identifies the entry (a text document) to be substituted as an input stream to the HTML output. The ENTRY=3
attribute identifies the reference URL.
The following SAS HTML tags are used in this example:
SASINSERT Tag• Substitution Syntax.•
This section of the template is rendered for viewing in e−mail as follows:
Letter of Congratulations
Below is a copy of the letter that was sent to each recipient of the top sales award.
December 30, 2000
International Sales
AlphaliteAirways Headquarters
Dear AlphaliteAirways Salesperson,
Congratulations on your much deserved recognition as
outstanding salesperson for AlphaliteAirways for 2000.
To express our gratitude for your excellent contribution,
we wish to present you with 25 stock options in
AlphaliteAirways.
Wishing you continued success in your career with
AlphaliteAirways.
Sincerely,
Alvin O. Taft, Jr.
Director−in−Chief
SAS® Integration Technologies: Developer's Guide
How to Create a Viewer 151
See http://www.AlphaliteAirways.com/headquarters/sales
for detailed sales figures.
Filtering Package Entries
Another method for locating package entries for inclusion in the viewer is name/value filtering. You can filter package
entries that are assigned an optional name/value pair when they are created according to specified criteria. Entries that
match are included in the rendered view. Filtering is especially powerful for searching large, nested packages.
In our example, we filter for all entries that have a name/value pair of type=report and include the matching entries in
the viewer. In our fictitious package, one HTML entry matches the name/value pair and so it is filtered for inclusion in
the viewer.
Here is the fourth section from the sample template that inserts an HTML file (according to matched criterion) into the
viewer.
<!−−Section 4: Filtering an Entry−−>
<SASINSERT>
<h2>Message from the President</h2>
<SASREPEAT>
$(entry="(type=report)" attribute=stream)
</SASREPEAT>
</SASINSERT>
The ENTRY="(type=report)" attribute filters all package entries that contain a name/value pair of type=report. The
<SASREPEAT> open tag and the </SASREPEAT> closing tag surround the search string in order to perform a
repetitive search for the name/value pair. Without this tag, the search would end after the first match. In this example,
only one HTML entry is matched. This entry is substituted as an input stream to the HTML output.
The following SAS HTML tags are used in this example:
SASINSERT Tag• Substitution Syntax• SASREPEAT Tag.•
This section of the template is rendered for viewing in e−mail as follows:
Message from the President
AlphaliteAirways delivers service. AlphaliteAirways is the
recognized industry leader according to its safety
record, volume of passengers served, and number of
routes serviced.
How are we able to live up to such high expectations
consistently? First and foremost, we do it through the
abilities of our top salespeople. We owe a huge debt to
these hard−working individuals who actively pursue
revenue for this company.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
How to Create a Viewer 152
How to Apply a Viewer
After you create a viewer template for a package, the publisher can apply it when publishing the package to e−mail
using the following methods:
SAS Publisher• Publish Package Interface•
Using SAS Publisher to Apply a Viewer
For the e−mail, channel subscriber, and WebDAV transports only, you can specify a viewer in the appropriate
transport type tab. Here is an example of completed viewer properties:
Viewer Field in the How Viewer Referenced Group Box
You specify the location of the viewer in the form of either a physical filename (for example,
c:\Public\viewtemplate.html or c:\Public\viewtemplate.txt) or a SAS fileref (for example, template).
Specify a file name extension that is appropriate to the type of template that is to be used:
.HTML• .TXT•
Arrow buttons are provided to the right of the Viewer field, allowing you to browse directories or to select from
previously defined locations.
Regardless of the selection for viewer reference, leaving the Viewer field blank causes optional viewer properties to
be ignored.
For more information about how to complete viewer options in the Where to Publish SAS Publisher tab, see
Specifying Package Format.
Using the Publish Package Interface to Apply a Viewer
For the e−mail, channel subscriber, and WebDAV delivery types only, you specify a viewer as a property to the
PACKAGE_PUBLISH SAS CALL routine.
You specify the VIEWER_NAME property and assign to it a viewer in the form of either an external filename or a
SAS fileref.
For example, the following code shows the application of an HTML viewer to a package that is published to e−mail:
publishType = "TO_EMAIL";
properties = "VIEWER_NAME";
viewerFile = "filename:c:\dept\saletemp.html";
emailAddress = "JohnDoe@alphalite.com";
Call package_publish(pid, publishType, rc,
properties, viewerFile, emailAddress);
How to Apply a Viewer 153
The following code shows the application of a text viewer to a package that is published to e−mail:
publishType = "TO_EMAIL";
properties = "TEXT_VIEWER_NAME";
viewerFile = "filename:c:\dept\saletemp.txt";
emailAddress = "JohnDoe@alphalite.com";
Call package_publish(pid, publishType, rc,
properties, viewerFile, emailAddress);
The following code publishes the package (to which an HTML viewer is applied) to all subscribers of the HR channel.
The subject property is specified so that all e−mail subscribers will receive the message with the specified subject.
pubType = "TO_SUBSCRIBERS";
storeInfo =
"LDAP://alpair02.unx.com:8010/o=Alphalite Airways,c=US";
viewerFile = "filename:c:\dept\saletemp.html";
channel = 'HR';
subject = "Weekly HR Updates:";
props = "VIEWER_NAME, SUBJECT, CHANNEL_STORE";
CALL PACKAGE_PUBLISH(packageId, "TO_SUBSCRIBERS", rc,
props, viewerFile, subject, storeInfo, channel);
The following code publishes the package (to which an HTML viewer is applied) to a WebDAV−compliant server.
rc = 0;
pubType = "TO_WEBDAV"
subject = "Nightly Maintenance Report"
properties= "VIEWER_NAME, COLLECTION_URL"
viewerFile = "filename:c:\dept\saletemp.html"
cUrl = "http://www.alpair.web/NightlyMaintReport"
CALL PACKAGE_PUBLISH(packageId, pubType,
rc, properties, viewerFile, cUrl);
For complete details about how to programmatically specify a viewer when you publish to the e−mail and the channel
subscriber types, see PACKAGE_PUBLISH CALL routine syntax.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
How to Apply a Viewer 154
<SASINSERT> Tag
Marks a section of the viewer file for viewer processing.
Syntax
<SASINSERT>
</SASINSERT>
Details
All viewer processing occurs within the opening <SASINSERT> tag and the closing </SASINSERT> tag. SAS tags
and substitution statements are recognized only when they appear within the <SASINSERT> and </SASINSERT>
tags.
The data that is inserted into the rendered view comes from a specified package entry. The data that is extracted from
the entry can be any of the following:
value of a SAS variable• description of the entry or package• entire entry, which is to be streamed into the HTML file• reference to the entry• package or nested package abstract.•
Example
See the Using the SASINSERT and SASTABLE Tags example.
Publishing Framework
<SASINSERT> Tag 155
Substitution Syntax
A substitution statement within the <SASINSERT> opening tag and the </SASINSERT> closing tag inserts data from
the specified package entry into a viewer file for delivery as HTML or text output.
Syntax
To specify a substitution, use the following syntax within the <SASINSERT> tag:
$(nested=z entry=x attribute=value)
The attributes of the SASINSERT substitution are defined as follows:
$( ) indicates the start of substitution mode using the dollar sign ($) followed by the open parenthesis. The close
parenthesis indicates the end of substitution mode.
nested=z
identifies the nested package within the main package that is to be involved in the substitution. If the
NESTED attribute is not specified, only the entries in the main package are involved in the substitution. For
information about the syntax of the z value, see Specifying Values for the NESTED and ENTRY Attributes.
entry=xidentifies the entry within the specified package that is to be targeted for the substitution. For information
about the syntax of the x value, see Specifying Values for the NESTED and ENTRY Attributes.
name=someName
identifies a name of a name/value pair. The value of this name/value pair will be substituted. The name= and
attribute= keywords cannot be specified on the same substitution string.
If entry= is specified along with name=, the entry's name/value specification will be used to make the
substitution. For example, the following substitution takes the first entry in the package and determines the
value of the name "title". This value is inserted into the HTML or text output:
$(entry=1 name="title")
This example evaluates the name/value that is specified at the main package level. The value for the name
"title" is substituted:
($name="title")
attribute=value
identifies the attributes of the specified entry that are to be inserted into the HTML or text output. The value
that is associated with this attribute can be any of the following:
description
inserts the description of the specified entry. For example, the following substitution inserts the
description of the specified entry into the HTML or text output:
$(entry=1 attribute=description)
stream streams the specified entry into the HTML or text output. The streamed entry must be one of the
following entry types:
Substitution Syntax 156
reference string (added to the package with the INSERT_REFERENCE CALL routine)• text file (added with INSERT_FILE routine)• binary file (added with INSERT_FILE routine)• HTML file (added with INSERT_HTML routine).•
For example:
$(entry=1 attribute=stream)
reference
inserts a reference by substituting the entry's file name into the rendered view. For example, the
following substitution inserts the file name of the first entry:
$(entry=1 attribute=reference)
abstractInsert the package abstract at this location. If the NESTED attribute is not specified, the abstract of
the main package is inserted in the HTML or text output. If the NESTED attribute is specified, the
abstract of the nested package is inserted in the HTML or text output. The ENTRY attribute is not
valid when the abstract attribute is specified. For example, the following substitution inserts the main
package abstract into the HTML or text output:
$(attribute=abstract)
Variable substitution is another type of substitution. It must be specified within the <SASTABLE> tag.
Details
Specifying Values for the NESTED and ENTRY Attributes
The NESTED and ENTRY attributes are used in substitution syntax within the <SASINSERT> tag and as attributes
on the <SASTABLE> tag. The examples that appear in this section apply to substitution syntax within the
<SASINSERT> tag, but all of the syntax rules also apply to the use of the NESTED and ENTRY attributes in the
<SASTABLE> tag.
You can specify the values of the NESTED and ENTRY attributes in two formsor name/value.
Identifying an Entry by its Order in the Package
You use the entry's numerical order in the package to identify which entry is to be involved in a substitution operation.
An example of package entry order follows:
SAS data set1. binary file2. reference string3. HTML file.4.
The SAS data set is the first entry, the binary file is the second entry, and so on.
For the NESTED attribute, a numeric value identifies the package that is involved in the substitution based on order of
nesting into the package. For example, nested=3 specifies the third package that is nested in the main package. To
accommodate packages with multiple levels of nesting, a period (.) differentiates levels of nesting. For example,
nested=2.5 specifies the fifth package that is nested in the second package that is nested in the main package.
SAS® Integration Technologies: Developer's Guide
Substitution Syntax 157
For the ENTRY attribute, a numeric value identifies the entry that is to be used in the substitution that is based on the
order of insertion into the package. For example, $(entry=2) specifies the second entry in the package.
If the NESTED attribute is not specified, the specified entry in the main package is used for the substitution.
Identifying an Entry by Filtering the Package
Name/value pairs are used in the NESTED and ENTRY attributes to specify filters that determine which nested
packages and entries are to be involved in a substitution operation. You must quote the name/value and contain it
within parentheses. For example,
$(nested="(type=report)" entry="(a=b)")
When the name/value pair is specified outside the <SASREPEAT> tags, only the first entry that matches the filter is
substituted. When the name/value pair is used inside the <SASREPEAT> tags, all entries that match the filter are
substituted into the HTML or text output.
To limit the search for an entry to the main package only, omit the NESTED attribute. For example,
$(entry="(type=report)") specifies that the entry that is to be involved in the substitution operation is the
first entry in the main package that has a name/value pair of type=report.
Entries in the main package are always candidates for name/value substitution, even when the NESTED attribute is
specified. In the following example, the entry that is involved in the substitution is either the first entry in the main
package that matches the a=b name/value pair or it is the first entry that matches a=b in the first nested package with
the type=report name/value pair.
$(nested="(type=report)" entry="(a=b)")
To substitute all entries that match the name/value pairs, enclose the substitution within the <SASREPEAT> tag. If
the preceding example were enclosed in <SASREPEAT> tags, the entries that are involved in the substitution would
be all those in the main package and the nested packages that match the a=b name/value pair.
The name/value syntax also supports the asterisk (*) wildcard on the NESTED attribute. The asterisk indicates "all
levels below." For example, to substitute "all entries in all nested packages beneath this level," use a period (.) and an
asterisk (*) in the NESTED attribute, as follows:
$(nested="(type=report).*" entry="(a=b)")
The preceding example identifies for the substitution all entries that match the a=b name/value pair in the following
packages:
the main package• the first nested package that contains a match of the type=report name/value pair, regardless of the nesting
level of that package
•
any package, regardless of name/value pair, that is nested beneath the first nested package.•
To substitute all matching entries in the main package and in all nested packages, use an asterisk in the NESTED
attribute, as shown in the following example:
$(nested="*" entry="(a=b)")
SAS® Integration Technologies: Developer's Guide
Substitution Syntax 158
The preceding example substitutes all entries in the main package and in all nested packages at any level that match
the name/value pair a=b.
Examples
$(entry=1 attribute=description)
Indicates that the description for package entry 1 is to be substituted at this location.
$(nested=1 entry=4 attribute=stream)
indicates that the fourth entry within the first nested package should be streamed at this location. The entry
must be either a reference, a text file, a binary file, or an HTML file.
$(nested=1.2 entry=2 attribute=stream)
identifies for streaming the second entry in the second package that is nested in the first package that is nested
in the main package.
$(nested="*" entry="(type=report)" attribute=description)
indicates that the description of the first entry within the main package or any nested packages, that matches
the type=report name/value pair is to be substituted into the HTML or text output.
If the substitution is contained within <SASREPEAT> tags, all entries in the main and nested packages that
match the type=report name/value pair would be substituted into the HTML or text output.
$(nested="(type=report)" attribute=abstract)
indicates that the abstract from the nested package within the main package that matches the type=report
name/value pair is to be substituted into the HTML or text output. If this substitution were specified within
<SASREPEAT> tags, the abstracts of all matching nested package entries in the main package would be
inserted into the HTML or text output.
$(name=title entry=1)
indicates that the first entry in the package will be used for the substitution. Because name= is specified, a
name/value substitution will occur. Name= identifies the name of a name/value pair; therefore, in this case, it
indicates a name of title. If the first entry's name/value specification contains a name of title, its value will be
substituted.
$(name=Definition entry="(type?report)")
indicates that the substitution will occur for the first entry within the main package that possesses the
type=report name/value pair. The name= syntax indicates that a name/value substitution will occur. If the
entry that matches the type?report filter has a name/value pair with the name of Definition, its value will be
substituted. Note that if this substitution is contained in a <SASREPEAT> tag, the name/value substitution
will occur for all entries in the main package that match the type?report filter.
$(name=title)
indicates that because entry= is not used in this substitution string, the name/value for the main package will
be used for the substitution. Name= identifies the name of a name/value pair, so in this case it indicates a
name of title. If the package's name/value specification contains a name of title, its value will be substituted.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Substitution Syntax 159
<SASTABLE> Tag
Populates HTML or text tables and lists.
Syntax
<SASTABLE nested=z entry=x
attribute=value>
/* insert HTML tags or static text as needed here */
$(variable=variableName)
/* insert HTML tags or static text as needed here */
</SASTABLE>
The attributes of the <SASTABLE> tag are defined as follows:
nested=z
identifies an optional nested package within the main package that is to be used to build the table or list. If the
NESTED attribute is not specified, only the main package is used to build the table or list. The numerical and
name/value syntax options available for the z value are defined in Specifying Values for the NESTED and
ENTRY Attributes.
entry=xidentifies the entry within the specified package that is to be used to build the table or list. The numerical and
name/value syntax options available for the x value are defined in Specifying Values for the NESTED and
ENTRY Attributes.
first=a specifies an optional numeric that designates the first row that is to be inserted into the table or list. The
default value is 1.
last=b specifies the last row of optional numeric data that is to be inserted into the table or list. The default is the last
row in the specified entry.
Note: The LAST attribute and the N attribute are mutually exclusive. If both are specified, the last one is
used.
n=c specifies the total number of optional rows that are to be inserted into the table or list, beginning with the first
row in the entry. The default is all rows in the entry.
Note: The N attribute and the LAST attribute are mutually exclusive. If both are specified, the last one is
used.
Details
Within the <SASINSERT> tags, the <SASTABLE> tag supports the development of HTML lists and tables. The
<SASTABLE> tag populates tables and lists by repetitively inserting HTML tags or static text and specified data into
HTML or text output. The insertion repeats for each row of data that has been specified for insertion. The location of
the data and the rows of data to be inserted are determined by the attributes of the <SASTABLE> tag.
<SASTABLE> Tag 160
Variable Substitution
Variable substitution is valid within the <SASTABLE> open tag and the </SASTABLE> closing tag. The variable
substitution syntax is
$(VARIABLE=variableName)
The variable substitution syntax specifies that the value of the VARIABLE attribute in the data set is to be substituted
into the tables and lists in either HTML or plain text format. This attribute is valid only within the <SASTABLE> tag.
The entry that is named in the <SASTABLE> tag must be a valid SAS data set. Any number of variable substitutions
can be specified within the <SASTABLE> tag as long as each one references a valid variable in the SAS data set.
Examples
The following example uses the <SASINSERT> and <SASTABLE> tags to build a list. The SAS data set that is used
is the second entry that is added to the main package. The value of the fileName variable is substituted on each
repetition.
<p>
<SASINSERT>
<ul>
<SASTABLE ENTRY=2>
<li>$(VARIABLE=fileName)</li>
</SASTABLE>
</ul>
</SASINSERT>
The following example uses the <SASINSERT> and <SASTABLE> tags to build a table. The SAS data set entry is
the first entry in the main package. The value of the variables fname, lname, state, and homepage are used to create
the table. The newly created table will contain one row for each row in the main package.
<SASINSERT>
<h1>Table Example using SASTABLE</h1>
<table border cellspacing=0 cellpadding=5
rules=groups>
<thead>
<tr><th>First Name</th>
<th>Last Name</th>
<th>State </th>
<th>HomePage</th></tr>
<tbody>
<SASTABLE ENTRY=1>
<tr> <td> $(VARIABLE=fname)</td>
<td> $(VARIABLE=lname)</td>
<td> $(VARIABLE=state)</td>
<td> <a href=$(VARIABLE=homepage)>
$(VARIABLE=homepage)</a></td></tr>
</SASTABLE>
</table>
</SASINSERT>
Publishing Framework
SAS® Integration Technologies: Developer's Guide
<SASTABLE> Tag 161
<SASREPEAT> Tag
Repeats a substitution for all entries that match given criteria.
Syntax
<SASREPEAT>
</SASREPEAT>
Details
The <SASREPEAT> tag causes a substitution that is enclosed within the tag to repeat for all entries that match the
specified name/value pair, as described in Specifying Name/Value Pairs. Without the <SASREPEAT> tag, the
substitution stops after matching the first entry.
Any HTML tags or static text that are included in the <SASREPEAT> tag are inserted into the output along with the
substitution data, and those tags are repeatedly inserted each time a new entry matches the name/value pair.
The <SASREPEAT> tag is recognized only within the <SASINSERT> tag and is relevant only when it is used with
name/value pair substitutions.
Examples
The following example uses the <SASREPEAT> tag to build a list of reports. The substitutions and the HTML tag
within the <SASREPEAT> tag are repeated for each entry that matches the type=report name/value pair.
<SASINSERT>
Available reports include the following:
<ul>
<SASREPEAT>
<li> $(entry="(type=report)"
attribute=description)</li>
</SASREPEAT>
</ul>
</SASINSERT>
An example of the rendered view follows:
Available reports include the following:
President's State of the Union address• AlphaliteAirways Annual Report• Sales Quotas for Midwest Territory•
The next example uses the <SASREPEAT> tag to build a table. The substitutions and the HTML tags within the
<SASREPEAT> tag are repeated for each entry in the main package that matches the type=report name/value pair.
<table border="1" cellspacing="0" cellpadding="3">
<SASREPEAT> Tag 162
<SASINSERT>
<SASREPEAT>
<tr><td>$(entry="(type=report)"
attribute=description)</td></tr>
</SASREPEAT>
</SASINSERT>
</table>
An example of the rendered view follows:
President's State of the Union Address AlphaliteAirways Annual Report Sales Quotas for Midwest Territory
Publishing Framework
SAS® Integration Technologies: Developer's Guide
<SASREPEAT> Tag 163
<SASECHO> Tag
Stores a text string to send to the SAS Log.
Syntax
<SASECHO text="text">
The <SASECHO> open tag has no corresponding closing tag.
Details
The <SASECHO> tag aids in the diagnosis of viewer parsing and processing problems by printing a message to the
SAS LOG window as the viewer file is processed.
The <SASECHO> tag is recognized only within the <SASINSERT> tags. If the text value contains embedded
punctuation and spaces, surround the text with quotation marks.
Example
<SASECHO text="Correctly executed first segment.">
Publishing Framework
<SASECHO> Tag 164
Using the <SASINSERT> and <SASTABLE> Tags:
Examples
The following example uses the <SASINSERT> and <SASTABLE> tags to build a list. The SAS data set that is used
is the second entry that is added to the main package. The value of the fileName variable is substituted on each
repetition.
<p>
<SASINSERT>
<ul>
<SASTABLE ENTRY=2>
<li>$(VARIABLE=fileName)</li>
</SASTABLE>
</ul>
</SASINSERT>
The following example uses the <SASINSERT> and <SASTABLE> tags to build a table. The SAS data set entry is
the first entry in the main package. The value of the variables fname, lname, state, and homepage are used to
create the table. The newly created table will contain one row for each row in the main package.
<SASINSERT>
<h1>Table Example using SASTABLE</h1>
<table border cellspacing=0 cellpadding=5
rules=groups>
<thead>
<tr><th>First Name</th>
<th>Last Name</th>
<th>State </th>
<th>HomePage</th></tr>
<tbody>
<SASTABLE ENTRY=1>
<tr> <td> $(Variable=fname)</td>
<td> $(Variable=lname)</td>
<td> $(Variable=state)</td>
<td> <a href=$(Variable=homepage)>
$(variable=homepage)</a></td></tr>
</SASTABLE>
<tr><td colspan=4 align=center>
Note: Simple table example.</td></tr>
</table>
</SASTABLE>
Refer to A Sample Viewer Template to see formatted output from <SASINSERT> and <SASTABLE> examples.
Publishing Framework
Using the <SASINSERT> and <SASTABLE> Tags: Examples 165
Sample HTML Viewer
This sample HTML viewer example is a collection of viewer coding sections that are described in Creating a Viewer.
<!−−Section 1: Formatting a Data Set
Variable in an HTML List−−>
<SASINSERT>
<h2>Congratulations!</h2>
$(entry=1 attribute=description)
<p>
<ul>
<SASTABLE ENTRY=2>
<li>$(VARIABLE=fname)
</SASTABLE>
</ul>
<!−−Section 2: Formatting a SAS Data Set
in a Table−−>
<h2>Record Sales from these Salespeople</h2>
$(entry=1 attribute=description)
<table border cellspacing=0 cellpadding=5
rules=groups>
<thead>
<tr>
<th>First Name</th>
<th>Last Name</th>
<th>Territory</th>
</tr>
</thead>
<tbody>
<SASTABLE ENTRY=1>
<tr>
<td> $(VARIABLE=fname)</td>
<td> $(VARIABLE=lname)</td>
<td> $(VARIABLE=territory)</td>
</tr>
</tbody>
</SASTABLE>
</table>
<!−−Section 3: Inserting a Text File
and a Reference−−>
<h2>Letter of Congratulations</h2>
Below is a copy of the letter that was sent
to each recipient of the top sales award.
$(entry=2 attribute=stream)
<p>
See <a href="$(entry=3 attribute=stream)">$(entry=3
attribute=stream)</a> for detailed sales figures.
<!−−Section 4: Filtering an Entry−−>
<h2>Message from the President</h2>
<SASREPEAT>
$(entry="(type=report)" attribute=stream)
</SASREPEAT>
</SASINSERT>
Sample HTML Viewer 166
Rendered View in E−mail
The rendered view appears in e−mail as follows:
Congratulations!
AlphaliteAirways Sales Force Briefing
John• Gary• Arthur• Jean• Tony• Dakota•
Record Sales from these Salespeople
AlphaliteAirways Sales Force Briefing
First Name Last Name Territory
John Smith NE
Gary DeStephano SE
Arthur Allen MW
Jean Forest NW
Tony Votta SW
Dakota Smith HA
Letter of Congratulations
Below is a copy of the letter that was sent to each recipient of the top sales award.
December 30, 2000
International Sales
AlphaliteAirways Headquarters
Dear AlphaliteAirways Salesperson,
Congratulations on your much deserved recognition as
outstanding salesperson for AlphaliteAirways for 2000.
To express our gratitude for your excellent contribution,
we wish to present you with 25 stock options in
AlphaliteAirways.
Wishing you continued success in your career with
AlphaliteAirways.
Rendered View in E−mail 167
Sincerely,
Alvin O. Taft, Jr.
Director−in−Chief
See http://www.AlphaliteAirways.com/headquarters/sales
for detailed sales figures.
Message from the President
AlphaliteAirways delivers service. AlphaliteAirways is the
recognized industry leader according to its safety
record, volume of passengers served, and routes serviced.
How are we able to live up to such high expectations
consistently? First and foremost, we do it through the
abilities of our top salespeople. We owe a huge debt to
these hard−working individuals who actively pursue
revenue for this company.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Rendered View in E−mail 168
SAS Program with an HTML Viewer
The following SAS program example includes two parts:
SAS code that creates two SAS data sets• Package publishing CALL routines that create a package, insert package entries, and publish the package to
e−mail with the aid of a viewer file.
•
The PACKAGE_PUBLISH CALL routine applies a viewer that is named realview.html to the package that is
rendered in e−mail.
See the viewer properties and attributes that are set in bold in the code below.
data empInfo;
length homePage $256;
input fname $ lname $ ages state $ siblings homePage $;
datalines;
John Smith 32 NY 4 http://alphaliteairways.com/~jsmith
Gary DeStephano 20 NY 2 http://alphaliteairways.com/~gdest
Arthur Allen 40 CA 2 http://alphaliteairways.com/~aallen
Jean Forest 3 CA 1 http://alphaliteairways.com/~jforest
Tony Votta 30 NC 2 http://www.pizza.com/~tova
Dakota Smith 3 NC 1 http://~alphaliteairways.com/~dakota
;
run;
quit;
data fileInfo;
length fileName $256;
input fileName $;
datalines;
Sales
Marketing
R&D
;
run;
quit;
data _null_;
rc=0; pid = 0;
call package_begin(pid,"Daily Orders Report.",'', rc);
if (rc eq 0) then put 'Package begin successful.';
else do;
msg = sysmsg();
put msg;
end;
call insert_ref(pid, "HTML",
"http://www.alphaliteairways.com",
"Check out the Alphalite Airways Web site
for more information." , "", rc);
if (rc eq 0) then put 'Insert Reference successful.';
else do;
msg = sysmsg();
put msg;
end;
SAS Program with an HTML Viewer 169
call insert_dataset(pid, "work", "empInfo",
"Data Set empInfo" , "", rc);
if (rc eq 0) then put 'Insert Data Set successful.';
else do;
msg = sysmsg();
put msg;
end;
call insert_dataset(pid, "work", "fileInfo",
"Data Set fileInfo" , "", rc);
if (rc eq 0) then put 'Insert Data Set successful.';
else do;
msg = sysmsg();
put msg;
end;
viewerName='filename:realview.html';
prop='VIEWER_NAME';
address="John.Smith@alphaliteairways.com";
call package_publish(pid, "TO_EMAIL", rc,
prop, viewerName, address);
if rc ne 0 then do;
msg = sysmsg();
put msg;
end;
else
put 'Publish successful';
call package_end(pid,rc);
if rc ne 0 then do;
msg = sysmsg();
put msg;
end;
else
put 'Package termination successful';
run;
To look at the content of the viewer template, see Sample Viewer Template.
To look at a rendered view of the package that is delivered to e−mail, see Simulated Rendered View of the Package in
E−mail.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
SAS Program with an HTML Viewer 170
Sample Viewer Template
A SAS program creates a package and applies a viewer template that is named realview.html. During package
publishing, viewer tag processing renders a view of the package for delivery via e−mail.
<html>
<HEAD>
<META HTTP−EQUIV="Content−Type CONTENT="text/html;
charset=ISO−8859−1">
<TITLE>Daily Purchase Summary</TITLE>
</HEAD>
<BODY>
<p>
<SASINSERT>
<h1>Table Example using SASTABLE</h1>
<table border cellspacing=0 cellpadding=5
rules=groups>
<thead>
<tr><th>First Name</th>
<th>Last Name</th>
<th>State </th>
<th>HomePage</th></tr>
</thead>
<tbody>
<SASTABLE ENTRY=2>
<tr><td> $(VARIABLE=fname)</td>
<td> $(VARIABLE=lname)</td>
<td> $(VARIABLE=state)</td>
<td> <a href="$(VARIABLE=homepage)">
$(VARIABLE=homepage)</a> </td>
</tr>
</tbody>
</SASTABLE>
</table>
<p>
<h1>List Example using SASTABLE</h1>
<ul>
<SASTABLE ENTRY=3>
<li>$(VARIABLE=org)</li>
</SASTABLE>
</ul>
<P>
<h2>Example using Stream</h2>
<SASINSERT>
<a href="$(ENTRY=1 ATTRIBUTE=STREAM)">$(ENTRY=1
ATTRIBUTE=STREAM)</a>
</SASINSERT>
<p>
</BODY>
</html>
Simulated Rendered View of the Package in E−mail
The following rendered view simulates the information that is displayed by the preceding viewer template.
Sample Viewer Template 171
SAS® Integration Technologies: Developer's Guide
Sample Viewer Template 172
Daily Purchase Summary
Table Example using SASTABLE
First Name Last Name State HomePage
John Smith NY http://alphaliteairways.com/~jsmith
Gary DeStephano NY http://alphaliteairways.com/~gdest
Arthur Allen CA http://alphaliteairways.com/~aallen
Jean Forest CA http://alphaliteairways.com/~jforest
Tony Votta NC http://pizza.com/~tova
Dakota Smith NC http://alphaliteairways.com/~dakota
List Example using SASTABLE
Sales• Marketing• R&D•
Example using Stream
http://alphaliteairways.com
Publishing Framework
Daily Purchase Summary 173
SAS Publisher
SAS Publisher provides an intuitive, easy−to−use graphical interface for you to point and click your way through the
package−publishing process. SAS Publisher serves as the interface to the Publish Package CALL routines that drive
the SAS Integration Technology publish−and−subscribe solution.
SAS Publisher lets the publisher select existing digital content within the business enterprise for inclusion in a single
package for immediate delivery to the people who need it most. Digital content can include both SAS and other
(external) data. In the context of SAS Publisher, package entities are referred to as items.
Package delivery methods span the range from simple to complex: simple e−mail to a list of known recipients,
information channels for end−user and group subscription, message queue or archive for subsequent person or
programmatic access, and collections on WebDAV−compliant servers for subsequent retrieval and reuse.
The ability of SAS Publisher to create and deliver information is the cornerstone of the Publishing Framework.
Underlying the functions of SAS Publisher is a rich set of Publish Package CALL routines, which you can also use
directly to develop programmatic solutions for package publishing.
Publishing Framework
SAS Publisher 174
Package Items
Package content takes the following forms:
SAS fileSAS catalog♦ SAS data set♦ SAS database–such as FDB and MDDB♦ SAS SQL view♦
•
Binary file–such as Excel, GIF, JPG, PDF, PowerPoint, and Word• HTML file, including ODS output• Reference string–such as a URL or HTML• Text file–such as a SAS program• Viewer file–such an HTML or text template that formats SAS file items for viewing in e−mail.•
Publishing Framework
Package Items 175
SAS Publisher Requirements
To run SAS Publisher, you need SAS Release 8 or higher. A license for Base SAS software and the production
version of SAS Integration Technologies is required.
Note: SAS Publisher is not supported in the z/OS operating environment.
Publishing Framework
SAS Publisher Requirements 176
How SAS Publisher Works
You use the SAS Publisher point−and−click interface to:
create a package of items1. deliver the package to one or more specified recipients (persons), or to a destination (for persons or
applications to access directly).
2.
Package creation and delivery is known collectively as publishing.
SAS Publisher functions are organized into the following tabs:
What to Publish
defines the package contents
Where to Publish
identifies either the recipients of or the destination for the package delivery
How to Publish
specifies optional package properties, such as archiving, expiration time and date, and options that are specific
to the specified delivery type.
Viewers
specifies a particular viewer template file (target viewer or applied viewer) and the reference type of the
viewer.
Publish Options
specifies additional options or properties based on the destination type.
Once you specify the required information on all tabs, the buttons along the right side of the What to Publish tab
become available for use. You can either publish the package immediately, or you can delay publishing and save the
underlying metadata that is generated during your SAS Publisher session so that you can continue editing it.
OK (Publish Package)
publishes the package and saves the metadata that defines the package. If you use SAS Publisher from
SAS/Warehouse Administrator, the OK (Save Metadata) button replaces the OK (Publish Package) button.
View Publish Code
displays the SAS code that SAS Publisher uses to create the metadata for publishing the package. You can
then save the code for later reuse–for example, publishing in a batch job.
Save Package Definition
saves the metadata that defines the package. You can then reuse that metadata by specifying the PUBMETA
parameter when starting SAS Publisher. See Starting SAS Publisher for details. All items that you want to
include in the package must already exist and be accessible when you publish it.
Publishing Framework
How SAS Publisher Works 177
Publishing Destination Types
A publishing destination type is the transport that the publisher selects for the delivery of a package to the intended
audience. You can choose from the following destinations:
E−Mailspecifies a common method for delivering a package to recipients whose identities are known to the publisher.
Message Queue
specifies a place in application messaging where one program (such as SAS Publisher) can send messages that
another program (such as SAS Package Retriever or a customized retrieval program) can retrieve. The two
programs communicate asynchronously without any knowledge of where the other program is located or even
whether the other program is running.
SAS Channel Subscribers
specifies a topic or identifier that acts as a conduit for related information. The channel carries the information
from the publisher who creates it to the subscribers who want it.
The Publishing Framework administrator creates a channel for each distinct topic or audience. For example,
users of a particular application might want a channel for discussion and data exchange, while the
programmers of that application might want another channel to discuss technical problems and future
enhancements. To be able to use them, the publisher must be aware of the channels that were defined in the
Publishing Framework.
Archivespecifies a package that is compressed and saved to a directory file. You can also catalog the archive in an
LDAP directory.
The archive contains the contents of a package and metadata that is necessary for extracting the contents. SAS
Publisher compressed an archive using ZIP compression and saves it with an SPK extension. SAS Publisher
then saves it to the location that you specified, which it remains available to users until its expiration date.
WebDAV (Web Distributed Authoring and Versioning−compliant server)
specifies an emerging industry standard that is based on extensions to HTTP 1.1. It lets package publishers,
programmers, and package retrievers collaborate on the development of files and collections of files on
remote Web servers. It also lets publishers publish packages to a Web−compliant server.
Publishing Framework
Publishing Destination Types 178
Starting SAS Publisher
SAS Publisher runs in UNIX and Windows operating environments.
You can start SAS Publisher from a SAS session or from within SAS/Warehouse Administrator.
Starting SAS Publisher from a SAS Session
To start SAS Publisher from a SAS session, enter the following in a SAS command line:
publishpackage <pubmeta=SAS−data−set>;
If you previously saved session metadata to a specific SAS data set, you can use the pubmeta= option to recall it in a
subsequent SAS Publisher session so that you can continue editing it.
As a shortcut, you can also enter the following in the command line:
publish
The following is an example of how to use the publishpackage command with the pubmeta= option:
publishpackage pubmeta=sasuser.code
where sasuser is the libname and code is the member name.
If the libname or the member name does not exist–for example, because of a typographical error–SAS Publisher
presents a message, such as:
Member CODE does not exist. Using SASUSER.ZPUBLISH instead.
To recover, verify the libname and member name that you specified. You can restart SAS Publisher, recalling the
correct libname and member name, or you can accept the metadata that has been saved to SASUSER.ZPUBLISH. All
metadata that is generated in a SAS Publisher session that you publish is automatically saved to
SASUSER.ZPUBLISH.
In addition, metadata from a subsequent SAS Publisher session overwrites the metadata that was generated in the
preceding publishing session.
Starting SAS Publisher from SAS/Warehouse Administrator
To start SAS Publisher as a SAS/Warehouse Administrator add−in, you must first install SAS Publisher as an add−in.
For details, see Using SAS Publisher with SAS/Warehouse Administrator.
After you have installed SAS Publisher as an add−in, select an item in a data warehouse and select Tools Add−ins
Define Package to Publish.
Publishing Framework
Starting SAS Publisher 179
Publishing a Package
You use the SAS Publisher point−and−click interface to:
create a package of items1. deliver the package to one or more specified recipients (persons) or to a destination (for persons or
applications to access directly).
2.
Package creation and delivery is known collectively as publishing.
To publish a package, you must provide the appropriate information using the SAS Publisher tabs and then run the
publish request. Here are the basic steps:
Define the package content in the What to Publish tab.1. Identify either the recipients of or the destination for the package delivery in the Where to Publish tab.2. In the How to Publish tab, specify whether to package the items in compressed (or SPK, short for SAS
Package) format, specify additional package options, and set an expiration date for the package. The fields in
the Options for Publishing panel vary based on the destination type you select on the Where to Publish tab.
3.
In the Viewers tab, specify the reference type of the viewer and whether it is a process viewer. Then select or
enter a viewer template file in the Viewer, Target Viewer, or Applied Viewer fields. Specify a MIME type if
you selected a target viewer.
For more information about viewers, see the section on Viewer Processing.
4.
In the Publish Options tab, specify additional options or properties, which are based on the destination type.5. Run an appropriate publish request by selecting a processing button on the What to Publish tab.6.
Publishing Framework
Publishing a Package 180
Publishing a Package, and Saving and Viewing Publish
Code
After you specify the required information on all tabs, the buttons along the right side of the What to Publish tab
become available for use.
You can either publish the package immediately, or you can delay publishing and save the underlying metadata that is
generated during your SAS Publisher session for continued editing.
Select a publishing option by clicking the appropriate button.
OK (Publish Package)
publishes the package immediately. If the package is published successfully, SAS Publisher saves the
metadata that describes the package to the SASUSER.ZPUBLISH data set by default. In addition, the saved
metadata repopulates the Items to Include in Package window of the What to Publish tab the next time you
start SAS Publisher. All items that you include in the package must be accessible when you define and
actually publish the package.
This button is available only after you specify all information that is required to publish a package.
View Publish Code
displays the underlying code, in the Generated Code to Publish the Specified Package window, that SAS
Publisher generates automatically when you publish the package. After the code displays, you can save and
run it later–for example, to publish information in a batch job. You can run this code in a SAS session by
cutting and pasting it into the SAS Program Editor window and submitting it.
Save Publish Definition
displays a Save As window that lets you navigate a directory structure so that you can save the package
definition to a file at a specified location. The saved file contains the metadata that is used to generate the
publish code in a SAS data set. You can republish the package by starting SAS Publisher with the
PUBMETA=libref.member parameter, which automatically populates the package information into the SAS
Publisher fields. Because the metadata for each package is saved in a separate data set, you can republish the
same package multiple times. You can also save variations of the same package to separate data sets for
subsequent publishing.
You can save the package definition at any time, even if you have not yet supplied all information that is
required to publish a package.
OK (Save Metadata)
saves the package metadata and exits the window.
This button appears only if you use SAS Publisher from SAS/Warehouse Administrator.
Execute Publish Code
publishes the package.
Publishing a Package, and Saving and Viewing Publish Code 181
This button appears only if you use SAS Publisher from SAS/Warehouse Administrator.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Publishing a Package, and Saving and Viewing Publish Code 182
Defining Package Content (What to Publish)
You can use the What to Publish tab to specify the items to include in the package.
Activate the What to Publish tab in the SAS Publisher window by selecting the tab title.
When you start SAS Publisher for the first time, the fields in the What to Publish tab are empty. Otherwise,
these fields already contain data from previous SAS Publish sessions. If you specified package metadata when
you started SAS Publisher, the content of that package automatically displays in the fields of this tab. If you
did not specify package metadata, the metadata from the last successful publish displays. By default, SAS
Publisher stores the metadata in SASUSER.ZPUBLISH.
1.
The What to Publish tab includes fields you can use to provide both an optional brief description and an
optional lengthier abstract of the package. It also lists the content of an existing package in the Items to
Include in Package area.
2.
Buttons to the left of the package view area let you add, edit, delete, and reorder package items. To add an
item, click the Add Item button, which opens the Specify Item to Insert window. Use this window to specify
the item and its defining parameters. For details about adding an item, see the section on Adding an Item.
3.
Once you finish specifying items for the package, you must decide on the transport to use for delivering the
package to the intended audience. Select the Where to Publish tab.
4.
Publishing Framework
Defining Package Content (What to Publish) 183
Adding an Item (Specify Item to Insert)
Specify the type of item that you want to add to the package by clicking the appropriate Type of Item to
Publish button. By default, the SAS Data Set item is already selected. Additional fields and buttons might
appear, depending on which item type you select.
For details about specifying options and advanced settings that are specific to the item type, see the following
topics:
Adding a SAS data set♦ Adding a SAS data base, SAS catalog, or SQL view♦ Adding ODS output♦ Adding an external file♦ Adding a reference♦ Adding a viewer.♦
1.
Next to the item type label that appears in the Description field, enter a brief description of the item you
selected. SAS Publisher uses the description as an annotation for the item when it is listed in the Items to
Include in Package field in the What to Publish tab. Though optional, this step is recommended.
Use the Clear button to erase the contents of the field as needed.
2.
In the Item Name/Value (optional) field, enter one or more name/value pairs that describe the content of the
package item.
You should develop conventions for name/value pairs and publicize them throughout your enterprise. When
channel subscribers or developers of package−retrieval programs understand your name/value pair
conventions, they can write filters for incoming package content. For example, some package recipients might
be interested only in result data that can be displayed in tables, graphs, and memos. Others might be package
producers who depend on SAS data inputs for continued processing.
Here is an example of some name/value pairs for a SAS data set package item:
3.
Adding an Item (Specify Item to Insert) 184
type=SAS dataset content=ticketsales priority=low
In this example, the publisher identifies the package item type as a SAS data set. Subscribers who filter out
SAS data sets will not receive this package entry. In addition, a retrieval program that filters only
high−priority package items will not select this package entry for delivery with the package. However, filters
that select content that relates to ticket sales will be delivered.
Once you have finished specifying the item, click OK to return to the What to Publish tab. The added item
displays in the Items to Include in Package window.
You can click the Add Item button to add more items to the package. Or you can select an item from the
window to perform any of the following actions:
edit by clicking Edit Item♦ delete by clicking Remove♦ rearrange by clicking Move Up or Move Down.♦
4.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Adding an Item (Specify Item to Insert) 185
Adding a SAS Data Set to a Package
If you specify SAS Data Set as the item type in the Specify Item to Insert window, additional fields and an additional
button appear in the Specify Item to Insert window.
Specify the format for the SAS data set by clicking the appropriate Packaging Format for Dataset button:
Native SAS Dataset
maintains SAS data in a proprietary format that is necessary for continued data processing in a SAS
environment.
Comma Separated Value
specifies a delimiter character that SAS Publisher uses to separate data columns, which is useful when
exporting SAS data to an external application, such as a third−party spreadsheet. A comma is the
default delimiter.
If you choose a comma−separated list format, you can accept the default delimiter or enter an alternative
delimiter in the Separator to Use for CSV field. You can also specify whether to exclude variable names,
labels, or both from the file by clicking the appropriate check boxes.
1.
Identify the instance of the item to be included in the package. Click the Select Data Set to Publish button to
display the Select a Member window, which works similarly to an Explorer window and lets you navigate a
directory structure so that you can locate and select the item to be included in the package.
Select a data set and click OK. The Select a Member window closes, and the name of the data set appears
automatically in the Select Data Set to Publish field in the Specify Item to Insert window.
2.
You can also specify a description and a name/value pair. For details, see Adding an Item (Specify Item to
Insert).
3.
In the Data Set Options field, specify options as a text string in the following form:
option1=value option2=value ...
For example:
pw='born2run' keep=empno
Surround string values, such as a password, with single quotation marks.
You can specify a value for data set options that apply to a data set that is opened for input.
The following are examples of options that you can specify in this field.
GENNUM=♦ LABEL=♦ OUTREP=♦ SORTEDBY=♦ TOBSNO=♦ TRANTAB=♦ PW=♦ READ=♦ WRITE=♦ ALTER=♦ FIRSTOBS=♦
4.
Adding a SAS Data Set to a Package 186
OBS=♦ WHERE=♦ IDXNAME=♦ IDXWHERE=♦ DROP=♦ KEEP=♦ RENAME=♦
For a complete list of data set options, refer to the SAS Data Set Options topic in either the SAS Online Help,
Release 9.0, or the SAS Release 9 online documentation.
To include either a read− or password−protected data set in the package, check Allow Read Protected Data
Sets to be Published.
If the data set that you specify is read−protected, you must also assign a password value to the PW= data set
option. This is the same password that the user must supply to access the read−protected data set when
retrieving the package. Publishing fails if you do not select the check box or specify a valid password. If you
do not select the check box, the SAS log contains the following message:
Publish of package failed −
ERROR: Unable to publish read protected data set
5.
From the Specify Item to Insert window, click OK again to return to the What to Publish tab to continue
specifying the package.
6.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Adding a SAS Data Set to a Package 187
Adding a SAS Database, SAS Catalog, or SQL View to a
Package
If you specify a SAS database type such as FDB or MDDB, a SAS catalog, or an SQL view as the item type in the
Specify Item to Insert window, a standard set of fields appears on the Specify Item to Insert window.
Identify the instance of the item to be included in the package. Click the Select item to Publish button to
display the Select a Member window, which works similarly to an Explorer window, which lets you navigate
a directory structure so that you can locate and select the item to be included in the package.
Select the appropriate item and click OK. Control returns to the Specify Item to Insert window, where the
name of the item appears automatically in the Select item to Publish field.
1.
Optionally, specify a description and a name/value pair. For details, see Adding an Item (Specify Item to
Insert).
2.
From the Specify Item to Insert window, click OK to return to the What to Publish tab to continue specifying
the package.
3.
Publishing Framework
Adding a SAS Database, SAS Catalog, or SQL View to a Package 188
Adding ODS Output to a Package
If you specify SAS ODS Output (HTML) as the item type on the Specify Item to Insert window, some
additional fields appear in the Specify Item to Insert window.
1.
Click the Select ODS Output to Publish button to display the SAS ODS Output to Publish window. The
SAS ODS Output to Publish window enables you to specify the location of ODS files to include in the
package.
2.
The Files Identified By field enables you to specify whether to use the physical filename of the file or a SAS
file reference. Select either the File Name or File Reference radio button to specify your preferred file
referencing method. Subsequent field names reflect your selection.
3.
Specify the HTML files and any additional companion files that are associated with the ODS output in the
Physical Locations of ODS Files panel. For detailed instructions, refer to Specifying the Physical Locations of
ODS Files.
4.
Specify the Web addresses for the ODS files in the ODS File Names panel.5. Once you complete the information in the SAS ODS Output to Publish window, click OK. to return to the
Specify Item to Insert window.
6.
Optionally specify a description and a name/value pair. For details, see Adding an Item (Specify Item to
Insert).
7.
You can optionally specify the encoding property in the Encoding field. Character−set encoding refers to how
a host internally represents character data. Hosts that share common architectures represent character data
identically. For example, UNIX hosts internally represent character data in ASCII−ISO format, z/OS hosts in
EBCDIC format, and Windows hosts in ASCII−ANSI format.
ODS files are published with a character−set encoding that is automatically generated by default or is
user−specified. Under some circumstances–for example, when publishing and retrieving host architectures are
8.
Adding ODS Output to a Package 189
different–you might decide to identify a character−set encoding that is appropriate for the retrieving host. This
information is delivered with the published package. Translation occurs on the retrieving host, not the
publishing host.
For complete details about publish−and−retrieve encoding behavior, see Publish/Retrieve Encoding Behavior.
You can optionally specify a nested directory in the Nested Directory Name field.9. From the Specify Item to Insert window, click OK again to return to the What to Publish tab to continue
specifying the package.
10.
Specifying the Physical Locations of ODS Files
If you use file names, you must specify the root location for the HTML files. This is the directory where the
HTML files are assumed to exist unless you specify otherwise.
You can use the down arrow button if present, to choose previously selected directory locations. You can also
use the right arrow button to explore your directory structure to locate the appropriate file name or fileref.
1.
Specify the file name or fileref for the body, contents, frame, and page files. You can use the down arrow
button if present, to choose previously selected directory locations. You can also use the right arrow button to
explore your directory structure to locate the appropriate file name or fileref.
Body File Name / Reference
specifies the file name or reference of the body file for the ODS output. This file contains the
generated HTML output that is created by the output objects.
If you specify file names, you can use an asterisk as a wildcard character in this field to include
multiple body files. This is useful because ODS names multipage output using a consecutive
numbering system–for example, body.html, body1.html, body2.html. Specifying body*.html lets you
include all generated body files in the package.
Contents File Name / Reference
specifies the file name or reference for the output's contents file. The contents file contains a link to
the body file for each HTML table that ODS creates from procedure or DATA step results.
Frame File Name / Reference
specifies the file name or reference for the output's frame file. The frame file lets you view the body
and contents files, the page file, or all three files.
Page File Name / Reference
specifies the file name or reference for the output's page file. The page file contains a link to the body
file for each page of HTML output that ODS creates from procedure or DATA step results.
2.
Specify the file name or fileref for any companion files. You can use the down arrow button (next to the
Companion File number field) to choose previously selected directory locations. You can also use the right
arrow button to explore your directory structure to locate the appropriate file name or fileref.
A companion file is an HTML file that you can add to a set of HTML files. Typically not an ODS−generated
file, a companion file is an HTML file that is referenced for inclusion in the ODS−generated file. Therefore,
one or more HTML files serve as companions to the ODS−generated file.
3.
To include graphics in the ODS output, specify the path to the graphics directory and the HTML file name of
the graphics file in the Graphics Path and the Graphics URL fields. You can use the down arrow button (next
to the Graphics Path field) to choose previously selected directory locations. You can also use the right arrow
button to explore your directory structure.
4.
SAS® Integration Technologies: Developer's Guide
Adding ODS Output to a Package 190
Specifying ODS File Names
The following fields enable you to specify Web addresses for the ODS files.
Body URL
specifies the HTML file name of the body file. If you specify File Name in the Files Identified By field, you
cannot enter a value in this field; rather, the value is that specified in the Body File Name field.
Contents URL
specifies the HTML file name of the contents file. If you specify File Name in the Files Identified By field,
you cannot enter a value in this field; rather, the value is that specified in the Contents File Name field.
Frame URL
specifies the HTML file name of the frame file. If you specify File Name in the Files Identified By field, you
cannot enter a value in this field; rather, the value is that specified in the Frame File Name field.
Page URL
specifies the HTML file name of the page file. If you specify File Name in the Files Identified By field, you
cannot enter a value in this field; rather, the value is that specified in the Page File Name field.
Companion URL number
specifies the HTML file name of the companion file. If you specify File Name in the Files Identified By field,
you cannot enter a value in this field; rather, the value is that specified in the Companion File number field.
Publishing Framework
SAS® Integration Technologies: Developer's Guide
Adding ODS Output to a Package 191
Adding an External File to a Package
If you specify External File as the item type on the Specify Item to Insert window, some additional fields appear in the
Specify Item to Insert window.
Specify whether the file contains text or binary data by clicking the appropriate button in the External File
Type field.
1.
Specify the type of data that the file contains and the data format of the file by selecting a value for the
Mimetype field. For example, a mime type of image/gif specifies that the file contains an image in GIF
format. A mime type of application/postscript specifies that the file contains application data that should be
treated as a postscript file.
You can customize the drop−down menu of mime types that appears for this field. The default field values are
contained in SASHELP.PUBLISH.MIMETYPES.SLIST. You can add your own mime values to either of the
following locations:
WORK.PUBLISH.MIMETYPES.SLIST♦ SASUSER.PUBLISH.MIMETYPES.SLIST♦
You can write an SCL application to create a MIMETYPES.SLIST in the WORK.PUBLISH or
SASUSER.PUBLISH catalog. For details about writing such an SCL application, refer to the SAS Component
Language: Reference in the SAS online documentation.
2.
Identify the instance of the external file that you want to include in the package. You can specify an external
file in either of the following ways:
Enter the name of the external file directly in the field to the right of the Select External File to
Publish button.
♦
Click the Select External File to Publish button to display the Open window that lets you navigate a
directory structure so that you can locate and select the external file that you want to include in the
package. Select an external file and click OK.
Focus returns to the Specify Item to Insert window, where the external file name appears
automatically in the Select External File to Publish field.
♦
3.
Optionally, specify a description and a name/value pair.
For details, refer to Adding an Item (Specify Item to Insert).
4.
Once you finish specifying external file options, click OK to return to the What to Publish tab.5.
Publishing Framework
Adding an External File to a Package 192
Adding a Reference to a Package
If you specify Reference as the item type on the Specify Item to Insert window, some additional fields appear in the
Specify Item to Insert window.
In the Reference Type panel, indicate whether the reference type is a URL or HTML.1. You can specify the reference in either of two ways:
Enter a prefix and a name directly in the field to the right of the Select Reference to Publish button.
The following prefixes are acceptible:
http://
ftp://
file:///
For instance, a typical URL specification is
http://www.mycorp.com/chart.html
As an alternative, you can specify a URL that is relative to a base URL location. For example, if the
base URL is www.mycorp.com, then the relative URL ./news/article.html locates article.html in the
news subdirectory, which is relative to the base URL.
♦
Click the Select Reference to Publish button, which displays the Open window. This window lets
you navigate a directory structure so that you can locate and select the item that you want to include
in the package.
Select a URL and click OK. Focus returns to the Specify Item to Insert window, where the reference
address appears automatically in the Select Reference to Publish field.
♦
2.
Optionally, specify a description and a name/value pair. For details, see Adding an Item (Specify Item to
Insert).
3.
Publishing Framework
Adding a Reference to a Package 193
Adding a Viewer to a Package
If you specify Viewer as the item type on the Specify Item to Insert window, some additional fields appear in the
Specify Item to Insert window.
In the Viewer Type panel, indicate whether the viewer type is HTML or Text.1. Specify the type of data that the file contains and the data format of the file by selecting a value for the
Mimetype field. For example, a mime type of image/gif specifies that the file contains an image in GIF
format. A mime type of application/postscript specifies that the file contains application data that should be
treated as a postscript file.
You can customize the drop−down menu of mime t