CREATE FUNCTION (外部スカラー) ステートメント

CREATE FUNCTION (外部スカラー) ステートメントは、ユーザー定義の外部スカラー関数を現行サーバーに登録する場合に使用されます。 スカラー関数 は、呼び出されるたびに 1 つの値を戻し、 SQL 式が使用可能な個所であれば一般に使用することができます。

呼び出し

このステートメントは、アプリケーション・プログラムに組み込んだり、動的 SQL ステートメントを使用して発行したりすることができます。これは、DYNAMICRULES の実行動作がパッケージに効力を持つ場合にのみ、動的に準備できる実行可能ステートメントです (SQLSTATE 42509)。

許可

ステートメントの許可 ID によって保持されている特権には、少なくとも以下のいずれかの権限が含まれていなければなりません。

データベースに対する IMPLICIT_SCHEMA 権限 (関数の暗黙または明示のスキーマ名が存在しない場合)
スキーマに対する CREATEIN 特権 (関数のスキーマ名が既存のスキーマを指している場合)。
スキーマに対する SCHEMAADM 権限 (関数のスキーマ名が既存のスキーマを参照する場合)。
DBADM 権限。

ステートメントの許可 ID が保持する特権には、以下のいずれかの権限も含まれている必要があります。

データベースに対する CREATE_EXTERNAL_ROUTINE 権限。
SYSADM 権限
DB2_ALTERNATE_AUTHZ_BEHAVIOUR レジストリー変数が設定されていて、値 EXTERNAL_ROUTINE_DBADM が含まれている場合は、DBADM 権限。

非 fenced 関数を作成するには、ステートメントの許可 ID が保持する特権に、以下の権限の少なくとも 1 つが含まれている必要があります (OLE DB 外部表関数またはメソッドには適用されません)。

データベースに対する CREATE_NOT_FENCED_ROUTINE 権限。
SYSADM 権限
DB2_ALTERNATE_AUTHZ_BEHAVIOUR レジストリー変数が設定されていて、値 NOT_FENCED_ROUTINE_DBADM が含まれている場合は、DBADM 権限
注: Db2 11.5.8 セキュリティー特殊ビルド 29133 には、SYSADM 権限と DBADM 権限の両方の暗黙権限に対する変更が含まれています。デフォルトでは、SYSADM 権限は、DBADM 権限ではなく、暗黙的に CREATE_EXTERNAL_ROUTINE 権限と CREATE_NOT_FENCED_ROUTINE 権限を持ちます。 DB2_ALTERNATE_AUTHZ_BEHAVIOUR レジストリー変数が設定されていて、EXTERNAL_ROUTINE_DBADM または NOT_FENCED_ROUTINE_DBADM のいずれかの値が含まれている場合、DBADM 権限も暗黙的にこれらの特権を持ちます。

構文

parameter-declaration

data-type1, data-type2, data-type3, data-type4

built-in-type

default-clause

option-list

predicate-specification

data-filter

index-exploitation

exploitation-rule

Notes:

¹ OUT and INOUT are valid only if the function has LANGUAGE C.
² The FOR BIT DATA clause can be specified in any order with the other column constraints that follow. The FOR BIT DATA clause cannot be specified with string units CODEUNITS32 (SQLSTATE 42613).
³ DB2SECURITYLABEL is the built-in distinct type that must be used to define the row security label column of a protected table.
⁴ For a column of type DB2SECURITYLABEL, NOT NULL WITH DEFAULT is implicit and cannot be explicitly specified (SQLSTATE 42842). The default value for a column of type DB2SECURITYLABEL is the session authorization ID's security label for write access.
⁵ LANGUAGE SQL is also supported.

説明

OR REPLACE

関数の定義が現行のサーバー上に存在している場合に、その関数の定義を置換するために指定します。既存の定義は、新しい定義がカタログ内で置換される前に効率的にドロップされます。ただし、関数に対して付与された特権は影響を受けないという例外があります。このオプションは、オブジェクトの所有者しか指定できません。このオプションは、関数の定義が現行のサーバー上に存在しない場合は無視されます。既存の関数を置換するには、新規定義の特定名および関数名が旧定義の特定名と関数名と同じであるか、または新規定義のシグニチャーが旧定義のシグニチャーと一致していなければなりません。これら以外の場合、新規関数が作成されます。

関数が行権限または列マスクの定義で参照されている場合、関数を置換することはできません (SQLSTATE 42893)。

function-name定義する関数の名前を指定します。これは、関数を指定する修飾または非修飾の名前です。 function-name の非修飾形式は SQL ID です。動的 SQL ステートメントでは、CURRENT SCHEMA 特殊レジスターが、修飾子のないオブジェクト名の修飾子として使用されます。静的 SQL ステートメントでは、QUALIFIER プリコンパイル/BIND オプションにより、修飾子のないオブジェクト名の修飾子が暗黙指定されます。修飾形式は、schema-name の後にピリオドと SQL ID が続きます。最初のパラメーターが構造化タイプの場合、修飾名は、最初のパラメーターのデータ・タイプと同じであってはなりません。

暗黙または明示の修飾子を含む名前、およびパラメーターの数と各パラメーターのデータ・タイプ (データ・タイプの長さ、精度、または位取りの各属性には関係なく) は、カタログに記述されている関数またはメソッドを指定するものであってはなりません (SQLSTATE 42723)。非修飾名とパラメーターの数およびデータ・タイプとの組み合わせは、そのスキーマ内では当然ユニークですが、複数のスキーマ間でユニークである必要はありません。

2 つの部分からなる名前を指定する場合、SYS で始まるschema-name は使用できません。使用した場合、エラー (SQLSTATE 42939) になります。

述部のキーワードとして使用される多くの名前は、システム使用として予約されており、 function-name として使用することはできません。それらの名前は、SOME、ANY、ALL、NOT、AND、OR、BETWEEN、NULL、LIKE、 EXISTS、IN、UNIQUE、OVERLAPS、SIMILAR、MATCH および比較演算子です。この規則に違反すると、エラーになります (SQLSTATE 42939)。

一般に、関数のシグニチャーに何らかの差異がある場合には、同じ名前を複数の関数に使用することができます。

禁止されてはいませんが、意図的にオーバーライドを行う場合を除き、外部ユーザー定義関数の名前として、組み込み関数と同じ名前を指定するのは避けるべきです。異なる意味を持つ関数に組み込みのスカラー関数または集約関数と同じ名前 (例えば、 LENGTH、VALUE、MAX など) を与えることは、たとえその引数が一致していたとしても、動的 SQL ステートメントの過程で、あるいは静的 SQL アプリケーションの再バインド時に問題が生じます。すなわち、アプリケーションが失敗することがあり、また、さらに悪いケースとして、外見上は正常に実行されていても、結果が異なる場合があります。

parameter-declaration関数の入力パラメーターの数を指定するとともに、各パラメーターのモード、名前、データ・タイプ、デフォルト値 (オプション) を指定します。このリストには、関数が受け取ることを予期している各パラメーターごとに 1 つの項目を指定する必要があります。最大 90 までパラメーターを指定できます (SQLSTATE 54023)。

パラメーターのない関数を登録できます。この場合、指定するデータ・タイプがない場合でも、括弧はコーディングする必要があります。以下に例を示します。

   CREATE FUNCTION WOOFER() ...

1 つのスキーマ内に存在する同名の 2 つの関数で、対応するすべてのパラメーターのタイプをまったく同じにすることはできません。このタイプの比較では長さ、精度、および位取りは考慮されません。したがって、CHAR(8) と CHAR(35)、また DECIMAL(11,2) と DECIMAL (4,3) は、それぞれ同じタイプと見なされます。緩やかに型付けされた特殊タイプをパラメーターに指定した場合、その特殊タイプは、特殊タイプのソース・タイプと同じデータ・タイプと見なされます。 Unicode データベースの場合には、CHAR(13) と GRAPHIC(8) は、それぞれ同じタイプと見なされます。さらに、DECIMAL と NUMERIC などのように、この目的で複数のタイプが同じタイプとして扱われることがあります。シグニチャーが重複していると、エラー (SQLSTATE 42723) を戻します。

INOUTINOUTパラメーターのモードを指定します。関数によってエラーが戻される場合、OUT パラメーターは未定義で、INOUT パラメーターは未変更です。デフォルトは IN です。

パラメーターを関数の入力パラメーターとして指定します。制御が戻されると、関数内のパラメーターに加えられたどのような変更も、呼び出し側コンテキストで利用できません。

OUT

パラメーターを関数の出力パラメーターとして指定します。

LANGUAGE C を使用して関数が定義されている必要があります (SQLSTATE 42613)。

関数を参照できるのはコンパウンド SQL (コンパイル済み) ステートメント内の割り当てステートメントの右側でのみであり、関数参照を式の一部にすることはできません (SQLSTATE 42887)。

INOUT

パラメーターを、関数の入力および出力パラメーターの両方として指定します。

LANGUAGE C を使用して関数が定義されている必要があります (SQLSTATE 42613)。

parameter-nameパラメーターのオプション名を指定します。パラメーター名は、述部指定の index-exploitation 節にある関数のパラメーターを参照するのに必要です。この名前は、パラメーター・リスト内の他のすべての parameter-name と同じにすることはできません (SQLSTATE 42734)。

