CREATE FUNCTION (外部スカラー)
CREATE FUNCTION (外部スカラー) ステートメントは、現行サーバー上に外部スカラー関数を定義します。ユーザー定義の外部スカラー関数は、呼び出されるたびに単一値を戻します。
呼び出し
このステートメントは、アプリケーション・プログラムに組み込むことができ、また対話式に呼び出すこともできます。 これは、動的に準備できる実行可能ステートメントです。
権限
このステートメントの権限 ID が保持する特権には、少なくとも以下の 1 つ が含まれていなければなりません。
- SYSFUNCS カタログ・ビューと SYSPARMS カタログ表の場合 1:
- 該当の表に対する INSERT 特権、および
- スキーマ QSYS2 に対する USAGE 特権
- データベース管理者権限
外部プログラムやサービス・プログラムが存在している 場合、このステートメントの権限 ID が保持する特権には、少なくとも次の いずれか 1 つを含める必要があります。
- SQL ステートメントで参照された外部プログラムやサービス・プログラムの場合
- その外部プログラムやサービス・プログラムが含まれるスキーマに対する USAGE 特権
- その外部プログラムやサービス・プログラムに対するシステム権限の *EXECUTE。
- そのプログラムやサービス・プログラムに対するシステム権限の *CHANGE。システムには、プログラム・オブジェクトを更新し、関数を別のシステムに保管/復元するために必要な情報を入れる場合にこの権限が必要となります。 ユーザーにこの権限が与えられていない場合、関数は同じように作成されますが、プログラム・オブジェクトは更新されません。
- データベース管理者権限
SQL 名が指定され、関数が作成されるライブラリーと同じ名前のユーザー・プロファイルが存在し、しかも、その名前がステートメントの権限 ID と異なっている場合、ステートメントの権限 ID が保持している特権には、少なくとも次のいずれか 1 つを含める必要があります。
- その名前を持つユーザー・プロファイルに対する *ADD システム権限
- データベース管理者権限
特殊タイプを参照する場合は、ステートメントの権限 ID によって保持される 特権に、少なくとも次のいずれか 1 つが含まれなければなりません。
- ステートメント内で識別された、それぞれの特殊タイプごとに、
- その特殊タイプに対する USAGE 特権、および
- 特殊タイプが含まれるスキーマに対する USAGE 特権
- データベース管理者権限
既存の関数に置き換えるには、ステートメントの権限 ID が保持する特権に、次のうち少なくともいずれか 1 つを含める必要があります。
- 次のシステム権限
- この関数に関連したサービス・プログラム・オブジェクトに対する *OBJMGT システム権限
- この関数を削除するために必要な全権限
- SYSFUNCS カタログ・ビューと SYSPARMS カタログ表に対する *READ システム権限
- データベース管理者権限
SQL 特権に対応するシステム権限については、『表またはビューへの権限を検査する際の対応するシステム権限』および 『特殊タイプへの権限を検査する際の対応するシステム権限』を参照してください。
構文
>>-CREATE -+------------+--FUNCTION--function-name--------------> '-OR REPLACE-' >--(--+---------------------------+--)--------------------------> | .-,---------------------. | | V | | '---parameter-declaration-+-' >--RETURNS -+-data-type2--+------------+------------------------+--> | '-AS LOCATOR-' | '-data-type3--CAST FROM--data-type4--+------------+-' '-AS LOCATOR-' >--option-list--+----------------------+----------------------->< '-SET OPTION-statement-'
- XML の ccsid-clause は、data-type2 および data-type3 でのみ使用できます。
- この文節とこの後の option-list にある文節は、どのような順番で指定してもかまいません。各文節を指定できるのは、それぞれ 1 回だけです。
説明
- OR REPLACE
- 現行サーバーにこの関数の定義が存在する場合に、その定義を置き換える、という動作を指定します。実際には、カタログで既存の定義を削除してから新しい定義に置き換える、という動作になりますが、例外として、この関数に対して与えられていた特権は影響を受けません。現行サーバーにこの関数の定義が存在しなければ、このオプションは無視されます。既存の関数を置き換えるには、新しい定義の specific-name および function-name が古い定義の specific-name および function-name と同じであるか、新しい定義のシグニチャーが古い定義のシグニチャーと一致している必要があります。そうでなければ、新しい関数が作成されます。
- function-name
- ユーザー定義関数の名前を指定します。名前、スキーマ名、パラメ
ーターの数、およびそれぞれのパラメーターのデータ・タイプ (データ・タ
イプの長さ、精度、位取り、または CCSID の属性に関係なく) の組み合わせ
で、現行サーバー上に存在しているユーザー定義の関数を識別してはなりません。
SQL 命名の場合、関数は、暗黙または明示修飾子で指定されたスキーマ内に作成されます。
システム命名の場合、関数は、修飾子で指定されたスキーマ内に作成されます。 修飾子を指定しなかった場合:
- CURRENT SCHEMA 特殊レジスターの値が *LIBL である場合、関数は、現行ライブラリー (*CURLIB) 内に作成されます。
- そうでない場合、関数は現行スキーマ内に作成されます。
通常、それぞれの関数の関数シグニチャーが固有であれば、複数の関数に同じ名前を指定することができます。
一部の関数名は、システムが使用するために予約されています。 詳しくは、CREATE FUNCTIONの『スキーマおよび関数名の選択』を参照してください。
- (parameter-declaration,...)
- 関数の入力パラメーターの数とそれぞれのパラメーターのデータ・タイプを指定します。
各 parameter-declaration は、関数の入力パラメーターを指定します。
パラメーターの最大数は、言語のタイプによって異なります。
- JAVA と ILE プログラムおよびサービス・プログラムの場合、最大数は 2000 です。
- OPM プログラムの場合、最大数は 90 です。
パラメーターの最大数は、その言語で許されるパラメーターの最大数によってさらに制限される可能性があります。
関数は、ゼロまたはそれ以上の入力パラメーターを持つことができます。関数が受け取ると予期しているパラメーターには、それぞれリスト内に 1 個の項目が必要です。関数のパラメーターはすべて入力パラメーターで、ヌル可能です。JAVA の場合は、DECIMAL タイプと NUMERIC タイプ以外の数値パラメーターがヌル可能です。CALLED ON NULL INPUT 関数でそのようなパラメーターの入力がヌル値になると、実行時エラーになります。詳しくは、CREATE FUNCTIONの『パラメーターの定義』を参照してください。- parameter-name
- パラメーター名を指定します。必須ではありませんが、各パラメーターにパラメーター名を指定することができます。 この名前は、パラメーター・リスト内の他のパラメーター名 と同じものであってはなりません。
- data-type1
- 入力パラメーターのデータ・タイプを指定します。このデータ・タイプは、組み込みデータ・タイプまたは特殊タイプにすることができます。この変数は、配列タイプにすることはできません。
- built-in-type
- 組み込みデータ・タイプを指定します。 それぞれの組み込みデータ・タイプの詳細については、CREATE TABLEを参照してください。 データ・タイプによってはすべての言語ではサポートされていないものもあります。 SQL データ・タイプとホスト言語データ・タイプのマッピングについての詳細は、「組み込み SQL プログラミング」トピック集を参照してください。組み込みデータ・タイプの仕様は、ユーザー定義関数の作成に使用する言語に対応していれば、指定することができます。
- distinct-type-name
- ユーザー定義特殊タイプを指定します。パラメーターの長さ、精度、または位取り属性は、
特殊タイプのソース・タイプの属性 (CREATE TYPE で指定された属性) と同じになります。特殊タイプの作成についての詳細は、CREATE TYPE (特殊)を参照してください。
特殊タイプの名前が修飾されていない場合、データベース・マネージャーは、SQL パス上のスキーマを検索することでそのスキーマ名を解決します。
CCSID が指定されている場合、関数に渡される前に、パラメーターはその CCSID に変換されます。CCSID が指定されていない場合は、CCSID は、関数 の呼び出し時点における現行サーバーのデフォルトの CCSID によって決まり ます。
日付、時刻、およびタイム・スタンプの各パラメーターは、ISO 形式の文字ストリングとしてプロシージャーに渡されます。
XML タイプのパラメーターでは、XML-cast-type 文節または AS LOCATOR 文節を指定する必要があります。
- AS LOCATOR
- 実際の値の代わりにパラメーターの値への
ロケーターを関数に渡すことを指定します。
AS LOCATOR は、LOB または XML データ・タイプまたは LOB または XML データ・タイプに基づく特殊タイプのパラメーターの場合に限り使用するようにしてください。AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- AS XML-cast-type
- XML タイプまたは XML タイプに基づく特殊タイプのパラメーターのデータ・タイプとしてこの関数に渡すデータ・タイプを指定します。LOCATOR を指定する場合は、パラメーターが実際の値ではなく値のロケーターになります。
CCSID 値を指定する場合に、グラフィック・データ・タイプとして指定できるのは、Unicode CCSID 値に限られます。CCSID 値を指定しない場合は、この関数の作成時に、SQL_XML_DATA_CCSID QAQQINI オプションの設定に基づいて CCSID が設定されます。デフォルトの CCSID は 1208 です。このオプションの説明については、XML 値を参照してください。
- default-clause
- パラメーターのデフォルト値を指定します。デフォルト値は、定数、特殊レジスター、グローバル変数、式、またはキーワード NULL にすることができます。式は、集約関数および列名を含まない、式で
定義されている任意の式です。デフォルト値が指定されていない場合、パラメーターにデフォルト値がないため、呼び出し時に省略できません。式ストリングの
最大長は 64K です。
デフォルトの式は、 パラメーターのデータ・タイプに対して割り当ての互換性がなければなりません 。
デフォルト式内でリスト中の数値定数を区切る区切り記号として 使用するコンマの後には、スペースが 1 つ必要です。
デフォルト式の中で参照されるすべてのオブジェクト は、関数が作成されるときに存在している必要があります。関数が起動されると、デフォルトは起動側の権限を使用して 評価されます。
配列タイプの パラメーターにデフォルトを指定することはできません。
- RETURNS
- 関数の結果のデータ・タイプを指定します。この文節は、オプションの CAST FROM 文節との関連で
考慮してください。
- data-type2
- 出力のデータ・タイプと属性を指定します。
あらゆる組み込みデータ・タイプ (ただし、LONG VARCHAR、LONG VARGRAPHIC、または DataLink は除く) や特殊タイプ (データ・リンクをベースとしていない) を指定することができます。配列タイプを指定することはできません。
CCSID が指定されている場合
- AS LOCATOR が指定されていない場合、戻される結果はその CCSID で コード化されていると想定されます。
- AS LOCATOR が指定され、ロケーターが指しているデータの CCSID が異なる CCSID でコード化されている場合、データは指定された CCSID に変換され ます。
CCSID が指定されず、ビューの最外部の選択リストで関数が参照されない場合、以下のようになります。
- AS LOCATOR が指定されていない場合、戻される結果は、ジョブの CCSID (グ ラフィック・ストリング戻り値の場合は、ジョブに関連したグラフィック CCSID) でコード化されていると想定されます。
- AS LOCATOR が指定され、ロケーターが指しているデータの CCSID が異なる CCSID でコード化されている場合、ロケーターが指しているデータは、ジョ ブの CCSID に変換されます。変換時に文字が失われるのを防ぐために、関数から戻される文字 をすべて表現できる CCSID を明示的に指定することを考慮してください。 これは、データ・タイプがグラフィック・ストリング・データの場合に特に重要です。 この場合、CCSID 1200 または 13488 (ユニコード・グラフィック・ストリング・データ) を使用することを考慮してください。
CCSID が指定されず、ビューの最外部の選択リストで関数が参照される場合、以下のようになります。
- AS LOCATOR が指定されていない場合、戻される結果は、関連するビュー列の CCSID でコード化されていると想定されます。
- AS LOCATOR が指定され、ロケーターが指しているデータの CCSID が異なる CCSID でコード化されている場合、ロケーターが指しているデータは、関連するビュー列の CCSID に変換されます。 変換時に文字が失われるのを防ぐために、関数から戻される文字 をすべて表現できる CCSID を明示的に指定することを考慮してください。 これは、データ・タイプがグラフィック・ストリング・データの場合に特に重要です。 この場合、CCSID 1200 または 13488 (ユニコード・グラフィック・ストリング・データ) を使用することを考慮してください。
- AS LOCATOR
- これを指定すると、関数は、実際の値ではなく、値のロケーターを戻します。
AS LOCATOR は、関数の結果が LOB または XML データ・タイプまたは LOB または XML データ・タイプに基づく特殊タイプのパラメーターを持っている場合に限り使用するようにしてください。AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- data-type3CAST FROMdata-type4
- 関数のデータ・タイプと属性 (データ・タイプ 4 )、および、その結果が呼び出しステートメントに戻されるデータ・タイプ (データ・タイプ 3 ) を指定します。
これら 2 つのデータ・タイプは、異なっていても構いません。例えば、次の定義の場合、関数は DOUBLE の値を戻しますが、データベース・マネージャーはそれを DECIMAL の値に変換してから、呼び出し元ステートメントに渡します。
data-type4 の値 は、XML タイプまたは特殊タイプであってはならず、data-type3 にキャスト可能である必要があります。 データ・タイプ 3 の値は、任意の組み込みデータ・タイプや特殊タイプにすることができます。 (データ・タイプのキャストについては、データ・タイプ間のキャストを参照してください。)CREATE FUNCTION SQRT (DECIMAL15,0)) RETURNS DECIMAL(15,0) CAST FROM DOUBLE ...CCSID については、上記のデータ・タイプ 2 の説明を参照してください。
- AS LOCATOR
- これを指定すると、関数は、実際の値ではなく、値のロケーターを戻します。
AS LOCATOR は、関数の結果が LOB データ・タイプまたは LOB データ・タイプに基づく特殊タイプのパラメーターを持っている場合に限り使用するようにしてください。
AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- LANGUAGE
- 関数本体を作成する言語インターフェース規則を指定します。
すべてのプログラムがサーバーの環境で実行するように設計しなければなりません。
LANGUAGE を指定しなかった場合、その LANGUAGE は、関数の作成時に、外部プログラムと関連したプログラム属性情報から決定されます。 次の場合、プログラムの言語は C であると想定されます。
- プログラムに関連したプログラム属性情報で、認識可能な言語を識別しない。
- プログラムが見つからない。
- C
- 外部プログラムは C で作成されます。
- C++
- 外部プログラムは C++ で作成されます。
- CL
- 外部プログラムは CL または ILE CL で作成されます。
- COBOL
- 外部プログラムは COBOL で作成されます。
- COBOLLE
- 外部プログラムは ILE COBOL で作成されます。
- JAVA
- 外部プログラムは JAVA で作成されます。このユーザー定義の関数は
データベース・マネージャーにより呼び出されます。この関数は、指定され
た Java™ クラスの共通静的メソッドでなければなりません。
LANGUAGE JAVA を指定する場合は、EXTERNAL NAME 文節で有効な external-java-routine-name の値を指定する必要があります。SCRATCHPAD、FINAL CALL、または DBINFO を指定する場合は、LANGUAGE JAVA を指定しないでください。
- PLI
- 外部プログラムは PL/I で作成されます。
- RPG
- 外部プログラムは RPG で作成されます。
- RPGLE
- 外部プログラムは ILE RPG で作成されます。
- PARAMETER STYLE
- 関数にパラメーターを渡し、関数から値を戻すために使用する規則を指定します。
- SQL
- 適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 関数に対して指定される入力パラメーター用の n 個のパラメーター。
- 関数の結果を表すパラメーター。
- 入力パラメーターに対する標識変数用の n 個のパラメーター。
- 結果の標識変数を表すパラメーター。
- SQLSTATE の CHAR(5) 出力パラメーター。戻される SQLSTATE は、関数
が成功したかどうかを示します。戻される SQLSTATE は、以下のいずれかです。
- 外部プログラムで実行された最後の SQL ステートメントからの SQLSTATE
- 外部プログラムによって割り当てられた SQLSTATE
ユーザーは、関数からエラーまたは警告を戻すために、外部プログラム 内で SQLSTATE を任意の有効な値にセットすることができます。
- 完全修飾関数名の VARCHAR(517) 入力パラメーター。
- 特定の名前の VARCHAR(128) 入力パラメーター。
- メッセージ・テキストの VARCHAR(1000) 出力パラメーター。
制御が呼び出し側プログラムに戻された場合、SQLCA の SQLERRMC フィ ールドの 6 番目のトークンにメッセージ・テキストが 入っています。入手できるのは、メッセージ・テキストの一部分だけです。 SQLERRMC 内のメッセージ・データのレイアウトについては、メッセージ・ファイル QSQLMSG 内のメッセージ SQL0443 の置換データ記述を参照してください。 完全なメッセージ・テキストは、GET DIAGNOSTICS ステートメントを使用して検索することができます。 詳しくは、GET DIAGNOSTICSを参照してください。
- 0 から 3 個のオプション・パラメーター
- CREATE FUNCTION ステートメントで SCRATCHPAD を指定した場合 、スクラッチパッドの構造 (後に CHAR(n) が続く INTEGER からなる) 入出力パラメーター。
- CREATE FUNCTION ステートメントで FINAL CALL を指定した場合、呼 び出しタイプの INTEGER 入力パラメーター。
- CREATE FUNCTION ステートメントで DBINFO を指定した場合、dbinfo 構造体の構造。
- DB2GENERAL
- このパラメーター・スタイルは、Java クラスでメソッドとして定義されている外部関数にパラメーターを渡し、外部関数から値を戻すための規則を指定するのに使用します。適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指 定される入力パラメーターです。
- 関数の結果を表すパラメーター。
DB2GENERAL は、LANGUAGE が JAVA の場合にのみ許されます。
- GENERAL
- 適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指 定される入力パラメーターです。
return_val func(parameter-1, parameter-2, ...)GENERAL は、EXTERNAL NAME でサービス・プログラムを識別する場合にのみ許可されます。
- GENERAL WITH NULLS
- 適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指 定される入力パラメーターです。
- 標識変数配列に追加の引数が渡されます。
- 結果の標識変数を表すパラメーター。
return_val func(parameter-1, parameter-2, ...)GENERAL WITH NULLS は、EXTERNAL NAME でサービス・プログラムを識別する場合にのみ許可されます。
- JAVA
- この関数で、Java 言語および ISO/IEC FCD 9075-13:2003「Information technology - Database languages - SQL - Part 13: Java Routines and Types (SQL/JRT)」仕様に準拠するパラメーター引き渡し規則を使用することを指定します。
適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指 定される入力パラメーターです。
return_val func(parameter-1, parameter-2, ...)JAVA は、LANGUAGE が JAVA の場合にのみ許されます。
パラメーターを渡す方法は、外部関数の言語によって決まります。例えば、C では、VARCHAR または CHAR パラメーターは NULL 文 字で終了するストリングとして渡されます。 詳しくは、「SQL プログラミング」のトピック集を参照してください。 Java ルーチンについては、「IBM® Developer Kit for Java」のトピック集を参照してください。
- SPECIFIC specific-name
- 関数の固有名を指定します。特定名の詳細については、CREATE FUNCTIONの『関数に特定の名前を指定する』を参照してください。
- GLOBAL DETERMINISTIC または STATEMENT DETERMINISTIC または NOT DETERMINISTIC
- 関数が同じ入力引数を指定して呼び出されるたびに、その関数が同じ結果を戻すかどうかを指定します。デフォルトは NOT DETERMINISTIC です。
- NOT DETERMINISTIC
- 関数が同じ入力引数を指定して呼び出されるたびに、その関数が同じ結果を戻さない場合があることを指定します。関数は、結果に影響を与えるいくつかの状態値によって変わってきます。
データベース・マネージャーは、SQL ステートメントの最適化時にこの情報を使用します。非 deterministic 関数の例として、乱数を生成する関数があります。
非決定的関数を並列タスクで実行すると、間違った結果が返される可能性があります。このような関数には DISALLOW PARALLEL 文節を指定してください。
NOT DETERMINISTIC は、特殊レジスター、非決定的関数、またはシーケンスに対する参照が この関数に含まれている場合に指定してください。
- GLOBAL DETERMINISTIC
- 関数が同じ入力引数を指定して呼び出されるたびに、その関数が常に同じ結果を戻すかを指定します。データベース・マネージャーは、SQL ステートメントの最適化時にこの情報を使用します。照会オプティマイザーは、グローバル deterministic なスカラー関数の結果を キャッシュに入れるよう選択する場合があります。2グローバル deterministic 関数の例としては、入力引数の平方根を計算する関数があります。
- STATEMENT DETERMINISTIC
- 関数が同じ入力引数を使用して呼び出されるたびに、同じ結果を戻さない可能性があるが、単一 SQL ステートメント内での関数の複数の呼び出しは、deterministic と見なされることを指定します。 照会オプティマイザーは、ステートメント deterministic なスカラー関数の結果をキャッシュに入れません。3ステートメント deterministic 関数の例としては、通貨変換を実行する関数があります。
- CONTAINS SQL、READS SQL DATA、MODIFIES SQL DATA、または NO SQL
- 関数が実行できる SQL ステートメントおよびネストされたルーチンの種別を指定します。データベース・マネージャーは、関数と、関数からローカルで呼び出すすべてのルーチンが発行する SQL ステートメントが、この指定と整合しているかどうかを検査します。ネストされたリモート・ルーチンが呼び出された場合、検査は実行されません。
各ステートメントの分類については、SQL ステートメントの特性を参照してください。
デフォルトは、READS SQL
DATA です。このオプションは、パラメーター・デフォルト式では無視されます。
- READS SQL DATA
- この関数が、データ・アクセス種別 READS SQL DATA、CONTAINS SQL、または NO SQL のステートメントを実行できるように指定します。この関数は、データの変更を行う SQL ステートメントは実行できません。
- NO SQL
- この関数が、データ・アクセス種別 NO SQL の SQL ステートメントのみを実行できるように指定します。
- CONTAINS SQL
- この関数が、データ・アクセス種別 CONTAINS SQL または NO SQL の SQL ステートメントのみを実行できるように指定します。この関数は、データの読み取りまたは変更を行う SQL ステートメントを実行できません。
- MODIFIES SQL DATA
- この関数は、どの関数でもサポートされないステートメントを除く すべての SQL ステートメントを実行できます。
- RETURNS NULL ON NULL INPUT または CALLED ON NULL INPUT
- 入力引数のいずれかが実行時にヌルである場合に関数を呼び出すかどうかを指定します。CALLED ON NULL INPUT がデフォルトです。
- RETURNS NULL ON INPUT
- 入力引数のいずれかが NULL である場合に関数を呼び出さないことを指定します。 結果は NULL 値です。
- CALLED ON NULL INPUT
- 引数値のいずれかまたは全部がヌルである場合に関数を呼び出すことを指定します。この指定は、ヌル引数値のテストを行うように関数をコーディングする必要があります。関数は NULL または非 NULL 値を戻すことができます。
- INHERIT SPECIAL REGISTERS
- 特殊レジスターの既存の値は、関数に入った後に継承されることを指定します。
- STATIC DISPATCH
- 関数を静的にディスパッチすることを指定します。 すべての関数が静的にディスパッチされます。
- NO DBINFO または DBINFO
- 関数を呼び出すときに、追加の状況情報を渡すかどうかを指定します。デフォルトは NO DBINFO です。
- NO DBINFO
- 補足情報を渡さないことを指定します。
- DBINFO
- データベース・マネージャーは、状況情報が入っている
構造体を関数に渡す必要があることを指定します。 表 1 は、DBINFO 構造体の説明を示しています。
DBINFO 構造体についての詳しい情報は、
ライブラリー QSYSINC 内の該当するソース・ファイルの組み込み sqludf に入っています。
例えば、C の場合、sqludf は QSYSINC/H で見つかります。
DBINFO は、PARAMETER STYLE SQL または PARAMETER STYLE DB2GENERAL でのみ許可されます。
表 1. DBINFO フィールド フィールド データ・タイプ 説明 リレーショナル・データベース VARCHAR(128) 現行サーバーの名前 権限 ID VARCHAR(128) 実行時権限 ID CCSID 情報 INTEGER
INTEGER
INTEGERINTEGER
INTEGER
INTEGERINTEGER
INTEGER
INTEGERINTEGERCHAR(8)ジョブの CCSID 情報。3 つの CCSID が 3 セット戻されます。各セット内の 3 つの CCSID を識別する情報は、次のとおりです。 - SBCS CCSID
- DBCS CCSID
- 混合 CCSID
CCSID の各設定は、異なるエンコード・スキーム (EBCDIC、ASCII、およびユニコード) のためのものです。
CREATE FUNCTION ステートメントのパラメーターの 1 つとして明示的 に CCSID を指定していない場合は、入力ストリングは、関数の実行時にジョブ の CCSID でコード化されるものと見なされます。 入力ストリングの CCSID がパラメーターの CCSID と同じではない場合 は、この外部関数に渡される入力ストリングは、外部プログラムの呼び出し の前に変換されます。
ターゲット列 VARCHAR(128) VARCHAR(128)VARCHAR(128)ユーザー定義の関数が UPDATE ステートメントの SET 文節 の右側に指定されている場合、次の情報がターゲット列を識別 します。 - スキーマ名
- 基本表名
- 列名
バージョンとリリース CHAR(8) データベース・マネージャーのバージョン、リリース、および修正レベル。 プラットフォーム INTEGER サーバーのプラットフォーム・タイプ。
- EXTERNAL ACTION または NO EXTERNAL ACTION
- 関数が、データベース・マネージャーが管理しないオブジェクトの状態を変更するアクションを行うかどうかを指定します。外部アクションの例には、メッセージの送信やストリーム・ファイルへのレコードの書き込みなどがあります。デフォルトは EXTERNAL ACTION です。
- EXTERNAL ACTION
- 関数が、データベース・マネージャーが管理しないオブジェクトの状態を変更するアクションを行うことができるかを指定します。したがって、関数は、それぞれの連続関数呼び出しで呼び出す必要があります。 EXTERNAL ACTION は、この関数に、外部アクションを持つ他の関数に対する 参照が含まれている場合に、指定してください。
- NO EXTERNAL ACTION
- 関数は外部アクションを行いません。
この関数は、連続した各関数呼び出しごとに呼び出す必要はありません。
NO EXTERNAL ACTION 関数は、連続した各関数呼び出しごとに呼び出されない場合があるので、EXTERNAL ACTION 関数よりもパフォーマンスが向上する可能性があります。
- FENCED または NOT FENCED
- データベース・マネージャー環境から分離した環境で外部関数を実行するかどうかを指定します。
FENCED がデフォルトです。
- FENCED
- この関数は別のスレッドで実行されます。
FENCED 関数では、関数の呼び出し間で SQL カーソルをオープン状態のままにすることができません。 ただし、あるスレッド内のカーソルは他のスレッド内のカーソルから独立しています。このことは、カーソル名の競合が起きる可能性を低くしています。
- NOT FENCED
- この関数は、呼び出し元の SQL ステートメントと同じスレッド内で実行できます。
NOT FENCED 関数では、関数の呼び出し間で SQL カーソルをオープン状態のままにすることができます。 カーソルをオープン状態のままにしておくことができるため、関数の 呼び出し間でカーソル位置も同じに維持されます。 ただし、UDF が呼び出し元の SQL ステートメントおよび他の NOT FENCED UDF と同じスレッド内で実行されるためにカーソル名が競合する場合があります。
NOT FENCED 関数は、通常 FENCED 関数よりもパフォーマンスが良好です。
- PROGRAM TYPE MAIN または PROGRAM TYPE SUB
- 他の製品との互換性を備えるために、このパラメーターが許可されています。
これは、ルーチンの外部プログラムが、プログラム (*PGM) であるか、サービス・プログラム (*SRVPGM) のプロシージャーであるかを示します。
- PROGRAM TYPE MAIN
- ルーチンがプログラムのメインエントリー・ポイントとして実行することを指定します。 外部プログラムは、*PGM オブジェクトでなければなりません。
- PROGRAM TYPE SUB
- ルーチンがサービス・プログラムのプロシージャーとして実行することを指定します。 外部プログラムは、*SRVPGM オブジェクトでなければなりません。
- NO FINAL CALL または FINAL CALL
- 関数の最終呼び出し を行うかどうかを指定します。
最終呼び出しによって、関数は、獲得済みのすべてのシステム・リソースを解放することができます。
最終呼び出しは、SCRATCHPAD キーワードを定義した関数でシステム・リソースを獲得し、そのシステム・リソースをスクラッチパッドに格納するときに使用できます。デフォルトは NO FINAL CALL です。
- NO FINAL CALL
- 関数に対する最終呼び出しを行わないことを指定します。 関数は、 呼び出しのタイプを指定する追加の引数を受け取りません。
- FINAL CALL
- 関数に対する最終呼び出しを行うことを指定します。
この関数は、最終呼び出しとその他の呼び出しを区別するために、呼び出しの
タイプを示す追加の引数を受け取ります。
FINAL CALL は、PARAMETER STYLE SQL または PARAMETER STYLE DB2GENERAL でのみ許可されます。
呼び出しには以下のタイプがあります。
- First Call (初回呼び出し)
- この SQL ステートメントでの関数に対するこの参照について の、関数に対する初回呼び出しを示します。初回呼び出しは通常呼び出しです。 SQL 引数が渡され、関数は結果を戻すものと見なされます。
- Normal Call (通常呼び出し)
- SQL 引数が渡され、関数が結果を戻すことを指定します。
- Final Call (最終呼び出し)
- この関数に対する最後の呼び出しであり、これにより関数はリソースを解放できることを指定します。
最終呼び出しは通常呼び出しではありません。
エラーが起きた場合は、データベース・マネージャーは最終呼び出しを行おうとします。
最終呼び出しが発生するのは以下の場合です。
- ステートメントの終わり : カーソル指向 ステートメント用のカーソルがクローズされたとき、またはステートメントの実行が完了したとき。
- 並列タスクの終わり : 並列タスクにより 関数が実行されたとき。
- トランザクションの終わり : ステートメント 処理の正常終了が発生しなかったとき。 例えば、何らかの理由によりアプリケーションのロジックがカーソルのクローズをバイパスした場合。
最終呼び出しを使用する関数には、 並列タスクが関数を実行した場合に誤った結果を受け取るものもあります。 例えば、関数が最終呼び出しごとに注釈を送信する場合、各関数ごとにではなく、 各並列タスクごとに 1 つの注釈が送信されます。 並列して実行した場合に正しく動作しない関数には、DISALLOW PARALLEL 文節を指定してください。
WITH HOLD として定義されているカーソルがオープン状態にあるときに コミット操作が発生した場合は、カーソルがクローズされるか アプリケーションが終了した時点で、最終呼び出しが行われます。 並列タスクの終わりにコミットが発生した場合は、WITH HOLD として定義されて いるカーソルがオープン状態にあってもなくても、最終呼び出しが行われます。
FINAL CALL ではコミット可能な操作は行ってはなりません。FINAL CALL は、COMMIT 操作の一部として呼び出されたクローズ中に実行される可能性があるからです。
- ALLOW PARALLEL または DISALLOW PARALLEL
- 関数を並列で実行できるかどうかを指定します。
NOT DETERMINISTIC、EXTERNAL ACTION、FINAL CALL、MODIFIES SQL DATA、SCRATCHPAD のいずれか 1 つ以上の文節を指定すると、デフォルトは DISALLOW PARALLEL になります。それ以外の場合は、ALLOW PARALLEL がデフォルトです。
- ALLOW PARALLEL
- データベース・マネージャーが関数の並列処理を考慮できることを指定します。データベース・マネージャーは、この関数を呼び出す SQL ステートメントまたはこの関数の中で実行する SQL ステートメントで並列処理を使用しなければならない、というわけではありません。
ALLOW PARALLEL の指定に関する注意点については、NOT DETERMINISTIC、EXTERNAL ACTION、MODIFIES SQL DATA、SCRATCHPAD、FINAL CALL の説明を参照してください。
- DISALLOW PARALLEL
- データベース・マネージャーが関数の並列処理を使用してはならないことを指定します。
- NO SCRATCHPAD または SCRATCHPAD
- 関数に、静的メモリー域が必要か否かを指定します。
- NO SCRATCHPAD
- これを指定すると、関数では、持続メモリー域を必要としなくなります。
- SCRATCHPAD integer
- これを指定すると、関数には、持続メモリー域の長さ整数が必要となります。
この整数に指定できる範囲は、1 から 16,000,000 です。
メモリー域を指定しなかった場合、その区域のサイズは 100 バイトになります。
パラメーター・スタイル SQL を指定すると、ポインターは、静的ストレージを指す必須パラメーターに続いて渡されます。ALLOW PARALLEL を指定すると、メモリー域は、ステートメント内のそれぞれのユーザー定義の関数参照に割り振られます。DISALLOW PARALLEL を指定すると、1 つのメモリー域だけが関数に割り振られます。
スクラッチパッドの有効範囲は SQL です。SQL ステートメント内の関数の参照ごとに、1 つのスクラッチパッドが存在します。 例えば、関数 UDFX が SCRATCHPAD キーワードによって定義されていると想定した場合、次の SQL ステートメント内では、UDFX の 3 つの参照に対して 3 つのスクラッチパッドが割り振られます。
関数が並列タスクのもとで実行されている場合、SQL ステートメント内の関数のそれぞれの参照の並列タスクごとに、1 つのスクラッチパッドが割り振られます。 これによって、予測不能の結果が生じる可能性があります。 例えば、関数で、呼び出される回数をカウントするためにスクラッチパッドを使用した場合、そのカウントは、SQL ステートメントではなく、並列タスクによって行われた呼び出し回数を反映します。 並列性を使用して正しく動作しない関数には、DISALLOW PARALLEL 文節を指定してください。SELECT A, UDFX(A) FROM TABLEB WHERE UDFX(A) > 103 OR UDFX(A) < 19SCRATCHPAD は、PARAMETER STYLE SQL または PARAMETER STYLE DB2GENERAL でのみ許可されます。
- EXTERNAL
- CREATE FUNCTION ステートメントを使用して、外部プログラミング言語によるコードに基づいた新規関数を定義するように指定します。
外部プログラム名 の指定がない場合、 外部プログラム名は該当の関数名と同じであると見なされます。
- NAME external-program-name
- SQL ステートメント内でこの関数が呼び出されたときに実行するプログラム、サービス・プログラム、または Java クラスを指定します。この名前は、関数が呼び出される時点でアプリケーション・サーバー上に存在しているプログラム、サービス・プログラム、または Java クラスを示すものでなければなりません。命名オプションが *SYS であり、その名前が修飾されていない場合:
- 関数の呼び出し時に、現行パスを使用して該当のプログラムを検索します。
- COMMENT、GRANT、LABEL、REVOKE の各操作をその関数で実行する時点で、*LIBL を使用して対象のプログラムまたはサービス・プログラムを検索します。
この名前の妥当性は、アプリケーション・サーバーで検査されます。名前の形式が正しくない場合、エラーが戻されます。
このプログラム、サービス・プログラム、または Java クラスは、関数の作成時に存在している必要はありませんが、関数の呼び出し時には存在している必要があります。
CONNECT、SET CONNECTION、RELEASE、DISCONNECT、COMMIT、ROLLBACK および SET TRANSACTION ステートメントは、関数の外部プログラム内で使用することはできません。
- NOT SECURED または SECURED
- 関数が行アクセス制御と列アクセス制御においてセキュアであると見なされるかどうかを指定します。
- NOT SECURED
- 関数が行アクセス制御と列アクセス制御において非セキュアであると見なされることを 指定します。これはデフォルトです。
- 表でアクティブな列アクセス制御が使用されている場合、関数の呼び出し時に、関数の引数が、列マスクが有効になっている列を参照してはなりません。
- SECURED
- 関数が行アクセス制御と列アクセス制御においてセキュアであると見なされることを指定します。このオプション は、C、C++、ILE RPG、ILE COBOL、ILE CL、または Java で作成された外部関数に対して使用できます。プログラム またはサービス・プログラムは、CREATE FUNCTION ステートメントが実行されるときに存在していなければなりません。
- 関数は、行の許可または列マスク内で参照される場合は、セキュアとして定義される 必要があります。
- SET OPTION-statement
- パラメーター・デフォルトに使用されるオプションを指定します。
各オプションのデフォルト値は、作成時に有効だったオプションによって異なります。詳しくは、SET OPTIONを参照してください。
デフォルト値式を処理するときには、 オプション ALWCPYDTA、CONACC、DATFMT、DATSEP、DECFLTRND、DECMPT、
DECRESULT、DFTRDBCOL、 LANGID、SQLCURRULE、SQLPATH、SRTSEQ、TGTRLS、TIMFMT、および TIMSEP が使用されます。オプション CNULRQD、CNULIGN、COMPILEOPT、EXTIND、NAMING、SQLCA は、CREATE FUNCTIONステートメントでは使用できません。 他のオプションは、受け入れられますが、無視されます。
注
ユーザー定義関数の定義に関する一般考慮事項: ユーザー定義関数の定義に関する一般情報については、CREATE FUNCTIONを参照してください。
- 既存のコメントまたはラベルは破棄されます。
- 別の外部プログラムを指定する場合、
- 権限を持つユーザーは新しいプログラムにコピーされません。
- ジャーナル監査は変更されません。
- 上記以外の場合、
- 権限を持つユーザーは維持されます。オブジェクト所有者は変更されない可能性があります。
- 現在のジャーナル監査は変更されません。
関数の作成: ILE 外部プログラムまたはサービス・プログラムに関連した 外部関数が作成されると、その関数に関連したプログラムやサービス・プログラムのオブジェクトへの 関数属性の保管が試行されます。 *PGM または *SRVPGM オブジェクトが保管された後、このシステムまたは別のシステムに 復元されると、属性が使用されてカタログが更新されます。
外部関数の場合は、次の制約の範囲内で属性を保管することができます。
- 外部プログラム・ライブラリーは、QSYS であってはなりません。
- 外部プログラムは、CREATE FUNCTION ステートメントの発行時に存在していなければなりません。
システム命名が指定され、外部プログラム名が修飾されない場合は、外部プログラムはライブラリー・リストで検出されなければなりません。
- 外部プログラムは、ILE *PGM オブジェクトか *SRVPGM オブジェクトにする必要があります。
- 外部プログラムには、32 ルーチンの属性が既に入っていてはなりません。
オブジェクトを更新できない場合でも、関数は作成されます。
関数の呼び出し: 外部関数が呼び出されると、その関数は、 外部プログラムやサービス・プログラムの作成時に指定された活動化グループであれば、 どの活動化グループ内でも実行します。 ただし、通常は、関数が呼び出し側プログラムと同じ活動化グループ内で実行するように ACTGRP(*CALLER) を使用します。 ACTGRP(*NEW) は使用できません。
LANGUAGE JAVA の関数は、常にデフォルトの活動化グループ (*DFTACTGRP) で実行されます。したがって、MODIFIES SQL DATA Java 関数を作成するときには、注意が必要です。その Java 関数による変更は、デフォルトの活動化グループで実行されるので、呼び出し側が新しい活動化グループ (*NEW) で実行されていると、トランザクションの問題が発生する可能性があります。
Java 関数に関する注釈: Java 関数を実行するためには、システムに IBM IBM Developer Kit for Java (5770-JV1) をインストールしておく必要があります。インストールされていないと、SQLCODE -443 が戻され、CPDB521 メッセージがジョブ・ログに入ります。
Java 関数の実行中にエラーが発生すると、SQLCODE -443 が戻されます。 エラーによっては、関数が実行されていたジョブのジョブ・ログに他のメッセージが入っている場合があります。
代替構文: 以下のキーワードは、旧リリースとの互換性を維持するためにサポートされている同義語です。 これらのキーワードは標準キーワードではないので、原則として使用しないようにしてください。
- キーワード VARIANT と NOT VARIANT は、NOT DETERMINISTIC と DETERMINISTIC の同義語として使用することができます。
- キーワード NULL CALL と NOT NULL CALL は、CALLED ON NULL INPUT と RETURNS NULL ON NULL INPUT の 同義語として使用できます。
- キーワード SIMPLE CALL は、GENERAL の同義語として使用できます。
- DB2GENERAL の同義語として、キーワード DB2GENRL を使用できます。
- SQL の同義語として、値 DB2SQL を使用できます。
- PARAMETER STYLE 文節のキーワード PARAMETER STYLE はオプションです。
- DETERMINISTIC の同義語として、キーワード IS DETERMINISTIC を使用できます。
例
例 1: C で書かれた外部関数プログラムが以下のロジックをインプリメントする必要があるとします:
rslt = 2 * input - 4入力引数の 1 つが NULL である場合にのみ、関数は NULL 値を戻す必要があります。 関数呼び出しを回避し、入力値が NULL の場合に NULL の結果を得るための最も簡単な方法は、CREATE FUNCTION ステートメント上に RETURNS NULL ON NULL INPUT と指定することです。 以下のステートメントは特定名 MINENULL1 を使用して、関数を定義します。
CREATE FUNCTION NTEST1 (SMALLINT)
RETURNS SMALLINT
EXTERNAL NAME NTESTMOD
SPECIFIC MINENULL1
LANGUAGE C
DETERMINISTIC
NO SQL
FENCED
PARAMETER STYLE SQL
RETURNS NULL ON NULL INPUT
NO EXTERNAL ACTIONプログラム・コードは次のとおりです。
void nudft1
(int *input, /* ptr to input argument */
int *output, /* ptr to output argument */
short *input_ind, /* ptr to input indicator */
short *output_ind, /* ptr to output indicator */
char sqlstate[6], /* sqlstate */
char fname[140], /* fully qualified function name */
char finst[129], /* function specific name */
char msgtext[71]) /* msg text buffer */
{
if (*input_ind == -1)
*output_ind = -1;
else
{
*output = 2*(*input)-4;
*output_ind = 0;
}
return;
} 例 2: ユーザーが CENTER という名前の外部関数を定義すると想定します。 関数プログラムは、C で作成されます。以下のステートメントは関数を定義し、データベース・マネージャーが関数の特定名を生成できるようにします。 関数本体を含むプログラムの名前は、関数の名前と同一であるため、EXTERNAL 文節には「NAME external-program-name」は含まれません。
CREATE FUNCTION CENTER (INTEGER, FLOAT)
RETURNS FLOAT
LANGUAGE C
DETERMINISTIC
NO SQL
PARAMETER STYLE SQL
NO EXTERNAL ACTION例 3: ユーザー McBride (データベース管理者権限を持っている) が SMITH スキーマ内に CENTER という名前の外部関数を作成すると想定します。 McBride は、この関数に特定名 FOCUS98 を指定しようとしています。 関数プログラムでは、ある種の一回限りの初期設定を実行し、結果を保管するためにスクラッチパッドを使用します。 関数プログラムでは、DOUBLE データ・タイプが指定された値を戻します。 ユーザー McBride によって書き込まれた以下のステートメントは関数を定義し、関数の呼び出し時に、DECIMAL(8,4) というデータ・タイプが指定された値が戻されるようにします。
CREATE FUNCTION SMITH.CENTER (DOUBLE, DOUBLE, DOUBLE)
RETURNS DECIMAL(8,4)
CAST FROM DOUBLE
EXTERNAL NAME CMOD
SPECIFIC FOCUS98
LANGUAGE C
DETERMINISTIC
NO SQL
FENCED
PARAMETER STYLE SQL
NO EXTERNAL ACTION
SCRATCHPAD
NO FINAL CALL例 4: 以下の例では、ストリング内の最初の母音の位置を戻す Java ユーザー定義関数を定義します。 ユーザー定義関数は Java で書かれており、隔離して実行されるクラス JAVAUDFS の FINDVWL メソッドです。
CREATE FUNCTION FINDV (VARCHAR(32000))
RETURNS INTEGER
FENCED
LANGUAGE JAVA
PARAMETER STYLE JAVA
EXTERNAL NAME 'JAVAUDFS.FINDVWL'
NO EXTERNAL ACTION
CALLED ON NULL INPUT
DETERMINISTIC
NO SQL