CREATE FUNCTION (ソース派生)
この CREATE FUNCTION (ソース化された) ステートメントは、現行サーバーで、他の既存のスカラー関数または集約関数に基づいてユーザー定義の関数を定義します。
呼び出し
このステートメントは、アプリケーション・プログラムに組み込むことができ、また対話式に呼び出すこともできます。 これは、動的に準備できる実行可能ステートメントです。
権限
このステートメントの権限 ID が保持する特権には、少なくとも以下の 1 つ が含まれていなければなりません。
- スキーマ内に作成する特権。詳しくは、スキーマ内で作成する必要のある権限を参照してください。
- データベース管理者権限
このステートメントの権限 ID が保持する特権には、少なくとも以下の 1 つ が含まれていなければなりません。
- SYSFUNCS カタログ・ビューと SYSPARMS カタログ表の場合
- 該当の表に対する INSERT 特権、および
- QSYS2 ライブラリーに対する *EXECUTE システム権限
- データベース管理者権限
ソース関数がユーザー定義の関数である場合は、そのソース関数に対して、このステートメントの権限 ID に、少なくとも次のいずれか 1 つを含める必要があります。
- その関数に対する EXECUTE 特権
- データベース管理者権限
ソース化関数を作成するには、ステートメントの権限 ID が保持する特権に、少なくとも次のいずれか 1 つを含める必要があります。
- 次のシステム権限
- サービス・プログラム作成 (CRTSRVPGM) コマンドに対する *USE
- プログラム作成 (CRTPGM) コマンドに対する *USE
- データベース管理者権限
SQL 名が指定され、関数が作成されるライブラリーと同じ名前のユーザー・プロファイルが存在し、しかも、その名前がステートメントの権限 ID と異なっている場合、ステートメントの権限 ID が保持している特権には、少なくとも次のいずれか 1 つを含める必要があります。
- その名前を持つユーザー・プロファイルに対する *ADD システム権限
- データベース管理者権限
特殊タイプを参照する場合は、ステートメントの権限 ID によって保持される 特権に、少なくとも次のいずれか 1 つが含まれなければなりません。
- ステートメント内で識別された、それぞれの特殊タイプごとに、
- その特殊タイプに対する USAGE 特権、および
- その特殊タイプを含むライブラリーに対する *EXECUTE システム権限
- データベース管理者権限
SQL 特権に対応するシステム権限の説明については、『表またはビューへの権限を検査する際の対応するシステム権限』、『関数またはプロシージャーへの権限を検査する際の対応するシステム権限』、および『特殊タイプへの権限を検査する際の対応するシステム権限』を参照してください。
構文
>>-CREATE--FUNCTION--function-name------------------------------> >--(--+---------------------------+--)--------------------------> | .-,---------------------. | | V | | '---parameter-declaration-+-' (1) >--RETURNS--data-type2--+------------+--------------------------> '-AS LOCATOR-' >--+-----------------------------------+------------------------> '-SPECIFIC--qualified-specific-name-' >--SOURCE--+-function-name--+------------------------------+-+--> | '-(--+--------------------+--)-' | | | .-,--------------. | | | | V | | | | '---parameter-type-+-' | '-SPECIFIC--qualified-specific-name---------------' >--+--------------------+-------------------------------------->< '-SET OPTION ステートメント-' parameter-declaration |--+----------------+--data-type1--+------------+--+----------------+--| '-parameter-name-' '-AS LOCATOR-' '-default-clause-' data-type1, data-type2, data-type3 |--+-built-in-type------+---------------------------------------| '-distinct-type-name-'
- RETURNS、SPECIFIC、および SOURCE 文節は、どのような順序で指定しても構いません。
説明
- function-name
- ユーザー定義の関数の名前を指定します。名前、スキーマ名、パラメ
ーターの数、およびそれぞれのパラメーターのデータ・タイプ (データ・タ
イプの長さ、精度、位取り、または CCSID の属性に関係なく) の組み合わせ
で、現行サーバー上に存在しているユーザー定義の関数を識別してはなりません。
SQL 命名の場合、関数は、暗黙または明示修飾子で指定されたスキーマ内に作成されます。
システム命名の場合、関数は、修飾子で指定されたスキーマ内に作成されます。 修飾子を指定しなかった場合:
- CURRENT SCHEMA 特殊レジスターの値が *LIBL である場合、関数は、現行ライブラリー (*CURLIB) 内に作成されます。
- そうでない場合、関数は現行スキーマ内に作成されます。
特殊タイプを指定した既存関数の使用を可能にするために、関数がその既存 関数をソースとして作成される場合、その名前は、その既存関数と同じ名前 にすることができます。通常、それぞれの関数の関数シグニチャーが固有であれば、複数の関数に同じ名前を指定することができます。
一部の関数名は、システムが使用するために予約されています。 詳しくは、CREATE FUNCTIONの『スキーマおよび関数名の選択』を参照してください。
- (parameter-declaration,...)
- 関数の入力パラメーターの数とそれぞれのパラメーターのデータ・タイプを指定します。
各 parameter-declaration は、関数の入力パラメーターを指定します。
最大
2000
のパラメーターを指定することができます。関数は、ゼロまたはそれ以上の入力パラメーターを持つことができます。関数が受け取ると予期しているパラメーターには、それぞれリスト内に 1 個の項目が必要です。関数のパラメーターはすべて入力パラメーターで、ヌル可能です。JAVA の場合は、DECIMAL タイプと NUMERIC タイプ以外の数値パラメーターがヌル可能です。CALLED ON NULL INPUT 関数でそのようなパラメーターの入力がヌル値になると、実行時エラーになります。詳しくは、CREATE FUNCTIONの『パラメーターの定義』を参照してください。
- parameter-name
- パラメーター名を指定します。必須ではありませんが、各パラメーターにパラメーター名を指定することができます。 この名前は、パラメーター・リスト内の他のパラメーター名 と同じものであってはなりません。
- data-type1
- パラメーターのデータ・タイプを指定します。
このデータ・タイプは、組み込みデータ・タイプまたは特殊データ・タイプにすることができます。この変数は、配列タイプにすることはできません。
SOURCE 文節で指定された関数の対応するパラメーターのタイプにキャスト可能であれば、任意の有効な SQL データ・タイプを使用できます (詳細は、データ・タイプ間のキャストを参照してください)。ただし、この検査は関数の呼び出し時にエラーが発生しないことを保証するものではありません。 詳しくは、『ソース化されたユーザー定義関数の呼び出しに関する考慮事項』を参照してください。
- built-in-type
- 入力パラメーターのデータ・タイプは組み込みデータ・タイプです。 それぞれの組み込みデータの詳細については、CREATE TABLEを参照してください。
- distinct-type-name
- 入力パラメーターのデータ・タイプは特殊タイプです。
パラメーターの長さ、精度、または位取り属性は、
特殊タイプのソース・タイプの属性 (CREATE TYPE で指定された属性) と同じになります。詳しくは、CREATE TYPE (特殊)を参照してください。
スキーマ名なしの特殊タイプを指定すると、データベース・マネージャーは、 SQL パス上のスキーマを検索することでそのスキーマ名を解決します。
外部関数にソース化された関数には、データ・リンクは使用できません。
CCSID が指定されている場合、関数に渡される前に、パラメーターはその CCSID に変換されます。CCSID が指定されていない場合は、CCSID は、関数 の呼び出し時点における現行サーバーのデフォルトの CCSID によって決まり ます。
- AS LOCATOR
- これを指定すると、入力パラメーターは、実際の値ではなく、値のロケーターになります。
AS LOCATOR は、入力パラメーターに LOB データ・タイプや LOB データ・タイプをベースとする特殊タイプが指定されている場合にのみ、
指定することができます。
AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- default-clause
- パラメーターのデフォルト値を指定します。デフォルト値は、定数、特殊レジスター、グローバル変数、式、またはキーワード NULL にすることができます。式は、集約関数および列名を含まない、式で
定義されている任意の式です。デフォルト値が指定されていない場合、パラメーターにデフォルト値がないため、呼び出し時に省略できません。式ストリングの
最大長は 64K です。
デフォルトの式は、 パラメーターのデータ・タイプに対して割り当ての互換性がなければなりません 。
デフォルト式内でリスト中の数値定数を区切る区切り記号として 使用するコンマの後には、スペースが 1 つ必要です。
デフォルト式の中で参照されるすべてのオブジェクト は、関数が作成されるときに存在している必要があります。
配列タイプの パラメーターにデフォルトを指定することはできません。
- RETURNS
- 関数の結果を指定します。
- data-type2
- 列のデータ・タイプを指定します。この列はNULL 可能です。可能なデータ・タイプは、組み込みデータ・タイプ (LONG VARCHAR、LONG VARGRAPHIC、DataLink を除く) または特殊タイプ (DataLink をベースとしないもの) です。 配列タイプ
にすることはできません。
ソース関数の結果タイプからキャスト可能なものであれば、有効な SQL データ・タイプを使用できます。 (データ・タイプのキャストについては、データ・タイプ間のキャストを参照してください) ただし、この検査はこの新しい関数の呼び出し時にエラーが発生しないことを保証するものではありません。 詳しくは、『ソース化されたユーザー定義関数の呼び出しに関する考慮事項』を参照してください。
- AS LOCATOR
- これを指定すると、関数は、実際の値ではなく、値のロケーターを戻します。
AS LOCATOR は、関数の出力に LOB データ・タイプや LOB データ・タイプをベースとする特殊タイプが指定されている場合にのみ、指定することができます。
AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR 文節は、SQL 関数をソースとする関数に使用することはできません。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- SPECIFIC qualified-specific-name
- 関数の固有名を指定します。特定名の詳細については、CREATE FUNCTIONの『関数に特定の名前を指定する』を参照してください。
- SOURCE
- 定義中の新規の関数がソース化関数になることを指定します。
ソース化関数 (sourced function) は、
別の関数 (ソース関数; source function) によってインプリメントされます。
関数は、現行サーバーに存在するスカラー関数または集約関数であり、次に示すいずれかのタイプの関数であることが必要です。
- CREATE FUNCTION ステートメントによって定義された関数
- CREATE TYPE ステートメントによって生成された cast 関数
- 組み込み関数
ソース関数が組み込み関数でない場合、特定の関数を識別するには、名前、関数シグニチャー、または特定名を使用できます。
ソース関数が組み込み関数である場合は、組み込み関数の関数シグニチャーを SOURCE 文節に指定する必要があります。ソース関数は、次の組み込み関数のいずれかであってはなりません (特定の構文が示されている場合は、示された形式のみが指定できません)。:- ARRAY_AGG
- 複数の引数を指定する場合の BINARY
- 複数の引数を指定する場合の BLOB
- CARDINALITY
- 複数の引数を指定する場合の CHAR
- 複数の引数を指定する場合の CLOB
- COALESCE
- CONTAINS
- DATAPARTITIONNAME
- DATAPARTITIONNUM
- 複数の引数を指定する場合の DBCLOB
- DBPARTITIONNAME
- DBPARTITIONNUM
- 複数の引数を指定する場合の DECFLOAT
- 複数の引数を指定する場合の DECIMAL
- 複数の引数を指定する場合の DECRYPT_BIN
- 複数の引数を指定する場合の DECRYPT_BINARY
- 複数の引数を指定する場合の DECRYPT_BIT
- 複数の引数を指定する場合の DECRYPT_CHAR
- 複数の引数を指定する場合の DECRYPT_DB
- EXTRACT
- 複数の引数を指定する場合の GRAPHIC
- HASH
- HASHED_VALUE
- LAND
- LOR
- MAX
- MAX_CARDINALITY
- MIN
- NODENAME
- NODENUMBER
- PARTITION
- POSITION
- RAISE_ERROR
- RID
- RRN
- SCORE
- 複数の引数が指定されている SECOND
- STRIP
- SUBSTRING
- 第 2 引数が整数である場合の TIMESTAMP
- 3 つ以上の引数が指定されている TIMESTAMP_FORMAT
- 複数の引数を指定する場合の TRANSLATE
- TRIM
- TRIM_ARRAY
- VALUE
- 複数の引数を指定する場合の VARBINARY
- 複数の引数を指定する場合の VARCHAR
- 複数の引数を指定する場合の VARGRAPHIC
- 3 つ以上の引数が指定されている VERIFY_GROUP_FOR_USER
- XMLAGG
- XMLATTRIBUTES
- XMLCOMMENT
- XMLCONCAT
- XMLDOCUMENT
- XMLELEMENT
- XMLFOREST
- XMLGROUP
- XMLNAMESPACES
- XMLPARSE
- XMLPI
- XMLROW
- XMLSERIALIZE
- XMLTEXT
- XMLVALIDATE
- XOR
- XSLTRANSFORM
- 複数の引数を指定する場合の ZONED
- function-name
- ソース関数として使用する関数を関数名で識別します。
ソース関数のパラメーターはいくつでも定義できます。指定したスキーマまたは暗黙スキーマの中に、指定した名前を使用して定義された関数が複数ある場合は、エラーが戻されます。
非修飾の関数名 が指定されている場合、SQL パスを使用して関数を探します。この名前の関数をただ 1 つ含み、ユーザーが EXECUTE 権限を持っている最初のスキーマがデータベース・マネージャーによって選択されます。関数が見つからない場合や、この名前の関数が複数存在するスキーマをデータベース・マネージャーが検出した場合は、エラーが返されます。
- function-name (parameter-type, ...)
- ソース関数として使用する関数を、関数を一意的に識別する関数シグニチャーで識別します。
function-name
(parameter-type,...) は、現行サーバーにおいて指定されたシグニチャーを持つ関数を識別する必要があります。
指定されたパラメーターは、関数の作成時に指定された、
対応する位置にあるデータ・タイプと一致していなければなりません。
関数インスタンスを識別する場合、データ・タイプの数とデータ・タイプの論理連結が使用されます。
データ・タイプの同義語は、一致として扱われます。
デフォルトがあるパラメーターは、このシグニチャーに含まれていなければなりません。
function-name() を指定する場合、識別される関数にパラメーターを使用することはできません。
組み込み関数をソース関数として使用するには、この構文のバリエーションを使用する必要があります。
- function-name
- ソース関数の名前を識別します。 非修飾名が指定されている場合、SQL パスのスキーマが検索されます。 指定しなければ、データベース・マネージャーは指定したスキーマ内で関数を検索します。
- パラメーター・タイプ,...
- 関数のパラメーターを識別します。
非修飾の特殊タイプ名を指定する場合、データベース・マネージャーはその特殊タイプのスキーマ名を解決するための SQL パスを検索します。
このコンテキストで指定する一部のデータ・タイプには、空の括弧を使用できます。長さ属性、精度属性、あるいは位取り属性があるデータ・タイプの場合、以下のいずれかの指定方法を使用します。
- 空の括弧は、データベース・マネージャーがデータ・タイプの一致の判別に際して属性を無視することを示します。例えば、DEC() は、DEC(7,2) のデータ・タイプで定義された関数のパラメーターに一致するものとみなされます。
- 長さ属性、精度属性、あるいは位取り属性に特定の値を指定した場合、 その値は、CREATE FUNCTION ステートメントの中で暗黙的または明示的に指定された値と正確に一致している必要があります。 データ・タイプが FLOAT の場合、 突き合わせはデータ・タイプ (REAL または DOUBLE) に基づいて行われるので、 精度は指定された値に厳密に一致している必要はありません。
- 長さ属性、精度属性、または位取り属性が明示的に指定されておらず、空の括弧も指定されていない場合、該当のデータ・タイプのデフォルト属性が暗黙指定されます。暗黙の長さは、CREATE FUNCTION ステートメントの中で暗黙的または明示的に指定さ れた値と正確に一致している必要があります。
サブタイプまたは CCSID 属性のあるデータ・タイプの場合は、FOR DATA 文 節または CCSID 文節の指定はオプションです。いずれの文節も指定しないと、データ・タイプが一致するかどうかを判定する場合に、データベース・マネージャーが属性を無視することを示します。 どちらか一方の文節を指定する場合は、CREATE FUNCTION ステートメントに 暗黙的または明示的に指定されている値と一致させる必要があります。
- AS LOCATOR
- 関数が、このパラメーターのロケーターを受け取るように定義されることを示します。
AS LOCATOR を指定する場合は、データ・タイプは LOB または LOB に基づく特殊タイプでなければなりません。
AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
AS LOCATOR を指定して、長さが明示的に指定された場合、データ・タイプの長さは無視されます。
AS LOCATOR 文節について詳しくは、CREATE FUNCTIONの『パラメーターに AS LOCATOR を指定する』を参照してください。
- SPECIFIC qualified-specific-name
- ソース関数として使用する関数を特定名で識別します。 この修飾特定名 は、指定されたスキーマに存在している特定の関数を識別していなければなりません。
- SET OPTION ステートメント
- パラメーター・デフォルトに使用されるオプションを指定します。
各オプションのデフォルト値は、作成時に有効だったオプションによって異なります。詳しくは、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ステートメントでは使用できません。 他のオプションは、受け入れられますが、無視されます。
作成しようとしている関数の入力パラメーターの数は、ソース関数のパラメーターの数と同じにする必要があります。 それぞれの入力パラメーターのデータ・タイプが、ソース関数の対応パラメーターと同じでなかったり、その対応パラメーターにキャストできない場合は、エラーが発生します。 ソース関数の最終結果のデータ・タイプは、ソース化関数の結果と一致させるか、あるいは、 その結果にキャストできるようにする必要があります。
CCSID が指定され、戻りデータの CCSID が異なる CCSID でコード化されて いる場合、データは指定された CCSID に変換されます。
CCSID が指定されていない場合、戻りデータの CCSID が異なる CCSID でコ ード化されている場合には、戻りデータはジョブの CCSID (グラフィック・ ストリング戻り値の場合は、ジョブに関連したグラフィック CCSID) に変換 されます。 変換時に文字が失われるのを防ぐために、関数から戻される文字 をすべて表現できる CCSID を明示的に指定することを考慮してください。 これは、データ・タイプがグラフィック・ストリング・データの場合に特に重要です。 この場合、CCSID 1200 または 13488 (ユニコード・グラフィック・ストリング・データ) を使用することを考慮してください。
注
ユーザー定義関数の定義に関する一般考慮事項: ユーザー定義関数の定義に関する一般情報については、CREATE FUNCTIONを参照してください。
関数の所有権: SQL 名が指定されている場合、
- 作成した関数が入れられるスキーマと同じ名前のユーザー・プロファイルが存在する場合、関数の所有者 はそのユーザー・プロファイルです。
- その他の場合は、関数の所有者 は、この ステートメントを実行しているスレッドのユーザー・プロファイルまたは グループ・ユーザー・プロファイルです。
システム名を指定した場合は、関数の所有者 は、この ステートメントを実行しているスレッドのユーザー・プロファイルまたはグループ・ユーザー・プロファイルです。
関数の権限: SQL 名を使用する場合は、関数は、*PUBLIC に対するシステム権限 *EXCLUDE を使用して作成されます。 システム名を使用する場合、関数は、スキーマの作成権限 (CRTAUT) パラメーターによって決められる *PUBLIC に対する権限を使用して作成されます。
関数の所有者がグループ・プロファイルのメンバー (GRPPRF キーワード) で あり、グループ権限が指定されている (GRPAUT キーワード) 場合は、そのグ ループ・プロファイルにも、その関数に対する権限が与えられます。
ソース化されたユーザー定義関数の呼び出しに関する考慮事項: ソース化関数が呼び出されると、関数のそれぞれの引数が関数に定義された関連パラメーターに割り当てられます。次に、その値は基礎となる関数の対応するパラメーターのデータ・タイプに (必要に応じて) キャストされます。 割り当てまたはキャストのいずれかで、エラーが発生する可能性があります。 例: 関数のパラメーターのデータ・タイプ、および長さ、 または精度の属性と一致する関数への入力に渡された引数は、 基礎となるソース関数の対応するパラメーターの長さが短かったり、精度が低かったりすると、 キャストできない可能性があります。 基礎となる関数の対応するパラメーターの属性以下の属性を使用して、 ソース化関数のパラメーターのデータ・タイプを定義することをお勧めします。
基礎となる関数の結果は、ソース化関数の RETURNS データ・タイプに割り当てられます。 基礎となる関数の RETURNS データ・タイプは、 ソース関数の RETURNS データ・タイプにキャストできない場合があります。 これが生じる可能性があるのは、新規のソース関数の RETURNS データ・タイプが、 基礎となる関数の RETURNS データ・タイプより長さが短かったり、精度が低い場合です。 例えば、以下の関数が存在すると想定して関数 A を呼び出した場合に、エラーが発生する場合があります。 関数 A は INTEGER を戻します。 関数 B は SMALLINT を戻すよう定義されているソース化関数であり、 その定義は関数 A を SOURCE 文節で参照します。 基礎となる関数の RETURNS データ・タイプを定義する属性以上の属性を使用して、 ソース化関数の RETURNS データ・タイプを定義することをお勧めします。
関数がユーザー定義関数に基づく場合の考慮事項: ソース化関数を外部スカラー関数をもとにして直接的または間接的に作成する場合、 そのソース化関数は、その外部スカラー関数の属性を継承します。 これには、ソース化関数のいくつかの層が含まれる場合があります。 例えば、関数 A が関数 B をソースとし、関数 B は関数 C をソースとしているとします。 また、関数 C は外部スカラー関数であるとします。 関数 A と B は、関数 C のすべての属性を継承します。
ソース派生関数 は、それが直接的に基づいているユーザー定義関数からセキュア属性を 継承します。組み込み関数に基づいているソース派生関数は、常にセキュアです。
関数の作成: ソース化関数が作成されると、 その関数を表す小さなサービス・プログラム・オブジェクトが作成されます。 このサービス・プログラムが別のシステムに保管および復元されると、 CREATE FUNCTION ステートメントの属性は自動的にそのシステム上のカタログに追加されます。
例
例 1: 特殊タイプ HATSIZE が定義され、 組み込みデータ・タイプ INTEGER に基づいていると想定します。 異なる部門の平均の帽子サイズを計算するために、AVG 関数を定義することができます。 組み込み関数 AVG をベースにしたソース化関数を作成します。
CREATE FUNCTION AVG (HATSIZE)
RETURNS HATSIZE
SOURCE AVG (INTEGER)ソース関数は組み込み関数であるため、 SOURCE 文節の構文には明示的なパラメーター・リストが含まれます。
特殊タイプ HATSIZE が作成された際に、2 つのキャスト関数が生成されました。 これにより、HATSIZE を引数用に INTEGER にキャストし、 INTEGER を関数の結果用に HATSIZE にキャストすることができます。
例 2: Smith が外部スカラー関数 CENTER を自分のスキーマに作成した後で、 この関数の使用が必要になります。ただし、この関数の呼び出し時に、 1 つの INTEGER 引数と 1 つの DOUBLE 引数ではなく、 2 つの INTEGER 引数を受け入れさせる必要があります。 CENTER をベースにしたソース化関数を作成します。
CREATE FUNCTION MYCENTER (INTEGER, INTEGER)
RETURNS DOUBLE
SOURCE SMITH.CENTER (INTEGER, DOUBLE);