data-type1パラメーターのデータ・タイプを指定します。データ・タイプは、組み込みデータ・タイプ、特殊タイプ、構造化タイプ、または参照タイプにすることができます。各組み込みデータ・タイプの詳細な説明については、CREATE TABLE を参照してください。一部のデータ・タイプは、すべての言語でサポートされません。 SQL データ・タイプとホスト言語データ・タイプのマッピングについて詳しくは、組み込み SQL アプリケーションで SQL データ・タイプにマップするデータ・タイプを参照してください。

日時タイプのパラメーターは文字データ・タイプとして受け渡され、そのデータは ISO 形式で受け渡されます。
DECIMAL (および NUMERIC) は、LANGUAGE C と OLE では無効です (SQLSTATE 42815)。
DECFLOAT は、LANGUAGE C、COBOL、CLR、JAVA、および OLE では無効です (SQLSTATE 42815)。
XML は、LANGUAGE OLE では無効です。
関数内での XML 値の表現は、関数呼び出しでパラメーターとして渡される XML 値をシリアライズしたバージョンであるため、タイプ XML のパラメーターは、構文 XML AS CLOB(n) を使用して宣言する必要があります。
CLR は 28 より大きい DECIMAL スケールをサポートしていません (SQLSTATE 42613)。
配列タイプを指定することはできません (SQLSTATE 42815)。
BINARY および VARBINARY データ・タイプは、LANGUAGE CLR と OLE では無効です (SQLSTATE 42815)。

ユーザー定義特殊タイプの場合、パラメーターの長さ、精度、または桁数の属性は、特殊タイプのソース・タイプのもの (CREATE TYPE で指定されたもの) になります。特殊タイプのパラメーターは、特殊タイプのソース・タイプとして受け渡されます。特殊タイプの名前が修飾されていない場合は、データベース・マネージャーによって SQL パス内のスキーマが検索され、スキーマ名が解決されます。

ユーザー定義構造化タイプの場合、適切なトランスフォーム関数が関連するトランスフォーム・グループに存在する必要があります。

参照タイプの場合、パラメーターが有効範囲を指定されていない場合は、パラメーターを REF(type-name) で指定できます。

DEFAULT

パラメーターのデフォルト値を指定します。デフォルト値は、定数、特殊レジスター、グローバル変数、式、またはキーワード NULL にすることができます。デフォルトとして指定できる特殊レジスターは、列のデフォルトに指定できる特殊レジスターと同じです (CREATE TABLE ステートメントの default-clause を参照)。他の特殊レジスターは、式を使用することによってデフォルトとして指定できます。

expression は、式で説明されている任意のタイプの式にすることができます。デフォルト値が指定されていない場合、パラメーターにデフォルト値がないため、対応する引数はプロシージャーの呼び出し時に省略できません。 expression の最大サイズは 64K バイトです。

デフォルトの式は、SQL データを変更してはなりません (SQLSTATE 428FL または SQLSTATE 429BL)。式は、パラメーターのデータ・タイプに対して割り当ての互換性がなければなりません (SQLSTATE 42821)。

以下の状況では、デフォルトを指定できません。

INOUT または OUT パラメーターの場合 (SQLSTATE 42601)
ARRAY、ROW、または CURSOR タイプのパラメーターの場合 (SQLSTATE 429BB)
PREDICATES 節も指定されている関数定義のパラメーターの場合 (SQLSTATE 42613)

AS LOCATOR

実際の値の代わりにパラメーターの値へのロケーターを関数に受け渡すことを指定します。 LOB データ・タイプを持つパラメーター、または LOB データ・タイプに基づく特殊タイプにのみ AS LOCATOR を指定します (SQLSTATE 42601)。値の代わりにロケーターを受け渡すと、関数に受け渡されるバイト数を特にパラメーターの値が非常に大きい場合に少なくできます。

AS LOCATOR 節は、データ・タイプをプロモート可能かどうかの判別に効果はなく、また関数解決で使用される関数シグニチャーにも影響を与えません。

関数が FENCED で NO SQL オプションを持っている場合、 AS LOCATOR 節は指定できません (SQLSTATE 42613)。

RETURNS

これは必須の節であり、関数の出力を指定します。

data-type2出力のデータ・タイプを指定します。

この場合、前述の関数パラメーター data-type1 で説明した外部関数のパラメーターに関するものとまったく同じ考慮事項が当てはまります。

AS LOCATOR: LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 AS LOCATOR 節を追加することができます。これは、実際の値の代わりに LOB ロケーターが UDF から渡されることを示します。

data-type3CAST FROMdata-type4

出力のデータ・タイプを指定します。

この形式の RETURNS 節は、関数コードから戻されたデータ・タイプとは異なるデータ・タイプを、呼び出しステートメントに戻すのに使用されます。たとえば、以下の例で、

   CREATE FUNCTION GET_HIRE_DATE(CHAR(6))
     RETURNS DATE CAST FROM CHAR(10)
     ...

CHAR(10) の値が関数コードからデータベース・マネージャーに戻され、データベース・マネージャーは、その値を DATE に変換して、変換された値を呼び出し側ステートメントに渡します。 data-type4 は、 data-type3 パラメーターにキャスト可能でなければなりません。キャスト可能でない場合、エラー (SQLSTATE 42880) になります。

data-type3 の長さ、精度または位取りは、 data-type4 から推断することができるので、 data-type3 に指定されるパラメーター化タイプの長さ、精度、または位取りを指定する必要はありません (指定は可能です)。代わりに、空の括弧を使用できます (例えば、VARCHAR() など)。 FLOAT() は、パラメーター値によって異なるデータ・タイプ (REAL または DOUBLE) を表すので、使用できません (SQLSTATE 42601)。

特殊タイプ、配列タイプ、および構造化タイプは、 data-type4 に指定するタイプとしては無効です (SQLSTATE 42815)。

キャスト操作は、変換エラーになる可能性があるランタイム・チェックの対象にもなります。

AS LOCATOR: data-type4 の指定が、 LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 AS LOCATOR 節を追加することができます。これは、実際の値の代わりに LOB ロケーターが UDF から戻されることを示します。

built-in-type

組み込みデータ・タイプの説明については、CREATE TABLE を参照してください。

SPECIFIC 特定名

定義する関数のインスタンスに対する固有名を指定します。この特定名は、この関数をソース関数として使用する場合、この関数をドロップする場合、またはこの関数にコメントを付ける場合に使用することができます。これは、関数の呼び出しには使用できません。 specific-name の非修飾形式は SQL ID です。修飾形式は、schema-name の後にピリオドと SQL ID が続きます。暗黙または明示の修飾子も含め、その名前が、アプリケーション・サーバーに存在する別の関数インスタンスまたはメソッド指定を識別するものであってはなりません。そうでない場合、エラー (SQLSTATE 42710) になります。

specific-name は、既存の function-name (関数名) と同じでも構いません。

修飾子を指定しない場合、function-name に使用された修飾子が使用されます。修飾子を指定する場合は、 function-name の明示修飾子または暗黙修飾子と同じでなければなりません。そうでない場合、エラー (SQLSTATE 42882) になります。

specific-name の指定がない場合、固有名がデータベース・マネージャーによって生成されます。生成される固有名は、SQL の後に文字タイム・スタンプが続く名前です (SQLyymmddhhmmssxxx)。

EXTERNAL

この節は、CREATE FUNCTION ステートメントが、外部プログラミング言語で書かれたコードに基づく新しい関数を登録するのに使用されており、文書化されたリンケージの規則とインターフェースに準拠していることを示します。

NAME 文節が指定されていない場合は、NAME function-name が想定されます。

NAME 'ストリング'

この節は、定義している関数をインプリメントするユーザー作成コードの名前を指定します。

'string' オプションは、最大 254 バイトのストリング定数です。ストリングに使用される形式は、指定した LANGUAGE によって異なります。

LANGUAGE C の場合:

指定する string (ストリング) は、作成しているユーザー定義関数を実行するためにデータベース・マネージャーが呼び出すライブラリー名と、そのライブラリー中の関数名です。ライブラリー (およびそのライブラリー中の関数) は、 CREATE FUNCTION ステートメントの実行時に存在している必要はありません。ただし、関数が SQL ステートメントで使用される時点では、そのライブラリーとそのライブラリー中の該当の関数は存在していなければならず、データベース・サーバーのマシンからアクセス可能でなければなりません。そうでない場合、エラーが戻されます (SQLSTATE 42724)。

string は、以下のように指定できます。

単一引用符内に、余分なブランクを使用することはできません。

ライブラリー ID (library_id)

関数を含むライブラリー名を指定します。データベース・マネージャーは、次のようにしてこのライブラリーを特定します。

オペレーティング・システム	ライブラリー名の場所
Linux® AIX®	`myfunc` が library_id として指定されており、データベース・マネージャーが /u/production から実行されている場合、データベース・マネージャーはライブラリー /u/production/sqllib/function/myfunc 内で関数を探します。
Windows	データベース・マネージャーは、環境変数 LIBPATH または PATH に指定されているディレクトリー・パスで関数を探します。

absolute_path_id

関数を含んでいるファイルの絶対パス名を指定します。以下の表に示すとおり、形式はオペレーティング・システムによって異なります。

オペレーティング・システム	絶対パス名の例
Linux AIX	'/u/jchui/mylib/myfunc' という値を指定すると、データベース・マネージャーは /u/jchui/mylib で myfunc 共有ライブラリーを探します。
Windows	'd:\mylib\myfunc.dll' という値を指定すると、データベース・マネージャーは d:\mylib ディレクトリーからダイナミック・リンク・ライブラリー myfunc.dll をロードします。絶対パス ID を使用してルーチン本体を識別する場合は、必ず .dll 拡張子を付加してください。

