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;
機能
SPPのサービスを要求します。dc_rpc_call関数を使うときは,要求するサービスがどのノードにあるかを意識する必要はありません。
サービスを要求するときには,「サービスグループ名」と「サービス名」を dc_rpc_call関数の引数に設定します。この名称に該当するサービス関数へサービスが要求されます。
dc_rpc_call関数を呼び出すUAPは,トランザクションとして実行していても,していなくてもかまいません。トランザクションとして実行している処理からdc_rpc_call関数でサービスを要求するときは,要求するサービスの処理はトランザクションブランチとして稼働します。dc_rpc_call関数を使う場合,サーバUAPがあるノードのOpenTP1が稼働していることが前提です。
dc_rpc_call関数を実行して応答を待っている間にシグナルを受信しても,関数はリターンされません。
リターン値の一覧のあとに,次の説明を掲載しています。dc_rpc_call関数の詳しい説明を知りたいときに参照してください。
(1)dc_rpc_call関数の引数について
(2)dc_rpc_call関数がエラーになる場合
(3)dc_rpc_call関数がエラーになるタイミング
(4)dc_rpc_call関数がエラーになったときに再実行する指定
(5)サービス要求に優先度を付ける場合
(6)リターン値DCRPCER_NO_SUCH_SERVICE_GROUPとDCRPCER_NET_DOWNの違い
(7)リターン値DCRPCER_SERVICE_TERMINATEDをリターンさせる指定
(8)エラーリターン値と同期点処理の関係
(9)サービスを要求するときの注意
(10)ドメイン修飾をしてサービスを要求する場合
UAPで値を設定する引数
●group
SPPのサービスグループ名を,31バイト以内のアスキー文字列で設定します。文字列の最後にはヌル文字を設定してください。このヌル文字は文字列の長さに数えません。
ドメイン修飾をしてサービスを要求するときは,サービスグループ名の後ろに@(アットマーク)とDNSのドメイン名を付けて,文字列の最後にはヌル文字を設定してください。
●service
SPPのサービス名を,31バイト以内のアスキー文字列で設定します。文字列の最後にはヌル文字を設定してください。このヌル文字は文字列の長さに数えません。
●in
サービスの入力パラメタを設定します。
●in_len
サービスの入力パラメタ長を設定します。1からDCRPC_MAX_MESSAGE_SIZE※までの範囲の長さが設定できます。DCRPC_MAX_MESSAGE_SIZEは,dcrpc.hで定義してあります。
●out
サービス関数から返ってくる応答を格納する領域を設定します。outで指す領域へ,サービス関数からの応答が設定されます。
●out_len
サービスの応答の長さを設定します。1からDCRPC_MAX_MESSAGE_SIZE※までの範囲の長さが設定できます。DCRPC_MAX_MESSAGE_SIZEは,dcrpc.hで定義してあります。
非応答型RPCの場合も,サービスの応答の長さを設定した領域のアドレスを指定する必要があります。この場合,サービスの応答の長さには,0を設定します。
●flags
RPCの形態とオプションを,次に示す形式で設定します。
{DCNOFLAGS|DCRPC_NOWAIT|DCRPC_NOREPLY|DCRPC_CHAINED}〔|DCRPC_TPNOTRAN〕〔|DCRPC_DOMAIN〕
DCRPC_TPNOTRANとDCRPC_DOMAINは,RPCの形態に付けて設定します。
サーバUAPから値が返される引数
●out
サービス関数が設定した,応答が返されます。
●out_len
サービス関数が設定した,応答の長さが返されます。
リターン値
ここで示すリターン値は,OpenTP1が返す値です。サービス関数から返される値ではありません。
リターン値 | リターン値(数値) | 意味 |
---|---|---|
0または正の整数 | 正常に終了しました。非同期応答型RPCの場合は,正の整数は記述子です。 | |
DCRPCER_INVALID_ARGS | -301 | 引数に設定した値が間違っています。 |
DCRPCER_PROTO | -302 | dc_rpc_open関数を呼び出していません。 |
DCRPCER_NO_BUFS | -304 | メモリが不足しました。または,サービス要求先SPPのメッセージ格納バッファプール(message_store_buflenオペランド)が不足したため,サービス要求を受け付けられませんでした。 サービス要求先SPPのユーザサービス定義,またはユーザサービスデフォルト定義のmessage_store_buflenオペランドの指定値を見直してください。 |
DCRPCER_NET_DOWN | -306 | 通信障害が起こりました。 ネットワークに障害が発生していないか確認してください。 |
リモートAPI機能を使用している場合は,dc_rpc_call関数の応答待ち時間を満了した可能性があります。 dc_rpc_call関数の応答待ち時間の設定(watch_timeオペランド,dc_rpc_set_watch_time関数の引数)を見直してください。 リモートAPI機能使用時にdc_rpc_call関数の応答待ち時間を満了した場合のリターン値をDCRPCER_TIMED_OUTに変更するには,ユーザサービス定義にrap_extend_functionオペランドを指定してください。rap_extend_functionオペランドについてはマニュアル「OpenTP1 システム定義」を参照してください。 | ||
DCRPCER_TIMED_OUT | -307 | dc_rpc_call関数の応答待ち時間を満了しました。 dc_rpc_call関数の応答待ち時間の設定(watch_timeオペランド,dc_rpc_set_watch_time関数の引数)を見直してください。 |
サービス要求先SPPが,サービス関数の実行中に異常終了しました。 サービス要求先SPPが異常終了した要因を調査してください。 | ||
DCRPCER_MESSAGE_TOO_BIG | -308 | in_lenに設定した入力パラメタ長が,最大値を超えています。 in_lenの設定値を見直してください。 |
DCRPCER_REPLY_TOO_BIG | -309 | サービス要求先SPPのサービス関数で設定した応答の長さ(out_len)が,dc_rpc_call関数の応答の長さ(out_len)を超えました。 サービス要求先SPPのサービス関数での応答の長さ(out_len)の設定を見直してください。 |
DCRPCER_NO_SUCH_SERVICE_GROUP | -310 | groupに設定したサービスグループ名が不正であるか,groupに設定したサービスグループのサービス要求先SPPが起動されていません。 groupの設定を見直すか,groupに設定したサービスグループのサービス要求先SPPを起動してください。 |
DCRPCER_NO_SUCH_SERVICE | -311 | serviceに設定したサービス名が不正であるか,サービス要求先SPPでserviceに設定したサービス名がユーザサービス定義ファイルのserviceオペランドに設定されていません。 serviceの設定を見直すか,serviceに設定したサービス名をサービス要求先SPPのserviceオペランドに設定してください。 |
DCRPCER_SERVICE_CLOSED | -312 | groupで設定したサービスグループのサービス要求先SPPは,サーバ閉塞またはサービス閉塞しています。 閉塞要因を調査し,閉塞を解除してください。 |
DCRPCER_SERVICE_TERMINATING | -313 | サービス要求先SPPは,終了処理中です。 |
DCRPCER_SERVICE_NOT_UP | -314 | groupに設定したサービスグループ名のサービス要求先SPPは起動していません。または,サービス要求送信処理で通信障害が起きたおそれがあります。 groupに設定したサービスグループ名のサービス要求先SPPを起動してください。すでに起動している場合は,ネットワーク障害が発生していないかを確認してください。 |
サービス要求の応答待ち時間(watch_timeオペランド,dc_rpc_set_watch_time関数の引数)に0を指定している場合に,サービス関数を実行中のサービス要求先SPPが異常終了しました。 サービス要求先SPPが異常終了した要因を調査してください。 | ||
DCRPCER_OLTF_NOT_UP | -315 | サービス要求先SPPのOpenTP1が起動していません。OpenTP1が停止処理中であるか,サービス要求送信処理で通信障害が起きたおそれがあります。 サービス要求先SPPのOpenTP1を起動するか,ネットワーク障害が発生していないかどうかを確認してください。 |
DCRPCER_SYSERR_AT_SERVER | -316 | サービス要求先SPPで,システムエラー(内部矛盾)が起こりました。 |
DCRPCER_NO_BUFS_AT_SERVER | -317 | サービス要求先SPPで,メモリが不足しました。 |
DCRPCER_SYSERR | -318 | サービス要求元UAPで,システムエラー(内部矛盾)が起こりました。 |
DCRPCER_INVALID_REPLY | -319 | サービス要求先SPPのサービス関数で設定する応答の長さ(out_len)が,1からDCRPC_MAX_MESSAGE_SIZE※で定義されている値の範囲にありません。 サービス要求先SPPのサービス関数内の応答の長さ(out_len)の設定を見直してください。 |
DCRPCER_OLTF_INITIALIZING | -320 | サービス要求先SPPのOpenTP1は,開始処理中です。 |
DCRPCER_NO_BUFS_RB | -323 | サービス要求元UAP,またはサービス要求先SPPで,メモリが不足しました。このリターン値が返った場合,トランザクションブランチはロールバックします。 サービス要求元UAP,またはサービス要求先SPPで,不要なメモリを確保していないか見直してください。 |
DCRPCER_SYSERR_RB | -324 | サービス要求元UAPで,システムエラー(内部矛盾)が起こりました。このリターン値が返った場合,トランザクションブランチはロールバックします。 |
DCRPCER_SYSERR_AT_SERVER_RB | -325 | サービス要求先SPPで,システムエラー(内部矛盾)が起こりました。このリターン値が返った場合,トランザクションブランチはロールバックします。 |
DCRPCER_REPLY_TOO_BIG_RB | -326 | サービス要求先SPPのサービス関数で設定した応答の長さ(out_len)が,dc_rpc_call関数の応答の長さ(out_len)を超えました。このリターン値が返った場合,トランザクションブランチはロールバックします。 サービス要求先SPPのサービス関数で,応答の長さ(out_len)の設定を見直してください。 |
DCRPCER_TRNCHK | -327 | ノード間負荷バランス機能,およびノード間負荷バランス拡張機能を使用している場合に,同一サービスグループ名のサービス要求先SPPのトランザクション属性(atomic_updateオペランド)が不一致になっています。または,負荷を分散する先のノードにあるOpenTP1のバージョンが,要求元UAPのOpenTP1のバージョンよりも古いため,ノード間負荷バランス機能,およびノード間負荷バランス拡張機能を実行できません。 このリターン値が返るのは,ノード間負荷バランス機能およびノード間負荷バランス拡張機能を使用しているSPPにサービスを要求した場合だけです。 ノード間負荷バランス機能,およびノード間負荷バランス拡張機能を使用するSPPのトランザクション属性(atomic_updateオペランド),またはOpenTP1のバージョンを見直してください。 |
dcsvgdef定義コマンドを使用して,非トランザクション属性(ユーザサービス定義のatomic_updateオペランドに'N'を指定,またはシステム共通定義のjnl_fileless_optionオペランドに'Y'を指定)のユーザサーバに対し,dc_rpc_call関数のflagsにDCRPC_TPNOTRANとの論理和を指定しないでサービスを要求しました。 dcsvgdef定義コマンドまたは,dc_rpc_call関数のflagsを見直してください | ||
DCRPCER_NO_SUCH_DOMAIN | -328 | groupのドメイン修飾をしたサービスグループ名のドメイン名が間違っています。 ドメイン名を見直してください。 |
DCRPCER_NO_PORT | -329 | groupにドメイン修飾をしてサービスを要求しましたが,ドメイン代表スケジュールサービスのポート番号が見つかりません。 システム共通定義のdomain_masters_portオペランドの設定,および/etc/servicesのドメイン代表スケジュールサービスのポート番号の設定を見直してください。 |
DCRPCER_SERVER_BUSY | -356 | サービス要求先SPP(ソケット受信型サーバ)が,サービス要求を受け取れません。 サービス要求先SPPのユーザサービス定義,またはユーザサービスデフォルト定義のmax_socket_msgオペランド,max_socket_msglenオペランドの設定を見直してください。 |
DCRPCER_TESTMODE | -366 | オンラインテスタを使用している環境で,テストモードのUAPから,テストモードでないSPPへサービスを要求しています。または,テストモードでないUAPからテストモードのSPPへサービスを要求しています。 UAPのテストモードの設定を見直してください。 |
DCRPCER_NOT_TRN_EXTEND | -367 | トランザクション属性の連鎖RPCを実行したあとで,flagsにDCRPC_TPNOTRANを設定し,dc_rpc_call関数でサービスを要求しています。 |
DCRPCER_SECCHK | -370 | サービス要求先SPPは,セキュリティ機能で保護されています。 dc_rpc_call関数を実行したサービス要求元UAPには,サービス要求先SPPへのアクセス権限がありません。サービス要求先SPPのアクセス権限を見直してください。 |
DCRPCER_TRNCHK_EXTEND | -372 | サービス要求先SPPのOpenTP1で,同時に起動できるトランザクションブランチの数を超えました。そのため,トランザクションブランチを開始できません。 トランザクションサービス定義のtrn_tran_process_countオペランドの設定を見直してください。 |
サービス要求元UAPが,一つのトランザクションブランチから開始できる子トランザクションブランチの最大数を超えました。そのため,トランザクションブランチを開始できません。 トランザクションサービス定義のtrn_max_subordinate_countオペランドの設定を見直してください。 | ||
トランザクション内のドメイン修飾をしたサービス要求で,flagsにDCRPC_TPNOTRANを設定していません。 | ||
サービス要求先SPPで,リソースマネジャ(RM)にエラーが発生しました。そのため,トランザクションブランチを開始できません。 リソースマネジャ(RM)のエラー要因を解決したあと,再度実行してください。 | ||
TP1/LiNKの「システム環境設定」ウィンドウの「トランザクション機能」が[あり]に設定されていません。 TP1/LiNKの「システム環境設定」の「トランザクション機能」の設定を見直してください。 | ||
DCRPCER_SERVICE_TERMINATED | -378 | サービス要求先SPPが,サービス関数の実行中に異常終了しました。 サービス要求先SPPのサービス関数処理を見直してください。このリターン値が返るのは,ユーザサービス定義のrpc_extend_functionオペランドに"00000001"を指定したサービス要求元UAPの場合だけです。rpc_extend_functionオペランドに"00000000"を指定,またはオペランドを省略した場合は,このリターン値ではなく,DCRPCER_TIMED_OUT,またはDCRPCER_SERVICE_NOT_UPが返ります。 |
(1)dc_rpc_call関数の引数について
dc_rpc_call関数の引数について説明します。
サーバUAPに渡す値
サービスを要求するときは,サービス関数から返ってくる応答の領域(out)を確保しておきます。クライアントUAPでは,dc_rpc_call関数に次の値を設定しておきます。
サーバUAPから戻ってくる値
サービス関数の処理が終了して応答が戻ってくると,次の値を参照できます。
out_len はサービス関数から実際に返ってきた応答の長さです。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関数の実行結果について説明します。
(2)dc_rpc_call関数がエラーになる場合
dc_rpc_call関数のエラーリターンする理由について説明します。
サーバUAPがあるノードのOpenTP1が稼働していない場合
サービスを要求されるOpenTP1が稼働していない場合は,dc_rpc_call関数は次に示すリターン値のどれかでエラーリターンします。
サーバUAPが稼働していない場合
サーバUAPがマルチサーバの場合,異常終了中,または部分回復処理中であっても,サービス要求はOpenTP1で新しく起動されたプロセスで実行されます。ただし,次に示す場合は,dc_rpc_call関数はエラーリターンします。
ノード間負荷バランス機能およびノード間負荷バランス拡張機能の環境でサービスを要求した場合
ノード間負荷バランス機能およびノード間負荷バランス拡張機能の環境では,該当するサービスのスケジュールが閉塞していると,OpenTP1が自動的にほかのノードにサービス要求を転送します。ただし,次に示す条件の場合dc_rpc_call関数はDCRPCER_TRNCHKでエラーリターンします。
これらのエラーリターンが起こった場合は,次に示す処置をしてください。
ソケット受信型サーバへサービスを要求する場合
ソケット受信型サーバでは,ユーザサービス定義の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でエラーリターンします。
(3)dc_rpc_call関数がエラーになるタイミング
サービスを要求されたSPPが異常終了した場合,クライアントUAPでエラーが返るタイミングについて説明します。
クライアントUAPの時間監視でエラーになる場合
次に示す場合には,クライアントUAPのユーザサービス定義のwatch_timeオペランドに指定した時間が経過したあとで,DCRPCER_TIMED_OUTでエラーリターンします。
(4)dc_rpc_call関数がエラーになったときに再実行する指定
開始処理中,または系切り替え中などでサービス要求先のOpenTP1が起動していない場合でも,dc_rpc_call関数をエラーとしないで,OpenTP1で要求先検索,およびサービス要求送信を再実行させられます。
要求先検索,およびサービス要求送信を再実行させる場合は,システム共通定義のrpc_retryオペランドにYを指定してください。要求先検索とサービス要求送信の再実行回数,および再実行間隔は,システム共通定義のrpc_retry_countオペランドとrpc_retry_intervalオペランドで指定します。システム共通定義で指定した再実行回数を超えた場合は,dc_rpc_call関数は次に示すどれかのステータスコードでエラーリターンします。
(5)サービス要求に優先度を付ける場合
サービス要求のスケジュールプライオリティは,dc_rpc_call関数を呼び出す直前に,dc_rpc_set_service_prio関数を呼び出して設定します。プライオリティを設定しない場合は,スケジュールサービスの省略時の解釈で,サービス要求の優先度が決まります。
(6)リターン値DCRPCER_NO_SUCH_SERVICE_GROUPとDCRPCER_NET_DOWNの違い
上記のリターン値は,該当するサービスグループ名のユーザサーバが見つからなかった場合にリターンされます。
(7)リターン値 DCRPCER_SERVICE_TERMINATED をリターンさせる指定
サービスを要求されたSPPが,処理を完了する前に異常終了したことをDCRPCER_TIMED_OUTまたはDCRPCER_SERVICE_NOT_UP以外のリターン値で判別したい場合には,ユーザサービス定義のrpc_extend_functionオペランドに"00000001"を指定します。この指定をすると,上記のエラー時にDCRPCER_SERVICE_TERMINATEDがリターンされるようになります。rpc_extend_functionオペランドに"00000000"を指定するか,またはオペランドを省略した場合は,DCRPCER_SERVICE_TERMINATED は返らないで,DCRPCER_TIMED_OUT またはDCRPCER_SERVICE_NOT_UPがリターンされます。
(8)エラーリターン値と同期点処理の関係
dc_rpc_call関数のリターン値と同期点処理(コミット,ロールバック)の関係について説明します。ここで説明する内容は,サービス要求がトランザクション処理になる場合に該当します。トランザクションでないサービス要求(flagsにDCRPC_TPNOTRANを設定した場合も含む)には該当しません。
dc_rpc_call関数がエラーリターンしてもコミットとなる場合
サービスを要求されたサービス関数の異常終了や,ノードの障害,ネットワーク障害の場合でも,DCRPCER_TIMED_OUTがリターンすることがあります。クライアントUAPがトランザクション処理でない場合は,DCRPCER_TIMED_OUTが返っても,要求したサービスがあるサービス関数は正常に終了していて,データベースへの更新などが実行されているときもあります。
ロールバック処理が必要なエラーリターン値
トランザクション処理から呼び出したdc_rpc_call関数がエラーリターンした場合,リターン値によっては,必ずトランザクションがロールバック(サーバUAPがrollback_only状態)になります。この場合,コミットの関数,またはロールバックの関数のどちらを使っても,必ずロールバックになります。必ずロールバックになるdc_rpc_call関数のリターン値を次に示します。
(9)サービスを要求するときの注意
(10)ドメイン修飾をしてサービスを要求する場合
ドメイン修飾したサービスグループ名を設定すると,DNSのドメイン内にあるOpenTP1のサービスを要求できます。ドメイン修飾をしたサービスグループ名は,サービスグループ名の後ろに,@とDNSのドメイン名を付けて設定します。
ドメイン修飾をしてサービスを要求するときの注意
ドメイン修飾をしたサービス要求をする前の準備
ドメイン修飾をしたRPCでは,次に示す環境設定をしてください。
OpenTP1scd ポート番号/tcp
注意事項
システム共通定義のall_nodeオペランドで指定したドメイン以外のOpenTP1システムにトランザクショナルRPCを行う場合,自ドメインおよび他ドメイン内のすべてのOpenTP1システムのノード識別子(システム共通定義のnode_idオペランド)は一意にする必要があります。また,すべてのOpenTP1システムは,バージョン03-02以降にする必要があります。これらの条件を満たしていないと,トランザクションが正しく回復できなくなる場合があります。