194 lines
12 KiB
HTML
194 lines
12 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="en-us" xml:lang="en-us">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="security" content="public" />
|
|
<meta name="Robots" content="index,follow" />
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
|
<meta name="DC.Type" content="concept" />
|
|
<meta name="DC.Title" content="CallableStatements" />
|
|
<meta name="abstract" content="The CallableStatement interface extends PreparedStatement and provides support for output and input/output parameters. The CallableStatement interface also has support for input parameters that is provided by the PreparedStatement interface." />
|
|
<meta name="description" content="The CallableStatement interface extends PreparedStatement and provides support for output and input/output parameters. The CallableStatement interface also has support for input parameters that is provided by the PreparedStatement interface." />
|
|
<meta name="DC.Relation" scheme="URI" content="statetyp.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="statemnt.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="prepstat.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="callproc.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="callexample1.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="callexample2.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="callexample3.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="callable" />
|
|
<meta name="DC.Language" content="en-us" />
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
|
<title>CallableStatements</title>
|
|
</head>
|
|
<body id="callable"><a name="callable"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">CallableStatements</h1>
|
|
<div><p>The CallableStatement interface extends PreparedStatement and provides
|
|
support for output and input/output parameters. The CallableStatement interface
|
|
also has support for input parameters that is provided by the PreparedStatement
|
|
interface.</p>
|
|
<p>The CallableStatement interface allows the use of SQL statements to call
|
|
stored procedures. Stored procedures are programs that have a database interface.
|
|
These programs possess the following:</p>
|
|
<ul><li>They can have input and output parameters, or parameters that are both
|
|
input and output.</li>
|
|
<li>They can have a return value.</li>
|
|
<li>They have the ability to return multiple ResultSets.</li>
|
|
</ul>
|
|
<p>Conceptually in JDBC, a stored procedure call is a single call to the database,
|
|
but the program associated with the stored procedure may process hundreds
|
|
of database requests. The stored procedure program may also perform a number
|
|
of other programmatic tasks not typically done with SQL statements.</p>
|
|
<p>Because CallableStatements follow the PreparedStatement model of decoupling
|
|
the preparation and processing phases, they have the potential for optimized
|
|
reuse (see <a href="prepstat.htm">PreparedStatement</a> for details).
|
|
Since SQL statements of a stored procedure are bound into a program, they
|
|
are processed as static SQL and further performance benefits can be gained
|
|
that way. Encapsulating a lot of database work in a single, reusable database
|
|
call is an example of using stored procedures optimally. Only this call goes
|
|
over the network to the other system, but the request can accomplish a lot
|
|
of work on the remote system.</p>
|
|
<div class="section"><h4 class="sectiontitle">Create CallableStatements</h4><p>The prepareCall method
|
|
is used to create new CallableStatement objects. As with the prepareStatement
|
|
method, the SQL statement must be supplied at the time that the CallableStatement
|
|
object is created. At that time, the SQL statement is precompiled. For example,
|
|
assuming a Connection object named conn already exists, the following creates
|
|
a CallableStatement object and completes the preparation phase of getting
|
|
the SQL statement ready for processing within the database:</p>
|
|
<blockquote><pre>PreparedStatement ps = conn.prepareStatement("? = CALL ADDEMPLOYEE(?, ?, ?");</pre>
|
|
</blockquote>
|
|
<p>The ADDEMPLOYEE stored procedure takes input parameters for a new
|
|
employee name, his social security number, and his manager's user ID. From
|
|
this information, multiple company database tables may be updated with information
|
|
about the employee such as his start date, division, department, and so on.
|
|
Further, a stored procedure is a program that may generate standard user IDs
|
|
and e-mail addresses for that employee. The stored procedure may also send
|
|
an e-mail to the hiring manager with initial usernames and passwords; the
|
|
hiring manager can then provide the information to the employee.</p>
|
|
<p>The
|
|
ADDEMPLOYEE stored procedure is set up to have a return value. The return
|
|
code may be a success or failure code that the calling program can use when
|
|
a failure occurs. The return value may also be defined as the new employee's
|
|
company ID number. Finally, the stored procedure program could have processed
|
|
queries internally and have left the ResultSets from those queries open and
|
|
available for the calling program. Querying all the new employee's information
|
|
and making it available to the caller through a returned ResultSet is reasonable.</p>
|
|
<p>How
|
|
to accomplish each of these types of tasks is covered in the following sections.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Specify ResultSet characteristics and auto-generated key support</h4><p>As
|
|
with createStatement and prepareStatement, there are multiple versions of
|
|
prepareCall that provide support for specifying ResultSet characteristics.
|
|
Unlike prepareStatement, the prepareCall method does not provide variations
|
|
for working with auto-generated keys from CallableStatements (JDBC 3.0 does
|
|
not support this concept.) The following are some examples of valid calls
|
|
to the prepareCall method:</p>
|
|
<p><strong>Example:</strong> The prepareCall method</p>
|
|
<pre>// The following is new in JDBC 2.0
|
|
|
|
CallableStatement cs2 = conn.prepareCall("? = CALL ADDEMPLOYEE(?, ?, ?)",
|
|
ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATEABLE);
|
|
|
|
// New in JDBC 3.0
|
|
|
|
CallableStatement cs3 = conn.prepareCall("? = CALL ADDEMPLOYEE(?, ?, ?)",
|
|
ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATEABLE,
|
|
ResultSet.HOLD_CURSOR_OVER_COMMIT);</pre>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Handle parameters</h4><p>As stated, CallableStatement objects
|
|
may take three types of parameters:</p>
|
|
<ul><li><strong>IN</strong> <p>IN parameters are handled in the same manner as PreparedStatements.
|
|
The various set methods of the inherited PreparedStatement class are used
|
|
to set the parameters.</p>
|
|
</li>
|
|
<li><strong>OUT</strong><p>OUT parameters are handled with the registerOutParameter
|
|
method. The most common form of registerOutParameter takes an index parameter
|
|
as the first parameter and an SQL type as the second parameter. This tells
|
|
the JDBC driver what to expect for data from the parameter when the statement
|
|
is processed. There are two other variations on the registerOutParameter method
|
|
that can be found in the <a href="javaapi/api/java/sql/package-summary.html" target="_blank">java.sql</a> package Javadoc.</p>
|
|
</li>
|
|
<li><strong>INOUT</strong><p>INOUT parameters require that the work for both IN parameters
|
|
and OUT parameters be done. For each INOUT parameter, you must call a set
|
|
method and the registerOutParameter method before the statement can be processed.
|
|
Failing to set or register any parameter results in an SQLException being
|
|
thrown when the statement is processed.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Refer to <a href="callexample2.htm">Example: Create a procedure
|
|
with input and output parameters</a> for more information.</p>
|
|
<p>As with
|
|
PreparedStatements, CallableStatement parameter values remain the same between
|
|
processes unless you call a set method again. The clearParameters method does
|
|
not affect parameters that are registered for output. After calling clearParameters,
|
|
all IN parameters must be set to a value again, but all OUT parameters do
|
|
not have to be registered again.</p>
|
|
<div class="note"><span class="notetitle">Note:</span> The concept of parameters must not
|
|
be confused with the index of a parameter marker. A stored procedure call
|
|
expects a certain number of parameters that are passed to it. A particular
|
|
SQL statement has ? characters (parameter markers) in it to represent values
|
|
that are supplied at runtime. Consider the following example to see the difference
|
|
between the two concepts:<pre>CallableStatement cs = con.prepareCall("CALL PROC(?, "SECOND", ?)");
|
|
|
|
cs.setString(1, "First"); //Parameter marker 1, Stored procedure parm 1
|
|
|
|
cs.setString(2, "Third"); //Parameter marker 2, Stored procedure parm 3</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Access stored procedure parameters by name</h4><p>Parameters
|
|
to stored procedures have names associated with them as the following stored
|
|
procedure declaration shows:</p>
|
|
<p><strong>Example:</strong> Stored procedure parameters</p>
|
|
<div class="note"><span class="notetitle">Note:</span> Read
|
|
the <a href="codedisclaimer.htm">Code example disclaimer</a> for important
|
|
legal information.</div>
|
|
<pre>CREATE
|
|
PROCEDURE MYLIBRARY.APROC
|
|
(IN PARM1 INTEGER)
|
|
LANGUAGE SQL SPECIFIC MYLIBRARY.APROC
|
|
BODY: BEGIN
|
|
<Perform a task here...>
|
|
END BODY</pre>
|
|
<p>There is a single integer parameter with the name PARM1.
|
|
In JDBC 3.0, there is support for specifying stored procedure parameters by
|
|
name as well as by index. The code to set up a CallableStatement for this
|
|
procedure is as follows:</p>
|
|
<blockquote><pre>CallableStatement cs = con.prepareCall("CALL APROC(?)");
|
|
|
|
cs.setString("PARM1", 6); //Sets input parameter at index 1 (PARM1) to 6.</pre>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<ul class="ullinks">
|
|
<li class="ulchildlink"><strong><a href="callproc.htm">Process CallableStatements</a></strong><br />
|
|
Processing SQL stored procedure calls with a CallableStatement object is accomplished with the same methods that are used with a PreparedStatement object.</li>
|
|
<li class="ulchildlink"><strong><a href="callexample1.htm">Example: Create a procedure with multiple ResultSets</a></strong><br />
|
|
This example shows how to access a database and then create a procedure with multiple ResultSets.</li>
|
|
<li class="ulchildlink"><strong><a href="callexample2.htm">Example: Create a procedure with input and output parameters</a></strong><br />
|
|
This example shows how to access a database and then create a procedure with input and output parameters.</li>
|
|
<li class="ulchildlink"><strong><a href="callexample3.htm">Example: Create a procedure with return values</a></strong><br />
|
|
This example shows how to access a database and then create a procedure with return values.</li>
|
|
</ul>
|
|
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="statetyp.htm" title="The Statement interface and its PreparedStatement and CallableStatement subclasses are used to process structured query language (SQL) commands against the database. SQL statements cause the generation of ResultSet objects.">Statement types</a></div>
|
|
</div>
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
|
<div><a href="statemnt.htm" title="A Statement object is used for processing a static SQL statement and obtaining the results produced by it. Only one ResultSet for each Statement object can be open at a time. All statement methods that process an SQL statement implicitly close a statement's current ResultSet if an open one exists.">Statements</a></div>
|
|
<div><a href="prepstat.htm" title="PreparedStatements extend the Statement interface and provide support for adding parameters to SQL statements.">PreparedStatements</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |