254 lines
17 KiB
HTML
254 lines
17 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="SQLGetSubString - Retrieve portion 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="rzadpfngtsbs" />
|
||
|
|
<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>SQLGetSubString</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfngtsbs"><a name="rzadpfngtsbs"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLGetSubString - Retrieve portion of a string value</h1>
|
||
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p> <samp class="codeph">SQLGetSubString()</samp> is
|
||
|
|
used to retrieve a portion of a large object value, referenced by a large
|
||
|
|
object locator that has been returned from the server (returned by a fetch
|
||
|
|
or a previous <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 SQLGetSubString (
|
||
|
|
SQLHSTMT StatementHandle,
|
||
|
|
SQLSMALLINT LocatorCType,
|
||
|
|
SQLINTEGER SourceLocator,
|
||
|
|
SQLINTEGER FromPosition,
|
||
|
|
SQLINTEGER ForLength,
|
||
|
|
SQLSMALLINT TargetCType,
|
||
|
|
SQLPOINTER DataPtr,
|
||
|
|
SQLINTEGER BufferLength,
|
||
|
|
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. SQLGetSubString arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="26.629422718808193%" id="d0e54">Data type</th>
|
||
|
|
<th align="left" valign="bottom" width="21.042830540037244%" id="d0e56">Argument </th>
|
||
|
|
<th align="left" valign="bottom" width="10.42830540037244%" id="d0e58">Use </th>
|
||
|
|
<th align="left" valign="bottom" width="41.899441340782126%" id="d0e60">Description </th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLHSTMT </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>StatementHandle</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">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="26.629422718808193%" headers="d0e54 ">SQLINTEGER *</td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>IndicatorValue</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">output </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">Always set to zero.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLINTEGER *</td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>StringLength</em></td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">output </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">The length of the returned information in <span class="synph"><span class="var">DataPtr</span></span> in
|
||
|
|
bytes<sup>a</sup> if the target C buffer type is intended for a binary or
|
||
|
|
character string variable and not a locator value. <p> If the pointer is
|
||
|
|
set to NULL, nothing is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLINTEGER </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>BufferLength</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">Maximum size of the buffer pointed to by <span class="synph"><span class="var">DataPtr</span></span> in
|
||
|
|
bytes.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLINTEGER </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>ForLength</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">This is the length of the string to be returned
|
||
|
|
by the function. For BLOBs and CLOBs, this is the length in bytes. For DBCLOBs,
|
||
|
|
this is the length in characters. <p>If <span class="synph"><span class="var">FromPosition</span></span> is
|
||
|
|
less than the length of the source string but <span class="synph"><span class="var">FromPosition</span></span> + <span class="synph"><span class="var">ForLength</span></span> -
|
||
|
|
1 extends beyond the end of the source string, the result is padded on the
|
||
|
|
right with the necessary number of characters (X'00' for BLOBs, single byte
|
||
|
|
blank character for CLOBs, and double byte blank character for DBCLOBs).</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLINTEGER </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>FromPosition </em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">For BLOBs and CLOBs, this is the position
|
||
|
|
of the first byte 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="26.629422718808193%" headers="d0e54 ">SQLINTEGER </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>SourceLocator </em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 "><span class="synph"><span class="var">SourceLocator</span></span> must
|
||
|
|
be set to the source LOB locator value.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLPOINTER </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>DataPtr</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">output </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">Pointer to the buffer where the retrieved
|
||
|
|
string value or an LOB locator is to be stored.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLSMALLINT </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>LocatorCType</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">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 align="left" valign="top" width="26.629422718808193%" headers="d0e54 ">SQLSMALLINT </td>
|
||
|
|
<td align="left" valign="top" width="21.042830540037244%" headers="d0e56 "><em>TargetCType</em> </td>
|
||
|
|
<td align="left" valign="top" width="10.42830540037244%" headers="d0e58 ">input </td>
|
||
|
|
<td align="left" valign="top" width="41.899441340782126%" headers="d0e60 ">The C data type of the <span class="synph"><span class="var">DataPtr</span></span>.
|
||
|
|
The target must be a C string variable (SQL_C_CHAR, SQL_C_WCHAR, SQL_C_BINARY,
|
||
|
|
or SQL_C_DBCHAR).</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td colspan="4" valign="top" headers="d0e54 d0e56 d0e58 d0e60 "><div class="note"><span class="notetitle">Note:</span> 1. This is in bytes even
|
||
|
|
for DBCLOB data. </div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><div class="p"> <samp class="codeph">SQLGetSubString()</samp> is used
|
||
|
|
to obtain any portion of the string that is represented by the LOB locator.
|
||
|
|
There are two choices for the target: <ul><li>The target can be an appropriate C string variable.</li>
|
||
|
|
<li>A new LOB value can be created on the server and the LOB locator for that
|
||
|
|
value can be assigned to a target application variable on the client.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p> <samp class="codeph">SQLGetSubString()</samp> can be used
|
||
|
|
as an alternative to <samp class="codeph">SQLGetData()</samp> for getting data in pieces.
|
||
|
|
In this case a column is first bound to an LOB locator, which is then used
|
||
|
|
to fetch the LOB as a whole or in pieces.</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><p> </p>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLGetSubString SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e278">SQLSTATE </th>
|
||
|
|
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e280">Description </th>
|
||
|
|
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e282">Explanation </th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>01</strong>004 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Data truncated </td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The amount of data to be returned is longer
|
||
|
|
than <span class="synph"><span class="var">BufferLength</span></span>. Actual length available for return
|
||
|
|
is stored in <span class="synph"><span class="var">StringLength</span></span>.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>07</strong>006 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Conversion that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The value specified for <span class="synph"><span class="var">TargetCType</span></span> is
|
||
|
|
not SQL_C_CHAR, SQL_C_BINARY, SQL_C_DBCHAR, or an LOB locator. <p>The value
|
||
|
|
specified for <span class="synph"><span class="var">TargetCType</span></span> is inappropriate for the
|
||
|
|
source (for example SQL_C_DBCHAR for a BLOB column).</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>22</strong>011 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Substring error occurred</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 "><span class="synph"><span class="var">FromPosition</span></span> is
|
||
|
|
greater than the length of the source string.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>58</strong>004 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 "> Unexpected system failure</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">Unrecoverable system error.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>HY</strong>003 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Program type out of range</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 "><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="d0e278 "><strong>HY</strong>009 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Argument value that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The value specified for <span class="synph"><span class="var">FromPosition</span></span> or <span class="synph"><span class="var">ForLength</span></span> is
|
||
|
|
not a positive integer. <p>The argument <span class="synph"><span class="var">DataPtr</span></span>, <span class="synph"><span class="var">StringLength</span></span>,
|
||
|
|
or <span class="synph"><span class="var">IndicatorValue</span></span> is a null pointer</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>HY</strong>010 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Function sequence error</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The specified <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="d0e278 "><strong>HY</strong>021</td>
|
||
|
|
<td valign="top" width="29.074074074074076%" headers="d0e280 ">Internal descriptor that is not valid </td>
|
||
|
|
<td valign="top" width="57.96296296296296%" headers="d0e282 ">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="d0e278 "><strong>HY</strong>090 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">String or buffer length that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The value of <span class="synph"><span class="var">BufferLength</span></span> is
|
||
|
|
less than 0.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 "><strong>HY</strong>C00 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">Driver not capable</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The application is currently connected to
|
||
|
|
a data source that does not support large objects.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e278 ">0F001 </td>
|
||
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e280 ">No locator currently assigned</td>
|
||
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e282 ">The value specified for <span class="synph"><span class="var">Locator</span></span> is
|
||
|
|
not currently an LOB locator.</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><div class="p"> <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="rzadpfngdata.htm#rzadpfngdata">SQLGetData - Get data from a column</a></li>
|
||
|
|
<li><a href="rzadpfngtlen.htm#rzadpfngtlen">SQLGetLength - Retrieve length of a string value</a></li>
|
||
|
|
<li><a href="rzadpfngtpos.htm#rzadpfngtpos">SQLGetPosition - Return starting position of string</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</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>
|