friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cli_5.4.0.1/rzadpfngcol.htm

363 lines
19 KiB
HTML
Raw Blame History

<?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="SQLGetCol - Retrieve one column of a row of the result set" />
<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="rzadpfngcol" />
<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>SQLGetCol</title>
</head>
<body id="rzadpfngcol"><a name="rzadpfngcol"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">SQLGetCol - Retrieve one column of a row of the result set</h1>
<div><div class="section"></div>
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetCol()</samp> retrieves data for a
single column in the current row of the result set. This is an alternative
to <samp class="codeph">SQLBindCol()</samp>, which transfers data directly into application
variables on a call to <samp class="codeph">SQLFetch()</samp>. <samp class="codeph">SQLGetCol()</samp> is
also used to retrieve large character based data in pieces.</p>
<p><samp class="codeph">SQLFetch()</samp> must
be called before <samp class="codeph">SQLGetCol()</samp>.</p>
<p>After calling <samp class="codeph">SQLGetCol()</samp> for
each column, <samp class="codeph">SQLFetch()</samp> is called to retrieve the next row.</p>
</div>
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLGetCol (SQLHSTMT hstmt,
SQLSMALLINT icol,
SQLSMALLINT fCType,
SQLPOINTER rgbValue,
SQLINTEGER cbValueMax,
SQLINTEGER *pcbValue);</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. SQLGetCol arguments</caption><thead align="left"><tr><th align="left" valign="top" width="20%" id="d0e72">Data type</th>
<th align="left" valign="top" width="20%" id="d0e74">Argument</th>
<th align="left" valign="top" width="20%" id="d0e76">Use</th>
<th align="left" valign="top" width="40%" id="d0e78">Description</th>
</tr>
</thead>
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLHSTMT</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>hstmt</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Input</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Statement handle.</td>
</tr>
<tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLINTEGER *</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>pcbValue</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Output</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Pointer to the value that indicates the number
of bytes DB2<sup>®</sup> UDB
CLI has available to return in the <em>rgbValue</em> buffer. If the data is
being retrieved in pieces, this contains the number of bytes still remaining,
excluding any bytes of the column's data that has been obtained from previous
calls to <samp class="codeph">SQLGetCol()</samp>. <p>The value is SQL_NULL_DATA if the
data value of the column is null. If this pointer is NULL and <samp class="codeph">SQLFetch()</samp> has
obtained a column containing null data, then this function fails because it
has no means of reporting this.</p>
<p>If <samp class="codeph">SQLFetch()</samp> has
fetched a column containing graphic data, then the pointer to <em>pcbValue</em> must
not be NULL or this function fails because it has no means of informing the
application about the length of the data retrieved in the <em>rgbValue</em> buffer.</p>
</td>
</tr>
<tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLINTEGER</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>cbValueMax</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Input</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Maximum size of the buffer pointed to by <em>rgbValue</em>.
If <em>fcType</em> is either SQL_DECIMAL or SQL_NUMERIC, <em>cbValueMax</em> must
be a precision and scale. The method to specify both values is to use (precision
* 256) + scale. This is also the value returned as the LENGTH of these data
types when using <samp class="codeph">SQLColAttributes()</samp>. </td>
</tr>
<tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLPOINTER</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>rgbValue</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Output</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Pointer to buffer where the retrieved column
data is to be stored.</td>
</tr>
<tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLSMALLINT</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>fCType</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Input</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Application data type of the column identified
by <em>icol</em>. The following types are supported: <ul><li>SQL_BIGINT</li>
<li>SQL_BINARY</li>
<li>SQL_BLOB</li>
<li>SQL_CHAR</li>
<li>SQL_CLOB</li>
<li>SQL_DATETIME</li>
<li>SQL_DBCLOB </li>
<li>SQL_DECIMAL</li>
<li>SQL_DOUBLE</li>
<li>SQL_FLOAT</li>
<li>SQL_GRAPHIC</li>
<li>SQL_INTEGER</li>
<li>SQL_NUMERIC</li>
<li>SQL_REAL</li>
<li>SQL_SMALLINT</li>
<li>SQL_TYPE_DATE</li>
<li>SQL_TYPE_TIME</li>
<li>SQL_TYPE_TIMESTAMP</li>
<li>SQL_VARBINARY</li>
<li>SQL_VARCHAR</li>
<li>SQL_VARGRAPHIC</li>
</ul>
</td>
</tr>
<tr><td align="left" valign="top" width="20%" headers="d0e72 ">SQLSMALLINT</td>
<td align="left" valign="top" width="20%" headers="d0e74 "><em>icol</em></td>
<td align="left" valign="top" width="20%" headers="d0e76 ">Input</td>
<td align="left" valign="top" width="40%" headers="d0e78 ">Column number for which the data retrieval
is requested.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Usage</h4><div class="p"><samp class="codeph">SQLGetCol()</samp> can be used with <samp class="codeph">SQLBindCol()</samp> for
the same row, as long as the value of <em>icol</em> does not specify a column
that has been bound. The general steps are: <ol><li><samp class="codeph">SQLFetch()</samp> - advances cursor to first row, retrieves
first row, transfers data for bound columns.</li>
<li><samp class="codeph">SQLGetCol()</samp> - transfers data for specified (unbound)
column.</li>
<li>Repeat step 2 for each column needed.</li>
<li><samp class="codeph">SQLFetch()</samp> - advances cursor to next row, retrieves next
row, transfers data for bound columns.</li>
<li>Repeat steps 2, 3 and 4 for each row in the result set, or until the result
set is no longer needed.</li>
</ol>
</div>
<p><samp class="codeph">SQLGetCol()</samp> retrieves long columns if the C
data type (<em>fCType</em>) is SQL_CHAR or if <em>fCType</em> is SQL_DEFAULT and
the column type is CHAR or VARCHAR.</p>
<p>On each <samp class="codeph">SQLGetCol()</samp> call,
if the data available for return is greater than or equal to <em>cbValueMax</em>,
truncation occurs. A function return code of SQL_SUCCESS_WITH_INFO that is
coupled with an SQLSTATE that denotes data truncation indicates truncation.
The application can call <samp class="codeph">SQLGetCol()</samp> again, with the same <em>icol</em> value,
to obtain later data from the same unbound column starting at the point of
truncation. To obtain the entire column, the application repeats such calls
until the function returns SQL_SUCCESS. The next call to <samp class="codeph">SQLGetCol()</samp> returns
SQL_NO_DATA_FOUND.</p>
<p>To discard the column data part way through the
retrieval, the application can call <samp class="codeph">SQLGetCol()</samp> with <em>icol</em> set
to the next column position of interest. To discard unretrieved data for the
entire row, the application should call <samp class="codeph">SQLFetch()</samp> to advance
the cursor to the next row; or, if it is not interested in any more data from
the result set, call <samp class="codeph">SQLFreeStmt()</samp> to close the cursor.</p>
<p>The <em>fCType</em> input
argument determines the type of data conversion (if any) needed before the
column data is placed into the storage area pointed to by <em>rgbValue</em>.</p>
<p>The
contents returned in rgbValue is always null-terminated unless <samp class="codeph">SQLSetEnvAttr()</samp> is
used to change the SQL_ATTR_OUTPUT_NTS attribute or if the application is
retrieving the data in multiple chunks. If the application is retrieving the
data in multiple chunks, the null-terminating byte is only added to the last
portion of data. </p>
<p>Truncation of numeric data types is not reported
if the truncation involves digits to the right of the decimal point. If truncation
occurs to the left of the decimal point, an error is returned (refer to the
diagnostics section).</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>
<li>SQL_NO_DATA_FOUND</li>
</ul>
<p>SQL_NO_DATA_FOUND is returned when the preceding <samp class="codeph">SQLGetCol()</samp> call
has retrieved all of the data for this column.</p>
<p>SQL_SUCCESS is returned
if a zero-length string is retrieved by <samp class="codeph">SQLGetCol()</samp>. If this
is the case, <em>pcbValue</em> contains 0, and <em>rgbValue</em> contains a null
terminator.</p>
<p>If the preceding call to <samp class="codeph">SQLFetch()</samp> fails, <samp class="codeph">SQLGetCol()</samp> should
not be called because the result is undefined.</p>
</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. SQLGetCol SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" width="25%" id="d0e374">SQLSTATE</th>
<th align="left" valign="top" width="25%" id="d0e376">Description</th>
<th align="left" valign="top" width="50%" id="d0e378">Explanation</th>
</tr>
</thead>
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e374 "><strong>07</strong>006</td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Restricted data type attribute violation</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">The data value cannot be converted to the
C data type specified by the argument <em>fCType</em>.</td>
</tr>
<tr><td align="left" valign="top" width="25%" headers="d0e374 "><strong>HY</strong>001</td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Memory allocation failure</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">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="d0e374 "><strong>HY</strong>009</td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Argument value that is not valid</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">The value of the argument <em>cbValueMax</em> is
less than 1 and the argument <em>fCType</em> is SQL_CHAR. <p>The specified
column number is not valid.</p>
<p>The argument <em>rgbValue</em> or <em>pcbValue</em> is
a null pointer.</p>
</td>
</tr>
<tr><td align="left" valign="top" width="25%" headers="d0e374 "><strong>HY</strong>010</td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Function sequence error</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">The specified <em>hstmt</em> is not in a cursor
positioned state. The function is called without first calling <samp class="codeph">SQLFetch()</samp>.</td>
</tr>
<tr><td align="left" valign="top" width="25%" headers="d0e374 "><strong>HY</strong>013 <strong>*</strong></td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Memory management problem</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">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="d0e374 "><strong>HY</strong>021</td>
<td valign="top" width="25%" headers="d0e376 ">Internal descriptor that is not valid </td>
<td valign="top" width="50%" headers="d0e378 ">The internal descriptor cannot be addressed or allocated,
or it contains a value that is not valid.</td>
</tr>
<tr><td align="left" valign="top" width="25%" headers="d0e374 "><strong>HY</strong>C00</td>
<td align="left" valign="top" width="25%" headers="d0e376 ">Driver not capable</td>
<td align="left" valign="top" width="50%" headers="d0e378 ">The SQL data type for the specified data
type is recognized but not supported by the driver. <p>The requested conversion
from the SQL data type to the application data <em>fCType</em> cannot be performed
by the driver or the data source.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>ODBC requires that <em>icol</em> not
specify a column of a lower number than the column last retrieved by <samp class="codeph">SQLGetCol()</samp> for
the same row on the same statement handle. ODBC also does not permit the use
of <samp class="codeph">SQLGetCol()</samp> to retrieve data for a column that resides
before the last bound column, (if any columns in the row have been bound).</p>
<p>DB2 UDB
CLI has relaxed both of these rules by allowing the value of <em>icol</em> to
be specified in any order and before a bound column, provided that <em>icol</em> does
not specify a bound column.</p>
</div>
<div class="section"><h4 class="sectiontitle">Example</h4></div>
<div class="example" id="rzadpfngcol__xmgdata"><a name="rzadpfngcol__xmgdata"><!-- --></a><p>Refer to the example in the <a href="rzadpfnfetch.htm">SQLFetch - Fetch next row</a> for a comparison between using bound columns
and using <samp class="codeph">SQLGetCol()</samp>.</p>
<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 = getcol.c
**
** Example of directly executing an SQL statement.
** Getcol is used to retrieve information from the result set.
** Compare to fetch.c
**
** Functions used:
**
** SQLAllocConnect SQLFreeConnect
** SQLAllocEnv SQLFreeEnv
** SQLAllocStmt SQLFreeStmt
** SQLConnect SQLDisconnect
**
** SQLBindCol SQLFetch
** SQLTransact SQLError
** SQLExecDirect SQLGetCursor
**************************************************************************/
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#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;
SQLCHAR sqlstmt[MAX_STMT_LEN + 1]="";
SQLRETURN rc;
rc = initialize(&amp;henv, &amp;hdbc);
if (rc != SQL_SUCCESS) return(terminate(henv, hdbc));
{SQLHSTMT hstmt;
SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = 'Eastern'";
SQLCHAR deptname[15],
location[14];
SQLINTEGER rlength;
rc = SQLAllocStmt(hdbc, &amp;hstmt);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, hstmt, rc);
printf("Departments in Eastern division:\n");
printf("DEPTNAME Location\n");
printf("-------------- -------------\n");
while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS)
{
rc = SQLGetCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15, &amp;rlength);
rc = SQLGetCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14, &amp;rlength);
printf("%-14.14s %-13.13s \n", deptname, location);
}
if (rc != SQL_NO_DATA_FOUND )
check_error (henv, hdbc, hstmt, rc);
}
rc = SQLTransact(henv, hdbc, SQL_COMMIT);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
terminate(henv, hdbc);
return (SQL_SUCCESS);
}/* end main */</pre>
</div>
</div>
<div class="section"><h4 class="sectiontitle">References</h4><ul><li><a href="rzadpfnbindc.htm#rzadpfnbindc">SQLBindCol - Bind a column to an application variable</a></li>
<li><a href="rzadpfnfetch.htm#rzadpfnfetch">SQLFetch - Fetch next row</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>
Reference in New Issue View Git Blame Copy Permalink