157 lines
11 KiB
HTML
157 lines
11 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="concept" />
|
||
|
|
<meta name="DC.Title" content="UDF concepts" />
|
||
|
|
<meta name="abstract" content="This topic is a discussion of the important concepts you need to know before coding UDFs." />
|
||
|
|
<meta name="description" content="This topic is a discussion of the important concepts you need to know before coding UDFs." />
|
||
|
|
<meta name="DC.subject" content="UDFs (User-defined functions), concepts, unqualified reference, function path, overloaded function names, function selection algorithm, schema-name and UDFs, schema-name, signature, two functions and the same, function, type of functions, scalar functions, column functions, aggregating functions, table functions, column function, aggregating function, table function, SET CURRENT FUNCTION PATH statement, length of time" />
|
||
|
|
<meta name="keywords" content="UDFs (User-defined functions), concepts, unqualified reference, function path, overloaded function names, function selection algorithm, schema-name and UDFs, schema-name, signature, two functions and the same, function, type of functions, scalar functions, column functions, aggregating functions, table functions, column function, aggregating function, table function, SET CURRENT FUNCTION PATH statement, length of time" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rbafyudf.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../rzajq/qryoptf.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="rbafyudfduvc" />
|
||
|
|
<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>UDF concepts</title>
|
||
|
|
</head>
|
||
|
|
<body id="rbafyudfduvc"><a name="rbafyudfduvc"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">UDF concepts</h1>
|
||
|
|
<div><p>This topic is a discussion of the important concepts you need to
|
||
|
|
know before coding UDFs.</p>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Types of function</h4><p>There are several types of functions:</p>
|
||
|
|
<ul><li><em>Built-in.</em> These are functions provided by and shipped with the
|
||
|
|
database. SUBSTR() is an example.</li>
|
||
|
|
<li><em>System-generated.</em> These are functions implicitly generated by the
|
||
|
|
database engine when a DISTINCT TYPE is created. These functions provide casting
|
||
|
|
operations between the DISTINCT TYPE and its base type.</li>
|
||
|
|
<li><em>User-defined.</em> These are functions created by users and registered
|
||
|
|
to the database.</li>
|
||
|
|
</ul>
|
||
|
|
<p>In addition, each function can be further classified as a <em>scalar</em>, <em>column</em>,
|
||
|
|
or <em>table</em> function.</p>
|
||
|
|
<p>A <em>scalar function</em> returns a single
|
||
|
|
value answer each time it is called. For example, the built-in function <samp class="codeph">SUBSTR()</samp> is
|
||
|
|
a scalar function, as are many built-in functions. System-generated functions
|
||
|
|
are always scalar functions. Scalar UDFs can either be external (coded in
|
||
|
|
a programming language such as C), written in SQL, or sourced (using the implementation
|
||
|
|
of an existing function).</p>
|
||
|
|
<p>A <em>column function</em> receives a set of
|
||
|
|
like values (a column of data) and returns a single value answer from this
|
||
|
|
set of values. These are also called <em>aggregating functions</em> in DB2<sup>®</sup>. Some built-in
|
||
|
|
functions are column functions. An example of a column function is the built-in
|
||
|
|
function AVG(). An external UDF cannot be defined as a column function. However,
|
||
|
|
a sourced UDF is defined to be a column function if it is sourced on one of
|
||
|
|
the built-in column functions. The latter is useful for distinct types. For
|
||
|
|
example, if a distinct type <samp class="codeph">SHOESIZE</samp> exists that is defined
|
||
|
|
with base type INTEGER, you can define a UDF, <samp class="codeph">AVG(SHOESIZE)</samp>,
|
||
|
|
as a column function sourced on the existing built-in column function, <samp class="codeph">AVG(INTEGER)</samp>. </p>
|
||
|
|
<p>A <em>table
|
||
|
|
function</em> returns a table to the SQL statement that references it. It must
|
||
|
|
be referenced in the FROM clause of a SELECT. A table function can be used
|
||
|
|
to apply SQL language processing power to data that is not DB2 data, or to
|
||
|
|
convert such data into a DB2 table. It can, for example, take a file and convert
|
||
|
|
it to a table, sample data from the World Wide Web and tabularize it, or access
|
||
|
|
a Lotus
|
||
|
|
Notes<sup>®</sup> database and return information about mail messages, such as the
|
||
|
|
date, sender, and the text of the message. This information can be joined
|
||
|
|
with other tables in the database. A table function can be defined as a external
|
||
|
|
function or an SQL function; it cannot be defined as a sourced function.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Full name of a function</h4><p>The full name of a function
|
||
|
|
using *SQL naming is <samp class="codeph"><schema-name>.<function-name></samp>.</p>
|
||
|
|
<p>The
|
||
|
|
full name of a function in *SYS naming is <samp class="codeph"><schema-name>/<function-name></samp>.
|
||
|
|
Function names cannot be qualified using *SYS naming in DML statements.</p>
|
||
|
|
<p>You
|
||
|
|
can use this full name anywhere you refer to a function. For example: </p>
|
||
|
|
<pre> QGPL.SNOWBLOWER_SIZE SMITH.FOO QSYS2.SUBSTR QSYS2.FLOOR</pre>
|
||
|
|
<p>However, you may also omit the <samp class="codeph"><schema-name>.</samp>,
|
||
|
|
in which case, DB2 must
|
||
|
|
determine the function to which you are referring. For example: </p>
|
||
|
|
<pre> SNOWBLOWER_SIZE FOO SUBSTR FLOOR</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Path</h4><p>The concept of <em>path</em> is central to DB2's
|
||
|
|
resolution of <em>unqualified</em> references that occur when <samp class="codeph">schema-name</samp> is
|
||
|
|
not specified. The path is an ordered list of schema names that is used for
|
||
|
|
resolving unqualified references to UDFs and UDTs. In cases where a function
|
||
|
|
reference matches a function in more than one schema in the path, the order
|
||
|
|
of the schemas in the path is used to resolve this match. The path is established
|
||
|
|
by means of the SQLPATH option on the precompile commands for static SQL.
|
||
|
|
The path is set by the SET PATH statement for dynamic SQL. When the first
|
||
|
|
SQL statement that runs in an activation group runs with SQL naming, the path
|
||
|
|
has the following default value: </p>
|
||
|
|
<pre> "QSYS","QSYS2","<ID>" </pre>
|
||
|
|
<p>This
|
||
|
|
applies to both static and dynamic SQL, where <samp class="codeph"><ID></samp> represents
|
||
|
|
the current statement authorization ID.</p>
|
||
|
|
<p>When the first SQL statement
|
||
|
|
in an activation group runs with system naming, the default path is *LIBL.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Overloaded function names</h4><p>Function names can be <em>overloaded</em>.
|
||
|
|
Overloaded means that multiple functions, even in the same schema, can have
|
||
|
|
the same name. Two functions cannot, however, have the same <em>signature</em>.
|
||
|
|
A function signature is the qualified function name and the data types of
|
||
|
|
all the function parameters in the order in that they are defined.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Function resolution</h4><p>It is the <em>function resolution
|
||
|
|
algorithm</em> that takes into account the facts of overloading and function
|
||
|
|
path to choose the <em>best fit</em> for every function reference, whether it
|
||
|
|
is a qualified or an unqualified reference. All functions, even built-in functions,
|
||
|
|
are processed through the function selection algorithm. The function resolution
|
||
|
|
algorithm does not take into account the type of a function. So a table function
|
||
|
|
may be resolved to as the <em>best fit</em> function, even though the usage
|
||
|
|
of the reference requires an scalar function, or vice versa.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Length of time that the UDF runs</h4><p>UDFs are called
|
||
|
|
from within an SQL statement execution, which is normally a query operation
|
||
|
|
that potentially runs against thousands of rows in a table. Because of this,
|
||
|
|
the UDF needs to be called from a low level of the database.</p>
|
||
|
|
<p>As a consequence
|
||
|
|
of being called from such a low level, there are certain resources (locks
|
||
|
|
and seizes) being held at the time the UDF is called and for the duration
|
||
|
|
of the UDF execution. These resources are primarily locks on any tables and
|
||
|
|
indexes involved in the SQL statement that is calling the UDF. Due to these
|
||
|
|
held resources, it is important that the UDF not perform operations that may
|
||
|
|
take an extended period of time (minutes or hours). Because of the critical
|
||
|
|
nature of holding resources for long periods of time, the database only waits
|
||
|
|
for a certain period of time for the UDF to finish. If the UDF does not finish
|
||
|
|
in the time allocated, the SQL statement calling the UDF will fail. </p>
|
||
|
|
<p>The
|
||
|
|
default UDF wait time used by the database should be more than sufficient
|
||
|
|
to allow a normal UDF to run to completion. However, if you have a long running
|
||
|
|
UDF and want to increase the wait time, this can be done using the UDF_TIME_OUT
|
||
|
|
option in the query INI file. Note, however, that there is a maximum time
|
||
|
|
limit that the database will not exceed, regardless of the value specified
|
||
|
|
for UDF_TIME_OUT. </p>
|
||
|
|
<p>Since resources are held while the UDF is run, it is important that the UDF
|
||
|
|
not operate on the same tables or indexes allocated for the original SQL statement
|
||
|
|
or, if it does, that it does not perform an operation that conflicts with
|
||
|
|
the one being performed in the SQL statement. Specifically, the UDF should
|
||
|
|
not try to perform any insert, update, or delete row operation on those tables.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rbafyudf.htm" title="In writing SQL applications, you can implement some actions or operations as a UDF or as a subroutine in your application: Although it may appear easier to implement new operations as subroutines in your application, you might want to consider the advantages of using a UDF instead.">Use user-defined functions (UDFs)</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relinfo"><strong>Related information</strong><br />
|
||
|
|
<div><a href="../rzajq/qryoptf.htm">Query Options File (QAQQINI)</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|