Business Information Server: Using Stored Procedures Craig D. Hanson White Paper 2 Unisys Business Information Server (BIS) solutions and products enable integration of a wide range of applications and databases running in heterogeneous environment. You can use the BIS for Windows product plus its included Internet Commerce Enabler (ICE) module in a ClearPath® environment to extend, add to, and integrate applications and databases. With this product, you extend the value of your ClearPath application environment. BIS offers exceptional capabilities to access data from multiple disparate sources and turn it to useful information. It facilitates synergy between different data sources and enables using the data in a new manner or in a new business process. This white paper describes powerful integration capabilities of store procedures provided by the BIS solution in the ClearPath OS 2200 environments. 3 Table of Contents 1. Overview .................................................................................................................................................... 5 2. @SPI Statement Basics ............................................................................................................................. 5 2.1 What is a Stored Procedure? ............................................................................................................... 5 2.2 @SPI Statement Syntax ...................................................................................................................... 5 3. Supported Databases & Platforms ............................................................................................................ 10 5. Retrieving Metadata ................................................................................................................................. 13 5.1 Guidelines & Considerations ............................................................................................................. 13 5.2 Examples .......................................................................................................................................... 14 5.2.1 S Option w/SQL Server, OLEDB Provider .................................................................................. 14 5.2.2 S Option w/Oracle Server, ODBC Provider ................................................................................. 15 5.2.3 C Option w/SQL Server, OLEDB Provider .................................................................................. 19 5.2.4 P Option w/SQL Server, ODBC Provider .................................................................................... 20 6. Executing Stored Procedures ................................................................................................................... 21 6.1 Guidelines & Considerations ............................................................................................................. 22 6.2 Examples .......................................................................................................................................... 23 6.2.1 SQL Server - 2 Input Parameters, w/OLEDB .............................................................................. 24 6.2.2 SQL Server - Output Parameters with Result set ........................................................................ 25 6.2.3 SQL Server - Parameterized SELECT Query ............................................................................. 28 6.2.4 Oracle DB – ResultSet w/ one input, Microsoft provider for Oracle ............................................. 29 6.2.5 Oracle DB - ResultSet w/REF Cursor, w/Microsoft providers ...................................................... 33 6.2.6 Oracle DB – w/REF Cursor and %ROWTYPE ............................................................................ 36 6.2.7 Oracle DB - w/REF Cursor; In, Out, & Resultset ......................................................................... 38 7. Executing Stored Procedures from BIS JavaScript ................................................................................... 41 7.1 BIS JavaScript Related Syntax .......................................................................................................... 42 7.1.1 Execute Method of Database Object .......................................................................................... 42 7.1.2 DatabaseArguments Object........................................................................................................ 42 7.2 JavaScript Example ........................................................................................................................... 43 4 1. Overview 2.2 @SPI Statement Syntax @SPI (Stored Procedure Interface statement) allows you The @SPI (Stored Procedure Interface) statement is to execute stored procedures on external databases and part of the MRI set of commands and combines many of return results to your Business Information Server script. the attributes of the @FCH and @SQL statements. The Through examples and explanations, this white paper MRI statements include: will describe the capabilities and limitations of the new SPI statement. Also, described is how to invoke the • Data Definition Information (@DDI) SPI feature to execute stored procedures from a Retrieves a table description from a BIS JavaScript. - relational database. 2. @SPI Statement Basics • Log On to Relational Database (@LGN) - Establishes communication between BIS and a 2.1 What is a Stored Procedure? relational database management system. The @SPI (Stored Procedure Interface) statement • Log Off Relational Database (@LGF) allows you to execute procedures that reside in an Terminates communication established with the external database. A stored procedure is typically a set - @LGN statement. of commands and control logic executed by the database to retrieve and/or update data in the database. • Relational Aggregate Fetch (@FCH) The procedure is physically stored in the database for - Retrieves data from one or more relational both security and performance reasons. The procedure tables and places the data in a result. language is specific to the database, but often is based on the SQL command language. Normally, a procedure • Relational Aggregate Modify (@RAM) written for one database, such as Microsoft SQL Server, - Creates or deletes relational tables, updates cannot be used on another database, such as Oracle. a table, inserts a record, or issues a Commit command. Stored procedures have different names and structures on different databases. For example, Microsoft SQL • Submit SQL (@SQL) Server defines both “functions” and “stored procedures”, - Submits SQL syntax to a relational both which can be executed with the @SPI statement. database manager. Oracle also has stored procedures, but they can be either stand-alone or part of a “package”. Like other MRI commands, the @SPI statement requires that you use the @LGN and @LGF commands to Regardless of the naming convention used, execution of connect and disconnect to a database. procedures is the same. The procedure name is specified along with input and output parameters. The results are returned to the user. Unlike the @FCH and @SQL statements, @SPI can return both a rowset and output parameters. The rowset is returned in the –0 result of the statement and the output parameters are returned to the specified BIS variables. The RETURN_VALUE is also returned to a specified BIS variable. 5 The @SPI statement supports the following operations: • Execute a single stored procedure. • Retrieve a list of stored procedures for a specified database. • Retrieve a list of columns with their definitions for a specified stored procedure. • Retrieve a list of parameters with their definitions for a specified stored procedure. The @SPI statement has the following syntax. All sub-fields are optional unless otherwise specified in the description below. CMD Field SP Field Param Field Param Type Field @SPI,c,d,lab,db,edsp?,action,wrap,vert ‘sp-syntax’ vpar1,...,vparn typ1,...,typn . Field/Sub-field Description CMD Field Required c,d Cabinet and drawer to hold the result. Default is 0,A lab Label to go to if the status in the STAT1$ variable is other than normal completion. db Database name. The name registered in MRIDBA. Required. edsp? edsp sub-field. Create a result if an error occurs? Y – The result contains the last statement sent to the database manager and the text of the system message. It also contains the status code and descriptive message. N – (default) A runtime error occurs if there is an error executing this statement action action sub-field. This option determines the action performed and allows you to retrieve meta-data about stored procedures in the specified database. The results are stored in the –0 result report. See details below. E – (default action) Execute the specified stored procedure. S – Returns a list of stored procedures in the specified database <db> C – Returns a list of columns in the specified stored procedure <sp-syntax> P – Returns a list of parameters in the specified stored procedure <sp-syntax> wrap wrap sub-field. T – Truncate the results. For ‘E’ action option, if the width of the rowset exceeds the width of the result report, the rows are truncated. Also truncates decimal values that do not fit within their field widths. For meta-data action options (S, P, C), the fields are truncated on the right side. W – Wrap results on multiple lines if the result exceeds the result report width. The “W” value