C言語関数のインターフェースを、以下に示します。
以下に示す関数(例:Defunc )を作成する例で説明します。
スレッドセーフとなるように作成してください。
int Defunc( int Oper, void **Handle, void **Data )
処理名 | 処理詳細 | 第1引数の概要(注） | 第2引数の概要 | 第3引数の概要 |
|---|---|---|---|---|
環境開設 | ユーザ-定義関数が動作する環境を作成します。ユーザー定義関数で持ちまわるハンドルを獲得します。 | DE_USER_FUNCTION_ | Handleの作成 |
|
変換実行 | ユーザー定義関数による変換の実処理を作成します。変換後のデータを復帰します。 | DE_USER_FUNCTION_ | DE_USER_FUNCTION_ |
|
領域解放 | 変換実行で復帰した変換後のデータ領域を解放します。 | DE_USER_FUNCTION_ | DE_USER_FUNCTION_ |
|
環境閉鎖 | ユーザー定義関数が動作する環境を閉鎖する処理です。ハンドルを解放します。 | DE_USER_FUNCTION_ | Handleの解放 |
|
注) 第1引数は、以下に示すData EffectorのC APIインクルードファイルで定義されています。
OS | ディレクトリ |
|---|---|
Windows | インストール先のフォルダ\include |
Linux/Solaris | /opt/FJSVshnde/include |
関数型・復帰値
int型で、正常の場合は0を、それ以外の場合は任意のエラーの種類を示す数値を返すように作成します。
復帰値に0以外の値が設定されている場合、出力領域（Data）に情報が設定されている場合には、本情報をエラーメッセージとして出力します。
エラーメッセージは、終端(\0)を含んで、512バイト以内で設定してください。512バイトより大きいエラーメッセージは、正しく表示されない場合があります。
また、エラーメッセージの中に、日本語などのマルチバイト文字が存在する場合に、処理を実行したシステムロケールの文字コードと、エラーメッセージに設定した文字コードが異なっていると、正しくメッセージが出力されないことがあります。
第1引数(呼び出し種別)
各処理は、ユーザー定義関数の第1引数の内容によって、処理を切り分けてください。
以下に、第1引数の内容と処理の関係を記述します。
処理名 | 第1引数の内容 |
|---|---|
環境開設 | DE_USER_FUNCTION_THREAD_OPEN |
変換実行 | DE_USER_FUNCTION_EXEC |
領域開放 | DE_USER_FUNCTION_FREE |
環境閉鎖 | DE_USER_FUNCTION_THREAD_CLOSE |
第2引数(ハンドル)
各処理の第2引数の内容について以下に記述します。
処理名 | 第2引数の内容 |
|---|---|
環境開設 | 作成したハンドルを設定します。 |
変換実行 | 環境開設で作成したハンドルが設定されます。 |
領域開放 | 環境開設で作成したハンドルが設定されます。 |
環境閉鎖 | 環境開設で作成したハンドルが設定されます。本ハンドルを解放してください。 |
第3引数(入出力データ)
各処理の第3引数の内容について以下に記述します。
第1引数が「DE_USER_FUNCTION_THREAD_OPEN」または「DE_USER_FUNCTION_THREAD_CLOSE」の場合には、入力として以下のようなデータ列へのポインタ(*Data)が渡されます。
第1引数が「DE_USER_FUNCTION_EXEC」の場合には、入力として以下のようなデータ列へのポインタ(*Data)として、ユーザー定義関数に渡された項目参照のデータが渡されます。
また、出力として処理結果の文字列のアドレス(*Data)を返すように作成します。
第1引数が「DE_USER_FUNCTION_FREE」の場合には、「DE_USER_FUNCTION_EXEC」の出力である処理結果の文字列のアドレスが渡されます。
図7.3 Dataの指定例
作成時の注意
第3引数の使用されるデータの指定方法を、以下に示します。
値の種類 | 項目のアドレス | 項目の文字列 |
|---|---|---|
EMPTY | NULL | - |
長さ0の文字列 | NULL以外 | \0だけ |
それ以外の文字列 | NULL以外 | \0終端文字列 |
値の種類 | *Data | 処理結果の文字列 |
|---|---|---|
EMPTY | NULL | - |
長さ0の文字列 | NULL以外 | \0だけ |
それ以外の文字列 | NULL以外 | \0終端文字列 |
Defunc関数でエラーが発生した場合、以下のメッセージを出力し、Data Effectorはエラー終了します。
shnde: ERROR: 03015: The user-defined function terminated abnormally. Return code = Defuncの復帰値; Message = “エラーメッセージ” User-defined function name = ユーザー定義関数名; Call code = 呼び出し種別. (機能名) |
Defunc関数から、Data EffectorのAPIを呼び出すことはできません。
動作ログに以下の情報を出力します。
ユーザー定義関数の処理時間(「呼び出し種別」の単位)
ユーザー定義関数の発行回数(「呼び出し種別」の単位)
Data Effectorでは処理を最適化しています。式や仮想項目に指定したcall関数は、指定した順序や条件通りに呼び出されるとは限りません。必要に応じて呼出しの有無の判断や呼出し順序の変更を行います。
ユーザー定義関数は参照透過性があるものとみなされ、同じ引数を与えた場合は、同じ結果が返却されると判断されます。その結果、最適化によりユーザー定義関数の呼出しが省略されることがあります。
ユーザー定義関数内でファイルやデータベースへ出力するなどの副作用のある処理は行わないでください。また、call関数の呼出し順序に依存した処理を行わないでください。
ユーザー定義関数内で行うデータ加工処理は、call関数の引数として渡される項目参照だけを使用するようにしてください。
