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 i 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 ii 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................................................................................................................................................153Tag.....................................................................................................................................................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 iv 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 v 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 vi 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 ix 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 x 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 xi 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 xv 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 1 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 2 SAS Stored Processes A stored process is a SAS program that is stored on a server and can be executed as required by requesting applications. You can use stored processes for Web reporting, analytics, building Web applications, delivering packages to clients or to the middle tier, and publishing results to channels or repositories. Stored processes can also access any SAS data source or external file and create new data sets, files, or other data targets supported by SAS. The ability to store your SAS programs on the server provides an effective method for change control management. For example, instead of embedding the SAS code into client applications, you can centrally maintain and manage this code from the server. This gives you the ability to change your SAS programs and at the same time ensure that every client that invokes a stored process will always get the latest version available. The stored process concept becomes even more powerful when you consider that these SAS programs can be invoked from multiple client contexts. For example, you might deploy Java applets and Windows−based applications that invoke your stored processes. If your strategy is to use a multi−tiered architecture, you can use Enterprise JavaBeans (EJB) technology, for example, to invoke the same stored processes from an application server. Using stored processes also enhances security and application integrity because the programs that access your sensitive data are contained on the server instead of being widely distributed with the client applications. There are two different types of stored processes. A limited form of stored processes, IOM Direct Interface Stored Processes, was introduced in Version 8. This type of stored process operates on a SAS Workspace Server and produces packages only. IOM Direct Interface Stored Processes are still fully supported. However, the focus of this documentation is on SAS Stored Processes. SAS Stored Processes are new with SAS Integration Technologies 9, and they can be used with either a SAS Workspace Server (to produce packages) or a SAS Stored Process Server (to produce packages or streaming results). You must use a SAS Metadata Server to administer SAS Stored Processes. To make a stored process accessible to client applications, you must allocate a storage location that your server can access. Then, use BI Manager to create metadata that describes the stored process and its location. BI Manager stores this metadata on the SAS Metadata Server so that it can be accessed by client applications. Note: BI Manager is available beginning with SAS Foundation Services 1.2. If you have not upgraded to this release, then you can use Stored Process Manager to register and manage stored processes. BI Manager replaces Stored Process Manager. For more information about using BI Manager to create and maintain the metadata defining a stored process, see the Help in SAS Management Console. SAS Stored Processes SAS Stored Processes 3 Stored Process Software Requirements General Requirements To manage and execute SAS Stored Processes for any client environment, you must have the following components installed: • SAS System software • SAS Management Console • BI Manager plug−in (a component of SAS Foundation Services) Client−Specific Requirements Stored processes can be accessed from many different client environments. Software requirements vary depending on the client environment. To use SAS Stored Processes in a Web application environment, the following components are recommended: • Java Runtime Environment (JRE) or Java Development Kit (JDK) • Servlet container • SAS Web Infrastructure Kit or SAS Information Delivery Portal To use SAS Stored Processes in a Java application, the following components are required: • Java Development Kit (JDK) • Servlet container (for servlets or JSPs only) • SAS Foundation Services To access SAS Stored Processes from Microsoft Office, the following component is required: • SAS Add−In for Microsoft Office To access SAS Stored Processes from a Web services client, install one of the following components: • SAS BI Web Services for Java • SAS BI Web Services for .NET To author SAS Stored Processes in a task oriented user interface, install the following component: • SAS Enterprise Guide You can install all of the components on a single system or install them across multiple systems. A development system might have all of the components on a single desktop system while a production system might have SAS installed on one or more systems, a servlet container on another system, and client software installed on multiple client desktop systems. See the product documentation for the individual components for specific requirements on host platforms. Stored Process Software Requirements 4 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 5 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 6 Creating Stored Processes A stored process is a SAS program that is hosted on a server and described by metadata. Stored processes can be written by anyone who is familiar with the SAS programming language or with the aid of a SAS code generator such as SAS Enterprise Guide. The basic steps to creating a stored process are as follows: 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 7 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 8 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 9 Input Parameters Most stored processes require information from the client to perform their intended function. This information can be in the form of presentation options for a report, selection criteria for data to be analyzed, names of data tables to be used or created, or an unlimited number of other possibilities. Input parameters are the most common way to deliver information from a client to a stored process. Input parameters are defined as name/value pairs. They appear in a stored process program as global macro variables. For example, if you have a stored process that analyzes monthly sales data, you might accept MONTH and YEAR as input parameters. The stored process program might be: *ProcessBody; %stpbegin; title "Product Sales for &MONTH, &YEAR"; proc print data=sales; where Month eq "&MONTH" and Year eq &YEAR; var productid product sales salesgoal; run; %stpend; Because input parameters are simply macro variables, they can be accessed through normal macro substitution syntax (¶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 10 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 11 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 12 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 13 Result Types A stored process is a SAS program and can produce any kind of output that a valid SAS program can produce. Output could include data sets, external files, e−mail messages, SAS catalogs, packages, and many other objects. In some cases, output (or a "result") is delivered to the client application executing the stored process. In other cases, the output is generated only on the server. When creating a stored process, you must describe any output that is returned to the client. There are four types of client output. • The simplest result type is None. The client receives no output from the stored process. The stored process is still able to create or update data sets, external files or other objects, but this output remains on the server. This result type is indicated by the input parameter _RESULT set to STATUS, because only the program status is returned to the client. • Streaming output delivers a data stream, such as an HTML page or XML document, to the client. This result type is indicated by _RESULT set to STREAM. The data stream can be textual or binary data and is visible to the stored process program as the _WEBOUT fileref. Any data written to the _WEBOUT fileref is streamed back to the client application. Streaming output is supported only on the stored process server. Stored processes executing on a workspace server cannot use streaming output. • Transient package output returns a temporary package to the client. The package can contain multiple entries, including SAS data sets, HTML files, image files, or any other text or binary files. The package exists only as long as the client is connected to the server. This result type is a convenient way to deliver multiple output objects (such as an HTML page with associated GIF or PNG images) to a client application. Transient package output is available on both stored process and workspace servers, but the implementations differ. On the stored process server, transient package output is indicated by _RESULT set to PACKAGE_TO_ARCHIVE and the input parameter _ARCHIVE_PATH set to TEMPFILE. On the workspace server, transient package output is indicated by _RESULT set to PACKAGE_TO_REQUESTER. • Permanent package output creates a package in a permanent location on a WebDAV server or in the server file system. The package is immediately accessible to the stored process client, but is also permanently accessible to any client with access to WebDAV or the server file system. This result type is a convenient way to publish output for permanent access. Output to WebDAV is indicated by _RESULT set to PACKAGE_TO_WEBDAV. The input parameter _COLLECTION_URL contains the target location. The input parameters _HTTP_USER and _HTTP_PASSWORD might be set if the WebDAV server is secured and credentials are available. _HTTP_PROXY_URL is set if an HTTP proxy server is required to access the WebDAV server. Output to the server file system is indicated by _RESULT set to PACKAGE_TO_ARCHIVE. The input parameters _ARCHIVE_PATH and _ARCHIVE_NAME contain the target repository and filename, respectively. Note that although the result type is chosen when you define a stored process, the result type can be changed by the client application through calls to the Stored Process Service API. Where possible, it is recommended that you write stored processes to support any appropriate client result type. This enables a client application to select the result type most appropriate for that application. The program can determine the desired client result type by examining the _RESULT input parameter. The %STPBEGIN and %STPEND macros include support for any of the four result types. The following stored process is capable of generating streaming, transient package, or permanent package output. (It can also be run with _RESULT set to STATUS, but this would produce no useful result.) *ProcessBody; %stpbegin; proc print data=SASHELP.CLASS noobs; var name age height; run; %stpend; Result Types 14 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 15 %STPBEGIN and %STPEND The %STPBEGIN and %STPEND macros provide standardized functionality for generating and delivering output from a stored process. This enables you to write stored processes that generate content in a variety of formats and styles with minimal programming effort. A typical stored process using these macros follows: /* ***************************************************** * Header comment documenting your * stored process and input parameters. * ************************************************** */ %global input parameters; *ProcessBody; ... any pre−processing of input parameters ... %stpbegin; ... stored process body ... %stpend; Note: You must include a semicolon at the end of the %STPBEGIN and %STPEND macro calls. The %STPBEGIN macro initializes the Output Delivery System (ODS) to generate output from the stored process. The %STPEND macro terminates ODS processing and completes delivery of the output to the client or other destinations. The macros must be used as a matched pair for proper operation. Streaming output and package output are supported. These macros rely on many reserved macro variables to control their actions. See the section on Reserved Macro Variables for a more detailed description of each macro variable mentioned in the following sections. Stored processes that do not use ODS to generate output should not use these macros or should set _ODSDEST to NONE to disable ODS initialization. In this case, your stored process must explicitly create any output. ODS Options ODS options are specified by various global macro variables. These variables are normally set by input parameters, but can be modified by the stored process. The following variables affect ODS output: • _ENCODING • _GOPT_DEVICE • _GOPT_HSIZE • _GOPT_VSIZE • _GOPT_XPIXELS • _GOPT_YPIXELS • _GOPTIONS • _ODSDEST • _ODSOPTIONS • _ODSSTYLE • _ODSSTYLESHEET The _ODSDEST variable is important because changing this variable enables your stored process to generate HTML, PDF, postscript, or a variety of other formats, including user written tagset destinations. Note that there are many variables that allow you to override ODS options. You must remember to verify whether any options specified by the %STPBEGIN and %STPEND 16 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 17 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 18 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 19 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 20 Reserved Macro Variables Many reserved macro variables are reserved for special purposes in stored processes. Reserved names generally are prefixed with an underscore character. It is recommended that you do not use the underscore prefix for any application variables to avoid conflicts. Some reserved macro variables are created automatically for all stored processes running on a particular server. Some are created by specific stored process client or middle−tier interfaces and are not created or available when other clients call the stored process. Variable Name _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 21 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 23 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 24 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 25 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 26 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 27 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 28 Stored Process Server Functions Stored process server functions are DATA step functions that you use to define character, numeric, and alphanumeric strings to generate output in the desired format. The following list of SAS Stored Process Server functions can be used to return the correct character, numeric, or alphanumeric value of a parameter setting. • STPSRVGETC • STPSRVGETN • STPSRVSET • STPSRV_HEADER • STPSRV_SESSION • STPSRV_UNQUOTE2 Note: You can also use APPSRV syntax from the Application Dispatcher in place of these functions. See the Application Dispatcher documentation for more information. SAS Stored Processes Stored Process Server Functions 29 STPSRVGETC Returns the character value of a server property Syntax Arguments Details Examples Syntax VALUE = STPSRVGETC( valuecode ) Note: The APPSRVGETC function can be used in place of STPSRVGETC. This feature is provided in order to enable you to convert existing SAS/IntrNet programs to stored processes. Arguments valuecode is the character string name of the property. Details The STPSRVGETC function takes one character string property and returns a character string result. Examples SAS Statements Results sencoding=stpsrvgetc('Default Output Encoding'); put sencoding=; sencoding=WLATIN1 version=stpsrvgetc('version'); version=SAS Stored Processes put version=; Version 9.1 (Build 18) SAS Stored Processes STPSRVGETC 30 STPSRVGETN Returns the numeric value of a server property Syntax Arguments Details Examples Syntax VALUE = STPSRVGETN( valuecode ) Note: The APPSRVGETN function can be used in place of STPSRVGETN. This feature is provided in order to enable you to convert existing SAS/IntrNet programs to stored processes. Arguments valuecode is the character string name of the property. Details The STPSRVGETN function takes one character string property and returns a numeric string result. Examples SAS Statements Results dsesstimeout=stpsrvgetn('default session timeout'); put dsesstimeout=; dsesstimeout=900 sessmaxtimeout=stpsrvgetn('maximum session timeout'); put sessmaxtimeout=; sessmaxtimeout=3600 session=stpsrvgetn('session timeout'); put session=; session=900 maxconreqs=stpsrvgetn('maximum concurrent requests'); put maxconreqs=; maxconreqs=1 deflrecl=stpsrvgetn('default output lrecl'); put deflrecl=; deflrecl=65535 version=stpsrvgetn('version'); put version=; version=9.1 STPSRVGETN 31 SAS® Integration Technologies: Developer's Guide SAS Stored Processes STPSRVGETN 32 STPSRVSET Sets the value of a server property Syntax Arguments Details Examples Syntax RC = STPSRVSET( valuecode, newvalue ) Note: The APPSRVSET function can be used in place of STPSRVSET. This feature is provided in order to enable you to convert existing SAS/IntrNet programs to stored processes. The following Application Dispatcher properties are not supported by the SAS Stored Process Server: REQUIRE COOKIE, REQUEST TIMEOUT, and AUTOMATIC HEADERS. Arguments valuecode is the character string name of the property. newvalue is the numeric string name of the property. The following table lists the valid properties for valuecode and provides a description of each. Valuecode Description PROGRAM ERROR specifies the return code when there is an error. This can be set to any value. SESSION TIMEOUT specifies the number of seconds that elapse before a session expires. The default session timeout is 900 (15 minutes). Details The STPSRVSET function takes one character string property and one numeric string property and returns a numeric string result. The return code is zero for success, non−zero for failure. Examples SAS Statements rc=stpsrvset('session timeout',900); rc=stpsrvset('program error',256); STPSRVSET 33 SAS® Integration Technologies: Developer's Guide SAS Stored Processes STPSRVSET 34 STPSRV_HEADER The DATA step function used to add or modify a header Syntax Arguments Details Examples Syntax OLD−HEADER = STPSRV_HEADER(Header Name,Header Value); Note: The APPSRV_HEADER function can be used in place of STPSRV_HEADER. This feature is provided in order to enable you to convert existing SAS/IntrNet programs to stored processes. Arguments Header Name is the name of the header to set or reset. Header Value is the new value for the header. See HTTP Headers for a list of commonly used HTTP headers. Details The STPSRV_HEADER function enables automatic header generation. You can add a header to the default list or modify an existing header from the list. When you modify the value of an existing header, the old value becomes the return value of the function. The automatic HTTP header generation feature recognizes Output Delivery System (ODS) output types and generates appropriate default content−type headers. If no content type is specified with STPSRV_HEADER, ODS is not used and no HTTP header is written to _WEBOUT, and a default Content−type: text/html header is generated. Examples SAS Statements Resulting Headers No calls to stpsrv_header Content−type: text/html /* add expires header */ rc = stpsrv_header('Expires','Thu, 18 Nov 1999 12:23:34 GMT'); Content−type: text/html Expires: Thu, 18 Nov 1999 12:23:34 GMT /* add expires header */ rc = stpsrv_header('Expires','Thu, 18 Nov 1999 12:23:34 GMT'); Content−type: text/html Expires: Thu, 18 Nov 1999 12:23:34 GMT STPSRV_HEADER 35 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 36 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 37 STPSRV_UNQUOTE2 Unmasks quotation mark characters in an input parameter Syntax Arguments Details Example Syntax call STPSRV_UNQUOTE2( paramname ) Arguments paramname is the character string name of the parameter. Details The STPSRV_UNQUOTE2 call routine takes the name of an input parameter (or any global macro variable) and unmasks matched pairs of single or double quotation marks. The call routine does not return a value; instead it modifies the specified macro variable. This call routine can be used to selectively remove quotation marks from stored process input parameters so that they can be used in statements that require quotation mark characters. Example This call routine is typically called with %SYSCALL in open macro code, as follows: /* MYGOPTIONS is an input parameter and might contain quotation marks, for example: dashline='c000000000000000'x */ %SYSCALL STPSRV_UNQUOTE2(MYGOPTIONS); /* Quote characters are now interpreted as expected goptions &MYGOPTIONS; ... */ SAS Stored Processes STPSRV_UNQUOTE2 38 Sessions The Web is a stateless environment. A client request to a server knows nothing of any preceding requests. This creates a simple environment for client and server developers, but it is difficult for application programmers. Often, programmers want to carry information from one request to the next. This is known as maintaining state. Sessions provide a convenient way to maintain state across multiple stored process requests. A session is the data that is saved from one stored process execution to the next. It consists of macro variables and library members (data sets and catalogs) that the stored process has explicitly saved. The session data is scoped so that all users have independent sessions. See Using Sessions for a sample Web application that uses sessions. Creating a Session The stored process must explicitly create a session with the STPSRV_SESSION function, as follows: In macro %let rc=%sysfunc(stpsrv_session(create)); In DATA step or SCL rc=stpsrv_session('create'); Creating a session will set the global macro variables _SESSIONID and _THISSESSION and create the SAVE session library. Using the Session A session saves all global macro variables whose names begin with SAVE_. For example, the statements %global save_mytext; %let save_mytext="Text to be saved for the life of the session"; cause the macro variable save_mytext to be available in subsequent stored processes that share the same session. Data sets and catalogs can also be saved across program requests using the SAVE library. Data sets and catalogs that are created in or copied to this library are available to all future stored processes that execute in the same session. Creating a session causes the automatic variables _THISSESSION and _SESSIONID to be set. Sample values for these variables are as follows: 0010 %let rc=%sysfunc(stpsrv_session(create)); 0011 %put _SESSIONID=&_SESSIONID; _SESSIONID=7CF645EB−6E23−4853−8042−BBEA7F866B55 0012 %put _THISSESSION=&_THISSESSION; _THISSESSION=/SASStoredProcess/do?_sessionid= 7CF645EB−6E23−4853−8042−BBEA7F866B55 These variables can be used to construct URLs or HTML forms that execute another stored process in the same session. For example, %let rc=%sysfunc(stpsrv_session(create)); data _null; Sessions 39 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 40 SAS® Integration Technologies: Developer's Guide SAS Stored Processes Sessions 41 Stored Process Samples The following samples demonstrate how a stored process generates different types of output using the %STPBEGIN and %STPEND macros. All of the samples are based on the following stored process: *ProcessBody; %STPBEGIN; title 'Age analysis by sex'; footnote; proc sort data=sashelp.class out=class; by sex age; run; proc gchart data=class; vbar3d age / group=sex discrete nozero shape=cylinder patternid=group; run; quit; title; proc print data=class; by sex age; id sex age; var name height weight; run; %STPEND; This code generates a bar chart and a table. The exact format and appearance of the output depends upon various input parameters. For these samples, assume the following input parameters were specified: Variable Value Comments _ODSDEST HTML Default destination. Not required. _ODSSTYLE SASWeb _GOPT_DEVICE ActxImg Generates a PNG image file. Available only on Windows platforms. _GOPT_XPIXELS 384 Image width in pixels _GOPT_YPIXELS 288 Image height in pixels Note: See the section on Reserved Macro Variables for a more detailed description of each macro variable mentioned in the previous table and in the following sections. Streaming Output Streaming output is generally used when you are executing a stored process from a Web−based application using the SAS Stored Process Web Application or when you are returning a single output file with no embedded links to companion files such as images. Because the stored process was registered with a result type of Streaming, the following input parameters are passed to the stored process: Variable Value _RESULT STREAM _ODSDEST HTML Stored Process Samples 42 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 43 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 44 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 45 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 46 Debugging Stored Processes There are two techniques for debugging stored processes: • Examining the SAS Log • Using SAS Options Examining the SAS Log The client interfaces provided to stored processes usually include a mechanism for retrieving the SAS log from a stored process. For example, passing an input parameter _DEBUG=LOG to the SAS Stored Process Web Application causes the SAS log to be returned with the stored process output. The SAS log is directly accessible from the Stored Process Service API. Assuming your installation is configured correctly, most run−time stored process errors will appear in the SAS log. If you are unable to access the SAS log from the client interface, you might be able to access the SAS log from the server log files. The server administrator controls the level of server logging enabled and the location of the server log files. Server log options vary depending on the server type. The stored process server enables you to capture the SAS log for each stored process in the server log with the APPLEVEL option. The APPLEVEL option can be specified in the Object Server Parameters field in the Server Manager definition for the server in SAS Management Console. The following table describes the supported values for the APPLEVEL option: APPLEVEL Value Logging Behavior 0 Summary. The stored process server only logs an identifying build statement and error conditions. 1 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. 2 Full. The stored process server logs APPLEVEL=1 messages, except that the SAS log is included for every stored process executed on the server. 3 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 47 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 48 Converting SAS/IntrNet Programs to Stored Processes Stored processes provide a conversion path for existing SAS/IntrNet applications, enabling them to take advantage of the SAS 9 BI Architecture. Many features are implemented in the stored process server and SAS Stored Process Web Application to minimize code changes required during a conversion. Existing SAS/IntrNet Application Dispatcher programs can usually be converted to streaming stored processes with minimal or no modifications. Conversion of existing programs requires the following steps: 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 49 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 50 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 51 Using Stored Processes SAS Stored Processes can be used in many different client applications. The following list gives a brief overview of each so that you can determine which client best suits your needs. SAS Add−In for Microsoft Office The SAS Add−In for Microsoft Office is a Component Object Model (COM) add−in that extends Microsoft Office by enabling you to dynamically execute stored processes and embed the results in Microsoft Word documents, Microsoft Excel spreadsheets, and Microsoft PowerPoint presentations. Additionally, within Excel you can use the SAS add−in to access and view SAS data sources or any data source that is available from your SAS server, and analyze SAS or Excel data by using analytic tasks. For more information, refer to the SAS Add−In for Microsoft Office Online Help, which is located within the product. SAS BI Web Services SAS BI Web Services provide a Web service interface to SAS Stored Processes. Web services can be hosted on a Java servlet container or Windows IIS. SAS BI Web Services implement the Discover and Execute Web methods specified by the XML for Analysis standard. The Discover method returns the metadata for a stored process, and the Execute method calls the SAS Stored Process Server to invoke a stored process. SAS Data Integration Studio SAS Data Integration Studio enables its administrators to publish jobs as stored processes. SAS Data Integration Studio can generate code that converts a job into a stored process, which is saved to a file and can be executed later by the SAS Stored Process Server. Metadata about the stored process is saved in the current metadata repository. Refer to the SAS Data Integration Studio product Help for more information. SAS Enterprise Guide SAS Enterprise Guide provides an integrated solution for authoring, editing, and testing stored processes. You can create stored processes from existing or new SAS code and create stored processes automatically from SAS Enterprise Guide tasks. Metadata registration and source code management are handled from one interface. SAS Enterprise Guide also has the capability to execute stored processes, which enables you to modify and test your stored process without leaving the SAS Enterprise Guide environment. Refer to the SAS Enterprise Guide product Help for more information. SAS Information Delivery Portal The SAS Information Delivery Portal provides integrated Web access to SAS reports, stored processes, information maps, and channels. If you have installed the SAS Information Delivery Portal, you can make stored processes available to be executed from the portal without the need for additional programming. The SAS Information Delivery Portal includes the SAS Stored Process Web Application. SAS Information Map Studio Stored processes can be used to implement information map data sources. Stored processes can use the full power of SAS procedures and the DATA step to generate or update the data in an information map. Refer to the SAS Information Map Studio product Help for more information about stored process information maps. SAS Stored Process Web Application The SAS Stored Process Web Application is a Java Web application that can execute stored processes and return results to a Web browser. The SAS Stored Process Web Application is similar to the SAS/IntrNet Application Broker and has the same general syntax and debug options as the Application Broker. See the Building Web Applications section for examples of this component. The SAS Stored Process Web Application is included with the SAS Web Infrastructure Kit, a component of SAS Integration Technologies. SAS Web Report Studio You can use SAS Web Report Studio to execute stored processes and to include stored processes or stored process results in a report. Refer to the SAS Web Report Studio product Help for more information. Stored Process Service The Stored Process Service is a Java application programming interface (API) that enables you to execute stored processes from a Java program. This API is commonly used in JSP pages, but can also be used from Using Stored Processes 52 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 53 Building a Web Application Stored processes are frequently used in Web−based applications. While almost any stored process can be executed through a Web interface, the typical Web application design might require special techniques. This section and the following sections document special issues you might encounter when building a Web application. Web applications are typically implemented by streaming output stored processes. Streaming output stored processes deliver their output through the _WEBOUT fileref. You can write directly to the _WEBOUT fileref using PUT statements or use the Output Delivery System (ODS) to generate output. The example code throughout this section demonstrates both approaches. Streaming output is only supported by the stored process server: the workspace server is not an appropriate host for many Web applications. Web applications can be implemented using the SAS Stored Process Web Application, the Stored Process Service API or a combination of both. The SAS Stored Process Web Application is a Java middle−tier application that executes stored processes on behalf of a Web client. Only SAS and HTML programming skills are required; no Java programming is required. Most of the examples in the remainder of this section assume the use of the SAS Stored Process Web Application. The Stored Process Service API enables the Java developer to embed stored processes within a Java Web application. SAS Stored Processes Building a Web Application 54 SAS Stored Process Web Application The SAS Stored Process Web Application is a Java Web application that can execute stored processes and return results to a Web browser. The SAS Stored Process Web Application is similar to the SAS/IntrNet Application Broker, and has the same general syntax and debug options. The SAS Stored Process Web Application is included with the SAS Web Infrastructure Kit, a component of SAS Integration Technologies. To execute the SAS Stored Process Web Application, enter the application's URL in the Web browser. Either the default Welcome page or static data is displayed. Here is an example of a URL for the SAS Stored Process Web Application: http://yourserver.com:8080/SASStoredProcess/do? In this example, if the Welcome.htm file is installed, then the Welcome page is displayed. The Welcome page might look like this: The Welcome page contains the following three links: Stored Process Samples Click this link to display a page of stored process samples that are installed with the SAS Web Infrastructure Kit. See the section about custom input forms for more information. List Available Stored Processes Click this link to display a page that contains a tree view of metadata repositories, folders, and stored processes. You can select a stored process in the tree view in order to view metadata for the stored process or to run the stored process. See the section about the stored process list and summary page for more information. SAS Integration Technologies Documentation Click this link to display the SAS Integration Technologies documentation library, which contains detailed documentation about each feature of the SAS Integration Technologies product. This link requires Internet access. In the previous example, if the Welcome.htm file has not been installed, then static data is displayed. The static data might look like this: Stored Process Web Application SAS Stored Process Web Application 55 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 56 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 57 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 58 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 59 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 60 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 61 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 62 SAS Stored Process Web Application Configuration The SAS Stored Process Web Application can be customized for your site through various configuration files and servlet initialization parameters. Configuration Files The following table describes the external files that are read by the SAS Stored Process Web Application. File 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 63 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 64 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 65 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 66 Web Application Input A Web application that uses stored processes must have a way of sending input parameters to the stored processes. Input parameters are normally generated by an HTML page and passed through the Stored Process Web Application or a user written JSP to the stored process. Input parameters can be specified in the following: • fields in an HTML form. The user provides the required information and submits the request. The Web browser sends data from the form (including both user entered data and hidden fields) to the server. HTML forms are generally used where user input is required to control the execution of the stored process. • a hypertext link in an anchor tag. The link URL includes parameter values that are passed to the server when the user selects the link. Hypertext links are generally used where the input parameters have fixed values, for example, as drill−down links in a table or image. • an inline image or other embedded link in the HTML page. This case also includes frames within an HTML frameset. In most cases, the Web browser fetches the embedded object when the user loads the HTML page. Fetching the embedded object can cause input parameters to be passed to a stored process. • URLs or forms created and submitted by JavaScript or a similar scripting technology in the Web browser. The HTML page using these techniques can be a static HTML page or a dynamic page generated on demand by another stored process or by a Java Server Page (JSP). In all cases, the input parameters must follow the naming conventions and other basic rules described in the Input Parameters section. Reserved parameter names should be used only as recommended. All of the previously mentioned techniques for specifying input parameters rely on URLs or HTML forms. The following sections discuss how parameters are passed in both cases. These sections assume the use of the Stored Process Web Application. JSPs generally will use similar conventions, but the details are determined by the author of the JSP. Specifying Input Parameters in a URL You can specify input parameters as a sequence of name/value pairs in a URL by using the query string syntax. For example, the URL http://yourserver/SASStoredProcess/do? _program=/WebApps/Sales/Weekly+Report®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 67 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. 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