7.2.4 電文情報設定UOC
機能
電文情報設定UOCは、電文のテスト要否、およびシステム検証支援の処理に必要な電文情報を指定するUOCです。
形式
ANSI C、C++の形式
#include <esplg_uoc.h> ESLONG uoc_func（struct es_plg_uoc_info *parm）
「uoc_func」部分には、システム内で一意の名称を指定してください。
説明
電文入力時に呼び出されるUOCです。
テスト比較支援機能のプラグイン使用時は、電文のキャプチャまたは受信に失敗した場合にも、本UOCが呼び出されます。この場合、電文の情報（ペアリングキー、クライアント識別子、要求電文種別）を設定する必要はありません。必要に応じて後処理（独自確保したリソースの解放等）のみを行ってください。
各実行形態と入力電文によるUOC実行の有無を以下に示します。
|
- |
本番環境 |
テスト環境 |
||
|---|---|---|---|---|
|
要求電文 |
応答電文 |
要求電文 |
応答電文 |
|
|
電文作成フェーズ（PCAP） |
○ |
○ |
- |
- |
|
電文作成フェーズ（キャプチャ） |
○ |
○ |
- |
- |
|
電文実行モード |
○ |
○ |
× |
○ |
- （凡例）
-
○：UOCが実行される
×：UOCは実行されない
電文情報設定UOCでは、電文について以下の情報を設定する必要があります。
-
ペアリングキー（プロトコルがTCPの場合）
-
クライアント識別子
-
要求電文種別（外部システムから既存システムへの電文の場合）
- ペアリングキーの判定
-
プロトコルがTCPの場合、UOCでは、要求電文と応答電文を関連付けるためのペアリングキーを指定する必要があります。同じペアリングキーを持つ要求電文と応答電文が揃うと、システム検証支援は電文比較UOCを呼び出して電文を比較します。
また、要求電文を電文組立UOCで組立後、framework_definition定義-t reply_watchtimeオペランドに指定した時間経過すると応答待ちタイムアウトとなり、要求電文を破棄します。タイムアウト後に応答電文を受信した場合、応答電文を破棄します。
- クライアント識別子の判定
-
UOCでは、電文のクライアント識別子を指定する必要があります。システム検証支援ではクライアント識別子単位にシリアライズして電文を送信します。依存関係がある電文には同じクライアント識別子を指定してください。プロトコルがTCPまたはHTTPの場合、デフォルト値としてパケットを送信したTCPコネクション（外部システム側のIPアドレス＋ポート番号と、既存システムのIPアドレス＋ポート番号の組み合わせ）を指定しています。プロトコルがRPCの場合、デフォルト値として外部システムのIPアドレス、外部システムの受信ポート番号、送信元スレッドIDを連結した値を指定しています。
- 要求電文種別の判定
-
プロトコルがTCPの場合、UOCでは、外部システムから既存システムへの電文に対して、要求電文種別を指定する必要があります。応答を待ち合わせる必要のある要求電文（同期要求電文）か、待ち合わせる必要がない要求電文（非応答要求電文）かを指定します。
パラメタの内容
es_plg_uoc_infoのパラメタ内容
typedef struct es_plg_uoc_info {
ESULONG run_mode; ………………… 実行形態
ESULONG protocol; ………………… プロトコル種別
unsigned char msgtype; ………………… 電文種別
unsigned char reqtype; ………………… 要求電文種別
char reserve[2]; ……………… 予備領域
ESULONG error_flg; ……………… エラー情報
ESCOM_IPADDR src_ip; ……………… 送信元IPアドレス
ESCOM_IPADDR dst_ip; ……………… 送信先IPアドレス
unsigned short src_port; ………………… 送信元ポート番号
unsigned short dst_port; ………………… 送信先ポート番号
char reserve2[4]; …………… 予備領域
ESCOM_AREA usr_tel_area; ………… 電文単位ユーザ領域
char usr_tel_area_state; ………… 電文単位ユーザ領域の状態
char reserve3[7]; …………… 予備領域
ESCOM_AREA usr_con_area; ……… コネクション単位ユーザ領域
char usr_con_area_state; ……… コネクション単位ユーザ領域の状態
char reserve4[7]; …………… 予備領域
ESCOM_AREA telegram; …… 電文情報
ESPLG_UOC_TELSIZE telegram_size; … 電文サイズ
char client_id[16]; ………… クライアント識別子
ESLONG rtn_detail; ………… 詳細エラーコード
char reserve 5[4]; …………… 予備領域
char key[64]; ……………… ペアリングキー
void *protoinf; ……………… プロトコル情報(参照出来ません)
ESULONG abort_code; …………… 強制停止理由コード
char reserve6[4]; …………… 予備領域
void *protocol_telinf ……… プロトコル固有情報
} ESPLG_UOC_INFO;
es_com_ipaddr（ESCOM_IPADDR）のパラメタ内容
typedef union es_com_ipaddr{
ESCOM_IPV4 ipv4; ……………… IPアドレス（IPv4）
char reserve[16]; ……………… 予備領域
} ESCOM_IPADDR;
es_com_ipv4（ESCOM_IPV4）のパラメタ内容
typedef struct es_com_ipv4 {
char reserve[12]; ……………… 予備領域
char ip[4]; ……………… IPアドレス（IPv4）
} ESCOM_IPV4;
es_com_area（ESCOM_AREA）のパラメタ内容
typedef struct es_com_area {
ESULONG size; ……………… 領域サイズ
char reserve[4]; ……………… 予備領域
char *data; ……………… 領域先頭アドレス
} ESCOM_AREA;
es_frw_telegram_rpc（ESFRW_TELEGRAM_RPC）のパラメタ内容
typedef struct es_frw_telegram_rpc {
char protocol_type; ………… プロトコル詳細種別
char clt_nid[5]; ………… クライアント側ノードID
char srv_nid[5]; ………… サーバ側ノードID
char reserve1[5]; ………… 予備領域
char group[32]; ………… サービスグループ名
char service[32]; ………… サービス名
ESLONG rtncode; ………… RPCリターンコード
ESULONG out_len; ………… 応答データ長
} ESFRW_TELEGRAM_RPC;
ESPLG_UOC_TELSIZEのパラメタ内容
typedef union {
ESPLG_UOC_HTTPSIZE http_size; …………HTTPプロトコルのサイズ格納領域
ESPLG_UOC_TCPSIZE tcp_size; …………TCPプロトコルのサイズ格納領域
} ESPLG_UOC_TELSIZE;
ESPLG_UOC_HTTPSIZEのパラメタ内容
typedef struct es_plg_uoc_httpsize{
ESULONG header_size; …………HTTPヘッダ部サイズ
ESULONG body_size; …………HTTPボディ部サイズ
} ESPLG_UOC_HTTPSIZE;
ESPLG_UOC_TCPSIZEのパラメタ内容
typedef struct es_plg_uoc_tcpsize{
ESULONG size; …………電文サイズ
char reserve[4];
} ESPLG_UOC_TCPSIZE;
システム検証支援が値を設定するパラメタ項目
- run_mode
-
システム検証支援の実行形態を設定します。
ESFRW_RUNMODE_CREATE_C：電文作成フェーズ（PCAP）
ESFRW_RUNMODE_CREATE_A：電文作成フェーズ（キャプチャ）
ESFRW_RUNMODE_TEST_R：テスト実行フェーズ
ESFRW_RUNMODE_TEST_C：テスト実行フェーズ（PCAP）
- protocol
-
プロトコル種別を設定します。
ESFRW_PROT_TCP：TCP
ESFRW_PROT_HTTP：HTTP
ESFRW_PROT_RPC：RPC
- msgtype
-
電文種別を設定します。
ESFRW_MSGTYPE_REQUEST_PRO：要求電文（本番環境）
ESFRW_MSGTYPE_RESPONSE_PRO：応答電文（本番環境）
ESFRW_MSGTYPE_RESPONSE_TST：応答電文（テスト環境）
- reqtype
-
プロトコル種別がESFRW_PROT_TCPの場合、ユーザが設定する値です。
システム検証支援はデフォルト値 ESFRW_MSGFORM_SYNC_ANSWER（同期応答型）を設定します。
-
プロトコル種別がESFRW_PROT_HTTPの場合、次のように設定します。
ESFRW_MSGFORM_SYNC_ANSWER：同期応答型
-
プロトコル種別がESFRW_PROT_RPCの場合、次のどれかを設定します。
ESFRW_MSGFORM_SYNC_ANSWER：同期応答型
ESFRW_MSGFORM_NOANSWER：非応答型
ESFRW_MSGFORM_NOSYNC_ANSWER：非同期応答型
-
- error_flg
-
システム検証支援が検知したエラー有無、およびエラー内容を設定します。以下のいずれかとなります。
ESFRW_ERROR_NONE：エラー無し
ESFRW_ERROR_RECV_CON：コネクション切断による受信・不可
ESFRW_ERROR_RECV_LOST：パケットロスト発生
ESFRW_ERROR_BUILD_TIMEOUT：電文組立中の後続パケット待ちタイムアウト
ESFRW_ERROR_RECV_TIMEOUT：応答待ちタイムアウトによる受信不可
設定値がESFRW_ERROR_NONE以外の場合、以下に示すパラメタだけ参照・設定可能です。
-
参照可能なパラメタ
run_mode
protocol
msgtype
reqtype
src_ip
dst_ip
src_port
dst_port
-
設定可能なパラメタ
abort_code
上記以外のパラメタは参照・設定しないでください。
-
- src_ip
-
電文の送信元のIPアドレスを設定します。（※1）
- dst_ip
-
電文の送信先のIPアドレスを設定します。（※1）
- src_port
-
電文の送信元のポート番号をホストバイトオーダーで設定します。
- dst_port
-
電文の送信先のポート番号をホストバイトオーダーで設定します。
- usr_tel_area
-
電文単位に共有するユーザ領域を設定します。
各メンバには以下の値が設定されています。
-
size
電文単位ユーザ領域のサイズを設定します。
-
data
電文単位ユーザ領域の先頭アドレスを設定します。
-
- usr_tel_area_state
-
電文単位ユーザ領域の状態を設定します。電文単位ユーザ領域の状態は電文単位ユーザ領域の領域サイズが0以外のときに設定します。
-
ESFRW_CONTST_NEW
新規に割当てられた領域であることを示します。
-
ESFRW_CONTST_RENEW
処理済みとなった電文のユーザ領域が再割当てされて、通知されたことを示します。ユーザ領域内には現在処理している電文とは無関係の情報が設定されている場合があります。必要に応じて、ユーザ領域に残っている必要な情報の退避、および初期化等を実施して使用してください。
-
ESFRW_CONTST_CONTINUE
当該電文のユーザ領域として、UOCに通知済の領域であることを示します。以前に通知された際に情報を設定していれば、参照することができます。
-
- usr_con_area
-
コネクション単位で共有するユーザ領域を設定します。
各メンバには以下の値が設定されています。
-
size
コネクション単位ユーザ領域のサイズを設定します。
-
data
コネクション単位ユーザ領域の先頭アドレスを設定します。
-
- usr_con_area_state
-
コネクション単位ユーザ領域の状態を設定します。コネクション単位ユーザ領域の状態はコネクション単位ユーザ領域の領域サイズが0以外のときに設定します。
-
ESFRW_CONTST_NEW
新規に割当てられた領域であることを示します。
-
ESFRW_CONTST_RENEW
切断されたコネクションのユーザ領域が再割当てされて、通知されたことを示します。ユーザ領域内には現在のコネクションとは無関係の情報が設定されている場合があります。必要に応じて、ユーザ領域に残っている必要な情報の退避、および初期化等を実施して使用してください。
-
ESFRW_CONTST_CONTINUE
当該コネクションのユーザ領域として、UOCに通知済の領域であることを示します。以前に通知された際に情報を設定していれば、参照することができます。
-
- telegram
-
入力電文に関する情報を設定します。
各メンバには以下の値が設定されています。
-
size
入力電文のサイズを設定します。
-
data
入力電文の先頭アドレスを設定します。
-
- telegram_size
-
プロトコルに応じて入力電文のサイズをESPLG_UOC_TELSIZE形式で設定します。
- client_id
-
ユーザが設定する値です。
システム検証支援はプロトコル種別に応じてデフォルト値を設定します。
プロトコル種別がESFRW_PROT_TCPまたはESFRW_PROT_HTTPの場合、コネクションごとにユニークとなる値を設定します。
プロトコル種別がESFRW_PROT_RPCの場合、外部システムのIPアドレス、外部システムの受信ポート番号、送信元スレッドIDを連結した値を設定します。
なお、framework_definition定義で、-uオプションのipaddr_serializeフラグメンバ値にYを指定した場合は、デフォルト値として外部システムのIPアドレスごとにユニークとなる値を設定します。
- key
-
プロトコル種別がESFRW_PROT_TCPの場合、ユーザが設定する値です。
以下の条件を全て満たす場合、システム検証支援では、デフォルト値として、蓄積ファイル内の電文情報の電文キー値を設定します。
-
テスト実行フェーズ
-
電文ファイルの種別が蓄積ファイル（framework_definition定義の-fオプションのtelegram_file_typeフラグメンバに"afl"を指定）
-
蓄積ファイル内の電文情報に電文キーが設定されている
上記の条件を満たさない場合は、デフォルト値として、コネクション毎にユニークとなる値を設定します。このデフォルト値を使用した場合、同一コネクションの要求電文と応答電文がペアリングされます。
-
- protocol_telinf
-
プロトコル固有の情報を格納した構造体のアドレスを設定します。各プロトコル用の構造体にキャストして使用してください。
-
プロトコル種別がESFRW_PROT_RPCの場合： ESFRW_TELEGRAM_RPC
-
プロトコル種別がESFRW_PROT_TCPまたはESFRW_PROT_HTTPの場合：NULL
-
- 注※1：
-
IPアドレスは、次に示す形式で設定します。
IPv4の場合
例） 送信元IPが172.165.112.20の場合
![[図データ]](GRAPHICS/F0000096.GIF)
- protocol_type
-
RPCのプロトコル詳細種別を設定します。
ESFRW_PROT_RPC_RPC：RPC
ESFRW_PROT_RPC_RAP：RAP
- clt_nid
-
要求電文（本番環境）の場合：クライアント側のノードIDを設定します。
要求電文（本番環境）以外、または電文内にノードIDが格納されていない場合：NULLを設定します。
- srv_nid
-
応答電文の場合：サーバ側のノードIDを設定します。
応答電文以外の場合：NULLを設定します。
- group
-
要求電文の場合：サービスグループ名を設定します。
それ以外の場合：NULLを設定します。
- service
-
要求電文の場合：サービス名を設定します。
要求電文以外の場合：NULLを設定します。
- rtncode
-
応答電文の場合：サーバ側が設定したRPCリターンコード（dc_rpc_call()等のリターン値）を設定します。
応答電文以外の場合：0を設定します。
- out_len
-
応答型の要求電文の場合：応答データ長（dc_rpc_call()等で指定したout_len値）を設定します。
応答型の要求電文以外の場合：0を設定します。
ユーザが設定するパラメタ項目
- reqtype
-
要求電文の種別を指定できます。指定できる電文種別は以下の通りです。
-
ESFRW_MSGFORM_SYNC_ANSWER：同期応答型
-
ESFRW_MSGFORM_NOANSWER：非応答型
テスト対象システムからの応答電文を待ち合わせる必要がない場合はESFRW_MSGFORM_NOANSWERを指定してください。
要求電文種別は以下の条件を全て満たす場合に設定してください。
-
プロトコル種別がTCP
-
要求電文（本番環境）
条件を満たさない場合、設定する必要はありません。システムテスト支援は設定値を無視します。
-
- client_id
-
電文のクライアント識別子を指定できます。以下の条件を全て満たす場合に設定してください。
-
テスト実行フェーズ（逐次実行モード）
-
要求電文（本番環境）
条件を満たさない場合、設定する必要はありません。システムテスト支援は設定値を無視します。
-
- rtn_detail
-
詳細エラーコードを-2147483648 〜 2147483647の範囲で設定できます。このコードはUOCがES_UOC_NGをリターンしたときにシステム検証支援に返されます。システム検証支援は詳細エラーコードをメッセージログファイルに出力します。
- key
-
ペアリングキーを指定できます。プロトコル種別がTCPの場合だけ設定してください。プロトコル種別がTCP以外のときは、設定する必要はありません。システムテスト支援は設定値を無視します。
- abort_code
-
システム検証支援を強制停止する理由を示すコードを0 ～ 4294967295の範囲で設定できます。
このコードはUOCがESPLG_UOC_ABORTをリターンしたときのみ有効です。システム検証支援は強制停止理由コードをKFSE64109-Eメッセージに出力します。
ユーザが設定する項目と電文のプロトコルとリターン値の関係
- 電文のプロトコルがTCPの場合
-
電文のプロトコルがTCPの場合に、ユーザが設定する項目とリターン値の関係を次に示します。
項目
リターン値
ESPLG_UOC_OK
ESPLG_UOC_MSG_DESTRUCT
ESPLG_UOC_NG
ESPLG_UOC_ABORT
要求電文種別
○※
×
×
×
クライアント識別子
○
×
×
×
詳細エラーコード
×
×
○
×
ペアリングキー
○
×
×
×
強制停止理由コード
×
×
×
○
- （凡例）
-
○：指定可能
×：指定不可（指定値は無視します）
- 注※
-
パケットの電文種別がESFRW_MSGTYPE_REQUEST_PROの場合に有効となります。
- 電文のプロトコルがHTTPの場合
-
電文のプロトコルがHTTPの場合に、ユーザが設定する項目とリターン値の関係を次に示します。
項目
リターン値
ESPLG_UOC_OK
ESPLG_UOC_MSG_DESTRUCT
ESPLG_UOC_NG
ESPLG_UOC_ABORT
要求電文種別
×
×
×
×
クライアント識別子
○
×
×
×
詳細エラーコード
×
×
○
×
ペアリングキー
×
×
×
×
強制停止理由コード
×
×
×
○
- （凡例）
-
○：指定可能
×：指定不可（指定値は無視します）
- 電文のプロトコルがRPCの場合
-
電文のプロトコルがRPCの場合に、ユーザが設定する項目とリターン値の関係を次に示します。
|
項目 |
リターン値 |
|||
|---|---|---|---|---|
|
ESPLG_UOC_OK |
ESPLG_UOC_MSG_DESTRUCT |
ESPLG_UOC_NG |
ESPLG_UOC_ABORT |
|
|
要求電文種別 |
× |
× |
× |
× |
|
クライアント識別子 |
○ |
× |
× |
× |
|
詳細エラーコード |
× |
× |
○ |
× |
|
ペアリングキー |
× |
× |
× |
× |
|
強制停止理由コード |
× |
× |
× |
○ |
- （凡例）
-
○：指定可能
×：指定不可（指定値は無視します）
リターン値
次のコードでリターン値を設定してください。
- ESPLG_UOC_OK
-
正常に電文情報を設定しました。
- ESPLG_UOC_MSG_DESTRUCT
-
電文を破棄します。
- ESPLG_UOC_ABORT
-
電文を強制停止します。
- ESPLG_UOC_NG
-
電文情報設定時にでエラーが発生しました。電文を破棄します。
- 上記以外
-
指定リターン値以外でリターンした場合、電文を破棄します。
注意事項
-
UOCで設定した値に不正があった場合、システム検証支援はメッセージログを出力し、対象の電文を破棄します。
-
パラメタerror_flgの値によってUOCリターン時の動作が異なります。
error_flgの値
動作
ESFRW_ERROR_NONE
- リターン値ESPLG_UOC_NGでリターンした場合
-
UOCからESPLG_UOC_NGでリターンした場合、システム検証支援はメッセージログを出力し、対象のメッセージを破棄します。
- リターン値ESPLG_UOC_ABORTでリターンした場合
-
システム検証支援はKFSE64109-Eメッセージを出力し、システム検証支援プロセスを強制停止します。
- UOCパラメタ不正の場合
-
UOCで設定した値に不正があった場合、システム検証支援はメッセージログを出力し、対象の電文を破棄します。
ESFRW_ERROR_NONE以外
- リターン値ESPLG_UOC_OKでリターンした場合
-
システム検証支援は処理を続行します。
- リターン値ESPLG_UOC_ABORTでリターンした場合
-
システム検証支援はKFSE64109-Eメッセージを出力し、システム検証支援プロセスを強制停止します。
- 上記以外の場合
-
システム検証支援は処理を続行します。