176 lines
11 KiB
HTML
176 lines
11 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="SQLGetLength - Retrieve length of a string value" />
|
||
|
|
<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="rzadpfngtlen" />
|
||
|
|
<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>SQLGetLength</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfngtlen"><a name="rzadpfngtlen"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLGetLength - Retrieve length of a string value</h1>
|
||
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetLength()</samp> is
|
||
|
|
used to retrieve the length of a large object value, referenced by a large
|
||
|
|
object locator that has been returned from the server (as a result of a fetch,
|
||
|
|
or an <samp class="codeph">SQLGetSubString()</samp> call) during the current transaction.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><div class="p"> <pre>SQLRETURN SQLGetLength (SQLHSTMT StatementHandle,
|
||
|
|
SQLSMALLINT LocatorCType,
|
||
|
|
SQLINTEGER Locator,
|
||
|
|
SQLINTEGER *StringLength,
|
||
|
|
SQLINTEGER *IndicatorValue);</pre>
|
||
|
|
</div>
|
||
|
|
</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. SQLGetLength arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e53">Data type</th>
|
||
|
|
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e55">Argument </th>
|
||
|
|
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e57">Use </th>
|
||
|
|
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e59">Description </th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLHSTMT </td>
|
||
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><em>StatementHandle</em> </td>
|
||
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Statement handle. This can be any statement
|
||
|
|
handle which has been allocated but which does not currently have a prepared
|
||
|
|
statement assigned to it.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLINTEGER *</td>
|
||
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><em>IndicatorValue</em> </td>
|
||
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Output </td>
|
||
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Always set to zero.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLINTEGER *</td>
|
||
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><em>StringLength</em></td>
|
||
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Output </td>
|
||
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">The length of the specified locator.<sup>1</sup> <p>If
|
||
|
|
the pointer is set to NULL then the SQLSTATE <span class="uicontrol">HY</span>009
|
||
|
|
is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLINTEGER </td>
|
||
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><em>Locator </em></td>
|
||
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Must be set to the LOB locator value.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLSMALLINT </td>
|
||
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><em>LocatorCType </em> </td>
|
||
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">The C type of the source LOB locator. <ul><li>SQL_C_BLOB_LOCATOR</li>
|
||
|
|
<li>SQL_C_CLOB_LOCATOR</li>
|
||
|
|
<li>SQL_C_DBCLOB_LOCATOR</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td colspan="4" valign="top" headers="d0e53 d0e55 d0e57 d0e59 "><p>1. This is in bytes even for DBCLOB
|
||
|
|
data.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p> <samp class="codeph">SQLGetLength()</samp> can be used
|
||
|
|
to determine the length of the data value represented by an LOB locator. It
|
||
|
|
is used by applications to determine the overall length of the referenced
|
||
|
|
LOB value so that the appropriate strategy to obtain some or all of the LOB
|
||
|
|
value can be chosen.</p>
|
||
|
|
<p>The Locator argument can contain any valid LOB
|
||
|
|
locator which has not been explicitly freed using a FREE LOCATOR statement
|
||
|
|
nor implicitly freed because the transaction during which it is created has
|
||
|
|
terminated.</p>
|
||
|
|
<p>The statement handle must not have been associated with
|
||
|
|
any prepared statements or catalog function calls.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Return codes</h4><div class="p"> <ul><li>SQL_SUCCESS</li>
|
||
|
|
<li>SQL_SUCCESS_WITH_INFO</li>
|
||
|
|
<li>SQL_STILL_EXECUTING</li>
|
||
|
|
<li>SQL_ERROR</li>
|
||
|
|
<li>SQL_INVALID_HANDLE</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Error conditions</h4>
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLGetLength SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e179">SQLSTATE </th>
|
||
|
|
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e181">Description </th>
|
||
|
|
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e183">Explanation </th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e179 "><strong>07</strong>006 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Conversion that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">The combination of the argument<span class="synph"><span class="var">LocatorCType</span></span> and <span class="synph"><span class="var">Locator</span> </span> is
|
||
|
|
not valid.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="12.962962962962962%" headers="d0e179 "><strong>0F</strong>001 </td>
|
||
|
|
<td valign="top" width="29.074074074074076%" headers="d0e181 ">LOB variable that is not valid</td>
|
||
|
|
<td valign="top" width="57.96296296296296%" headers="d0e183 ">The value specified for the argument <span class="synph"><span class="var">Locator</span></span> has
|
||
|
|
not been associated with an LOB locator.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e179 "><strong>58</strong>004 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Unexpected system failure</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">Unrecoverable system error.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e179 "><strong>HY</strong>003 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Program type out of range</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">The argument <span class="synph"><span class="var">LocatorCType</span></span> is
|
||
|
|
not one of SQL_C_CLOB_LOCATOR, SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e179 "><strong>HY</strong>009 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Argument value that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">The argument <span class="synph"><span class="var">StringLength</span></span> or <span class="synph"><span class="var">IndicatorValue</span></span> is
|
||
|
|
a null pointer.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e179 "><strong>HY</strong>010 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Function sequence error</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">The specified argument <span class="synph"><span class="var">StatementHandle</span></span> is
|
||
|
|
not in an <span class="synph"><span class="var">allocated</span></span> state.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="12.962962962962962%" headers="d0e179 "><strong>HY</strong>021</td>
|
||
|
|
<td valign="top" width="29.074074074074076%" headers="d0e181 ">Internal descriptor that is not valid</td>
|
||
|
|
<td valign="top" width="57.96296296296296%" headers="d0e183 ">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="12.962962962962962%" headers="d0e179 "><strong>HY</strong>C00 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e181 ">Driver not capable</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e183 ">The application is currently connected to
|
||
|
|
a data source that does not support large objects.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p> This function is not available when
|
||
|
|
connected to a DB2<sup>®</sup> server
|
||
|
|
that does not support Large Objects. </p>
|
||
|
|
</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>
|
||
|
|
<li><a href="rzadpfngtpos.htm#rzadpfngtpos">SQLGetPosition - Return starting position of string</a></li>
|
||
|
|
<li><a href="rzadpfngtsbs.htm#rzadpfngtsbs">SQLGetSubString - Retrieve portion of a string value</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>
|