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

User Manual:

Open the PDF directly: View PDF .
Page Count: 899

Download
Open PDF In Browser	View PDF

SAS 9.1.3 Integration 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.

SAS® Integration Technologies: Developer's Guide

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

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

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
Tag.....................................................................................................................................................155
Substitution Syntax......................................................................................................................................................156
Tag.......................................................................................................................................................160
Tag....................................................................................................................................................162
Tag........................................................................................................................................................164
Using the and Tags: Examples..............................................................................165
Sample HTML Viewer.................................................................................................................................................166
Rendered View in E−mail............................................................................................................................................167

iii

SAS® Integration Technologies: Developer's Guide

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

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

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

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

vii

SAS® Integration Technologies: Developer's Guide

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

viii

SAS® Integration Technologies: Developer's Guide

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

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

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

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

xii

SAS® Integration Technologies: Developer's Guide

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

xiii

SAS® Integration Technologies: Developer's Guide

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

xiv

SAS® Integration Technologies: Developer's Guide

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

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

xvi

SAS® Integration Technologies: Developer's Guide

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

xvii

SAS® Integration Technologies: Developer's Guide

Table of Contents
_OPEN...........................................................................................................................................................................872
_SETOPTIONS............................................................................................................................................................875
_SEARCH.....................................................................................................................................................................877

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

SAS® Integration Technologies: Developer's Guide
• 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 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

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

SAS® Integration Technologies: Developer's Guide

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
Stored Process Software Requirements

SAS® Integration Technologies: Developer's Guide
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

Stored Process Software Requirements

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:
1. Writing the Stored Process
2. Choosing or Defining a Server
3. Registering the Metadata

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

SAS® Integration Technologies: Developer's Guide
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:
Creating Stored Processes

SAS® Integration Technologies: Developer's Guide
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

