dc_rpc_call

ANSI C ，C++の形式

#include <dcrpc.h>
int  dc_rpc_call(char *group,char *service,char *in,
                 DCULONG *in_len,char *out,DCULONG *out_len,
                 DCLONG flags)

K&R版 C の形式

#include <dcrpc.h>
int dc_rpc_call(group,service,in,in_len,out,out_len,flags)
char      *group;
char      *service;
char      *in;
DCULONG   *in_len;
char      *out;
DCULONG   *out_len;
DCLONG    flags;

●group

SPPのサービスグループ名を，31バイト以内のアスキー文字列で設定します。文字列の最後にはヌル文字を設定してください。このヌル文字は文字列の長さに数えません。

ドメイン修飾をしてサービスを要求するときは，サービスグループ名の後ろに@（アットマーク）とDNSのドメイン名を付けて，文字列の最後にはヌル文字を設定してください。

●service

SPPのサービス名を，31バイト以内のアスキー文字列で設定します。文字列の最後にはヌル文字を設定してください。このヌル文字は文字列の長さに数えません。

●in

サービスの入力パラメタを設定します。

●in_len

サービスの入力パラメタ長を設定します。1からDCRPC_MAX_MESSAGE_SIZE^※までの範囲の長さが設定できます。DCRPC_MAX_MESSAGE_SIZEは，dcrpc.hで定義してあります。

注※

rpc_max_message_sizeオペランドを使用した場合，DCRPC_MAX_MESSAGE_SIZEの値（1メガバイト）ではなく，rpc_max_message_sizeオペランドに指定した値になります。

●out

サービス関数から返ってくる応答を格納する領域を設定します。outで指す領域へ，サービス関数からの応答が設定されます。

●out_len

サービスの応答の長さを設定します。1からDCRPC_MAX_MESSAGE_SIZE^※までの範囲の長さが設定できます。DCRPC_MAX_MESSAGE_SIZEは，dcrpc.hで定義してあります。

注※

rpc_max_message_sizeオペランドを使用した場合，DCRPC_MAX_MESSAGE_SIZEの値（1メガバイト）ではなく，rpc_max_message_sizeオペランドに指定した値になります。

非応答型RPCの場合も，サービスの応答の長さを設定した領域のアドレスを指定する必要があります。この場合，サービスの応答の長さには，0を設定します。

●flags

RPCの形態とオプションを，次に示す形式で設定します。

{DCNOFLAGS|DCRPC_NOWAIT|DCRPC_NOREPLY|DCRPC_CHAINED}〔|DCRPC_TPNOTRAN〕〔|DCRPC_DOMAIN〕

DCNOFLAGS

同期応答型RPC

DCRPC_NOWAIT

非同期応答型RPC

DCRPC_NOREPLY

非応答型RPC

DCRPC_CHAINED

連鎖RPC

DCRPC_TPNOTRAN

トランザクション処理からのサービス要求で，要求先の処理をトランザクションにしない場合に設定します。DCRPC_TPNOTRANを設定すると，トランザクションの処理からのサービス要求でも，サービス関数の処理はトランザクションになりません。

DCRPC_DOMAIN

サービスグループ名をドメイン修飾した場合に指定します。ドメイン修飾をしたRPCはトランザクションブランチにできません。そのため，トランザクションの処理からdc_rpc_call関数を使う場合は，必ずDCRPC_TPNOTRANと一緒に指定してください。

DCRPC_TPNOTRANとDCRPC_DOMAINは，RPCの形態に付けて設定します。

（例1）

同期応答型RPCでトランザクションにしないサービス要求をする場合，flagsには「DCNOFLAGS｜DCRPC_TPNOTRAN」と設定します。

（例2）

トランザクションの処理から，同期応答型RPCでドメイン修飾をしたサービス要求をする場合，flagsには「DCNOFLAGS|DCRPC_TPNOTRAN|DCRPC_DOMAIN」と設定します。

●out

サービス関数が設定した，応答が返されます。

●out_len

サービス関数が設定した，応答の長さが返されます。

サーバUAPに渡す値

サービスを要求するときは，サービス関数から返ってくる応答の領域（out）を確保しておきます。クライアントUAPでは，dc_rpc_call関数に次の値を設定しておきます。

