299 lines
14 KiB
HTML
299 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="SQLGetCursorName - Get cursor name" />
|
||
|
|
<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="rzadpfngcurn" />
|
||
|
|
<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>SQLGetCursorName</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfngcurn"><a name="rzadpfngcurn"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLGetCursorName - Get cursor name</h1>
|
||
|
|
<div><div class="section"></div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetCursorName()</samp> returns
|
||
|
|
the cursor name associated with the input statement handle. If a cursor name
|
||
|
|
is explicitly set by calling <samp class="codeph">SQLSetCursorName()</samp>, this name
|
||
|
|
is returned; otherwise, an implicitly generated name is returned.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLGetCursorName (SQLHSTMT hstmt,
|
||
|
|
SQLCHAR *szCursor,
|
||
|
|
SQLSMALLINT cbCursorMax,
|
||
|
|
SQLSMALLINT *pcbCursor);</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. SQLGetCursorName arguments</caption><thead align="left"><tr><th align="left" valign="top" width="20%" id="d0e51">Data type</th>
|
||
|
|
<th align="left" valign="top" width="20%" id="d0e53">Argument</th>
|
||
|
|
<th align="left" valign="top" width="20%" id="d0e55">Use</th>
|
||
|
|
<th align="left" valign="top" width="40%" id="d0e57">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e51 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e53 "><em>szCursor</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e55 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e57 ">Cursor name</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e51 ">SQLHSTMT</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e53 "><em>hstmt</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e55 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e57 ">Statement handle</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e51 ">SQLSMALLINT *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e53 "><em>pcbCursor</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e55 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e57 ">Amount of bytes available to return for <em>szCursor</em></td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e51 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e53 "><em>cbCursorMax</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e55 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e57 ">Length of buffer <em>szCursor</em></td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p><samp class="codeph">SQLGetCursorName()</samp> returns
|
||
|
|
a cursor name if a name is set using <samp class="codeph">SQLSetCursorName()</samp> or
|
||
|
|
if a SELECT statement is processed on the statement handle. If neither of
|
||
|
|
these is true, then calling <samp class="codeph">SQLGetCusorName()</samp> results in
|
||
|
|
an error.</p>
|
||
|
|
<p>If a name is set explicitly using <samp class="codeph">SQLSetCursorName()</samp>,
|
||
|
|
this name is returned until the statement is dropped, or until another explicit
|
||
|
|
name is set.</p>
|
||
|
|
<p>If an explicit name is not set, an implicit name is generated
|
||
|
|
when a SELECT statement is processed, and this name is returned. Implicit
|
||
|
|
cursor names always begin with SQLCUR.</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. SQLGetCursorName SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" width="25%" id="d0e151">SQLSTATE</th>
|
||
|
|
<th align="left" valign="top" width="25%" id="d0e153">Description</th>
|
||
|
|
<th align="left" valign="top" width="50%" id="d0e155">Explanation</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>01</strong>004</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Data truncated</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">The cursor name returned in <em>szCursor</em> is
|
||
|
|
longer than the value in <em>cbCursorMax</em>, and is truncated to <em>cbCursorMax</em> -
|
||
|
|
1 bytes. The argument <em>pcbCursor</em> contains the length of the full cursor
|
||
|
|
name available for return. The function returns SQL_SUCCESS_WITH_INFO.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>40</strong>003 <strong>*</strong></td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Statement completion unknown</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">The communication link between the CLI and
|
||
|
|
the data source fails before the function completes processing.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>58</strong>004</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">System error</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">Unrecoverable system error.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>HY</strong>001</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Memory allocation failure</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">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="d0e151 "><strong>HY</strong>009</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Argument value that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">The argument <em>szCursor</em> or <em>pcbCursor</em> is
|
||
|
|
a null pointer. <p>The value specified for the argument <em>cbCursorMax</em> is
|
||
|
|
less than 1.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>HY</strong>010</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Function sequence error</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">The statement <em>hstmt</em> is not in execute
|
||
|
|
state. Call <samp class="codeph">SQLExecute()</samp>, <samp class="codeph">SQLExecDirect()</samp> or <samp class="codeph">SQLSetCursorName()</samp> before
|
||
|
|
calling <samp class="codeph">SQLGetCursorName()</samp>.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>HY</strong>013 <strong>*</strong></td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">Memory management problem</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">The driver is unable to access memory required
|
||
|
|
to support the processing or completion of the function.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e151 "><strong>HY</strong>015</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e153 ">No cursor name available.</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e155 ">There is no open cursor on the <em>hstmt</em> and
|
||
|
|
no cursor name has been set with <samp class="codeph">SQLSetCursorName()</samp>. The
|
||
|
|
statement associated with <em>hstmt</em> does not support the use of a cursor.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>ODBC's generated cursor names start
|
||
|
|
with SQL_CUR and X/Open CLI generated cursor names begin with SQLCUR. DB2<sup>®</sup> UDB
|
||
|
|
CLI uses SQLCUR.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Example</h4></div>
|
||
|
|
<div class="example" id="rzadpfngcurn__xmgcurn"><a name="rzadpfngcurn__xmgcurn"><!-- --></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 = getcurs.c
|
||
|
|
**
|
||
|
|
** Example of directly executing a SELECT and positioned UPDATE SQL statement.
|
||
|
|
** Two statement handles are used, and SQLGetCursor is used to retrieve the
|
||
|
|
** generated cursor name.
|
||
|
|
**
|
||
|
|
** Functions used:
|
||
|
|
**
|
||
|
|
** SQLAllocConnect SQLFreeConnect
|
||
|
|
** SQLAllocEnv SQLFreeEnv
|
||
|
|
** SQLAllocStmt SQLFreeStmt
|
||
|
|
** SQLConnect SQLDisconnect
|
||
|
|
**
|
||
|
|
** SQLBindCol SQLFetch
|
||
|
|
** SQLTransact SQLError
|
||
|
|
** SQLExecDirect SQLGetCursorName
|
||
|
|
**************************************************************************/
|
||
|
|
#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 frc);
|
||
|
|
|
||
|
|
/*******************************************************************
|
||
|
|
** main
|
||
|
|
** - initialize
|
||
|
|
** - terminate
|
||
|
|
*******************************************************************/
|
||
|
|
int main()
|
||
|
|
{
|
||
|
|
SQLHENV henv;
|
||
|
|
SQLHDBC hdbc;
|
||
|
|
SQLRETURN rc,
|
||
|
|
rc2;
|
||
|
|
|
||
|
|
rc = initialize(&henv, &hdbc);
|
||
|
|
if (rc != SQL_SUCCESS) return(terminate(henv, hdbc));
|
||
|
|
|
||
|
|
{SQLHSTMT hstmt1,
|
||
|
|
hstmt2;
|
||
|
|
SQLCHAR sqlstmt[]="SELECT name, job from staff for update of job";
|
||
|
|
SQLCHAR updstmt[MAX_STMT_LEN + 1];
|
||
|
|
SQLCHAR name[10],
|
||
|
|
job[6],
|
||
|
|
newjob[6],
|
||
|
|
cursor[19];
|
||
|
|
|
||
|
|
SQLINTEGER rlength, attr;
|
||
|
|
SQLSMALLINT clength;
|
||
|
|
|
||
|
|
rc = SQLAllocStmt(hdbc, &hstmt1);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
|
||
|
|
/* make sure the statement is update-capable */
|
||
|
|
attr = SQL_FALSE;
|
||
|
|
rc = SQLSetStmtAttr(hstmt1,SQL_ATTR_FOR_FETCH_ONLY, &attr, 0);
|
||
|
|
|
||
|
|
/* allocate second statement handle for update statement */
|
||
|
|
rc2 = SQLAllocStmt(hdbc, &hstmt2);
|
||
|
|
if (rc2 != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
|
||
|
|
rc = SQLExecDirect(hstmt1, sqlstmt, SQL_NTS);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, hstmt1, rc);
|
||
|
|
|
||
|
|
/* Get Cursor of the SELECT statement's handle */
|
||
|
|
rc = SQLGetCursorName(hstmt1, cursor, 19, &clength);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, hstmt1, rc);
|
||
|
|
|
||
|
|
/* bind name to first column in the result set */
|
||
|
|
rc = SQLBindCol(hstmt1, 1, SQL_CHAR, (SQLPOINTER) name, 10,
|
||
|
|
&rlength);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, hstmt1, rc);
|
||
|
|
|
||
|
|
/* bind job to second column in the result set */
|
||
|
|
rc = SQLBindCol(hstmt1, 2, SQL_CHAR, (SQLPOINTER) job, 6,
|
||
|
|
&rlength);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, hstmt1, rc);
|
||
|
|
|
||
|
|
|
||
|
|
printf("Job Change for all clerks\n");
|
||
|
|
|
||
|
|
while ((rc = SQLFetch(hstmt1)) == SQL_SUCCESS)
|
||
|
|
{
|
||
|
|
printf("Name: %-9.9s Job: %-5.5s \n", name, job);
|
||
|
|
printf("Enter new job or return to continue\n");
|
||
|
|
gets(newjob);
|
||
|
|
if (newjob[0] != '\0')
|
||
|
|
{
|
||
|
|
sprintf( updstmt,
|
||
|
|
"UPDATE staff set job = '%s' where current of %s",
|
||
|
|
newjob, cursor);
|
||
|
|
rc2 = SQLExecDirect(hstmt2, updstmt, SQL_NTS);
|
||
|
|
if (rc2 != SQL_SUCCESS )
|
||
|
|
check_error (henv, hdbc, hstmt2, rc);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
if (rc != SQL_NO_DATA_FOUND )
|
||
|
|
check_error (henv, hdbc, hstmt1, rc);
|
||
|
|
SQLFreeStmt(hstmt1, SQL_CLOSE);
|
||
|
|
}
|
||
|
|
|
||
|
|
printf("Commiting Transaction\n");
|
||
|
|
rc = SQLTransact(henv, hdbc, SQL_COMMIT);
|
||
|
|
if (rc != SQL_NO_DATA_FOUND )
|
||
|
|
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="rzadpfnexec.htm#rzadpfnexec">SQLExecute - Execute a statement</a></li>
|
||
|
|
<li><a href="rzadpfnexecd.htm#rzadpfnexecd">SQLExecDirect - Execute a statement directly</a></li>
|
||
|
|
<li><a href="rzadpfnscurn.htm#rzadpfnscurn">SQLSetCursorName - Set cursor name</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>
|