Create Data Source on Stored Procedure in BIRT
Author：mwu
Keywords
BIRT, Stored Procedure ， JDBC, Data Source ， Cursor ， Input parameter,
Output Parameter
Version Control
Version
Date
Description of Changes
Draft 1
Jun 10 2008
First draft
You can get the Chinese version from:
http://www.actuatechina.com/thread58.html#post363
-1-
www.birt-exchange.com
Table of Contents
1. Introduction............................................................................................................................................. 3
2. Return type of Stored Procedure .......................................................................................................... 3
3. Syntax of Calling Stored Procedure ..................................................................................................... 4
4. Create Stored Procedure Data Source ................................................................................................. 4
5. Calling Stored Procedure ...................................................................................................................... 5
1. Calling Stored Procedure returning a single result set ................................................................... 6
2. Calling stored procedure containing input/output parameters ........................................................ 7
3. Calling Stored Procedure contains RETURN value ........................................................................ 9
4. Calling Stored Procedure containing CURSOR .............................................................................. 9
5. Calling Stored Procedure returning multiple result sets ................................................................ 11
6. References and Resources ................................................................................................................. 14
-2-
www.birt-exchange.com
1.
Introduction
Both Stored Procedure and Function are collections of SQL.Generally ， Stored
Procedure is a group of Transact-SQL statements compiled into a single execution
plan, it could call some function to get value. Indeed ，we can take the Stored
Procedure on as a Function without return value, but Function is a method calling
with value returned.
Due to the different support of Stored Procedure in Different relation database and
different type of returning value ， user need a common access the to Stored
Procedure. BIRT provide an easy way to achieve this from stored procedure, which
makes it easier to customize report design for user.
This document only deals with how to create a data source on stored procedures in
BIRT 2.3.0.
2.
Return type of Stored Procedure
Stored Procedure returns value in 5 ways：
1. Single Result Set
A single result set for each ‘Select’ statement contained in the stored procedure
or any other stored procedures called by the stored procedure. The result set
could be generated from a temp table, a permanent table or a local variable.
2. Output Parameter
Output parameter is a parameter declared with output value, whose return data
could be Integer or String value etc.
3. RETURN Codes
This is a special value for the stored procedure to indicate the status of stored
procedure. It is always an Integer value.
-3-
www.birt-exchange.com
4. Cursor
The cursor we mentioned here is Global Cursor. It can be referenced outside the
stored procedure. Some DBMS do not support CURSOR, and also JDBC does
not support this feature in its API. But the most popular DBMS, like Oracle,
Postgre SQL and DB2 support this return type. BIRT also allows user to access
this return type.
5. Multiple Result Set
This return type is a mixed type of above 4 types. The combination type could be
Output Parameter and Single Result Set, or Output Parameter and Cursor type
etc. The result set could be achieved by its name or index.
3.
Syntax of Calling Stored Procedure
JDBC allows user to call a stored procedure by a standard way. There are 2 calling
method, one is calling with return value, another is calling without return value
{?= call <procedure-name>[<arg1>,<arg2>, ...]}
{call <procedure-name>[<arg1>,<arg2>, ...]}
In BIRT，the access to Stored Procedure follows JDBC3.0 standard。The syntax
above is applicable to BIRT. Here ，<arg1>… could use the place holder(?) or
default value as its input value。
4.
Create Stored Procedure Data Source
Firstly, we should create a JDBC data source to indicate which DBMS we prefer to
use, and then provide the call statement to execute the stored procedure. The step
to create a Stored Procedure data source is:
1. Create a JDBC Data Source
2. Choose SQL Stored Procedure type as Data Set Type
3. Input the query statement to call a stored procedure
-4-
www.birt-exchange.com
As shown below：
5.
Calling Stored Procedure
In this chapter, we will give the example to show how to call the Stored Procedure
with different return values.
Note: Stored Procedures are supported by most DBMS, but there is a fair amount
of variation in their syntax and capabilities. For this reason, Example 1, 2, 3 is
intended to be run on Sybase database. The stored procedure uses the table
‘Customers’ which records all information of customers as its target table. Since
Cursor type is unsupported in Sybase, for all cursor related case, we use Oracle as
our sample database; it will use ‘OFFICES’ and ‘CUSTOMERS’ tables in this
database.
-5-
www.birt-exchange.com
1. Calling Stored Procedure returning a single result set
Case 1：In Sybase DBMS, using the following SQL statement to create a stored
procedure named get_All_Customers：
CREATE PROCEDURE get_All_Customers
AS
SELECT * FROM Customers
GO
This Stored Procedure tries to get all records from ‘Customers’ table. In BIRT, The
Stored Procedure is called as：
Statement： { call get_All_Customers () }
Then the result set as following：
-6-
www.birt-exchange.com
2. Calling stored procedure containing input/output parameters
In stored procedure, user could input the parameter value to get the expected result
set. For example, with ’Customers’ table, select the Customer’s name and phone
number information base on specified user ID. Here, @id is input parameter, the
@name and @phone is defined as output parameters. The Stored Procedure is
defined as following：
-7-
www.birt-exchange.com
CREATE PROCEDURE get_Cursotermer_ByID
(@id int, @name varchar(50) output,@phone varchar(50) output)
AS
SELECT @name=customerName,@phone=phone
FROM Curstomers
WHERE customerNumber =@id
GO
Statement：{ call get_Cursotermer_ByID (?,?,?)}
In ‘Parameters’ tab，BIRT will generate all available parameters in the table list.
User could input the default value for the input parameter, and then switch to
‘Preview Output Parameters’ tab, then he will get result set. In some case, due to
-8-
www.birt-exchange.com
the jdbc driver implementation or some connection interior problem, the
parameter cannot be listed automatically in the table list; user could input his
parameter manually, it will also take effect.
3. Calling Stored Procedure contains RETURN value
Still using the same stored procedure in 2 section，we can get its RETURN
value in a similar way.
Statement:{ ?=call dbo.get_Cursotermer_ByID (?,?,?) },
The difference with 2 section is, in ‘parameter’ tab, there is an added
“:@RETURN_VALUE” parameter. Generally, if user wants to call Function, he
can use the RETUREN value to get the value of function.
4. Calling Stored Procedure containing CURSOR
Not all DBMS support CURSOR type. Here we take Oracle DBMS as an
example.
In ORACLE, the statement we create a Stored Procedure like following, it will get
all result set from ‘OFFICES’ table:
-9-
www.birt-exchange.com
CREATE OR REPLACE PAGKAGE TESTPACKAGE AS
TYPE TEST_CURSOR IS REF CURSOR;
END TESTPACKAGE;
CREATE
OR
REPLACE
PROCEDURE
TESTLIN2
(
TEST_CUSROR
OUT
TESTPACKAGE.TEST_CURSOR) AS
BEGIN
OPEN TEST_CURSOR FOR SELECT * FROM OFFICES;
END TESTLIN2
In JDBC3.0 standard, there is no cursor type in its return type. So, we handle this
special type as java.sql.Types.Others. We can called this Stored Procedure as
following：
Statement:{ CALL TESTLIN2(?) }
- 10 -
www.birt-exchange.com
5. Calling Stored Procedure returning multiple result sets
We will give a detailed example to show how to calling a Stored Procedure
contains both output parameter and multiple result sets. The Stored Procedure’s
CREATE statement is：
- 11 -
www.birt-exchange.com
CREATE OR REPLACE PROCEDURE TESTMULTIPLE
(
P_CUSTOMERNUMBER IN NUMBER,
P_CUSTOMERCURSOR1 OUT SYS_REFCURSOR,
P_CUSTOMERCURSOR2 OUT SYS_REFCURSOR,
P_CUSTOMERNAME OUT VARCHAR2,
P_COUNTRY OUT VARCHAR2
)
AS
BEGIN
OPEN P_CUSTOMERCURSOR1 FOR
SELECT * FROM CUSTOMERS
WHERE CUSTOMERNUMBER>P_CUSTOMERNUMBER;
SELECT COUNTRY INTO P_COUNTRY
FROM CUSTOMERS
WHERE CUSTOMERNUMBER=P_CUSTOMERNUMBER;
OPEN P_CUSTOMERCURSOR2 FOR
SELECT * FROM CUSTOMERS;
SELECT CUSTOMERNAME INTO P_CUSTOMERNAME
FROM CUSTOMERS
WHERE CUSTOMERNUMBER=P_CUSTOMERNUMBER;
END;
Statement:{ CALL TESTMULTIPLE(?,?,?,?,?) }
The step to call this procedure is like following:
- 12 -
www.birt-exchange.com
Currently, BIRT2.3.0 doesn’t support achieving multiple result sets at the same time.
But it is allowed user get the different result set based on the ‘Settings’ preference,
user just need to specify result set name/index as its search key, then he will get the
corresponding result set.
- 13 -
www.birt-exchange.com
6.
References and Resources
BIRT Official website:www.eclipse.org/BIRT
BIRT Exchange website：www.birt-exchange.com
JDBC 3.0 documentation：
http://jcp.org/aboutJava/communityprocess/first/jsr054/index.html
- 14 -