• 入力パラメタ（in）

• 入力パラメタ長（in_len）

• 応答の長さ（out_len）

  入力パラメタ，入力パラメタ長，応答の長さは，クライアントUAPのdc_rpc_call関数で設定した値が，そのままサービス関数に渡されます。文字コードや数字の表記形式を変えたい場合は，クライアントUAP，または要求されたサービス関数の処理で変換してください。応答を返さないサービス関数のサービスを要求するときは，応答の長さを設定しても無視されます。

  入力パラメタ長と応答の長さの最大値は，それぞれヘッダファイルdcrpc.hのDCRPC_MAX_MESSAGE_SIZE^※で宣言しています。最大値を確認する場合は，dcrpc.hの内容を参照してください。

  注※

  rpc_max_message_sizeオペランドを使用した場合，DCRPC_MAX_MESSAGE_SIZEの値（1メガバイト）ではなく，rpc_max_message_sizeオペランドに指定した値になります。

サーバUAPから戻ってくる値

サービス関数の処理が終了して応答が戻ってくると，次の値を参照できます。

• サービス関数の応答（out）

• サービス関数の応答の長さ（out_len）

out_len はサービス関数から実際に返ってきた応答の長さです。outとout_lenを参照できる場合を次に示します。

• 同期応答型RPC，連鎖RPCの場合

  dc_rpc_call関数がリターンしたあと。

• 非同期応答型RPCの場合

  dc_rpc_poll_any_replies関数が該当する応答を受け取ってリターンしたあと。out_lenは参照できません。

• 非応答型RPCの場合

  outとout_lenは参照できません。

dc_rpc_call関数，またはdc_rpc_poll_any_replies関数がエラーリターンした場合には，outとout_lenは参照できません。

返ってきた応答が，クライアントUAPで確保した応答の領域（out）よりも大きい場合は，DCRPCER_REPLY_TOO_BIGでエラーリターンします。

flagsに設定する値

flagsに設定した値とdc_rpc_call関数の実行結果について説明します。

• 同期応答型RPC（flagsにDCNOFLAGSを設定）

  dc_rpc_call関数は，応答が返るか，通信先でエラーが起こるまでリターンしません。

• 非同期応答型RPC（flagsにDCRPC_NOWAITを設定）

  dc_rpc_call関数は，すぐにリターンします。ただし，応答を参照できるのは，dc_rpc_poll_any_replies関数で非同期に応答を受信したあとです。応答（out）の領域は，次に示す方法で非同期応答型RPCを終了するまで，解放しないでください。

  • dc_rpc_poll_any_replies関数で応答を受け取る

  • dc_rpc_discard_further_replies関数で応答の受信を拒否

  • トランザクションの処理からサービスを要求した場合は，コミット，またはロールバックした

  トランザクションの処理で非同期応答型RPCを使う場合，同期点処理（コミット，またはロールバック）前にdc_rpc_poll_any_replies関数で応答を受け取ってください。同期点処理後には，dc_rpc_poll_any_replies関数で応答は受信できません。dc_rpc_poll_any_replies関数が受信する応答を特定する場合は，dc_rpc_call関数がリターンしたときに返された正の整数（記述子）を，dc_rpc_poll_any_replies関数の引数に設定します。受信する応答を特定する場合は，dc_rpc_call関数のリターン値を保持しておいてください。

  なお，非トランザクションの処理で，同期点処理後に応答を受け取りたい場合は，システムサービス定義のrpc_extend_functionオペランドで該当するオプションを指定する必要があります。

  rpc_extend_functionについては，マニュアル「OpenTP1 システム定義」を参照してください。

• 非応答型RPC（flagsにDCRPC_NOREPLYを設定）

  dc_rpc_call関数は，サービス関数の処理が終わるのを待たないで，すぐにリターンします。サービス関数は応答を返さないサービスと見なされます。そのため，サービス関数が実行されたかどうかは，サービスを要求したUAPからはわかりません。DCRPC_NOREPLYを設定した場合は，応答（out）と応答の長さ（out_len）の値は参照できません。

