217 lines
15 KiB
HTML
217 lines
15 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="SQLBindFileToParam - Bind LOB file reference to LOB parameter" />
|
|
<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="rzadpfnbndfp" />
|
|
<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>SQLBindFileToParam - Bind LOB file reference to LOB parameter</title>
|
|
</head>
|
|
<body id="rzadpfnbndfp"><a name="rzadpfnbndfp"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLBindFileToParam - Bind LOB file reference to LOB parameter</h1>
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLBindFileToParam()</samp> is
|
|
used to associate (bind) a parameter marker in an SQL statement to a file
|
|
reference or an array of file references. This enables data from the file
|
|
to be transferred directly into an LOB column when that statement is subsequently
|
|
processed.</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 calling <samp class="codeph">SQLExecute()</samp> or <samp class="codeph">SQLExecDirect()</samp>,
|
|
the application must make sure that this information is available in the deferred
|
|
input buffers. These values can be changed between <samp class="codeph">SQLExecute()</samp> calls.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><div class="p">
|
|
<pre>SQLRETURN SQLBindFileToParam (SQLHSTMT StatementHandle,
|
|
SQLSMALLINT ParameterNumber,
|
|
SQLSMALLINT DataType,
|
|
SQLCHAR *FileName,
|
|
SQLSMALLINT *FileNameLength,
|
|
SQLINTEGER *FileOptions,
|
|
SQLSMALLINT MaxFileNameLength,
|
|
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. SQLBindFileToParam arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e58">Data type</th>
|
|
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e60">Argument </th>
|
|
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e62">Use</th>
|
|
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e64">Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>FileName</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Pointer to the location that contains the
|
|
file name or an array of file names when the statement (<span class="synph"><span class="var">StatementHandle</span></span>)
|
|
is processed. This is either the complete path name of the file or a relative
|
|
file name. If a relative file name is provided, it is appended to the current
|
|
path of the client process. <p>This argument cannot be NULL.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLHSTMT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>StatementHandle</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Statement handle.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>FileOptions</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Pointer to the location that contains the
|
|
file option (or an array of file options) to be used when reading the file.
|
|
The location is accessed when the statement (<span class="synph"><span class="var">StatementHandle</span></span>)
|
|
is processed. Only one option is supported (and it must be specified): <dl><dt class="dlterm">SQL_FILE_READ </dt>
|
|
<dd>A regular file that can be opened, read and closed. (The length is computed
|
|
when the file is opened)</dd>
|
|
</dl>
|
|
<p> This pointer cannot be NULL.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>IndicatorValue </em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input (deferred), output (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Pointer to the location that contains an
|
|
indicator value (or array of values), which is set to SQL_NULL_DATA if the
|
|
data value of the parameter is to be null. It must be set to 0 (or the pointer
|
|
can be set to null) when the data value is not null.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLSMALLINT *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>FileNameLength </em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input (deferred)</td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Pointer to the location that contains the
|
|
length of the file name (or an array of lengths) at the time the next <samp class="codeph">SQLExecute()</samp> or <samp class="codeph">SQLExecDirect()</samp> function
|
|
is run using the <span class="synph"><span class="var">StatementHandle</span></span>. <p>If this pointer
|
|
is NULL, then a length of <span>SQL_NTS</span> is assumed.</p>
|
|
<p>The maximum
|
|
value of the file name length is 255.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLSMALLINT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>DataType</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">SQL data type of the column. The data type
|
|
must be one of: <ul><li>SQL_BLOB</li>
|
|
<li>SQL_CLOB</li>
|
|
<li>SQL_DBCLOB</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLSMALLINT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>MaxFileNameLength </em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">This specifies the length of the <span class="synph"><span class="var">FileName</span></span> buffer.
|
|
If the application calls <samp class="codeph">SQLParamOptions()</samp> to specify multiple
|
|
values for each parameter, this is the length of each element in the <span class="synph"><span class="var">FileName</span></span> array.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e58 ">SQLSMALLINT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e60 "><em>ParameterNumber</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e62 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e64 ">Parameter marker number. Parameters are numbered
|
|
sequentially, from left to right, starting at 1.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p> The application calls <samp class="codeph">SQLBindFileToParam()</samp> once
|
|
for each parameter marker whose value should be obtained directly from a file
|
|
when a statement is processed. Before the statement is processed, <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> values must be set. When the statement
|
|
is processed, the data for any parameter which has been bound using <samp class="codeph">SQLBindFIleToParam()</samp>
|
|
is read from the referenced file and passed to the server.</p>
|
|
<p> A LOB parameter
|
|
marker can be associated with (bound to) an input file using <samp class="codeph">SQLBindFileToParam()</samp>,
|
|
or with a stored buffer using <samp class="codeph">SQLBindParameter()</samp>. The most
|
|
recent bind parameter function call determines the type of binding that is
|
|
in effect. </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. SQLBindFileToParam SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e271">SQLSTATE </th>
|
|
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e273">Description </th>
|
|
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e275">Explanation </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>58</strong>004 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">Unexpected system failure</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">Unrecoverable system error.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>HY</strong>004 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">SQL data type out of range</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">The value specified for <span class="synph"><span class="var">DataType</span></span> is
|
|
not a valid SQL type for this function call.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>HY</strong>009 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">Argument value that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 "><span class="synph"><span class="var">FileName</span></span>, <span class="synph"><span class="var">FileOptions</span></span> <span class="synph"><span class="var">FileNameLength</span></span>, is a null pointer.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>HY</strong>010 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">Function sequence error</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">The function is called while in a data-at-processing
|
|
(<samp class="codeph">SQLParamData()</samp>or <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="12.962962962962962%" headers="d0e271 "><strong>HY</strong>021</td>
|
|
<td valign="top" width="29.074074074074076%" headers="d0e273 ">Internal descriptor that is not valid</td>
|
|
<td valign="top" width="57.96296296296296%" headers="d0e275 ">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="d0e271 "><strong>HY</strong>090 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">String or buffer length that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">The value specified for the input argument <span class="synph"><span class="var">MaxFileNameLength</span></span> is
|
|
less than 0.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>HY</strong>093 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">Parameter number that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">The value specified for <span class="synph"><span class="var">ParameterNumber</span></span> is
|
|
either less than 1 or greater than the maximum number of parameters supported.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e271 "><strong>HY</strong>C00 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e273 ">Driver not capable</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e275 ">The server does not support Large Object
|
|
data types.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>This function is not available when
|
|
connected to DB2 servers that do not support Large Object data types. </p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">References</h4><ul><li><a href="rzadpfnbndpa.htm#rzadpfnbndpa">SQLBindParam - Bind a buffer to a parameter marker</a></li>
|
|
<li><a href="rzadpfnexec.htm#rzadpfnexec">SQLExecute - Execute a statement</a></li>
|
|
<li><a href="rzadpfnpopt.htm#rzadpfnpopt">SQLParamOptions - Specify an input array for a 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> |