! func_id

呼び出される関数の入り口点名を指定します。 ! ライブラリー ID と機能 ID の間の区切り文字として機能します。以下の表に示すとおり、形式はオペレーティング・システムによって異なります。

オペレーティング・システム	関数の入り口点名
Linux AIX	'mymod!func8' という値を指定すると、ライブラリー $inst_home_dir/sqllib/function/mymod を検索し、そのライブラリー内のエントリー・ポイント func8 を使用するように、データベース・マネージャーに指示します。
Windows	'mymod!func8' という値を指定すると、mymod.dll ファイルをロードし、ダイナミック・リンク・ライブラリー (DLL) 内の func8() 関数を呼び出すように、データベース・マネージャーに指示します。

ストリングの形式が正しくない場合には、エラーが戻されます (SQLSTATE 42878)。

すべての外部関数の本体は、すべてのデータベース・パーティションで使用可能なディレクトリーにある必要があります。

LANGUAGE JAVA の場合:

指定された string には、作成中のユーザー定義関数を実行するためにデータベース・マネージャーが呼び出す、オプションの jar ファイル ID、クラス ID、およびメソッド ID が含まれています。クラス ID とメソッド ID は、 CREATE FUNCTION ステートメントの実行時には存在している必要はありません。 jar_id を指定する場合、 ID は、 CREATE FUNCTION ステートメントの実行時に存在していなければなりません。ただし、関数が SQL ステートメントで使用される時点では、メソッド ID は存在していなければならず、データベース・サーバーのマシンからアクセス可能でなければなりません。そうでない場合、エラーが戻されます (SQLSTATE 42724)。

string は、以下のように指定できます。

単一引用符内に、余分なブランクを使用することはできません。

jar_id

jar の集合をデータベースへインストールしたときに、その jar の集合に付けられた jar ID を指定します。これは、単純 ID またはスキーマ修飾 ID のいずれかにすることができます。例えば、'myJar' や 'mySchema.myJar' のようになります。

クラス ID

Java™ オブジェクトのクラス ID を識別します。クラスがパッケージの一部である場合、クラス ID の部分に完全なパッケージ接頭部 (例: 'myPacks.UserFuncs') が含まれている必要があります。 Java 仮想マシンがクラスを検索するディレクトリーは、以下の表に示すように、オペレーティング・システムによって異なります。

オペレーティング・システム	Java 仮想マシンがクラスを検索するディレクトリー。
Linux AIX	'.../myPacks/UserFuncs/'
Windows	'...\myPacks\UserFuncs\'

メソッド ID

呼び出す Java オブジェクトのメソッド名を識別します。

LANGUAGE CLR の場合:
指定された string は、作成する関数を実行するためにデータベース・マネージャーが呼び出す .NET アセンブリー (ライブラリーまたは実行可能モジュール)、そのアセンブリー内のクラス、およびそのクラス内のメソッドを表します。モジュール、クラス、およびメソッドは、 CREATE FUNCTION ステートメントの実行時に存在している必要はありません。ただし、関数を SQL ステートメントで使用する時点では、モジュール、クラス、およびメソッドは存在していなければならず、データベース・サーバーのマシンからアクセス可能でなければなりません。そうでない場合、エラーが戻されます (SQLSTATE 42724)。

'/clr' コンパイラー・オプションで管理対象コード拡張を指定してコンパイルされている C++ ルーチンは、 'LANGUAGE C' ではなく 'LANGUAGE CLR' としてカタログする必要があります。データベース・サーバーは、必要な実行時の決定を行えるようにするために、 .NET インフラストラクチャーがユーザー定義関数内で使用されていることを認識している必要があります。 .NET インフラストラクチャーを使用するすべてのユーザー定義関数は、 'LANGUAGE CLR' としてカタログする必要があります。

string は、以下のように指定できます。

名前は、単一引用符で囲む必要があります。余分なブランクを使用することはできません。

アセンブリー
クラスを含む DLL ファイルまたは他のアセンブリー・ファイルを指定します。ファイル拡張子 (.dll など) まで指定します。絶対パス名を指定しない場合、ファイルは、データベース製品のインストール・パスの関数ディレクトリーに存在していなければなりません。
例えば、c:\sqllib\function などです。

ファイルがインストール関数ディレクトリーのサブディレクトリーにある場合は、絶対パスを指定せずに、ファイル名の前にサブディレクトリーを指定します。

例えば、インストール・ディレクトリーが c:\sqllib で、アセンブリー・ファイルが c:\sqllib\function\myprocs\mydotnet.dll の場合、アセンブリーの指定は 'myprocs\mydotnet.dll' と指定するだけで十分です。

このパラメーターの大文字小文字が区別されるかどうかは、ファイル・システムの設定と同じです。

クラス ID
呼び出すメソッドが属するアセンブリー内のクラスの名前を指定します。クラスが名前空間内にある場合は、クラスだけでなく絶対名前空間も指定することが必要です。例えば、クラス EmployeeClass が名前空間 MyCompany.ProcedureClasses にあるのであれば、 MyCompany.ProcedureClasses.EmployeeClass をクラスとして指定しなければなりません。一部の .NET 言語用のコンパイラーはクラスの名前空間としてプロジェクト名を追加するため、コマンド行コンパイラーと GUI コンパイラーのどちらを使用するかで動作が異なってくるので注意してください。このパラメーターには、大文字と小文字の区別があります。
メソッド ID
指定したクラス内で呼び出されるメソッドを指定します。このパラメーターには、大文字と小文字の区別があります。
LANGUAGE OLE の場合:
指定する string は、作成中のユーザー定義関数を実行するためにデータベース・マネージャーが呼び出す、 OLE のプログラム ID (progid) またはクラス ID (clsid)、およびメソッド ID です。プログラム ID またはクラス ID、およびメソッド ID は、 CREATE FUNCTION ステートメントの実行時に存在している必要はありません。ただし、関数が SQL ステートメントで使用される時点では、メソッド ID は存在していなければならず、データベース・サーバーのマシンからアクセス可能でなければなりません。そうでない場合、エラーが戻されます (SQLSTATE 42724)。

string は、以下のように指定できます。

単一引用符内に、余分なブランクを使用することはできません。
プログラム ID
OLE オブジェクトのプログラム ID を指定します。
progid は、データベース・マネージャーには解釈されず、実行時に OLE API に転送されるだけです。指定する OLE オブジェクトは、作成可能である必要があり、実行時バインディング (ディスパッチに基づくバインディングとも呼ばれる) をサポートしている必要があります。

clsid
作成する OLE オブジェクトのクラス ID を指定します。 OLE オブジェクトが progid を指定して登録されていない場合に、 progid を指定する代わりに使用することができます。 clsid の形式は次のとおりです。
```
{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
```
ここで 'n' は英数字です。 clsid は、データベース・マネージャーには解釈されず、実行時に OLE API に転送されるだけです。
メソッド ID
呼び出す OLE オブジェクトのメソッド名を指定します。
LANGUAGE CPP の場合:
指定する string は、ライブラリー ID とライブラリー中のクラス ID です。これには、作成されるユーザー定義関数を実行するためにデータベース・マネージャーが呼び出す評価メソッドが含まれています。ストリングの形式が正しくない場合には、エラーが戻されます (SQLSTATE 42878)。

ライブラリー (またはライブラリー中のクラス) は、CREATE FUNCTION ステートメントの実行時に存在している必要はありません。ただし、関数が SQL ステートメントで使用される時点では、そのライブラリーとそのライブラリー中の該当のクラスは存在していなければならず、データベース・サーバーのマシンからアクセス可能でなければなりません。そうでない場合、エラーが戻されます (SQLSTATE 42724)。

すべての外部関数の本体は、すべてのデータベース・パーティションで使用可能なディレクトリーにある必要があります。
string は、以下のように指定できます。
単一引用符内に、余分なブランクを使用することはできません。
ライブラリー ID (library_id)
関数が入っているライブラリーの名前:
- UNIX システムでは、指定されたライブラリー ID が myfuncであり、データベース・マネージャーが /u/productionから実行されている場合、データベース・マネージャーは以下のライブラリーで関数を探します。
  /u/production/sqllib/function/myfunc
- Windows オペレーティング・システムの場合、データベース・マネージャーは、LIBPATH または PATH 環境変数によって指定されているディレクトリー・パスで関数を探します。
absolute_path_id
関数が入ったファイルの絶対パス。以下に例を示します。
- UNIX システムでは、以下のように指定すると、データベース・マネージャーは /u/jchui/mylib で myfunc 共有ライブラリーを探します。
  '/u/jchui/mylib/myfunc'
- Windows オペレーティング・システムでは、以下のように指定すると、データベース・マネージャーは d:\mylib ディレクトリーからダイナミック・リンク・ライブラリー myfunc.dll をロードします。
  'd:\mylib\myfunc.dll'
  絶対パス ID がルーチン本体の識別に使用されている場合は、.dll 拡張子を必ず付加してください。
クラス ID
呼び出すメソッドが入っているクラスの名前。
例えば、'mymod!myclass' を指定した場合には、次のようになります。
- UNIX システムでは、データベース・マネージャーはライブラリー $inst_home_dir/sqllib/function/mymod を探し、そのライブラリー内の myclass クラスの評価メソッドを呼び出します。
- Windows オペレーティング・システムでは、データベース・マネージャーは mymod.dll ファイルをロードし、ダイナミック・リンク・ライブラリー (DLL) 内の myclass クラスの評価メソッドを呼び出します。