• 連鎖RPC（flagsにDCRPC_CHAINEDを設定）

  dc_rpc_call関数は，応答が返るか，通信先でエラーが起こるまでリターンしません。連鎖RPCで同じサービスグループに属するサービスを複数回要求する場合は，最初の要求時と同じプロセスで実行できます。

  連鎖RPCを使う場合には，次に示す制限があります。

  1. 2回目以降のdc_rpc_call関数では，ユーザサーバおよびサービスの閉塞を検出できません。

  2. 2回目以降のdc_rpc_call関数でサービス関数の処理で異常が起こった場合には，ユーザサーバ全体が閉塞します。サービス単位では閉塞しません。

サーバUAPがあるノードのOpenTP1が稼働していない場合

サービスを要求されるOpenTP1が稼働していない場合は，dc_rpc_call関数は次に示すリターン値のどれかでエラーリターンします。

• DCRPCER_NET_DOWN

• DCRPCER_SERVICE_NOT_UP

• DCRPCER_OLTF_NOT_UP

• DCRPCER_OLTF_INITIALIZING

サーバUAPが稼働していない場合

サーバUAPがマルチサーバの場合，異常終了中，または部分回復処理中であっても，サービス要求はOpenTP1で新しく起動されたプロセスで実行されます。ただし，次に示す場合は，dc_rpc_call関数はエラーリターンします。

1. 閉塞しているSPPへはサービスを要求できません。サービスグループが閉塞されている場合は，DCRPCER_SERVICE_CLOSED でエラーリターンします。

2. ユーザサーバの停止コマンド（dcsvstopコマンド）またはOpenTP1の停止コマンド（dcstopコマンド）で，SPPが終了処理中または終了している場合は，次に示すどれかのステータスコードでエラーリターンします。

   • DCRPCER_SERVICE_TERMINATING

   • DCRPCER_SERVICE_CLOSED

   • DCRPCER_NO_SUCH_SERVICE_GROUP

   これらのうち，どのリターン値が返るかは，dc_rpc_call関数を呼び出したタイミングで決まります。

3. OpenTP1が開始処理中の場合は，DCRPCER_OLTF_INITIALIZINGでエラーリターンします。この場合は，サーバUAPまたはOpenTP1が起動完了したあとに正常にサービスを要求できることがあります。OpenTP1は，メッセージID KFCA01809-Iのメッセージログが出力されると起動を完了するので，このメッセージが表示されてから再びサービスを要求してください。

ノード間負荷バランス機能およびノード間負荷バランス拡張機能の環境でサービスを要求した場合

ノード間負荷バランス機能およびノード間負荷バランス拡張機能の環境では，該当するサービスのスケジュールが閉塞していると，OpenTP1が自動的にほかのノードにサービス要求を転送します。ただし，次に示す条件の場合dc_rpc_call関数はDCRPCER_TRNCHKでエラーリターンします。

1. トランザクション処理の場合，転送しようとした先のノードにあるサービスのトランザクション属性が，閉塞していたサービスと一致していないとき。

2. 転送しようとした先のノードにあるOpenTP1のバージョンが，サービスを要求したOpenTP1のノードのバージョンよりも低いとき。

これらのエラーリターンが起こった場合は，次に示す処置をしてください。

1. ノード間負荷バランス機能およびノード間負荷バランス拡張機能を構成する複数のSPPのトランザクション属性を一致させてください。

2. ノード間負荷バランス機能およびノード間負荷バランス拡張機能を構成する複数のOpenTP1のバージョンを一致させてください。

ソケット受信型サーバへサービスを要求する場合

ソケット受信型サーバでは，ユーザサービス定義のmax_socket_msgオペランドとmax_socket_msglenオペランドの指定で，データの輻輳制御をしています。そのため，定義した値を超えた場合，サービス要求を受信できない場合があります。このときdc_rpc_call関数は，DCRPCER_SERVER_BUSYでエラーリターンします。この値が返った場合は，クライアントUAPはしばらく時間をおいてから再実行すれば，サービスを要求できることがあります。

連鎖RPCを使った場合

トランザクションとして処理している連鎖RPCを使っているUAPから，同じサーバUAPへトランザクションでないdc_rpc_call関数を呼び出すと，DCRPCER_NOT_TRN_EXTENDでエラーリターンします。

オンラインテスタを使っている場合

オンラインテスタを使っている場合に，テストモードのUAPとテストモードでないUAP間でdc_rpc_call関数を呼び出すと，DCRPCER_TESTMODE でエラーリターンします。

