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

254 lines
17 KiB
HTML
Raw Permalink 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="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>
Reference in New Issue View Git Blame Copy Permalink