NAME ID

指定する identifier は SQL ID です。 SQL ID は、ストリングの library-id として使用されます。区切られた ID でない場合、ID は大文字に変換されます。 ID がスキーマ名で修飾されている場合、スキーマ名の部分は無視されます。この形式の NAME は、LANGUAGE C でのみ使用可能です。

LANGUAGE

この必須の節は、ユーザー定義関数の本体が準拠している言語インターフェース規則を指定します。

C: データベース・マネージャーが、ユーザー定義関数を C の関数であるかのように呼び出します。ユーザー定義関数は、標準 ANSI C プロトタイプで定義されている C 言語の呼び出しおよびリンケージの規則に準拠していなければなりません。
JAVA: データベース・マネージャーは、Java クラスのメソッドとしてユーザー定義関数を呼び出します。
CLR: データベース・マネージャーは、.NET クラスのメソッドとしてユーザー定義関数を呼び出します。 LANGUAGE CLR は、Windows オペレーティング・システムで実行されるユーザー定義関数に対してのみサポートされます。 NOT FENCED は CLR ルーチンに指定できません (SQLSTATE 42601)。
OLE: データベース・マネージャーは、OLE 自動化オブジェクトによって公開されたメソッドとして、ユーザー定義関数を呼び出します。ユーザー定義関数は、「OLE Automation Programmer's Reference」に説明されている、OLE 自動化データ・タイプと呼び出しメカニズムに準拠している必要があります。
LANGUAGE OLE は、Windows オペレーティング・システムでのみ、このデータベース製品のユーザー定義関数に対してサポートされます。 LANGUAGE OLE を指定した UDF には、THREADSAFE は指定できません (SQLSTATE 42613)。
CPP: データベース・マネージャーは、C++ クラスの評価メソッドを呼び出すことにより、ユーザー定義関数を呼び出します。
Python: データベース・マネージャーは、Python クラスのメソッドとしてユーザー定義関数を呼び出します。

PARAMETER STYLE

この節は、関数にパラメーターを渡し、関数から値を戻すのに用いる規則を指定するために使用します。

DB2GENERAL

Java クラスのメソッドとして定義されている外部関数にパラメーターを渡したり、外部関数から値を返したりするための規則を指定するために使用されます。これは、LANGUAGE JAVA を使用する場合にだけ指定できます。

DB2GENERAL の同義語として値 DB2GENRL が使用可能です。

JAVA

これは、この関数が、Java 言語および SQLJ ルーチンの仕様に準拠するパラメーター引き渡し規則を使用することを意味します。これを指定できるのは、LANGUAGE JAVA を使用し、パラメーターとして構造化データ・タイプを指定せず、戻りタイプとして CLOB、BLOB、DBCLOB のいずれかのデータ・タイプを指定していない場合だけです (SQLSTATE 429B8)。 PARAMETER STYLE JAVA 関数は、 FINAL CALL、SCRATCHPAD または DBINFO 節をサポートしていません。

SQL

C 言語の呼び出しとリンケージ規則、OLE 自動化オブジェクトによって公開されたメソッド、または .NET オブジェクトの共有静的メソッドに準拠する規則を、この外部関数との間でパラメーターを渡し、値を戻す場合の規則として指定します。これは、LANGUAGE C、LANGUAGE CLR、または LANGUAGE OLE を使用する場合に指定する必要があります。

NPSGENERIC

C++ クラスのメソッドとして定義された外部関数との間で、パラメーターを渡し、値を戻す場合に用いる規則を指定します。これは、LANGUAGE オプションが CPP または PYTHONに設定されている場合にのみ指定できます。

NPSGENERIC がパラメーター・スタイルとして指定されているとき、UDF は nz.udx_ver2.Udf クラスの派生クラスとして C++ で記述されます。このクラスは、以下の 2 つのメソッドに加え、そのコンストラクターとデストラクターを実装する必要があります。

static Udf* Udf::instantiate(UdxInit *pInit): 静的メンバー・メソッド instantiate()。これは、UDF 派生クラスの新規インスタンスをインスタンス化し、新規インスタンスへのポインターをクラス UDF ポインターとして返す必要があります。エンジンはこのメソッドを使用して UDF オブジェクトのインスタンスを作成します。
virtual ReturnValue Udf::evaluate(): メンバー・メソッド evaluate()。これは、ユーザー関数を評価して値を呼び出し元に返すためにエンジンによって呼び出されます。

PARAMETER CCSID

関数とやり取りされるすべてのストリング・データに使用されるコード化スキームを指定します。 PARAMETER CCSID 節を指定しない場合のデフォルトは、 Unicode データベースでは PARAMETER CCSID UNICODE、他のすべてのデータベースでは PARAMETER CCSID ASCII になります。

ASCII: ストリング・データがデータベース・コード・ページでエンコードされることを指定します。データベースが Unicode データベースの場合は、 PARAMETER CCSID ASCII を指定することはできません (SQLSTATE 56031)。関数が呼び出されるときのアプリケーション・コード・ページはデータベース・コード・ページです。
UNICODE: ストリング・データが Unicode でエンコードされることを指定します。データベースが Unicode データベースの場合、文字データは UTF-8、 GRAPHIC データは UCS-2 になります。データベースが Unicode データベースでない場合は、文字データは UTF-8 になります。いずれの場合も、関数が呼び出されるときのアプリケーション・コード・ページは 1208 です。
データベースが Unicode データベースではないのに、 PARAMETER CCSID UNICODE を指定した関数を作成すると、その関数は GRAPHIC タイプ、XML タイプ、またはユーザー定義タイプを取ることができません (SQLSTATE 560C1)。

データベースが Unicode ではなく、データベース構成に代替照合シーケンスが指定されている場合、 PARAMETER CCSID ASCII または PARAMETER CCSID UNICODE を指定した関数を作成できます。関数とやり取りされるすべてのストリング・データは、適切なコード・ページに変換されます。

この節は、 LANGUAGE CPP、 LANGUAGE OLE、LANGUAGE JAVA、または LANGUAGE CLR と一緒に指定することはできません (SQLSTATE 42613)。

DETERMINISTIC または NOT DETERMINISTIC

この節は任意指定で、特定の引数値に対して関数が常に同じ結果を戻すか (DETERMINISTIC)、それとも状態値に依存して関数の結果が影響を受けるか (NOT DETERMINISTIC) を指定します。つまり DETERMINISTIC を伴う関数は、連続で同じ入力を指定して呼び出しが行われた場合に常に同じ結果を戻します。 NOT DETERMINISTIC を指定すると、同じ入力によって常に同じ結果が生じることを利用した最適化ができなくなります。乱数を生成する関数は、NOT DETERMINISTIC 関数の例です。入力の平方根を求める関数は、DETERMINISTIC 関数の例です。

FENCED または NOT FENCED

この節は、関数をデータベース・マネージャーのオペレーティング環境のプロセスまたはアドレス・スペースで実行しても安全と見なされるかどうかを指定します。

関数が FENCED として登録されると、データベース・マネージャーは、その内部リソース (データ・バッファーなど) を保護して、その関数からアクセスされないようにします。多くの関数は、FENCED または NOT FENCED のどちらかで実行するように選択することができます。一般に、FENCED として実行される関数は、 NOT FENCED として実行されるものと同じようには実行されません。

注意:

適切にコード化、検討、およびテストされていない関数に NOT FENCED を使用すると、データベースの整合性に危険を招く場合があります。このデータベース製品では、発生する可能性のある一般的な不注意による障害の多くに対して安全保護策が講じられていますが、NOT FENCED ユーザー定義関数が使用される場合には、完全な整合性を確保できません。

LANGUAGE OLE または NOT THREADSAFE を指定した関数には、FENCED のみを指定できます (SQLSTATE 42613)。

関数が FENCED で NO SQL オプションを持っている場合、 AS LOCATOR 節は指定できません (SQLSTATE 42613)。

NOT FENCED 節を指定している場合は、LANGUAGE CLR ユーザー定義関数を作成できません (SQLSTATE 42601)。

THREADSAFE または NOT THREADSAFE

関数を他のルーチンと同じプロセスで実行しても安全か (THREADSAFE)、そうでないか (NOT THREADSAFE) を指定します。

関数が OLE 以外の LANGUAGE で定義される場合:

関数が THREADSAFE に定義されている場合には、データベース・マネージャーは他のルーチンと同じプロセスで関数を呼び出すことができます。一般に、スレッド・セーフにするには、関数はどのグローバルあるいは静的データ域をも使用してはなりません。多くのプログラミング解説書には、スレッド・セーフ・ルーチンの作成に関する説明が含まれています。 FENCED および NOT FENCED 関数の両方が THREADSAFE になることが可能です。
関数が NOT THREADSAFE と定義される場合には、データベース・マネージャーが関数を他のルーチンと同じプロセスで同時に呼び出すことは決してありません。

FENCED 関数の場合、LANGUAGE が JAVAまたは CLR なら THREADSAFE がデフォルトです。これ以外のすべての言語の場合は、NOT THREADSAFE がデフォルトです。関数が LANGUAGE OLE に定義される場合には、THREADSAFE は指定できません (SQLSTATE 42613)。