セキュリティ機能を使っている場合

dc_rpc_call関数を呼び出したときに，目的のサービスがセキュリティ機能で保護されていて，dc_rpc_call関数を呼び出したクライアントUAPにSPPへのアクセス権がない場合は，DCRPCER_SECCHKでエラーリターンします。

クライアントUAPの時間監視でエラーになる場合

次に示す場合には，クライアントUAPのユーザサービス定義のwatch_timeオペランドに指定した時間が経過したあとで，DCRPCER_TIMED_OUTでエラーリターンします。

• SPPがあるノードのOpenTP1全体が異常終了した場合

• サービス要求のデータがサーバUAPに届く前，またはサーバUAPの処理が完了してからクライアントUAPに結果が届く前に障害が起こった場合

dc_rpc_call関数がエラーリターンしてもコミットとなる場合

サービスを要求されたサービス関数の異常終了や，ノードの障害，ネットワーク障害の場合でも，DCRPCER_TIMED_OUTがリターンすることがあります。クライアントUAPがトランザクション処理でない場合は，DCRPCER_TIMED_OUTが返っても，要求したサービスがあるサービス関数は正常に終了していて，データベースへの更新などが実行されているときもあります。

ロールバック処理が必要なエラーリターン値

トランザクション処理から呼び出したdc_rpc_call関数がエラーリターンした場合，リターン値によっては，必ずトランザクションがロールバック（サーバUAPがrollback_only状態）になります。この場合，コミットの関数，またはロールバックの関数のどちらを使っても，必ずロールバックになります。必ずロールバックになるdc_rpc_call関数のリターン値を次に示します。

• DCRPCER_INVALID_REPLY

• DCRPCER_NO_BUFS_AT_SERVER

• DCRPCER_NO_SUCH_SERVICE

• DCRPCER_REPLY_TOO_BIG_RB

ドメイン修飾をしてサービスを要求するときの注意

1. ドメイン修飾をしてサービスを要求する場合は，dc_rpc_call関数のflagsにDCRPC_DOMAINを設定します。DCRPC_DOMAINを設定しないでドメイン修飾をしたサービスグループ名を設定すると，dc_rpc_call関数は DCRPCER_NO_SUCH_SERVICE_GROUPでエラーリターンします。

2. ドメイン修飾をしたRPCの場合，dc_rpc_call関数を呼び出したプロセスがトランザクションの処理でも，トランザクションを拡張できません。そのため，トランザクションの処理からドメイン修飾をしてサービスを要求する場合は，flagsにDCRPC_TPNOTRANを指定して，トランザクションを拡張しないようにしてください。なお，ドメイン名に自ドメインを設定した場合でも，トランザクションを拡張できません。

3. ドメイン修飾をしたRPCでは，キュー受信型サーバにだけサービスを要求できます。ソケット受信型サーバへは，ドメイン修飾をしたサービス要求はできません。

4. ドメイン修飾をしたサービス要求では，namdomainsetupコマンドで登録したホストで起動されるドメイン代表スケジュールサービスへサービス要求を送信します。ドメイン代表スケジュールサービスのポート番号は，/etc/services から取得します。サービス要求の送信で障害が起こった場合は，namdomainsetupコマンドで複数のホスト名を登録していれば，順次送信を試みます。ドメイン修飾をしたRPCが正常に終了しても，ドメイン代表スケジュールサービスへの送信で障害が起こっている場合もあります。

ドメイン修飾をしたサービス要求をする前の準備

ドメイン修飾をしたRPCでは，次に示す環境設定をしてください。

1. DNSのドメインデータファイルへ，ドメイン代表スケジュールサービスを起動するホスト名を登録します。登録するときは，namdomainsetupコマンドを使います。

2. ドメイン修飾をしたサービス要求をするOpenTP1を起動するホストの/etc/servicesへ，ドメイン代表スケジュールサービスのポート番号を設定します。ポート番号は，次の形式で記述してください。

   OpenTP1scd ポート番号/tcp

3. ドメイン代表スケジュールサービスを起動するOpenTP1のスケジュールサービス定義のscd_portオペランドに，ドメイン代表スケジュールサービスのウェルノウンポートを指定します。