211 lines
14 KiB
HTML
211 lines
14 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="SQLBindFileToCol - Bind LOB file reference to LOB column" />
|
|
<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="rzadpfnbndfc" />
|
|
<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>SQLBindFileToCol - Bind LOB file reference to LOB column</title>
|
|
</head>
|
|
<body id="rzadpfnbndfc"><a name="rzadpfnbndfc"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLBindFileToCol - Bind LOB file reference to LOB column</h1>
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLBindFileToCol()</samp> is
|
|
used to associate (bind) an LOB column in a result set to a file reference
|
|
or an array of file references. This enables data in that column to be transferred
|
|
directly into a file when each row is fetched for the statement handle.</p>
|
|
<p>The
|
|
LOB file reference arguments (file name, file name length, file reference
|
|
options) refer to a file within the application's environment (on the client).
|
|
Before fetching each row, the application must make sure that these variables
|
|
contain the name of a file, the length of the file name, and a file option
|
|
(new / overwrite / append). These values can be changed between each fetch.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><div class="p"> <pre>SQLRETURN SQLBindFileToCol (SQLHSTMT StatementHandle,
|
|
SQLSMALLINT ColumnNumber,
|
|
SQLCHAR *FileName,
|
|
SQLSMALLINT *FileNameLength,
|
|
SQLINTEGER *FileOptions,
|
|
SQLSMALLINT MaxFileNameLength,
|
|
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. SQLBindFileToCol arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e50">Data type</th>
|
|
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e52">Argument</th>
|
|
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e54">Use</th>
|
|
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e56">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>FileName</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Pointer to the location that contains the
|
|
file name or an array of file names at the time of the next fetch using the <span class="synph"><span class="var">StatementHandle</span></span>.
|
|
This is either the complete path name of the file(s) or a relative file name(s).
|
|
If relative file name(s) are provided, they are appended to the current path
|
|
of the running application. This pointer cannot be NULL.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLHSTMT</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>StatementHandle</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Statement handle.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>FileOptions</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Pointer to the location that contains the
|
|
file option to be used when writing the file at the time of the next fetch
|
|
using the <span class="synph"><span class="var">StatementHandle</span></span>. The following <span class="synph"><span class="var">FileOptions</span></span> are
|
|
supported: <dl><dt class="dlterm">SQL_FILE_CREATE</dt>
|
|
<dd>Create a new file. If a file by this name already exists, SQL_ERROR is
|
|
returned.</dd>
|
|
<dt class="dlterm">SQL_FILE_OVERWRITE</dt>
|
|
<dd>If the file already exists, overwrite it. Otherwise, create a new file.</dd>
|
|
<dt class="dlterm">SQL_FILE_APPEND</dt>
|
|
<dd>If the file already exists, append the data to it. Otherwise, create a
|
|
new file.</dd>
|
|
</dl>
|
|
<p>Only one option can be chosen per file, there is no default.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>IndicatorValue</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Output (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Pointer to the location that contains an
|
|
indicator value.
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>StringLength</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Output (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Pointer to the location that contains the
|
|
length in bytes of the LOB data that is returned. If this pointer is NULL,
|
|
nothing is returned.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLSMALLINT *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>FileNameLength</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Pointer to the location that contains the
|
|
length of the file name (or an array of lengths) at the time the next fetch
|
|
using the <span class="synph"><span class="var">StatementHandle</span></span>. If this pointer is NULL,
|
|
then a length of <span>SQL_NTS</span> is assumed. <p>The maximum value of the
|
|
file name length is 255.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>ColumnNumber</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">Number identifying the column. Columns are
|
|
numbered sequentially, from left to right, starting at 1.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e50 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e52 "><em>MaxFileNameLength</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e54 ">Input</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e56 ">This specifies the length of the <span class="synph"><span class="var">FileName</span></span> buffer.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p>The application calls <samp class="codeph">SQLBindFileToCol()</samp> once
|
|
for each column that should be transferred directly to a file when a row is
|
|
fetched. LOB data is written directly to the file without any data conversion,
|
|
and without appending null-terminators.</p>
|
|
<p><span class="synph"><span class="var">FileName</span></span>, <span class="synph"><span class="var">FileNameLength</span></span>,
|
|
and <span class="synph"><span class="var">FileOptions</span></span> must be set before each fetch. When <samp class="codeph">SQLFetch()</samp> or <samp class="codeph">SQLFetchScroll()</samp> is
|
|
called, the data for any column which has been bound to an LOB file reference
|
|
is written to the file or files pointed to by that file reference. Errors
|
|
associated with the deferred input argument values of <samp class="codeph">SQLBindFileToCol()</samp> are
|
|
reported at fetch time. The LOB file reference, and the deferred <span class="synph"><span class="var">StringLength</span></span> and <span class="synph"><span class="var">IndicatorValue</span></span> output arguments are updated between fetch operations.</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_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. SQLBindFileToCol SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="25%" id="d0e250">SQLSTATE</th>
|
|
<th align="left" valign="bottom" width="25%" id="d0e252">Description</th>
|
|
<th align="left" valign="bottom" width="50%" id="d0e254">Explanation</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e250 "><strong>58</strong>004 </td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">Unexpected system failure</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 ">Unrecoverable system error.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e250 "><strong>HY</strong>002</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">Column number that is not valid</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 ">The value specified for the argument <span class="synph"><span class="var">icol</span></span> is
|
|
less than 1. <p>The value specified for the argument <span class="synph"><span class="var">icol</span></span> exceeded
|
|
the maximum number of columns supported by the data source.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e250 "><strong>HY</strong>009</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">Argument value that is not valid</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 "><span class="synph"><span class="var">FileName</span></span>, <span class="synph"><span class="var">StringLength</span></span>,
|
|
or <span class="synph"><span class="var">FileOptions</span></span> is a null pointer.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e250 "><strong>HY</strong>010</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">Function sequence error</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 ">The function is called while in a data-at-processing
|
|
(<samp class="codeph">SQLParamData()</samp>, <samp class="codeph">SQLPutData()</samp>) operation.
|
|
<p>The function is called while within a BEGIN COMPOUND and END COMPOUND
|
|
SQL operation.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td valign="top" width="25%" headers="d0e250 "><strong>HY</strong>021</td>
|
|
<td valign="top" width="25%" headers="d0e252 ">Internal descriptor that is not valid</td>
|
|
<td valign="top" width="50%" headers="d0e254 ">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="d0e250 "><strong>HY</strong>090</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">String or buffer length that is not valid</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 ">The value specified for the argument <span class="synph"><span class="var">MaxFileNameLength</span></span> is
|
|
less than 0.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e250 "><strong>HY</strong>C00</td>
|
|
<td align="left" valign="top" width="25%" headers="d0e252 ">Driver not capable</td>
|
|
<td align="left" valign="top" width="50%" headers="d0e254 ">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 DB2<sup>®</sup> servers
|
|
that do not support Large Object data types. </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="rzadpfnbndfp.htm#rzadpfnbndfp">SQLBindFileToParam - Bind LOB file reference to LOB parameter</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> |