NOT FENCED 関数の場合には、THREADSAFE がデフォルトです。 NOT THREADSAFE を指定することはできません (SQLSTATE 42613)。

RETURNS NULL ON NULL INPUT または CALLED ON NULL INPUT

このオプション節を使用すると、引数のいずれかが NULL の場合に、外部関数を呼び出さないようにすることができます。ユーザー定義関数がパラメーターなしで定義されている場合、引数が NULL になるこの状態は発生することがないので、この仕様のコーディング方法はそれほど重要ではありません。この節を指定しない場合、デフォルトは RETURNS NULL ON NULL INPUT です。ただし、PARAMETER STYLE JAVA が指定されている場合は除きます。この場合のデフォルトは CALLED ON NULL INPUT です。

RETURNS NULL ON NULL INPUT が指定されており、実行時に関数の引数のいずれかが NULL 値の場合、このユーザー定義関数は呼び出されず、結果は NULL 値になります。

CALLED ON NULL INPUT が指定されると、引数が NULL 値か否かに関係なくユーザー定義関数が呼び出されます。これは、NULL 値を戻す場合も、通常の (NULL 以外の) 値を戻す場合もあります。ただし、NULL の引数値の有無のテストは UDF が行う必要があります。

値 NULL CALL は、後方互換性またはファミリーの互換性のために、 CALLED ON NULL INPUT の同義語として使うことができます。同様に、NOT NULL CALL は、RETURNS NULL ON NULL INPUT の同義語として使用できます。

READS SQL DATA、NO SQL、または CONTAINS SQL

関数で実行できる SQL ステートメントの種別を指定します。データベース・マネージャーによって、この関数で実行される SQL ステートメントが、この指定と整合しているかどうかが検査されます。

各ステートメントの種別については、ルーチンおよびトリガーで実行できる SQL ステートメントを参照してください。

デフォルトは READS SQL DATA です。

READS SQL DATA: データ・アクセス種別が READS SQL DATA、CONTAINS SQL、または NO SQL であるステートメントを関数で実行できるように指定します (SQLSTATE 38002 または 42985)。この関数では、データを変更する SQL ステートメントを実行できません。 (SQLSTATE 38003 または 42985。)
NO SQL: データ・アクセス種別が NO SQL である SQL ステートメントのみを関数で実行できるように指定します (SQLSTATE 38001)。
CONTAINS SQL: データ・アクセス種別が CONTAINS SQL または NO SQL である SQL ステートメントのみを関数で実行できるように指定します (SQLSTATE 38004 または 42985)。この関数では、データを読み取ったり変更したりする SQL ステートメントを実行できません (SQLSTATE 38003 または 42985)。

STATIC DISPATCH

このオプション節は、関数解決時に、データベース・サーバーが関数のパラメーターの静的タイプ (宣言済みタイプ) に基づいて関数を選択することを指定します。

EXTERNAL ACTION または NO EXTERNAL ACTION

関数が、データベース・マネージャーによって管理されていないオブジェクトの状態を変更するアクションを取るかどうかを指定します。外部アクションの例としては、メッセージの送信やファイルへのレコードの書き込みがあります。デフォルトは EXTERNAL ACTION です。

EXTERNAL ACTION: 関数が、データベース・マネージャーによって管理されていないオブジェクトの状態を変更するアクションを取ることを指定します。
外部アクションが指定された関数は、関数が並列タスクによって実行されると、不正確な結果を戻す場合があります。例えば、初期呼び出しを受けるたびに注釈を送信する関数の場合、関数ごとに 1 つの注釈が送信されるのではなく、並列タスクごとに 1 回ずつ送信されることになります。並列処理を正しく扱うことのできない関数については、DISALLOW PARALLEL 節を指定します。
NO EXTERNAL ACTION: 関数が、データベース・マネージャーによって管理されていないオブジェクトの状態を変更するアクションを取らないことを指定します。データベース・マネージャーは、SQL ステートメントの最適化中に、この情報を使用します。

NO SCRATCHPAD または SCRATCHPAD length

