295 lines
14 KiB
HTML
295 lines
14 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="reference" />
|
|
<meta name="DC.Title" content="SQLPrepare - Prepare a statement" />
|
|
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1999, 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1999, 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="rzadpfnprep" />
|
|
<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>SQLPrepare</title>
|
|
</head>
|
|
<body id="rzadpfnprep"><a name="rzadpfnprep"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLPrepare - Prepare a statement</h1>
|
|
<div><div class="section"></div>
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLPrepare()</samp> associates
|
|
an SQL statement with the input statement handle and sends the statement to
|
|
the DBMS to be prepared. The application can reference this prepared statement
|
|
by passing the statement handle to other functions.</p>
|
|
<p>If the statement
|
|
handle has been used with a SELECT statement, <samp class="codeph">SQLFreeStmt()</samp> must
|
|
be called to close the cursor, before calling <samp class="codeph">SQLPrepare()</samp>.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLPrepare (SQLHSTMT hstmt,
|
|
SQLCHAR *szSqlStr,
|
|
SQLINTEGER cbSqlStr);</pre>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Function arguments</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="all"><caption>Table 1. SQLPrepare arguments</caption><thead align="left"><tr><th align="left" valign="top" width="20%" id="d0e56">Data type</th>
|
|
<th align="left" valign="top" width="20%" id="d0e58">Argument</th>
|
|
<th align="left" valign="top" width="20%" id="d0e60">Use</th>
|
|
<th align="left" valign="top" width="40%" id="d0e62">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e56 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e58 "><em>szSqlStr</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e60 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e62 ">SQL statement string.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e56 ">SQLHSTMT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e58 "><em>hstmt</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e60 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e62 ">Statement handle. There must not be an open
|
|
cursor associated with <em>hstmt</em>.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e56 ">SQLINTEGER</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e58 "><em>cbSqlStr</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e60 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e62 ">Length of contents of <em>szSqlStr</em> argument.
|
|
<p>This must be set to either the exact length of the SQL statement in <em>szSqlstr</em>,
|
|
or to SQL_NTS if the statement text is null-terminated.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><div class="p">As soon as a statement has been prepared using <samp class="codeph">SQLPrepare()</samp>,
|
|
the application can request information about the format of the result set
|
|
(if it is a SELECT statement) by calling: <ul><li><samp class="codeph">SQLNumResultCols()</samp></li>
|
|
<li><samp class="codeph">SQLDescribeCol()</samp></li>
|
|
<li><samp class="codeph">SQLColAttributes()</samp></li>
|
|
</ul>
|
|
</div>
|
|
<p>A prepared statement can be processed once, or multiple times
|
|
by calling <samp class="codeph">SQLExecute()</samp>. The SQL statement remains associated
|
|
with the statement handle until the handle is used with another <samp class="codeph">SQLPrepare()</samp>, <samp class="codeph">SQLExecDirect()</samp>, <samp class="codeph">SQLColumns()</samp>, <samp class="codeph">SQLSpecialColumns()</samp>, <samp class="codeph">SQLStatistics()</samp>,
|
|
or <samp class="codeph">SQLTables()</samp>.</p>
|
|
<p>The SQL statement string might contain
|
|
parameter markers. A parameter marker is represented by a "?" character, and
|
|
indicates a position in the statement where the value of an application variable
|
|
is to be substituted, when <samp class="codeph">SQLExecute()</samp> is called. <samp class="codeph">SQLBindParam()</samp> is
|
|
used to bind (or associate) an application variable to each parameter marker,
|
|
and to indicate if any data conversion should be performed at the time the
|
|
data is transferred.</p>
|
|
<p>The SQL statement cannot be a COMMIT or ROLLBACK. <samp class="codeph">SQLTransact()</samp> must
|
|
be called to issue COMMIT or ROLLBACK.</p>
|
|
<p>If the SQL statement is a positioned
|
|
DELETE or a Positioned UPDATE, the cursor referenced by the statement must
|
|
be defined on a separate statement handle under the same connection handle.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Return codes</h4><ul><li>SQL_SUCCESS</li>
|
|
<li>SQL_SUCCESS_WITH_INFO</li>
|
|
<li>SQL_ERROR</li>
|
|
<li>SQL_INVALID_HANDLE</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Diagnostics</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLPrepare SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" width="25%" id="d0e189">SQLSTATE</th>
|
|
<th align="left" valign="top" width="25%" id="d0e191">Description</th>
|
|
<th align="left" valign="top" width="50%" id="d0e193">Explanation</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e189 "><strong>24</strong>000</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e191 ">Cursor state that is not valid</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e193 ">There is an open cursor on the specified <em>hstmt</em>.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e189 "><strong>37</strong>xxx</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e191 ">Syntax error or access violation</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e193 "><em>szSqlStr</em> contained one or more of
|
|
the following statements: <ul><li>A COMMIT</li>
|
|
<li>A ROLLBACK</li>
|
|
<li>An SQL statement that the connected database server cannot prepare</li>
|
|
<li>A statement containing a syntax error</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e189 "><strong>HY</strong>001</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e191 ">Memory allocation failure</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e193 ">The driver is unable to allocate memory required
|
|
to support the processing or completion of the function.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e189 "><strong>HY</strong>009</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e191 ">Argument value that is not valid</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e193 "><em>szSqlStr</em> is a null pointer. <p>The
|
|
argument <em>cbSqlStr</em> is less than 1, but not equal to SQL_NTS.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e189 "><strong>HY</strong>013 <strong>*</strong></td>
|
|
<td align="left" valign="top" width="25%" headers="d0e191 ">Memory management problem</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e193 ">The driver is unable to access memory required
|
|
to support the processing or completion of the function.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="25%" headers="d0e189 "><strong>HY</strong>021</td>
|
|
<td valign="top" width="25%" headers="d0e191 ">Internal descriptor that is not valid </td>
|
|
<td valign="top" width="50%" headers="d0e193 ">The internal descriptor cannot be addressed or allocated,
|
|
or it contains a value that is not valid.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="note"><span class="notetitle">Note:</span> Not all Database Management Systems (DBMSs) report all of the
|
|
above diagnostic messages at prepare time. Therefore an application must also
|
|
be able to handle these conditions when calling <samp class="codeph">SQLExecute()</samp>.</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Example</h4></div>
|
|
<div class="example" id="rzadpfnprep__xmprep"><a name="rzadpfnprep__xmprep"><!-- --></a><div class="p">Refer to <a href="rzadpxminter.htm#rzadpxminter">Example: Interactive SQL and the equivalent DB2 UDB CLI function calls</a> for
|
|
a listing of the <samp class="codeph">check_error, initialize, and terminate</samp> functions
|
|
used in the following example.<div class="note"><span class="notetitle">Note:</span> By using the code examples, you agree
|
|
to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
|
|
<pre>/*************************************************************************
|
|
** file = prepare.c
|
|
**
|
|
** Example of preparing then repeatedly executing an SQL statement.
|
|
**
|
|
** Functions used:
|
|
**
|
|
** SQLAllocConnect SQLFreeConnect
|
|
** SQLAllocEnv SQLFreeEnv
|
|
** SQLAllocStmt SQLFreeStmt
|
|
** SQLConnect SQLDisconnect
|
|
**
|
|
** SQLBindCol SQLFetch
|
|
** SQLTransact SQLError
|
|
** SQLPrepare SQLSetParam
|
|
** SQLExecute
|
|
**************************************************************************/
|
|
|
|
#include <stdio.h>
|
|
#include <string.h>
|
|
#include <stdlib.h>
|
|
#include "sqlcli.h"
|
|
|
|
#define MAX_STMT_LEN 255
|
|
|
|
int initialize(SQLHENV *henv,
|
|
SQLHDBC *hdbc);
|
|
|
|
int terminate(SQLHENV henv,
|
|
SQLHDBC hdbc);
|
|
|
|
int print_error (SQLHENV henv,
|
|
SQLHDBC hdbc,
|
|
SQLHSTMT hstmt);
|
|
|
|
int check_error (SQLHENV henv,
|
|
SQLHDBC hdbc,
|
|
SQLHSTMT hstmt,
|
|
SQLRETURN rc);
|
|
|
|
/*******************************************************************
|
|
** main
|
|
** - initialize
|
|
** - terminate
|
|
*******************************************************************/
|
|
int main()
|
|
{
|
|
SQLHENV henv;
|
|
SQLHDBC hdbc;
|
|
SQLCHAR sqlstmt[MAX_STMT_LEN + 1]="";
|
|
SQLRETURN rc;
|
|
|
|
rc = initialize(&henv, &hdbc);
|
|
if (rc == SQL_ERROR) return(terminate(henv, hdbc));
|
|
|
|
{SQLHSTMT hstmt;
|
|
SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = ?";
|
|
SQLCHAR deptname[15],
|
|
location[14],
|
|
division[11];
|
|
|
|
SQLINTEGER rlength,
|
|
plength;
|
|
|
|
rc = SQLAllocStmt(hdbc, &hstmt);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
|
|
|
|
/* prepare statement for multiple use */
|
|
rc = SQLPrepare(hstmt, sqlstmt, SQL_NTS);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
|
|
/* bind division to parameter marker in sqlstmt */
|
|
rc = SQLSetParam(hstmt, 1, SQL_CHAR, SQL_CHAR, 10, 10, division,
|
|
&plength);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
|
|
/* bind deptname to first column in the result set */
|
|
rc = SQLBindCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15,
|
|
&rlength);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
rc = SQLBindCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14,
|
|
&rlength);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
|
|
printf("\nEnter Division Name or 'q' to quit:\n");
|
|
printf("(Eastern, Western, Midwest, Corporate)\n");
|
|
gets(division);
|
|
plength = SQL_NTS;
|
|
|
|
while(division[0] != 'q')
|
|
{
|
|
rc = SQLExecute(hstmt);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
|
|
printf("Departments in %s Division:\n", division);
|
|
printf("DEPTNAME Location\n");
|
|
printf("-------------- -------------\n");
|
|
|
|
while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS)
|
|
{
|
|
printf("%-14.14s %-13.13s \n", deptname, location);
|
|
}
|
|
if (rc != SQL_NO_DATA_FOUND )
|
|
check_error (henv, hdbc, hstmt, rc);
|
|
SQLFreeStmt(hstmt, SQL_CLOSE);
|
|
printf("\nEnter Division Name or 'q' to quit:\n");
|
|
printf("(Eastern, Western, Midwest, Corporate)\n");
|
|
gets(division);
|
|
}
|
|
}
|
|
|
|
rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);
|
|
if (rc != SQL_SUCCESS )
|
|
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
|
|
|
|
terminate(henv, hdbc);
|
|
return (0);
|
|
}/* end main */</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">References</h4><ul><li><a href="rzadpfncolat.htm#rzadpfncolat">SQLColAttributes - Obtain column attributes</a></li>
|
|
<li><a href="rzadpfndecol.htm#rzadpfndecol">SQLDescribeCol - Describe column attributes</a></li>
|
|
<li><a href="rzadpfnexecd.htm#rzadpfnexecd">SQLExecDirect - Execute a statement directly</a></li>
|
|
<li><a href="rzadpfnexec.htm#rzadpfnexec">SQLExecute - Execute a statement</a></li>
|
|
<li><a href="rzadpfnnrcol.htm#rzadpfnnrcol">SQLNumResultCols - Get number of result columns</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzadphdapi.htm" title="This topic provides a description of each CLI function.">DB2 UDB CLI functions</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |