360 lines
12 KiB
HTML
360 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>sqludf_append()--SQL LOB Append to Locator</title>
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- Begin Header Records ============================================== -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- sqludf_append.htm created by Paul Hospers on Tue Aug 6 2002 -->
|
||
|
|
<!-- 0300507 JETAYLOR html cleanup -->
|
||
|
|
<!--End Header Records ============================================== -->
|
||
|
|
<!-- end header records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>sqludf_append()--SQL LOB Append to Locator</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
<pre>
|
||
|
|
#include <sqludf.h>
|
||
|
|
|
||
|
|
extern int SQL_API_FN sqludf_append(
|
||
|
|
udf_locator * <em>udfloc_p</em>,
|
||
|
|
unsigned char * <em>buffer_p</em>,
|
||
|
|
long <em>length</em>,
|
||
|
|
long * <em>return_len_p</em>)
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program Name: QSYS/QSQAPIS<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>sqludf_append()</strong> function appends data to the end of the LOB data the locator represents.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>udfloc_p</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Pointer to the LOB locator value.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>buffer_p</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Pointer to the buffer containing the data to append to the end of the LOB data represented by the locator.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>length</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The number of bytes to append.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>return_len_p</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input/Output) Pointer to the number of bytes actually appended.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>No authorization is required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<strong>sqludf_append()</strong>
|
||
|
|
|
||
|
|
<p>returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<dl compact>
|
||
|
|
<dt>0</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was successful. The
|
||
|
|
information is returned in the buffer pointed to by <em>return_len_p</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>-3</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was not successful. An invalid parameter was passed into the function.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>-137</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was not successful. The resulting length of the append exceeds the maximum allowed. The maximum length is 2147483647 bytes.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>-423</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was not successful. The <em>udfloc_p</em> parameter
|
||
|
|
points to an invalid locator value.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>-901</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was not successful. An SQL system error has occurred.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>-7034</dt>
|
||
|
|
|
||
|
|
<dd><strong>sqludf_append()</strong> was not successful. LOB locators are not allowed with COMMIT(*NONE).<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">SQL7034 D</td>
|
||
|
|
<td width="85%" valign="top">LOB locators are not allowed with COMMIT(*NONE).</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">SQL0901 D</td>
|
||
|
|
<td width="85%" valign="top">SQL system error.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">SQL0952 D</td>
|
||
|
|
<td width="85%" valign="top">Processing of the SQL statement ended. </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">CPF9872 E</td>
|
||
|
|
<td width="85%" valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>This API is used to append data to the end of the LOB data represented by the locator.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
|
||
|
|
<li><a href="sqludf_create_locator.htm">sqludf_create_locator()</a>--SQL LOB create locator</li>
|
||
|
|
<li><a href="sqludf_create_locator_with_ccsid.htm">sqludf_create_locator_with_ccsid()</a>--SQL LOB create locator with ccsid</li>
|
||
|
|
|
||
|
|
<li><a href="sqludf_free_locator.htm">sqludf_free_locator()</a>--SQL LOB free locator</li>
|
||
|
|
|
||
|
|
<li><a href="sqludf_length.htm">sqludf_length()</a>--SQL LOB locator length</li>
|
||
|
|
|
||
|
|
<li><a href="sqludf_substr.htm">sqludf_substr()</a>--SQL LOB substring locator</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
|
||
|
|
<p>This UDF takes a locator for an input LOB, and returns a locator for another LOB which is a subset of the input LOB. There are some criteria passed as a second input value, which tell the UDF how exactly to break up the input LOB.</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <string.h>
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <sql.h>
|
||
|
|
#include <sqludf.h>
|
||
|
|
|
||
|
|
void SQL_API_FN lob_subsetter(
|
||
|
|
udf_locator * lob_input, /* locator of LOB value to carve up */
|
||
|
|
char * criteria, /* criteria for carving */
|
||
|
|
udf_locator * lob_output, /* locator of result LOB value */
|
||
|
|
sqlint16 * inp_nul,
|
||
|
|
sqlint16 * cri_nul,
|
||
|
|
sqlint16 * out_nul,
|
||
|
|
char * sqlstate,
|
||
|
|
char * funcname,
|
||
|
|
char * specname,
|
||
|
|
char * msgtext ) {
|
||
|
|
|
||
|
|
/* local vars */
|
||
|
|
short j; /* local indexing var */
|
||
|
|
int rc; /* return code variable for API calls */
|
||
|
|
sqlint32 input_len; /* receiver for input LOB length */
|
||
|
|
sqlint32 input_pos; /* current position for scanning input LOB */
|
||
|
|
char lob_buf[100]; /* data buffer */
|
||
|
|
sqlint32 input_rec; /* number of bytes read by sqludf_substr */
|
||
|
|
sqlint32 output_rec; /* number of bytes written by sqludf_append */
|
||
|
|
|
||
|
|
/*---------------------------------------------
|
||
|
|
* UDF Program Logic Starts Here
|
||
|
|
*---------------------------------------------
|
||
|
|
* What we do is create an output handle, and then
|
||
|
|
* loop over the input, 50 bytes at a time.
|
||
|
|
* Depending on the "criteria" passed in, we may decide
|
||
|
|
* to append the 50 byte input lob segment to the output, or not.
|
||
|
|
*---------------------------------------------
|
||
|
|
* Create the output locator, right in the return buffer.
|
||
|
|
*/
|
||
|
|
|
||
|
|
rc = sqludf_create_locator(SQL_TYP_CLOB, &lob_output);
|
||
|
|
/* Error and exit if unable to create locator */
|
||
|
|
if (rc) {
|
||
|
|
memcpy (sqlstate, "38901", 5);
|
||
|
|
/* special sqlstate for this condition */
|
||
|
|
goto exit;
|
||
|
|
}
|
||
|
|
/* Find out the size of the input LOB value */
|
||
|
|
rc = sqludf_length(lob_input, &input_len) ;
|
||
|
|
/* Error and exit if unable to find out length */
|
||
|
|
if (rc) {
|
||
|
|
memcpy (sqlstate, "38902", 5);
|
||
|
|
/* special sqlstate for this condition */
|
||
|
|
goto exit;
|
||
|
|
}
|
||
|
|
/* Loop to read next 50 bytes, and append to result if it meets
|
||
|
|
* the criteria.
|
||
|
|
*/
|
||
|
|
for (input_pos = 1; (input_pos < input_len); input_pos += 50) {
|
||
|
|
/* Read the next 50 (or less) bytes of the input LOB value */
|
||
|
|
rc = sqludf_substr(lob_input, input_pos, 50,
|
||
|
|
(unsigned char *) lob_buf, &input_rec) ;
|
||
|
|
/* Error and exit if unable to read the segment */
|
||
|
|
if (rc) {
|
||
|
|
memcpy (sqlstate, "38903", 5);
|
||
|
|
/* special sqlstate for this condition */
|
||
|
|
goto exit;
|
||
|
|
}
|
||
|
|
/* apply the criteria for appending this segment to result
|
||
|
|
* if (...predicate involving buffer and criteria...) {
|
||
|
|
* The example shows if the segment matches the first 6
|
||
|
|
* characters with the criteria it is appended.
|
||
|
|
*/
|
||
|
|
if (memcmp(lob_buf,criteria,6) == 0) {
|
||
|
|
rc = sqludf_append(lob_output,
|
||
|
|
(unsigned char *) lob_buf, input_rec, &output_rec) ;
|
||
|
|
/* Error and exit if unable to read the 50 byte segment */
|
||
|
|
if (rc) {
|
||
|
|
memcpy (sqlstate, "38904", 5);
|
||
|
|
/* special sqlstate for this condition */
|
||
|
|
goto exit;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
/* } end if criteria for inclusion met */
|
||
|
|
} /* end of for loop, processing 50-byte chunks of input LOB
|
||
|
|
* if we fall out of for loop, we are successful, and done.
|
||
|
|
*/
|
||
|
|
*out_nul = 0;
|
||
|
|
exit: /* used for errors, which will override null-ness of output. */
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Referring to this UDF code, observe that: </p>
|
||
|
|
<ul>
|
||
|
|
<li>There are includes for <em>sql.h</em>, where the type
|
||
|
|
<tt>SQL_TYP_CLOB</tt> used in the <tt>sqludf_create_locator()</tt> call is
|
||
|
|
defined, and <tt>sqludf.h</tt>, where the type <tt>udf_locator</tt>
|
||
|
|
is defined.</li>
|
||
|
|
<li>The first input argument, and the third input argument (which represents
|
||
|
|
the function output) are defined as pointers to <tt>sqludf_locator</tt>,
|
||
|
|
that is, they represent CREATE FUNCTION specifications of AS LOCATOR.
|
||
|
|
</li>
|
||
|
|
<li>The UDF does not test whether either input argument is null, as NOT NULL
|
||
|
|
CALL is specified in the CREATE FUNCTION statement.</li>
|
||
|
|
<li>In the event of error, the UDF exits with <tt>sqlstate</tt> set to
|
||
|
|
38<i>xxx</i>. This is sufficient to stop the execution of the
|
||
|
|
statement referencing the UDF. The actual 38<i>xxx</i> SQLSTATE
|
||
|
|
values you choose are not important to DB2, but can serve to differentiate the
|
||
|
|
exception conditions which your UDF may encounter.</li>
|
||
|
|
<li>By using the <tt>input_rec</tt> variable as the length of the data
|
||
|
|
appended, the UDF takes care of any partial buffer condition.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Following is the CREATE FUNCTION statement for this UDF:</p>
|
||
|
|
<pre> CREATE FUNCTION carve(CLOB(50M) AS LOCATOR, VARCHAR(255) )
|
||
|
|
RETURNS CLOB(50M) AS LOCATOR
|
||
|
|
NOT NULL CALL
|
||
|
|
DETERMINISTIC
|
||
|
|
NO SQL
|
||
|
|
NO EXTERNAL ACTION
|
||
|
|
LANGUAGE C
|
||
|
|
PARAMETER STYLE DB2SQL
|
||
|
|
EXTERNAL NAME 'MYLIB/LOBUDFS(lob_subsetter)' ;
|
||
|
|
</pre>
|
||
|
|
<p>Referring to this statement, observe that:</p>
|
||
|
|
<ul>
|
||
|
|
<li>NOT NULL CALL is specified, so the UDF will not be called if any of its
|
||
|
|
input SQL arguments are NULL, and does not have to check for this
|
||
|
|
condition.</li>
|
||
|
|
<li>The function is specified as DETERMINISTIC, meaning that with a given
|
||
|
|
input CLOB value and a given set of criteria, the result will be the same
|
||
|
|
every time.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Now you can successfully run the following statement:
|
||
|
|
<pre>
|
||
|
|
strcpy(hvchar,"return this text 1 "
|
||
|
|
"remove 1 "
|
||
|
|
"return this text 2 "
|
||
|
|
"remove 2 ");
|
||
|
|
exec sql set :hvloc = clob(:hvchar);
|
||
|
|
exec sql set :hvloc2 = carve(:hvloc,'return');
|
||
|
|
strcpy(hvchar,"");
|
||
|
|
exec sql set :hvchar = char(:hvloc2);
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
<p>The UDF is used to subset the value represented by the host variable
|
||
|
|
:hvchar. The first and third 50 byte character segments are returned from the UDF. </p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R3
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href= "file1.htm">Database and File APIs</a> |<a href=
|
||
|
|
"aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|