Creating Stored Processes

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
(¶m−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

SAS® Integration Technologies: Developer's Guide
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.

Input Parameters

SAS® Integration Technologies: Developer's Guide

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

value="optTwo">
value="optThree">
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.

Input Parameters

SAS® Integration Technologies: Developer's Guide
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
0, the first value is set in 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

Input Parameters

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

SAS® Integration Technologies: Developer's Guide
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

Result Types

%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

SAS® Integration Technologies: Developer's Guide
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
%STPBEGIN and %STPEND

SAS® Integration Technologies: Developer's Guide
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
%STPBEGIN and %STPEND

SAS® Integration Technologies: Developer's Guide
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
%STPBEGIN and %STPEND

SAS® Integration Technologies: Developer's Guide
◊ _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

%STPBEGIN and %STPEND

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
_ABSTRACT

Used By

Description

%STPBEGIN/ Text string briefly describing a package created by
%STPEND
%STPBEGIN and %STPEND.
Specifies an action for the Web application to take.
Possible values for this variable are as follows:
FORM

_ACTION

Web Clients

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

SAS® Integration Technologies: Developer's Guide
_ADDRESSLIST_DATASET_LIBNAME,
_ADDRESSLIST_DATASET_MEMNAME,
_ADDRESSLIST_VARIABLENAME,
_DATASET_OPTIONS

%STPBEGIN/ Specifies a data set containing email addresses
%STPEND
when _RESULT is set to PACKAGE_TO_EMAIL.

_APSLIST

Stored Process List of the names of all the parameters that were
Server
passed to the program.

_ARCHIVE_FULLPATH

Full path and name of an archive package created
by %STPEND when _RESULT is set to
%STPBEGIN/ PACKAGE_TO_ARCHIVE or
%STPEND
PACKAGE_TO_REQUESTER. This value is set by
%STPEND and is an output value only. Setting it
before %STPEND has no effect.

_ARCHIVE_NAME

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
%STPBEGIN/
PACKAGE_TO_REQUESTER, then the package is
%STPEND
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

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
%STPBEGIN/ be directly overridden by a client input parameter.
The special value TEMPFILE causes the archive
%STPEND
package to be created in a temporary directory that
exists only until the stored process completes
executing and the client disconnects from the
server.
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.

_AUTHTYP

Web Clients

_CHANNEL

Specifies a subscriber channel when _RESULT is
%STPBEGIN/ set to PACKAGE_TO_SUBSCRIBERS. See
%STPEND
PACKAGE_PUBLISH for more information about
channel names.

_COLLECTION_URL

URL of the WebDAV collection to be created
when _RESULT is set to
%STPBEGIN/ PACKAGE_TO_WEBDAV. See also _IF_EXISTS.
%STPEND
This value is set through the stored process service
API and cannot be directly overridden by a client
input parameter.

_DEBUG

Web Clients

Reserved Macro Variables

Debugging flags. For information about setting the
default value of _DEBUG, see Setting the Default
22

SAS® Integration Technologies: Developer's Guide
Value of _Debug.
_DESCRIPTION

%STPBEGIN/ Descriptive text embedded in a package created by
%STPEND
%STPBEGIN and %STPEND.

_DOMAIN

Web Clients

_EMAIL_ADDRESS

Specifies destination e−mail addresses when
_RESULT is set to PACKAGE_TO_EMAIL.
%STPBEGIN/
Multiple addresses can be specified using the
%STPEND
multiple value convention for stored process
parameters.

_ENCODING

%STPBEGIN/
Sets the encoding for all ODS output.
%STPEND

_EXPIRATION_DATETIME

Expiration datetime embedded in a package
%STPBEGIN/
created by %STPBEGIN and %STPEND. Must be
%STPEND
specified in a valid SAS datetime syntax.

_FROM

%STPBEGIN/ Specifies the e−mail address of the sender when
%STPEND
_RESULT is set to PACKAGE_TO_EMAIL.

_GOPT_DEVICE, _GOPT_HSIZE,
_GOPT_VSIZE, _GOPT_XPIXELS,
_GOPT_YPIXELS

Sets the corresponding SAS/GRAPH option. See
the DEVICE, HSIZE, VSIZE, XPIXELS, and
%STPBEGIN/ YPIXELS options in "Graphics Options and
Device Parameters Dictionary" in the SAS/GRAPH
%STPEND
Reference in SAS Help and Documentation for
more information.

_GOPTIONS

Sets any SAS/GRAPH option documented in
"Graphics Options and Device Parameters
Dictionary" in the SAS/GRAPH Reference in SAS
%STPBEGIN/ Help and Documentation. You must specify the
option name and its value in the syntax used for
%STPEND
the GOPTIONS statement. For example, set
_GOPTIONS to ftext=Swiss htext=2 to
specify the Swiss text font with a height of 2.

Authentication domain for the SAS Stored Process
Web Application.

Web Clients

URL for the location of SAS/GRAPH applets. This
variable is set to /sasweb/graph for most
installations.

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.

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/ Password used (with _HTTP_USER) to access the
%STPEND
WebDAV server when _RESULT is set to
PACKAGE_TO_WEBDAV. This value is set through

_GRAFLOC

_HTACPT

_HTCOOK

Reserved Macro Variables

SAS® Integration Technologies: Developer's Guide
the stored process service API and cannot be
directly overridden by a client input parameter.

_HTTP_PROXY_URL

Proxy server used to access the WebDAV server
when _RESULT is set to
%STPBEGIN/
PACKAGE_TO_WEBDAV. This value is set through
%STPEND
the stored process service API and cannot be
directly overridden by a client input parameter.

_HTTP_USER

User name used (with _HTTP_PASSWORD) to
access the WebDAV server when _RESULT is set
%STPBEGIN/
to PACKAGE_TO_WEBDAV. This value is set
%STPEND
through the stored process service API and cannot
be directly overridden by a client input parameter.

_HTUA

Web Clients

_IF_EXISTS

Can be NOREPLACE, UPDATE, or
%STPBEGIN/
UPDATEANY. See PACKAGE_PUBLISH
%STPEND
options for more information.

_MESSAGE_QUEUE

Specifies a target queue when _RESULT is set to
PACKAGE_TO_QUEUE. See
%STPBEGIN/ PACKAGE_PUBLISH for more information about
queue names. Multiple queues can be specified
%STPEND
using the multiple value convention for stored
process parameters.

Specifies the name of the user agent. This variable
is not set by default but can be enabled in the
params.config file.

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/ Applies to packages only. See PACKAGE_BEGIN
%STPEND
for more information about this variable.

_NAMEVALUE

A list of one or more name/value pairs used for
%STPBEGIN/ filtering when generating packages. See
PACKAGE_BEGIN for more information about
%STPEND
this variable.

_METAPERSON

_ODSDEST

%STPBEGIN/ Specifies the ODS destination. The default ODS
%STPEND
destination is HTML if _ODSDEST is not
specified. Valid values of _ODSDEST include the
following:
• CSV
• CSVALL
• TAGSETS.CSVBYLINE
• HTML
• LATEX

Reserved Macro Variables

SAS® Integration Technologies: Developer's Guide
• NONE (no ODS output is generated)
• PDF
• PS
• RTF
• SASREPORT
• WML
• XML
• any tagset destination

_ODSOPTIONS

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
%STPBEGIN/
_ODSENCODING.
%STPEND
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/ Sets the ODS STYLE= option. You can specify
%STPEND
any ODS style that is valid on your system.

_ODSSTYLESHEET

Sets the ODS STYLEHEET= option. To store a
generated style sheet in a catalog entry and
%STPBEGIN/
automatically replay it using the SAS Stored
%STPEND
Process Web Application, specify myfile.css
(url="myfile.css")
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:
_PROGRAM

All
//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
Reserved Macro Variables

SAS® Integration Technologies: Developer's Guide
Stored Process A complete URL for use with programs that use
Server/Web
the Output Delivery System (ODS). It is composed
Client
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

Specifies a designated e−mail address to which
%STPBEGIN/
package recipients might respond when _RESULT
%STPEND
is set to PACKAGE_TO_EMAIL.

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

_REPOSITORY

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.

Reserved Macro Variables

SAS® Integration Technologies: Developer's Guide
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.

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.

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

A unique identifier for the session. The
Stored Process
_SESSIONID variable is created only if a session
Server
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.

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.

_RMTADDR

_RMTHOST

_SRVPROT

Reserved Macro Variables

SAS® Integration Technologies: Developer's Guide
Identifies the Web server software. This variable is
not set by default but can be enabled in the
params.config file.

_SRVSOFT

Web Clients

_STPERROR

Global error variable. Set to 0 if %STPBEGIN and
%STPBEGIN/
%STPEND complete successfully. Set to a
%STPEND
non−zero numeric value if an error occurs.

_STPWORK

Specifies a temporary working directory to hold
%STPBEGIN/ files that are published in a package. This variable
%STPEND
is set by %STPBEGIN and is not modified by the
stored process.

_SUBJECT

%STPBEGIN/ Specifies a subject line when _RESULT is set to
%STPEND
PACKAGE_TO_EMAIL.

_THISSESSION

A URL composed from the values of _URL and
_SESSIONID. This variable is created by the
Stored Process stored process server and is used as the base URL
for all URL references to the current session. The
Server/Web
_THISSESSION variable is created only if the
Client
_URL variable is passed in and a session has been
explicitly created.

_TMPCAT

A unique, temporary catalog name. This catalog
can be used to store temporary entries to be
retrieved later. In socket servers, the _TMPCAT
Stored Process catalog is deleted after a number of minutes
specified in the variable _EXPIRE. This variable is
Server
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

Reserved Macro Variables

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

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'); version=SAS Stored Processes
put version=;
Version 9.1 (Build 18)

SAS Stored Processes

STPSRVGETC

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

SAS® Integration Technologies: Developer's Guide
SAS Stored Processes

STPSRVGETN

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

SAS® Integration Technologies: Developer's Guide
SAS Stored Processes

STPSRVSET

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

SAS® Integration Technologies: Developer's Guide
/* add pragma header*/
Cache−control: no−cache
rc = stpsrv_header('Cache−control',
'no−cache');
/* add expires header */
Content−type: text/html
rc = stpsrv_header('Expires','Thu, Cache−control: no−cache
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','');

SAS Stored Processes

STPSRV_HEADER

STPSRV_SESSION
Creates or deletes a session
Syntax
Arguments
Details
Examples

Syntax
RC = STPSRV_SESSION( 'command' , )
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".
timeout
is 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

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

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

SAS® Integration Technologies: Developer's Guide
file _webout;
put '';
put '';
put 'Session Test Page';
/* Link to another stored process in the same session */
put 'Test';
put '';
put '';
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.

Sessions

SAS® Integration Technologies: Developer's Guide
SAS Stored Processes

Sessions

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

SAS® Integration Technologies: Developer's Guide
_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
_RESULT

Value
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
Stored Process Samples

SAS® Integration Technologies: Developer's Guide

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
_RESULT

Value
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

Stored Process Samples

SAS® Integration Technologies: Developer's Guide
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
_RESULT

Value
STATUS (is modified in the stored process)

_EMAIL_ADDRESS DeptManagers@abc.com

Stored Process Samples

SAS® Integration Technologies: Developer's Guide
_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

Stored Process Samples

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

Summary. The stored process server only logs an identifying build statement and error conditions.

Default. 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.

Full. The stored process server logs APPLEVEL=1 messages, except that the SAS log is included
for every stored process executed on the server.

Debug. 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

SAS® Integration Technologies: Developer's Guide
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

Debugging Stored Processes

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:
1. 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.
2. Modify the program as required to address the compatibility issues discussed in the Issues section.
3. 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.
4. Register the stored process using BI Manager. Choose Streaming for the type of output. You do not need
to register any parameter definitions.
5. 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.
6. Run the stored process.
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

SAS® Integration Technologies: Developer's Guide

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,
Converting SAS/IntrNet Programs to Stored Processes

SAS® Integration Technologies: Developer's Guide
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 ' ' ;
put 'Test.
If you see this in order, it worked.';
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 ' ' ;
put 'Test.
If you see this in order, it worked.';
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=' ' ;
ods html text='Test.
If you see this in order, it worked.';
... other code ...
ods html close;

SAS Stored Processes
Converting SAS/IntrNet Programs to Stored Processes

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

SAS® Integration Technologies: Developer's Guide
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

Using Stored Processes

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

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

SAS® Integration Technologies: Developer's Guide
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=
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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide
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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide

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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide

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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide
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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide
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 Stored Process Web Application

SAS® Integration Technologies: Developer's Guide
Execution Option
to Customize

SAS Variable Name
of Input Parameter

Output type

_ODSDEST

ODS style

_ODSSTYLE

Graphics device

_GOPT_DEVICE

Show SAS Log
Show execution time
Show execution trace

_DEBUG

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 Stored Process Web Application

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

Params.config

Description
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

SAS® Integration Technologies: Developer's Guide
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

servlet.auth.type

Recommended
SAS Variable
Name

_AUTHTYP

Description
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.
specifies the HTTP request header as received by the SAS Stored
Process Web Application.

servlet.header
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.

specifies a particular HTTP request header line as received by the
SAS Stored Process Web Application, where is the header
keyword name.

SAS Stored Process Web Application Configuration

SAS® Integration Technologies: Developer's Guide
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 Stored Process Web Application Configuration

SAS® Integration Technologies: Developer's Guide
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 Stored Process Web Application Configuration

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®ion=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

SAS® Integration Technologies: Developer's Guide
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 ®ion=West is interpreted as ®ion=West in some browsers. Use HTML
encoding to avoid this problem. For example, use

instead of

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 = '';

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 tag and ends with the 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 tag generally points to the Stored Process Web Application or a JSP that will
execute the stored process. The METHOD attribute of the 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,

Web Application Input

SAS® Integration Technologies: Developer's Guide
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
/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:
\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
Web Application Input

SAS® Integration Technologies: Developer's Guide
/Reports/East Region/Sales Summary 2005

would have a custom input form maintained and deployed from this location:
\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

Web Application Input

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

SAS® Integration Technologies: Developer's Guide
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
HTTP Headers

SAS® Integration Technologies: Developer's Guide
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.
HTTP Headers

SAS® Integration Technologies: Developer's Guide
SAS Stored Processes

HTTP Headers

Embedding Graphics
Web pages frequently contain embedded graphic images. For static images, an tag is enough to embed the
image:

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

SAS® Integration Technologies: Developer's Guide

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