この節はオプションであり、この外部関数に対してスクラッチパッドを用意するか否かを指定するのに使用することができます。 (ユーザー定義関数を再入可能にすることを強くお勧めします。再入可能にすると、スクラッチパッドによってある呼び出しと次の呼び出しとの間に関数が「状態を保存する」手段が用意されます。

SCRATCHPAD を指定すると、ユーザー定義関数の最初の呼び出し時に、その外部関数によって使用されるスクラッチパッドにメモリーが割り振られます。ユーザー定義関数を呼び出すたびに、スクラッチパッドをアドレッシングする外部関数に追加の引数が渡されます。このスクラッチパッドには、次の特性があります。
- length を指定すると、スクラッチパッドのサイズをバイト単位で設定できます。この値は 1 から 32 767 の範囲で指定する必要があります (SQLSTATE 42820)。デフォルト・サイズは 100 バイトです。
- すべて X'00' に初期化されます。
- その有効範囲は、該当の SQL ステートメントです。 SQL ステートメントでの外部関数に対する参照ごとに 1 つのスクラッチパッドがあります。したがって、以下のステートメントの関数 UDFX が SCRATCHPAD キーワードを指定して定義されている場合、 3 つのスクラッチパッドが割り当てられます。
```
   SELECT A, UDFX(A) FROM TABLEB
     WHERE UDFX(A) > 103 OR UDFX(A) < 19
```
  ALLOW PARALLEL が指定されているか、またはデフォルト値として使用された場合、その有効範囲は前述のものとは異なります。関数が複数のデータベース・パーティションで実行される場合、関数が処理されるそれぞれのデータベース・パーティションにおいて、 SQL ステートメントでの関数へのそれぞれの参照ごとにスクラッチパッドが割り当てられます。同様に、パーティション内並列処理をオンにして照会が実行される場合、 3 より多くのスクラッチパッドが割り当てられることがあります。
- スクラッチパッドは持続します。その内容は、外部関数のある呼び出しから次の呼び出しになっても存続します。外部関数のある呼び出しによってスクラッチパッドに対して行われた変更はいずれも、次の呼び出し時に存続しています。データベース・マネージャーは、各 SQL ステートメントの実行開始時に、スクラッチパッドを初期設定します。各副照会の実行開始時には、データベース・マネージャーによってスクラッチパッドがリセットされます。 FINAL CALL オプションが指定されている場合、システムは、スクラッチパッドのリセットに先立って、最終呼び出しを行います。
- これは、外部関数が獲得するシステム・リソース (メモリーなどの) の中央点として使用することもできます。関数は、最初の呼び出しでメモリーを獲得し、そのアドレスをスクラッチパッドに保管して、後の呼び出しでそれを参照することができます。
  (このようにシステム・リソースが獲得される場合、FINAL CALL キーワードも指定する必要があります。これにより、ステートメントの最後で特殊な呼び出しが行われ、外部関数は獲得したシステム・リソースをすべて解放することができます。)
NO SCRATCHPAD を指定すると、外部関数に対してスクラッチパッドは割り振られず、渡されません。

SCRATCHPAD を PARAMETER STYLE JAVA 関数と組み合わせて指定することはできません。

FINAL CALL または NO FINAL CALL

この節はオプションであり、外部関数に対する最終呼び出しが行われるか否かを指定します。このような最終呼び出しの目的は、外部関数が、獲得したシステム・リソースすべてを解放できるようにすることです。外部関数がメモリーなどのシステム・リソースを獲得し、それをスクラッチパッドに固定するような状況では、これを SCRATCHPAD キーワードと共に使用すると便利です。

FINAL CALL を指定すると、呼び出しのタイプを指定する追加の引数が実行時に外部関数に渡されます。呼び出しのタイプは次のとおりです。

通常呼び出し

SQL 引数が渡され、結果が戻されることが予期されます。

最初の呼び出し

この SQL ステートメントのユーザー定義関数に対する参照に対応する外部関数の最初の呼び出し。最初の呼び出しは通常呼び出しです。

最終呼び出し

外部関数がリソースを解放できるようにするための、その関数に対する最終呼び出し。最終呼び出しは、通常呼び出しではありません。この最終呼び出しは、以下の時点で行われます。

ステートメントの最後

これは、カーソル指向型のステートメントでカーソルがクローズされた場合、あるいはステートメントが実行を終了した場合に発生します。

並列タスクの最後

これは、関数が並列タスクで実行された場合に発生します。

トランザクションの最後または中断

これは、通常のステートメント終了が発生しなかった場合に発生します。例えば、何らかの理由で、アプリケーションのロジックが、カーソルをクローズしないようになっている場合があります。このタイプの最終呼び出しの際、CLOSE カーソル以外は、 SQL ステートメントが発行されない可能性があります (SQLSTATE 38505)。このタイプの最終呼び出しは、call type 引数に特殊な値を使用して示されます。

WITH HOLD として定義されたカーソルがオープンされている間に、コミット操作が発生すると、それ以降のカーソルのクローズ時、またはアプリケーションの終了時に最終呼び出しが行われます。
NO FINAL CALL を指定すると、call type 引数は外部関数に渡されず、最終呼び出しは行われません。

FINAL CALL は、以下のパラメーター設定と組み合わせて指定することはできません。

PARAMETER STYLE JAVA
LANGUAGE CPP

ALLOW PARALLEL または DISALLOW PARALLEL

この節はオプションで、関数への 1 つの参照に対して、関数の呼び出しを並列化できるか否かを指定します。一般に、ほとんどのスカラー関数の呼び出しは並列化が可能ですが、並列化できない関数 (1 つのスクラッチパッドのコピーに依存する関数など) もあります。スカラー関数に対して ALLOW PARALLEL または DISALLOW PARALLEL を指定すると、その指定が受け入れられます。関数にどちらのキーワードが当てはまるかを判別するには、以下の点について検討する必要があります。

UDF のすべての呼び出しが、互いに完全に独立していますか? YES の場合には、ALLOW PARALLEL を指定します。
UDF を呼び出すごとに、次の呼び出しに関係する値を提供するスクラッチパッドが更新されますか? (例えば、カウンターの増分など。) YES の場合には、DISALLOW PARALLEL を指定するか、またはデフォルトを受け入れます。
1 つのデータベース・パーティションでのみ起こる必要のある外部アクションが UDF によって実行されますか? YES の場合には、DISALLOW PARALLEL を指定するか、またはデフォルトを受け入れます。
コストのかかる初期化処理の実行回数を最小にするためだけに、スクラッチパッドを使用していますか? YES の場合には、ALLOW PARALLEL を指定します。
関数は、カラム・オーガナイズ表にアクセスする照会で呼び出されますか? YES の場合には、ALLOW PARALLEL を指定するとパフォーマンスが改善される可能性があります。

いずれの場合も、すべての外部関数の本体は、すべてのデータベース・パーティションで使用可能なディレクトリーにある必要があります。

ステートメントで以下の 1 つ以上のオプションが指定されている場合以外は、デフォルト値は ALLOW PARALLEL です。

NOT DETERMINISTIC
EXTERNAL ACTION
SCRATCHPAD
FINAL CALL

これらのオプションのいずれかが指定または暗黙指定されている場合は、デフォルト値は DISALLOW PARALLEL です。

INHERIT SPECIAL REGISTERS

このオプション節は、関数の更新可能な特殊レジスターが、呼び出しステートメントの環境からの初期値を継承することを指定します。カーソルの選択ステートメントで呼び出される関数の場合、初期値はカーソルがオープンした際の環境から継承します。ネストされたオブジェクト (例えば、トリガーまたはビュー) に呼び出されるルーチンの場合、初期値は (オブジェクト定義から継承するのではなく) ランタイム環境から継承します。

特殊レジスターに対する変更が、関数の呼び出し側に戻されることはありません。

更新不能の特殊レジスター (日時特殊レジスターなど) は、現在実行中のステートメントのプロパティーを反映するので、デフォルト値に設定されます。

NO DBINFO または DBINFO

この節はオプションで、データベース・サーバーにおいて既知である特定の情報を追加の呼び出し時引数として UDF に渡すか (DBINFO)、または渡さないか (NO DBINFO) を指定します。 NO DBINFO がデフォルト値です。 DBINFO は、以下の節では使用できません (SQLSTATE 42613)。

LANGUAGE OLE
PARAMETER STYLE JAVA

DBINFO を指定すると、以下の情報を含む構造が UDF に渡されます。

データベース名 - 現在接続されているデータベースの名前。
アプリケーション ID - データベースへの接続ごとに確立された、固有アプリケーション ID。
アプリケーション許可 ID - アプリケーション実行時の許可 ID。この UDF とアプリケーションとの中間でネストされている UDF は無関係。
コード・ページ - データベースのコード・ページを識別します。
スキーマ名 - 表名とまったく同じ条件のもとでは、スキーマの名前が入ります。その他の場合はブランクです。
表名 - UDF 参照が UPDATE ステートメントの SET 節の右側にある場合、または INSERT ステートメントの VALUES リストの項目である場合のいずれかに限り、更新または挿入される表の非修飾名が入ります。その他の場合はブランクです。
列名 - 表名とまったく同じ条件で、更新または挿入される列の名前が入ります。その他の場合はブランクです。
データベースのバージョン/リリース - UDF を呼び出すデータベース・サーバーのバージョン、リリースおよび修正レベルを識別します。
プラットフォーム - サーバーのプラットフォーム・タイプが入ります。
表関数の結果の列番号 - 外部スカラー関数には当てはまりません。

TRANSFORM GROUP グループ名

関数を呼び出す際のユーザー定義の構造化タイプのトランスフォーメーションに使用するトランスフォーム・グループを指定します。関数定義にパラメーターまたは RETURNS データ・タイプとしてユーザー定義の構造化タイプが含まれている場合、トランスフォームが必要になります。この節が指定されない場合には、デフォルトのグループ名 DB2_FUNCTION が使用されます。指定した (またはデフォルトの) group-name が、参照された構造化タイプに定義されていない場合、エラーになります (SQLSTATE 42741)。指定した group-name または構造化タイプに必須の FROM SQL または TO SQL トランスフォーム関数が定義されていない場合には、エラーになります (SQLSTATE 42744)。

トランスフォーム関数は、FROM SQL および TO SQL の両方とも、指定された場合も暗黙的に指定されている場合でも、構造化タイプと組み込みタイプ属性とのトランスフォームを適切に実行する SQL 関数でなければなりません。

PREDICATES

述部でこの関数が使用されるときに実行される、フィルター操作や索引拡張の活用を定義します。述部仕様では、検索条件のオプションの SELECTIVITY 節を指定できます。 PREDICATES 節が指定された場合、関数は NO EXTERNAL ACTION を指定した DETERMINISTIC として定義しなければなりません (SQLSTATE 42613)。 PREDICATES 節が指定されており、データベースが Unicode データベースでない場合は、PARAMETER CCSID UNICODE を指定してはなりません (SQLSTATE 42613)。

WHEN 比較演算子

比較演算子 (=、<、>、>=、<=、<>) を使用した述部での関数の特定の使用法について説明します。

関数の RETURNS タイプに比較可能なデータ・タイプを使用して、定数値を指定します (SQLSTATE 42818)。述部が同じ比較演算子とこの定数でこの関数を使用する場合、指定されたフィルターおよび索引の活用がオプティマイザーにより考慮されます。
EXPRESSION AS 式名: 式に名前を提供します。述部が同じ比較演算子と式でこの関数を使用する場合、指定されたフィルターおよび索引の活用が行われます。この式には、式名が割り当てられ、検索関数の引数として使用できるようになっています。 expression-name は、作成されている関数のいずれかの parameter-name と同じにすることはできません (SQLSTATE 42711)。式が指定される際に、その式のタイプが識別されます。

FILTER USING

結果表をさらにフィルター操作する際に使用する、外部関数またはケース式の指定を許可します。

関数呼び出し

結果表の追加のフィルター操作の実行に使用できるフィルター関数を指定します。これは定義された関数のバージョンであり (述部で使用)、ユーザー定義述部で実行される行数を減らし、行を限定するかどうかを判別します。索引により生成される結果が、ユーザー定義述部に期待される結果に近い場合には、フィルター関数を適用する効果はあまりありません。これを指定しない場合は、データのフィルター操作は実行されません。

この関数は、任意の parameter-name、expression-name、または定数を引数として使用でき (SQLSTATE 42703)、整数を戻します (SQLSTATE 428E4)。戻り値 1 の場合は行が保持され、その他の場合は破棄されます。

この関数は、以下の要件を満たしていなければなりません。

LANGUAGE SQL で定義されていないこと (SQLSTATE 429B4)
NOT DETERMINISTIC または EXTERNAL ACTION で定義されていないこと (SQLSTATE 42845)
いずれかのパラメーターのデータ・タイプとして構造化データ・タイプがないこと (SQLSTATE 428E3)
副照会が含まれていないこと (SQLSTATE 428E4)
XMLQUERY または XMLEXISTS 式が含まれていないこと (SQLSTATE SQLSTATE 428E4)

引数が他の関数またはメソッドを呼び出す場合、このネストされた関数またはメソッドにもこれらの規則が課されます。ただし、引数が組み込みデータ・タイプに評価されるかぎり、システム生成の observer メソッドをフィルター関数 (または、引数として使用される任意の関数またはメソッド) への引数として使用することができます。

関数の定義者は、指定されたフィルター関数に対して EXECUTE 特権を持っていなければなりません。

function-invocation 節は、データベース・コード・ページ内で、65 536 バイト以内の長さでなければなりません (SQLSTATE 22001)。

ケース式

結果表をさらにフィルター操作するためのケース式を指定します。 searched-when-clause および simple-when-clause では、 parameter-name、expression-name、または定数を使用できます (SQLSTATE 42703)。 FILTER USING function-invocation に指定された規則を使って、外部関数を結果式として使用することができます。 case-expression で参照される関数またはメソッドはすべて、 function-invocation にリストされている 4 つの規則にも適合していなければなりません。

case-expression の中では副照会および XMLQUERY または XMLEXISTS 式は使用できません (SQLSTATE 428E4)。

ケース式は整数を戻さなければなりません (SQLSTATE 428E4)。結果式で戻り値が 1 の場合は行が保持され、その他の場合は破棄されます。

case-invocation 節は、データベース・コード・ページ内で、65 536 バイト以内の長さでなければなりません (SQLSTATE 22001)。

索引の活用索引を活用するために使用する索引拡張の検索メソッドによって、規則のセットを定義します。

SEARCH BY INDEX EXTENSION index-extension-name

索引拡張を指定します。 index-extension-name は、既存の索引拡張を指定する必要があります。

EXACT

述部評価の時に索引検索が厳密に行われることを指定します。 EXACT を使用して、索引検索後に、オリジナルのユーザー定義の述部関数もフィルターも適用する必要がないことを示します。 EXACT 述部は、索引検索が述部と同じ結果を戻す場合に便利です。

EXACT が指定されない場合には、索引検索後、オリジナルのユーザー定義述部が適用されます。索引が類似した述部を提供するのにとどまると思われる場合には、 EXACT オプションは指定しないでください。

索引検索が使用されない場合には、フィルター関数とオリジナルの述部を適用する必要があります。

活用規則検索ターゲットおよび検索引数を記述し、さらにこれらを使用して索引拡張で定義した検索メソッドを介して索引検索を実行する方法を記述します。

WHEN KEY (parameter-name1)

検索ターゲットを定義します。 1 つのキーにつき 1 つしか、探索ターゲットを指定できません。 parameter-name1 値は、定義された関数のパラメーター名を指定します (SQLSTATE 42703 または 428E8)。

parameter-name1 のデータ・タイプは、索引拡張で指定したソース・キーのデータ・タイプに適合しなければなりません (SQLSTATE 428EY)。この適合は、組み込みおよび特殊データ・タイプで厳密に一致しなければならず、構造化タイプの同じタイプ階層内になければなりません。

指定されたパラメーターの値が、指定された索引拡張に基づく索引により網羅される列である場合、この節は真となります。

USE search-method-name(parameter-name2)

検索引数を定義します。索引拡張で定義されている検索メソッドから、使用する検索メソッドを指定します。 search-method-name は、索引拡張で定義される検索メソッドと適合しなければなりません (SQLSTATE 42743)。 parameter-name2 値は、定義された関数のパラメーター名、または EXPRESSION AS 節の expression-name を指定します (SQLSTATE 42703)。これは、検索ターゲットに指定したパラメーター名と異なっていなければなりません (SQLSTATE 428E9)。パラメーターの数と各 parameter-name2 のデータ・タイプは、索引拡張の検索メソッドに定義されるパラメーターに適合しなければなりません (SQLSTATE 42816)。この適合は、組み込みおよび特殊データ・タイプで厳密に一致しなければならず、構造化タイプの同じタイプ階層内になければなりません。

NOT SECURED または SECURED

関数が行および列のアクセス制御に対してセキュアであるどうかを指定します。デフォルトは NOT SECURED です。

NOT SECURED: 関数がセキュアであると見なされないことを示します。この関数が呼び出されるとき、この関数の引数は、列マスクが有効で列レベルのアクセス制御がその表でアクティブ化されている列を参照できません (SQLSTATE 428HA)。この規則は、ステートメントのどこかで呼び出されるセキュアではないユーザー定義関数に適用されます。
SECURED: 関数がセキュアであると見なされることを示します。関数は、行権限または列マスクで参照されるときに、セキュアでなければなりません (SQLSTATE 428H8)。

STAY RESIDENT NO

関数のためにロードしたライブラリーを関数の終了後にメモリー内に残さないことを指定します。この節は以下の場合に無視されます。

NOT FENCED 節を指定した場合。
LANGUAGE オプションを JAVA または CLR に設定した場合。

注

あるデータ・タイプが他のデータ・タイプにキャスト可能かどうかの判別では、 CHAR や DECIMAL などのパラメーター化データ・タイプの長さまたは精度と位取りは考慮されません。したがって、ソース・データ・タイプの値をターゲット・データ・タイプの値にキャストしようとすると、関数の使用時にエラーになる可能性があります。例えば、VARCHAR は DATE にキャストできますが、実際にはソース・タイプが VARCHAR(5) と定義されている場合には、関数の使用時にエラーになります。
ユーザー定義関数のパラメーターのデータ・タイプを選択する際には、その入力値に影響を与えるプロモーションの規則を考慮してください (データ・タイプのプロモーションを参照)。例えば、入力値として使用できる定数のデータ・タイプは、予期される以外の組み込みデータ・タイプである可能性があり、さらには、予期されるデータ・タイプにプロモートできない場合があります。プロモーションの規則に従って、一般にパラメーターには次のデータ・タイプを使用するようにしてください。
- SMALLINT の代わりに INTEGER
- REAL の代わりに DOUBLE
- CHAR の代わりに VARCHAR
- GRAPHIC の代わりに VARGRAPHIC
プラットフォーム間での UDF の移植性を保つためには、以下のデータ・タイプは使用しないようにする必要があります。
- FLOAT- 代わりに DOUBLE または REAL を使用してください。
- NUMERIC- 代わりに DECIMAL を使用してください。
- LONG VARCHAR- 代わりに CLOB (または BLOB) を使用してください。
関数とメソッドは、オーバーライド関係になってはなりません (SQLSTATE 42745)。オーバーライドについて詳しくは、CREATE TYPE (構造化)を参照してください。
関数のシグニチャーは、メソッドのシグニチャーと同じであってはなりません (関数の最初の parameter-type と、メソッドの subject-type を比較) (SQLSTATE 42723)。
まだ存在していないスキーマ名を用いて関数を作成すると、ステートメントの許可 ID に IMPLICIT_SCHEMA 権限がある場合に限り、そのスキーマが暗黙に作成されます。スキーマの所有者は SYSIBM になります。スキーマに対する CREATEIN 特権が PUBLIC に付与されます。
パーティション・データベース環境では、外部ユーザー定義関数またはメソッドでの SQL の使用はサポートされていません (SQLSTATE 42997)。
索引拡張を定義するには、NO SQL として定義されたルーチンしか使用できません (SQLSTATE 428F8)。
関数が SQL を許可する場合、外部プログラムは、フェデレーテッド・オブジェクトへのアクセスを試行してはなりません (SQLSTATE 55047)。
NOT FENCED として定義されている Java ルーチンは、FENCED THREADSAFE として定義されているかのように呼び出されます。
PARAMETER STYLE DB2GENERAL 節が指定されている場合、XML パラメーターは、LANGUAGE JAVA 外部関数でのみサポートされます。
表アクセスの制限
関数が READS SQL DATA に定義されている場合には、関数のいかなるステートメントも、関数を呼び出したステートメントによって変更されている表にはアクセスできません (SQLSTATE 57053)。例えば、ユーザー定義関数 BONUS() が READS SQL DATA に定義されているとします。ステートメント UPDATE EMPLOYEE SET SALARY = SALARY + BONUS(EMPNO) が呼び出される場合、 BONUS 関数の SQL ステートメントは、EMPLOYEE 表からの読み取りを行えません。
デフォルト値の設定: デフォルト値で定義された関数のパラメーターは、この関数の呼び出し時に、それらのデフォルト値に設定されますが、この関数の呼び出し時に、値が対応する引数に提供されていないか、または DEFAULT で指定されている場合にのみ、このように設定されます。
特権: 関数の定義者は、関数に対する WITH GRANT OPTION 付きの EXECUTE 特権と、関数をドロップする権利を常に与えられます。
SQL ステートメントで関数が使用されるとき、関数の定義者は、その関数によって使用されるすべてのパッケージに対する EXECUTE 特権か、EXECUTEIN 特権か、パッケージが含まれるスキーマに対する DATAACCESS 権限を持っている必要があります。
EXTERNAL ACTION 関数: EXTERNAL ACTION 関数が最外部の選択リスト以外で呼び出された場合、関数が呼び出される回数は使用されるアクセス・プランによって異なるため、結果が予測不能になります。
代替構文: このデータベース製品の以前のバージョンおよび他のデータベース製品との互換性のために、以下の代替の構文がサポートされています。これらの代替は非標準であり、使用すべきではありません。
- PARAMETER STYLE SQL の代わりに PARAMETER STYLE DB2SQL を指定できます。
- DETERMINISTIC の代わりに NOT VARIANT を、また NOT DETERMINISTIC の代わりに VARIANT を指定することができます。
- CALLED ON NULL INPUT の代わりに NULL CALL を、また RETURNS NULL ON NULL INPUT の代わりに NOT NULL CALL を指定できます。
以下の構文はデフォルトの振る舞いとして受け入れられます。
- ASUTIME NO LIMIT
- NO COLLID
- PROGRAM TYPE SUB
- STAY RESIDENT NO
- Unicode データベースでの CCSID UNICODE
- PARAMETER CCSID UNICODE が指定されていない場合、非 Unicode データベース内での CCSID ASCII
セキュア関数の作成: 通常、SECADM 権限を持つユーザーは、トリガーおよび関数などのデータベース・オブジェクトを作成する特権を持ちません。一般的に、このユーザーは、関数によってアクセスされるデータを検査し、それがセキュアであることを確認してから、セキュアなユーザー定義関数の作成に必要な特権を現在保持しているユーザーに対して、CREATE_SECURE_OBJECT 権限を付与します。関数が作成されると、関数所有者の CREATE_SECURE_OBJECT 権限が取り消されます。
SECURED 属性は、ユーザー定義関数に対するすべての変更についての変更制御監査プロシージャーをユーザーが確立したことを宣言する、アサーションとして見なされます。データベース・マネージャーは、その制御監査プロシージャーが、すべての後続の ALTER FUNCTION ステートメントまたは外部パッケージに対する変更に有効であると見なします。
セキュア関数での他のユーザー定義関数の呼び出し: セキュア・ユーザー定義関数がその他のユーザー定義関数を呼び出す場合、データベース・マネージャーは、それらのネストしたユーザー定義関数に SECURED 属性があるかどうかを妥当性検査しません。これらのネストされた関数が機密データにアクセスできる場合、SECADM 権限を持つユーザーは、それらの関数がデータへのアクセスを許可されていること、およびそれらの関数に対するすべての変更に対して変更管理監査プロシージャーが確立されていることを確認する必要があります。
セキュア属性の変更 (SECURED から NOT SECURED およびその逆) を伴う既存関数の置換: 関数に依存するパッケージおよび動的キャッシュ SQL ステートメントは、無効になる可能性があります。これは、行レベルまたは列レベルのアクセス制御がアクティブになっている表が関係するステートメントでは、セキュア属性がアクセス・パスの選択に影響を及ぼすためです。

例

Pellow は、自身の PELLOW スキーマに CENTER 関数を登録します。デフォルト値のあるキーワードはデフォルト値を使い、関数特定名はシステムに生成させることにします。
```
   CREATE FUNCTION CENTER (INT,FLOAT)
     RETURNS FLOAT
     EXTERNAL NAME 'mod!middle'
     LANGUAGE C
     PARAMETER STYLE SQL
     DETERMINISTIC
     NO SQL
     NO EXTERNAL ACTION
```
ここで、McBride (DBADM 権限を持つ) が PELLOW スキーマに別の CENTER 関数を登録し、関数にデータ定義言語でその後使用するための明示的な特定名を付け、すべてのキーワード値を明示的に指定します。また、この関数はスクラッチパッドを使用し、おそらく後続の結果に影響するデータをスクラッチパッドに累積します。 DISALLOW PARALLEL が指定されているので、関数への参照は並列化されず、したがって 1 つのスクラッチパッドを使用して一度限りの初期化と結果の保存が行われます。
```
   CREATE FUNCTION PELLOW.CENTER (FLOAT, FLOAT, FLOAT)
     RETURNS DECIMAL(8,4) CAST FROM FLOAT
     SPECIFIC FOCUS92
     EXTERNAL NAME 'effects!focalpt'
     LANGUAGE C   PARAMETER STYLE SQL
     DETERMINISTIC   FENCED   NOT NULL CALL   NO SQL   NO EXTERNAL ACTION
     SCRATCHPAD   NO FINAL CALL 
     DISALLOW PARALLEL
```

以下の例は、入力が NULL の場合にのみ NULL を返す規則「output = 2 * input - 4」をインプリメントするために作成された C 言語のユーザー定義関数プログラムです。これは、CREATE FUNCTION ステートメントで NOT NULL CALL を指定することにより、より簡単に (つまり NULL 値チェックを行わずに) 作成することができます。 CREATE FUNCTION ステートメントは、次のとおりです。

   CREATE FUNCTION ntest1 (SMALLINT)
     RETURNS SMALLINT
     EXTERNAL NAME 'ntest1!nudft1'
     LANGUAGE C    PARAMETER STYLE SQL
     DETERMINISTIC   NOT FENCED   NULL CALL
     NO SQL   NO EXTERNAL ACTION

プログラム・コードは、次のとおりです。

#include "sqlsystm.h"
/* NUDFT1 IS A USER_DEFINED SCALAR FUNCTION */
/* udft1 accepts smallint input
and produces smallint output
implementing the rule:
if (input is null)
set output = null;
else
set output = 2 * input - 4;
*/
void SQL_API_FN nudft1
(short *input,      /* ptr to input arg */
short *output,     /* ptr to where result goes */
short *input_ind,  /* ptr to input indicator var */
short *output_ind, /* ptr to output indicator var */
char sqlstate[6],  /* sqlstate, allows for null-term */
char fname[28],    /* fully qual func name, nul-term */
char finst[19],    /* func specific name,  null-term */
char msgtext[71])  /* msg text buffer,     null-term */
{
/* first test for null input */
if (*input_ind == -1)
{
/* input is null, likewise output */
*output_ind = -1;
}
else
{
/* input is not null.  set output to 2*input-4 */
*output = 2 * (*input) - 4;
/* and set out null indicator to zero */
*output_ind = 0;
}
/* signal successful completion by leaving sqlstate as is */
/* and exit */
return;
}
/* end of UDF: NUDFT1 */

以下の例では、ストリング内の最初の母音の位置を返す Java UDF を登録します。 UDF は Java で作成され、fenced で実行され、クラス javaUDFsの findvwl メソッドです。

   CREATE FUNCTION findv ( CLOB(100K))
     RETURNS INTEGER
     FENCED
     LANGUAGE JAVA
     PARAMETER STYLE JAVA
     EXTERNAL NAME 'javaUDFs.findvwl'
     NO EXTERNAL ACTION
     CALLED ON NULL INPUT 
     DETERMINISTIC
     NO SQL

この例では、タイプ SHAPE の 2 つのパラメーター g1 および g2 を入力として取るユーザー定義述部 WITHIN を概説します。
```
CREATE FUNCTION within (g1 SHAPE, g2 SHAPE)
RETURNS INTEGER
LANGUAGE C
PARAMETER STYLE SQL
DETERMINISTIC
NOT FENCED
NO SQL
NO EXTERNAL ACTION
EXTERNAL NAME 'db2sefn!SDESpatilRelations'
PREDICATES
WHEN = 1
FILTER USING mbrOverlap(g1..xmin, g1..ymin, g1..xmax, g1..max,
g2..xmin, g2..ymin, g2..xmax, g2..ymax)
SEARCH BY INDEX EXTENSION gridIndex
WHEN KEY(g1) USE withinExplRule(g2)
WHEN KEY(g2) USE withinExplRule(g1)
```
WITHIN 関数の記述は、任意のユーザー定義の関数の記述に類似しているものの、以下を追加することにより、この関数がユーザー定義の述部で使用できることを指定することができます。
- PREDICATES WHEN = 1 は、DML ステートメントの WHERE 節でこの関数が
```
   within(g1, g2) = 1
```
  と表されるときに、述部はユーザー定義の述部として扱われ、索引拡張 gridIndex で定義される索引は、この述部に適合する行を検索するのに使用されるように指定します。定数が指定される場合には、DML ステートメントで指定される定数は、索引の作成ステートメントで指定される定数と完全に一致していなければなりません。この条件は主に、結果タイプが 1 または 0 のブール式に対応するように提供されています。他の場合には、EXPRESSION 節を選択することをお勧めします。
- FILTER USING mbrOverlap は、フィルター関数 mbrOverlap を参照します。これは、WITHIN 述部の低コスト・バージョンです。この例では、mbrOverlap 関数は入力として最小境界長方形を受け取り、これらがオーバーラップするかどうかを素早く判別します。 2 つの入力の形の最小の境界長方形がオーバーラップしない場合、g1 が g2 に含まれることはありません。このようにして、タプルを安全に廃棄でき、コストの高い WITHIN 述部のアプリケーションを避けることができます。
- SEARCH BY INDEX EXTENSION 節は、索引拡張と検索ターゲットの組み合わせをこのユーザー定義の述部で使用できることを指定します。
この例では、タイプ POINT の 2 つのパラメーター P1 および P2 を入力として取るユーザー定義述部 DISTANCE を概説します。
```
   CREATE FUNCTION distance (P1 POINT, P2 POINT)
     RETURNS INTEGER
     LANGUAGE C
     PARAMETER STYLE SQL
     DETERMINISTIC
     NOT FENCED
     NO SQL
     NO EXTERNAL ACTION
     EXTERNAL NAME 'db2sefn!SDEDistances'
     PREDICATES
     WHEN > EXPRESSION AS distExpr
     SEARCH BY INDEX EXTENSION gridIndex
     WHEN KEY(P1) USE distanceGrRule(P2, distExpr)
     WHEN KEY(P2) USE distanceGrRule(P1, distExpr)
```
DISTANCE 関数の記述は、任意のユーザー定義関数の記述に類似しているものの、以下の追加により、この関数が述部で使用される場合に、この述部がユーザー定義述部であることを指定します。
- PREDICATES WHEN> EXPRESSION AS distExpr も、有効な述部指定です。 WHEN 節で式が指定されると、この述部が DML ステートメントのユーザー定義述部であるかどうかを判別するために、この式の結果タイプが使用されます。以下に例を示します。
```
   SELECT T1.C1
     FROM T1, T2
     WHERE distance (T1.P1, T2.P1) > T2.C2
```
  述部指定 distance は、2 つのパラメーターを入力として使用し、タイプ INTEGER の T2.C2 を使用して結果を比較します。 (特定の定数を使用する場合とは異なり) 式の右辺のデータ・タイプのみ問題となるため、 CREATE FUNCTION DDL にある EXPRESSION 節を選択して、比較値としてワイルドカードを指定するとよいでしょう。
  別の方法として、以下のステートメントも有効なユーザー定義述部です。
```
   SELECT T1.C1
     FROM T1, T2
     WHERE distance(T1.P1, T2.P1) > distance (T1.P2, T2.P2)
```
  現在のところ、右辺しか式として扱われないという制限があります。左辺の項は、ユーザー定義述部用のユーザー定義関数です。
- SEARCH BY INDEX EXTENSION 節は、索引拡張と検索ターゲットの組み合わせをこのユーザー定義の述部に使用できることを指定します。 distance 関数の場合、distExpr として指定された式も範囲生成関数 (索引拡張の一部として定義) に渡される検索引数の 1 つです。式の ID は、式の名前を定義するのに使用され、引数として範囲生成関数に渡されます。