9.22 COMPOSER_CALLF
注意： 9.1 組み込み関数の規則 利用オプション
この組み込み関数は、LANSA Composer V3.0 以降で利用可能です。
この組み込み関数は、ソースシステム（組み込み関数が実行されるシステム）がVersion 3以上のLANSA Composerシステムであり、LANSA Composer リクエストサーバー ソフトウェアがその中に入っていることを前提としています。そうでない場合には、この組み込み関数の実行は失敗します。
COMPOSER_CALLFはLANSA Composer リクエストサーバーを通じて、サーバー別名の引数によって識別されるLANSA ComposerシステムもしくはLANSAシステムにある、指定されたLANSAファンクションを呼び出します。
LANSAの交換リストを使用して、最大7つの値を渡したり受け取ったりすることができます。全てのパラメータは、EXCH01 - EXCH07という名前の交換変数を使用して、A(256）で受け渡されます。
この組み込み関数は、他のLANSAシステムや区画にインストールされているLANSAアプリケーションに含まれる処理ロジックを起動するために、カスタム・アクティビティ・プロセッサもしくはLANSA Composerの他のユーザー定義のプラグイン・コンポーネントで使用されることを目的としています。
この組み込み関数を実行する前に、9.24 COMPOSER_USE 組み込み関数を使用して、サーバー接続詳細とそれを表す別名を定義しなくてはいけません。
CALL_FUNCTION組み込み関数についてのその他の重要な情報については、以下を参照してください。
呼び出されるファンクションについてのLANSAプログラミングの考慮事項
LANSA Composer リクエストサーバーを通して実行されるファンクション呼び出しに関するその他の考慮事項
CALL_FUNCTIONアクティビティやLANSA Composer リクエストサーバーについて詳しく知りたい場合には、『LANSA Composer ガイド』を参照されることをお勧めします。
引数
番号 | タイプ | 必須/任意 | 記述 | 最小長 | 最大長 | 最小小数桁数 | 最大小数桁数 |
|---|---|---|---|---|---|---|---|
1 | A | 必須 | LANSA Composerのサーバー別名。 LANSA Composerサーバーシステムへの接続詳細を識別するのに使用される別名を指定します。名前は、COMPOSER_USE組み込み関数を使用して、現在のセッションにおいて、これより前に指定されていなくてはいけません。 | 1 | 10 | ||
2 | A | 必須 | 呼び出されるファンクションを含むLANSAプロセスの名前。 IBM i：*DIRECTが指定されている場合には、ファンクションはFUNCTION OPTIONS(*DIRECT)で定義されていなくてはいけません。 Windowsサーバー：*DIRECTではなく、プロセス名が指定されていなくてはいけません。 | 1 | 10 | ||
3 | A | 必須 | 呼び出されるファンクションの名前。必須。 | 1 | 7 | ||
4 | N | 任意 | 使用される交換変数の数。指定されていない場合、省略値の0とみなされます。 | 1 | 5 | 0 | 0 |
5 | A | 任意 | 交換変数EXCH01の値 (「交換変数」を参照)。 | 1 | 256 | ||
6 | A | 任意 | 交換変数EXCH02の値 (「交換変数」を参照)。 | 1 | 256 | ||
7 | A | 任意 | 交換変数EXCH03の値 (「交換変数」を参照)。 | 1 | 256 | ||
8 | A | 任意 | 交換変数EXCH04の値 (「交換変数」を参照)。 | 1 | 256 | ||
9 | A | 任意 | 交換変数EXCH05の値 (「交換変数」を参照)。 | 1 | 256 | ||
10 | A | 任意 | 交換変数EXCH06の値 (「交換変数」を参照)。 | 1 | 256 | ||
11 | A | 任意 | 交換変数EXCH07の値 (「交換変数」を参照)。 | 1 | 256 | ||
12 | A | 任意 | 同期呼び出しか否か。 組み込み関数がファンクション呼び出しが完了するのを待つかどうかを指定します。 省略値は'Y'で、待ちます。 それ以外の値が指定されている場合には、組み込み関数はファンクション呼び出しを投げた後、すぐに終了します。 このパラメータが'Y'の場合、この組み込み関数は呼び出されたファンクションからの値(EXCH01～EXCH07の交換変数)のみ受け取ることができます。 | 1 | 1 | ||
13 | N | 任意 | 同期タイムアウト（秒）。 組み込み関数が、同期呼び出しが完了するのを待つ秒数。このタイムアウトを超えた場合、組み込み関数は結果コード'TM'で終了します。 デフォルトは30秒です。 | 1 | 5 | 0 | 0 |
14 | N | 任意 | 要求の有効期限（秒数）。IBM i のみ。Windowsサーバーには適用されません。 IBM i サーバーにおいてのみ、リクエストサーバーに要求が投げられた後、要求が有効である秒数を指定します。リクエストサーバーが要求を処理し始めるまでに指定された間隔よりも長く経過した場合には、要求の有効期限が切れたと考え、その処理を行うのを取りやめます。 省略値はゼロ(0)であり、この場合、要求は期限切れを起こしません。 有効期限は、IBM i サーバーのリクエストサーバーを通して実行された要求にのみ適用されることにご注意ください。Windowsサーバー上で実行される場合には、有効期限は適用されません。 | 1 | 5 | 0 | 0 |
戻り値
番号 | タイプ | 必須/任意 | 記述 | 最小長 | 最大長 | 最小小数桁数 | 最大小数桁数 |
|---|---|---|---|---|---|---|---|
1 | A | 任意 | 結果コード。 組み込み関数が正常に完了した場合には、結果コードには'OK'と入ります。同期要求がタイムアウトした場合には、結果コードには'TM'と入ります。それ以外の結果コードは、エラーが起こったことを示します。 | 2 | 2 | ||
2 | A | 任意 | 交換変数EXCH01の値 (「交換変数」を参照)。 | 1 | 256 | ||
3 | A | 任意 | 交換変数EXCH02の値 (「交換変数」を参照)。 | 1 | 256 | ||
4 | A | 任意 | 交換変数EXCH03の値 (「交換変数」を参照)。 | 1 | 256 | ||
5 | A | 任意 | 交換変数EXCH04の値 (「交換変数」を参照)。 | 1 | 256 | ||
6 | A | 任意 | 交換変数EXCH05の値 (「交換変数」を参照)。 | 1 | 256 | ||
7 | A | 任意 | 交換変数EXCH06の値 (「交換変数」を参照)。 | 1 | 256 | ||
8 | A | 任意 | 交換変数EXCH07の値 (「交換変数」を参照)。 | 1 | 256 |
例
この例では、COMPOSERという別名を使いあらかじめ定義されたLANSAシステムへ接続して（COMPOSER_USEを参照）、簡単なファンクション呼び出しを行います。プロセス名は変数#PROCESSに、ファンクション名は変数#FUNCTIONに指定されています。
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION)この例ではファンクションを呼び出すために、上記と同じLANSAシステムに接続します。プロセス名は変数#PROCESSに、ファンクション名は変数#FUNCTIONに指定されています。次の2つのパラメータ値が受け渡されます。'VALUE 1' 及び 'VALUE 2'です。これらの値を交換リストを通じて受け取るには、呼び出されるファンクションにEXCH01及びEXCH02というフィールドが定義されていなくてはいけません。このケースでは、呼び出しが非同期であるため、ファンクションが完了するのを待たずに処理が続行されます。
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION 2 'VALUE 1' 'VALUE 2' *Default *Default *Default *Default *Default N) to_get(#RESULT)この例ではファンクションを呼び出すために、上記と同じLANSAシステムに接続します。プロセス名は変数#PROCESSに、ファンクション名は変数#FUNCTIONに指定されています。2つのパラメータ値が受け渡され、3つのパラメータ値が戻ってきます。これらの値を交換リストを通じて受け取るには、呼び出されるファンクションにEXCH01及びEXCH02というフィールドが定義されていなくてはいけません。加えて、変数を返すためにEXCH03というフィールドも定義されている必要があり、これらのフィールドは交換される必要があります。
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION 2 'VALUE 1' 'VALUE 2') to_get(#RESULT #VAR1 #VAR2 #VAR3)交換変数
組み込み関数の引数や戻り値は、LANSA交換リストを経由して呼びだされたファンクションを相手に、最大7つの値を渡したり受け取ったりするのに使用できます。パラメータはEXCH01～EXCH07という名前の長さ256の文字変数として、交換リストに置かれたり受け取ったりします。
呼び出されるファンクションも、交換される値を受け取るために、EXCH01 ～ EXCH07という名前の変数を使用しなくてはいけません。呼び出されるファンクションがこれらの変数を経由して値を返す必要がある場合には、適切なところでEXCHANGEコマンドを実行しなくてはいけません。
組み込み関数は、4番目の引数に指定されたパラメータの数だけ（最大7つ）、交換リストに値を置いたり、値を受け取ったりします。使用される場合には、パラメータが連続して指定されている必要があります。例えば、値に3を指定する場合、組み込み関数は変数EXCH01、EXCH02、EXCH03を交換し、その他の交換変数の引数の値は無視されます。
組み込み関数は同期的に実行された場合、呼び出されたファンクションから戻ってきた値のみを受け取ることに注意してください。
交換リストを使用した情報の交換について詳しくは「EXCHANGE」コマンドの記述をご参照ください。
呼び出されるファンクションについてのLANSAプログラミングの考慮事項
- PROCESSパラメータに*DIRECTが指定されている場合、ファンクションはFUNCTION OPTIONS(*DIRECT)で定義されていなくてはいけません。
- 呼び出されるファンクションはRDMLであっても、RDMLXであっても構いません。
- ファンクションは、対応する組み込み関数の引数に指定された値を（交換リストを経由して）受け取るために、EXCH01 ～ EXCH07のフィールドを定義しなくてはいけません。
- ファンクションは、対応する組み込み関数の戻り値に値を（交換リストを経由して）戻すために、EXCH01 ～ EXCH07のフィールドとともにEXCHANGEコマンドを使用しなくてはいけません。
- IBM i サーバーにおいてのみ、コンパイルもしくはファンクションの実行前に、呼び出されるファンクションのあるLANSAシステムのLANSAデータエリアDC@A01の487カラム目に'Y'が設定されている必要があります。この条件が満たされない場合には、呼び出されたファンクションはEXCH01 ～ EXCH07の変数値を正しく受け取ったり返したりすることができません。
これらの要件によっては、開発者がその考慮事項を満たすためだけにファンクションを書くことが必要になる場合があります。その場合、ファンクションはLANSAアプリケーションの既存のファンクションを呼び出す簡単な"スタブ"ファンクションになる場合が多いです。
LANSA Composer リクエストサーバーを通して実行されるファンクション呼び出しに関するその他の考慮事項
この組み込み関数はLANSA Composer リクエストサーバーを通じてファンクション呼び出しを実行します。
このように実行される場合、ファンクション呼び出しは別のプロセスやジョブで実行されます（リクエスト・サーバー）。組み込み関数とリクエストサーバーのプロセスやジョブは、要求を実行して結果を返すために、協力してやり取りをおこないます。
これらはアプリケーションに対して概ね影響を与えません。しかしながら、これらの実行方法に関していくつか特別に考慮すべきことがあり、それには以下の項目に関連する考慮事項が含まれます。
- ユーザー・プロファイル、権限、実行環境
- IBM i 作業管理 (ジョブやサブシステム)
- 呼び出されるファンクションがコンパイルされる方法
LANSA Composerのリクエストサーバーを通して実行された要求に関しては、詳しくは『LANSA Composer ガイド』の付録F (「LANSA Composer リクエストサーバー」) を参照してください。