CREATE FUNCTION (外部表)
CREATE FUNCTION (外部表) ステートメントは、現行サーバー上に外部表関数を定義します。この外部表関数は、結果表を戻します。
外部ユーザー定義表関数 を副選択の FROM 文節の中で使用できます。この表関数は、呼び出しのたびに 1 行ずつを返すことによって、表を副選択に返します。
呼び出し
このステートメントは、アプリケーション・プログラムに組み込むことも、 あるいは対話式に実行することもできます。 これは、動的に準備できる実行可能ステートメントです。
権限
このステートメントの権限 ID が保持する特権には、少なくとも以下の 1 つ が含まれていなければなりません。
- SYSFUNCS カタログ・ビューと SYSPARMS カタログ表の場合
- 該当の表に対する 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-+-' .-,---------------------------------------. V | >--RETURNS TABLE--(----column-name--data-type2--+------------+-+--)--> '-AS LOCATOR-' >--option-list--+----------------------+----------------------->< '-SET OPTION-statement-'
- XML の ccsid-clause は、data-type2 でのみ使用できます。
- この文節とこの後の 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 パス上のスキーマを検索することでそのスキーマ名を解決します。
PARAMETER STYLE JAVA を指定する場合は、ラージ・オブジェクト (LOB) データ・タイプのパラメーターはサポートされません。
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 TABLE
- この関数の出力が表であることを指定します。この文節の後に、結果表の列の名前とデータ・タイプのリストを括弧で囲んで記述します。
結果列の最大数は、言語のタイプによって異なります。 パラメーターの数が N であるとします。
- JAVA と ILE プログラムおよびサービス・プログラムの場合、列の数は 8000-N 以下でなければなりません。
- OPM プログラムの場合、列の数は 125 - N 以下でなければなりません。
- column-name
- 出力表の列の名前を指定します。 同じ名前を何度も指定することはできません。
- data-type2
- 列のデータ・タイプを指定します。列はNULL 可能です。
あらゆる組み込みデータ・タイプ (ただし、LONG VARCHAR、LONG VARGRAPHIC、または DataLink は除く) や特殊タイプ (データ・リンクをベースとしていない) を指定することができます。配列タイプを指定することはできません。
DATE または TIME を指定した場合は、表関数は ISO 形式の日付または 時刻を戻す必要があります。
CCSID が指定されている場合
- AS LOCATOR が指定されていない場合、戻される結果はその CCSID で コード化されていると想定されます。
- AS LOCATOR が指定され、ロケーターが指しているデータの CCSID が異なる CCSID でコード化されている場合、データは指定された CCSID に変換され ます。
CCSID が指定されていない場合
- AS LOCATOR が指定されていない場合、戻される結果は、ジョブの CCSID (グ ラフィック・ストリング戻り値の場合は、ジョブに関連したグラフィック 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 を指定する』を参照してください。
- LANGUAGE
- 言語文節は、外部プログラムの言語を指定します。
LANGUAGE を指定しなかった場合、その LANGUAGE は、関数の作成時に、外部プログラムと関連したプログラム属性情報から決定されます。 次の場合、プログラムの言語は C であると想定されます。
- プログラムに関連したプログラム属性情報で、認識可能な言語を識別しない。
- プログラムが見つからない。
- C
- 外部プログラムは C で作成されます。
- C++
- 外部プログラムは C++ で作成されます。
- CL
- 外部プログラムは CL または ILE CL で作成されます。
- COBOL
- 外部プログラムは COBOL で作成されます。
- COBOLLE
- 外部プログラムは ILE COBOL で作成されます。
- JAVA
- 外部プログラムは JAVA で作成されます。データベース・マネージャーは 、ユーザー定義関数を、Java™ クラス内のメソッドとして呼び出します。
- PLI
- 外部プログラムは PL/I で作成されます。
- RPG
- 外部プログラムは RPG で作成されます。
- RPGLE
- 外部プログラムは ILE RPG で作成されます。
- PARAMETER STYLE
- 関数にパラメーターを渡し、関数から値を戻すために使用する規則を指定します。
- DB2GENERAL
- このパラメーター・スタイルは、Java クラスでメソッドとして定義されている外部関数にパラメーターを渡し、外部関数から値を戻すための規則を指定するのに使用します。適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指 定される入力パラメーターです。
- その後の M 個のパラメーターは、RETURNS TABLE 文節に指定されて いる、この関数の結果列です。
DB2GENERAL は、LANGUAGE が JAVA の場合にのみ許されます。
- SQL
- 適用可能なパラメーターはすべて渡されます。これらのパラメーターは、次の順序で配列されるように定義されます。
- 最初の N 個のパラメーターは、CREATE FUNCTION ステートメント上に指定される入力パラメーターです。
- その後の M 個のパラメーターは、RETURNS TABLE 文節に指定されて いる、この関数の結果列です。
- 入力パラメーターの標識変数を表す N 個のパラメーター。
- RETURNS TABLE 文節に指定されているこの関数の結果列の標識変数を表す M 個のパラメーター。
- SQLSTATE の CHAR(5) 出力パラメーター。戻される SQLSTATE は、関数
が成功したかどうかを示します。戻される SQLSTATE は、以下のいずれかです。
- 外部プログラムで実行された最後の SQL ステートメントからの SQLSTATE
- 外部プログラムによって割り当てられた SQLSTATE
ユーザーは、関数からエラーまたは警告を戻すために、外部プログラム 内で SQLSTATE を任意の有効な値にセットすることができます。
- 完全修飾関数名の VARCHAR(517) 入力パラメーター。
- 特定の名前の VARCHAR(128) 入力パラメーター。
- メッセージ・テキストの VARCHAR(1000) 出力パラメーター。
- CREATE FUNCTION ステートメントで SCRATCHPAD を指定した場合 、スクラッチパッドの構造 (後に CHAR(n) が続く INTEGER からなる) 入出力パラメーター。
- 呼び出しタイプを示す INTEGER 入力パラメーター。
- CREATE FUNCTION ステートメントで DBINFO を指定した場合、dbinfo 構造体の構造。
パラメーターを渡す方法は、外部関数の言語によって決まります。例えば、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 ステートメントの最適化時にこの情報を使用します。表関数の結果表に影響するような方法で、特殊レジスター、非決定的な関数、シーケンスのいずれかを参照する表関数は、非決定的な表関数の例です。
- GLOBAL DETERMINISTIC
- 関数が同じ入力引数を指定して呼び出されるたびに、その関数が常に同じ結果表を戻すかを指定します。データベース・マネージャーは、SQL ステートメントの最適化時にこの情報を使用します。照会オプティマイザーは、 グローバル deterministic な関数の結果をキャッシュに入れるよう選択することができます。
- STATEMENT DETERMINISTIC
- 関数が同じ入力引数を使用して呼び出されるたびに、同じ結果を戻さない可能性があるが、単一 SQL ステートメント内での関数の複数の呼び出しは、deterministic と見なされることを指定します。 照会オプティマイザーは、ステートメント deterministic な関数の結果をキャッシュに入れません。1
- 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 NULL INPUT
- 入力引数のいずれかがヌルである場合に関数を呼び出さないことを指定します。結果は、表に行がない、空表になります。
- CALLED ON NULL INPUT
- 引数値のいずれかがヌルである場合に関数を呼び出すことを指定します。この指定は、ヌル引数値のテストを行うように関数をコーディングする必要があります。関数は、その論理に よっては、空の表を戻す場合があります。
- INHERIT SPECIAL REGISTERS
- 特殊レジスターの既存の値は、関数に入った後に継承されることを指定します。
- STATIC DISPATCH
- 関数を静的にディスパッチすることを指定します。 すべての関数が静的にディスパッチされます。
- NO DBINFO または DBINFO
- 関数を呼び出すときに、追加の状況情報を渡すかどうかを指定します。デフォルトは NO DBINFO です。
- NO DBINFO
- 補足情報を渡さないことを指定します。
- DBINFO
- データベース・マネージャーは、状況情報が入っている
構造体を関数に渡す必要があることを指定します。 表 1 は、DBINFO 構造体の説明を示しています。
DBINFO 構造体についての詳しい情報は、ライブラリー QSYSINC 内の該当するソース・ファイルの sqludf に入っています。
例えば、C の場合、sqludf は QSYSINC/H で見つかります。
表 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 サーバーのプラットフォーム・タイプ。 表関数の列リスト項目の数。 SMALLINT 下記の「表関数の列リスト」フィールドに指定されている表関数列 リスト内のゼロでない項目の数。 予約済み CHAR(24) 将来の利用のため予約済み。 表関数の列リスト ポインター (16 バイト) このフィールドは、データベース・マネージャーが動的に割り振る短整数の配列を指すポインターです。「表関数の列リスト項目の数」フィールドに n を指定した場合、最初の n 個 の項目のみが対象になります。n は、0 またはそれより大きく、この関数 の RETURNS TABLE 文節で定義した結果列の数と同じかまたはそれより小さい値です。 個々の値は、このステートメントが表関数から取得する必要がある列の 順序番号に対応しています。 つまり、1 の値は最初に定義された結果列を意味し、2 は 2 番目に定義 された結果列を意味します (以下同様)。 これらの値はどのような順序になっていても構いません。 SELECT COUNT(*) FROM TABLE(TF(...)) AS QQ のように、実際の列値 を必要としない照会を指定するステートメントの場合は、n はゼロになる ことがあるという点に注意してください。 この配列により最適化が可能になる場合があります。 それは、この関数が、表関数のすべての結果列のすべての値を戻す必要 がなくなるからです。 特定のコンテキストでは一部の値しか必要とされないことがあり、配列内で 番号により識別されている列がこれらの値に相当します。 この最適化により関数ロジックが複雑になることもあるので、定義されてい るすべての列を戻すことを選択することもできます。
- 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
- 関数に対する独立した最初の呼び出し と最終呼び出し を行うかどうかを指定します。 呼び出しのタイプを区別するために、関数は呼び出しのタイプを指定する追加引数を受け取ります。表関数の場合は、FINAL CALL と NO FINAL CALL のどちらが有効になっているかにかかわりなく、call-type 引数が常に存在します。その引数では、初回呼び出し、オープン呼び出し、フェッチ呼び出し、クローズ呼び出し、最終呼び出しのいずれかを指定します。
NO FINAL CALL の場合、データベース・マネージャーは、表関数に対して、オープン、フェッチ、クローズの 3 つのタイプの呼び出しだけを実行します。しかし、FINAL CALL が指定されている場合は、 オープン、取り出しおよびクローズに加えて、 表関数に対して最初の呼び出しと最終呼び出しを行うことができます。
最終呼び出しによって、関数は、獲得済みのすべてのシステム・リソースを解放することができます。 最終呼び出しは、SCRATCHPAD キーワードを定義した関数でシステム・リソースを獲得し、そのシステム・リソースをスクラッチパッドに格納するときに使用できます。デフォルトは NO FINAL CALL です。
- NO FINAL CALL
- 関数に対して独立した初回呼び出しと最終呼び出しを実行しない、という動作を指定します。ただし、関数に対して、オープン呼び出し、フェッチ呼び出し、クローズ呼び出しは実行します。さらに、表関数は、呼び出しのタイプを指定した追加の引数を常に受け取ります。
- FINAL CALL
- 関数に対して独立した初回呼び出しと最終呼び出しを実行する、という動作を指定します。これは、スクラッチパッドをどの時点で再初期化するかも制御します。
呼び出しには以下のタイプがあります。
- First Call (初回呼び出し)
- この SQL ステートメントでの関数に対するこの参照について の、関数に対する初回呼び出しを示します。
- Open Call (オープン呼び出し)
- この SQL での表関数結果をオープンするための呼び出しを指定します。
- Fetch Call (フェッチ呼び出し)
- この SQL ステートメントで表関数から行をフェッチするための呼び出しを指定します。
- Close Call (クローズ呼び出し)
- この SQL での表関数結果をクローズするための呼び出しを指定します。
- Final Call (最終呼び出し)
- この関数に対する最後の呼び出しであり、これにより関数はリソースを解放できることを指定します。
エラーが起きた場合は、データベース・マネージャーは最終呼び出しを行おうとします。
最終呼び出しが発生するのは以下の場合です。
- ステートメントの終わり : カーソル指向 ステートメント用のカーソルがクローズされたとき、またはステートメントの実行が完了したとき。
- トランザクションの終わり : ステートメント 処理の正常終了が発生しなかったとき。 例えば、何らかの理由によりアプリケーションのロジックがカーソルのクローズをバイパスした場合。
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 を指定すると、ポインターは、静的ストレージを指す必須パラメーターに続いて渡されます。
この関数には、メモリー域が 1 つだけ割り振られます。
スクラッチパッドの有効範囲は SQL です。SQL ステートメント内の関数の参照ごとに、1 つのスクラッチパッドが存在します。 例えば、関数 UDFX が SCRATCHPAD キーワードによって定義されていると想定した場合、次の SQL ステートメント内では、UDFX の 2 つの参照に対して 2 つのスクラッチパッドが割り振られます。
SELECT A.C1, B.C1 FROM TABLE(UDFX(:hv1)) AS A, TABLE(UDFX(:hv1)) AS B
- 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 ステートメントは、関数の外部プログラム内で使用することはできません。
- CARDINALITY bigint
- この関数が戻すものとして予期される行数の見積もりを指定します。この見積もりは、データベース・マネージャーが最適化を行う際に使用されます。
bigint は、
0 から 9 223 372 036 854 775 807 までの範囲内でなければなりません。
データベース・マネージャーは、CARDINALITY が指定されていない場合は有限値を想定します。
呼び出されるたびに行を戻して表終了状態を戻すことのない表関数は、無限カーディナリティーを持ちます。 データを戻す前に結果としての表終了状態を必要とする照会がこのような関数を呼び出すと、その照会は中断しない限り戻りません。 表終了状態を戻すことのない表関数を、DISTINCT、GROUP BY、または ORDER BY を伴う照会で使用すべきではありません。
- NOT SECURED または SECURED
- 関数が行アクセス制御と列アクセス制御においてセキュアであると見なされるかどうかを指定します。
- NOT SECURED
- 関数が行アクセス制御と列アクセス制御において非セキュアであると見なされることを 指定します。これはデフォルトです。
- 表でアクティブな列アクセス制御が使用されている場合、関数の呼び出し時に、関数の引数が、列マスクが有効になっている列を参照してはなりません。
- SECURED
- 関数が行アクセス制御と列アクセス制御においてセキュアであると見なされることを指定します。このオプション は、C、C++、ILE RPG、ILE COBOL、ILE CL、または Java で作成された外部関数に対して使用できます。プログラム またはサービス・プログラムは、CREATE FUNCTION ステートメントが実行されるときに存在していなければなりません。
- 関数は、行の許可または列マスク内で参照される場合は、セキュアとして定義される 必要があります。
- SET OPTION-statement
- パラメーター・デフォルトに使用されるオプションを指定します。各オプションのデフォルト値は、作成時に有効だったオプションによって異なります。詳しくは、SET OPTIONを参照してください。
デフォルト値式を処理するときには、 オプション ALWCPYCTA、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 オブジェクトが保管された後、このシステムまたは別のシステムに 復元されると、属性が使用されてカタログが更新されます。
外部関数の場合は、次の制約の範囲内で属性を保管することができます。
- 外部プログラム・ライブラリーは、SYSIBM、QSYS、または QSYS2 であってはなりません。
- 外部プログラムは、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 の 同義語として使用できます。
- DB2GENERAL の同義語として、値 DB2GENRL を使用できます。
- PARAMETER STYLE 文節のキーワード PARAMETER STYLE はオプションです。
- DETERMINISTIC の同義語として、キーワード IS DETERMINISTIC を使用できます。
- PARAMETER STYLE SQL の同義語として、キーワード PARAMETER STYLE DB2SQL を使用できます。
例
以下の例で作成する表関数は、テキスト管理システム内にある既知の各文書 を示す単一の文書 ID 列が入った行を 1 つずつ戻します。 最初のパラメーターは特定のサブジェクト・エリアに対応し、2 番目の パラメーターには特定のストリングが入ります。
単一セッションのコンテキストでは、この UDF は常に同じ表を戻す ので、DETERMINISTIC として定義されています。 RETURNS 文節が DOCMATCH からの出力を定義している点に注意してください。 各表関数について、FINAL CALL を指定する必要があります。 DOCMATCH の場合の出力のサイズは大きく変化しますが、代表的な値 は CARDINALITY 20 なので、最適化プログラムを支援するためにこの値が指定されています。
CREATE FUNCTION DOCMATCH (VARCHAR(30), VARCHAR(255))
RETURNS TABLE (DOCID CHAR(16))
EXTERNAL NAME 'MYLIB/RAJIV(UDFMATCH)'
LANGUAGE C
PARAMETER STYLE SQL
NO SQL
DETERMINISTIC
NO EXTERNAL ACTION
NOT FENCED
SCRATCHPAD
FINAL CALL
DISALLOW PARALLEL
CARDINALITY 20