232 lines
16 KiB
HTML
232 lines
16 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="SQLGetPosition - Return starting position of string" />
|
|
<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="rzadpfngtpos" />
|
|
<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>SQLGetPosition</title>
|
|
</head>
|
|
<body id="rzadpfngtpos"><a name="rzadpfngtpos"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLGetPosition - Return starting position of string</h1>
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetPosition()</samp> is
|
|
used to return the starting position of one string within an LOB value (the
|
|
source). The source value must be an LOB locator, the search string can be
|
|
an LOB locator or a literal string.</p>
|
|
<p> The source and search LOB locators
|
|
can be any that have been returned from the database from a fetch or a <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 SQLGetPosition (SQLHSTMT StatementHandle,
|
|
SQLSMALLINT LocatorCType,
|
|
SQLINTEGER SourceLocator,
|
|
SQLINTEGER SearchLocator,
|
|
SQLCHAR *SearchLiteral,
|
|
SQLINTEGER SearchLiteralLength,
|
|
SQLINTEGER FromPosition,
|
|
SQLINTEGER *LocatedAt,
|
|
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. SQLGetPosition arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="21.37546468401487%" id="d0e55">Data type</th>
|
|
<th align="left" valign="bottom" width="22.490706319702603%" id="d0e57">Argument </th>
|
|
<th align="left" valign="bottom" width="11.152416356877323%" id="d0e59">Use </th>
|
|
<th align="left" valign="bottom" width="44.98141263940521%" id="d0e61">Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>SearchLiteral</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">This argument points to the area of storage
|
|
that contains the search string literal. <p>If <span class="synph"><span class="var">SearchLiteralLength</span></span> is
|
|
0, this pointer must be NULL.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLHSTMT </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>StatementHandle</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">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="21.37546468401487%" headers="d0e55 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>IndicatorValue</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Output </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">Always set to zero.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>LocatedAt</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Output </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">For BLOBs and CLOBs, this is the byte position
|
|
at which the string is located or, if not located, the value zero. For DBCLOBs,
|
|
this is the character position. <p> If the length of the source string is
|
|
zero, the value 1 is returned.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLINTEGER </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>FromPosition </em></td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">For BLOBs and CLOBs, this is the position
|
|
of the first byte within the source string at which the search is to start.
|
|
to be returned by the function. For DBCLOBs, this is the first character.
|
|
The start byte or character is numbered 1.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLINTEGER </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>SearchLiteralLength</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">The length of the string in <span class="synph"><span class="var">SearchLiteral</span></span>(in
|
|
bytes).<sup>1</sup> <p>If this argument value is 0, then the argument <span class="synph"><span class="var">SearchLocator</span></span> is
|
|
meaningful.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLINTEGER </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>SearchLocator</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">If the <span class="synph"><span class="var">SearchLiteral</span></span> pointer
|
|
is NULL and if <span class="synph"><span class="var">SearchLiteralLength</span></span> is set to 0,
|
|
then <span class="synph"><span class="var">SearchLocator</span></span> must be set to the LOB locator
|
|
associated with the search string; otherwise, this argument is ignored.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLINTEGER </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>SourceLocator</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 "><span class="synph"><span class="var">SourceLocator</span></span> must
|
|
be set to the source LOB locator.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="21.37546468401487%" headers="d0e55 ">SQLSMALLINT </td>
|
|
<td align="left" valign="top" width="22.490706319702603%" headers="d0e57 "><em>LocatorCType</em> </td>
|
|
<td align="left" valign="top" width="11.152416356877323%" headers="d0e59 ">Input </td>
|
|
<td align="left" valign="top" width="44.98141263940521%" headers="d0e61 ">The C type of the source LOB locator. This
|
|
can be: <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="d0e55 d0e57 d0e59 d0e61 "><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">SQLGetPosition()</samp> is used
|
|
in conjunction with <samp class="codeph">SQLGetSubString()</samp> in order to obtain
|
|
any portion of a string in a random manner. In order to use <samp class="codeph">SQLGetSubString()</samp>,
|
|
the location of the substring within the overall string must be known in advance.
|
|
In situations where the start of that substring can be found by a search
|
|
string, <samp class="codeph">SQLGetPosition()</samp> can be used to obtain the starting
|
|
position of that substring.</p>
|
|
<p> The <span class="synph"><span class="var">Locator</span></span> and <span class="synph"><span class="var">SearchLocator</span></span> (if
|
|
used) arguments can contain any valid LOB locator which has not been explicitly
|
|
freed using a FREE LOCATOR statement or implicitly freed because the transaction
|
|
during which it is created has terminated.</p>
|
|
<p> The <span class="synph"><span class="var">Locator</span></span> and <span class="synph"><span class="var">SearchLocator</span></span> must
|
|
have the same LOB locator type.</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. SQLGetPosition SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e280">SQLSTATE </th>
|
|
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e282">Description </th>
|
|
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e284">Explanation </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>07</strong>006 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Conversion that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">The combination of the <span class="synph"><span class="var">LocatorCType</span></span> argument
|
|
and either of the LOB locator values is not valid.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="12.962962962962962%" headers="d0e280 "><strong>0F</strong>001 </td>
|
|
<td valign="top" width="29.074074074074076%" headers="d0e282 ">LOB variable that is not valid</td>
|
|
<td valign="top" width="57.96296296296296%" headers="d0e284 ">The value specified for argument <span class="synph"><span class="var">Locator</span></span> or <span class="synph"><span class="var">SearchLocator</span></span> is
|
|
not currently an LOB locator.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>42</strong>818 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Length that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">The length of the pattern is too long.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>58</strong>004 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Unexpected system failure</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">Unrecoverable system error.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>HY</strong>009 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Argument value that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">The argument <span class="synph"><span class="var">LocatedAt</span></span> or <span class="synph"><span class="var">IndicatorValue</span></span> is
|
|
a null pointer. <p>The argument value for <span class="synph"><span class="var">FromPosition</span></span> is
|
|
not greater than 0.</p>
|
|
<p> <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.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>HY</strong>010 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Function sequence error</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">The specified <span class="synph"><span class="var">StatementHandle</span></span> argument
|
|
is not in an <span class="synph"><span class="var">allocated</span></span> state.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="12.962962962962962%" headers="d0e280 "><strong>HY</strong>021</td>
|
|
<td valign="top" width="29.074074074074076%" headers="d0e282 ">Internal descriptor that is not valid </td>
|
|
<td valign="top" width="57.96296296296296%" headers="d0e284 ">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="d0e280 "><strong>HY</strong>090 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">String or buffer length that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">The value of <span class="synph"><span class="var">SearchLiteralLength</span></span> is
|
|
less than 1, and not SQL_NTS.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e280 "><strong>HY</strong>C00 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e282 ">Driver not capable</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e284 ">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="rzadpfnexfet.htm#rzadpfnexfet">SQLExtendedFetch - Fetch array of rows</a></li>
|
|
<li><a href="rzadpfnfetch.htm#rzadpfnfetch">SQLFetch - Fetch next row</a></li>
|
|
<li><a href="rzadpfngtlen.htm#rzadpfngtlen">SQLGetLength - Retrieve length of a string value</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> |