4.2.3 KC RECEIVE

画面データの受信

【呼出形式（C）】

UINT  XWSIAPI
XWSI_KC_RECV(ReqHandle,ws_errno,recv_inf,code_type,gaiji,emu_end_status,dev_status,data_kind,recv_buffer）

USHORT            ReqHandle         リクエストハンドル
UINT             *ws_errno          処理結果
XWsiTrnsInf      *recv_inf          受信タイミング
USHORT            code_type         コード変換タイプ
USHORT            gaiji             漢字変換指定
USHORT           *emu_end_status    DSPEMU終了情報
XWsiLine25Inf    *dev_status        デバイス状態情報
USHORT            data_kind         受信データ種別
XWsiRecvText    **recv_buffer       画面バッファ

【機能】

現時点の画面バッファ、デバイス状態情報を受け取ります。獲得した画面バッファは、アプリケーションが不必要になった時点でWSMGR FREEで開放してください。

ディスプレイエミュレータでは、目で画面を見るのと同じことをAPI として提供しています。

KC RECEIVEには、WAITモードとNON WAITモードの2つのモードがあります。

(recv_inf.modeで指定します）。WAITモードは、キー入力が可能な状態になるまで待ち、そのときの画面データの内容を返すモードです。これはホストからのデータが分割されてWRITE された場合、画面が全部揃ったことをキーボードアンロックで認識することができます。

(1) WAITモードタイミングチャート

KC SEND でも述べたように、キーボードロックは途中で瞬間はずれることがあるので、それを解決するために key_unlock_timeを指定します。

詳しくは、「4.2.2 KC SEND」を参照してください。

NON WAITモードは、アプリケーションから依頼があったときに画面データを取り込むモードです。

KC ESTART でディスプレイエミュレータを起動している場合、ディスプレイエミュレータの終了キーが押されたことを受け取ることはできますが終了はされません。ディスプレイエミュレータを終了したい場合は、KC EEND を行ってください。

画面データを受け取るほかに、dev_statusとして、通常ディスプレイエミュレータで表示されている25行目の情報をコード化して通知します。この情報により、ホストとの接続状態を詳細に知ることができます。

アプリケーションが受け取ったデータ（recv_buffer)は、WSMGR がOSから獲得（ALLOC）した領域ですので、アプリケーションが必要なくなった場合は、WSMGR FREEを行って開放してください。

開放したあとにこの領域を参照すると、そのアプリケーションはトラップにより終了させられてしまうので注意してください。

【引数】

ReqHandle		WSMGR OPENによって得られたリクエストハンドル。
ws_errno		処理結果が格納されるアドレス。
recv_inf		受信タイミング情報が格納されているアドレス。
	1)mode	レスポンスを返すタイミング。以下の2モード指定可能。
		XWSIMOD_NOWAIT	(0)			NON WAITモード
		要求時の画面バッファの内容を返す。
		XWSIMOD_WAIT	(1)			WAITモード
		キー入力可能になるまで WAIT しキー入力可能になった時点の画面バッファの内容を返す。注) ESTART中でエミュレータの終了キーが押されていたら即時復帰します。
	2)wait_time	受信タイミングをWAITモードに指定した時の応答待ち時間を指定する(単位秒／0: 無限待ち）。
	3)key_unlock_time	キーアンロックタイム（単位100m秒） WAITモード時、キー入力可能になったときの待ち時間（「4.2.2 KC SEND」参照）
code_type		1 バイトコード系のコード変換の種別指定。
		XWSICNV_STUP		(0)			WSMGR CONNECTで指定したセットアップファイルに設定されているコード種別（下記 1～3 のいずれかより選択）
		XWSICNV_EBCALPH		(1)			EBCDIC 英小文字
		XWSICNV_EBCKANA		(2)			EBCDIC カナ有り
		XWSICNV_EBCASCI		(3)			EBCDIC.ASCII
gaiji		漢字変換指定 XWSIDWC_CNV_UJIS (X'01): 非漢字、第1・2水準とユーザ作成のJEF 変換テーブルを利用した漢字変換。
emu_end_status		DSPEMU終了情報を格納するアドレス。 ESTARTにより起動されたDSPEMUが、終了キーを押されたことにより終了待ち状態にあるという情報（同一リクエストハンドルでESTARTされているとき有効）
dev_status		デバイス状態情報を格納するアドレス
data_kind		受信データ指定
		XWSIKC_NOOPT	(0)		画面データのみ
		XWSIKC_FLDINF	(1)		画面データ、フィールドアトリビュート情報
recv_buffer		画面バッファデータを格納するアドレス

【関数返却値】

XWSIWSAPI_GOOD	(0)	WSAPI が正常に処理されました。
XWSIWSOS_ERR	(1)	WSMGR でWindows API コールを行いその結果エラーになった場合、設定されます。また、そのとき受け取ったエラーコードをws_errno に格納します。
XWSIWSAPI_ERR	(2)	WSAPI が異常で終了したことを示します。エラー詳細は、ws_errno に格納されます。

【出力】

ws_errno		関数返却値＝ XWSIWSOS_ERR (1) のとき Windows API コールから返されるエラーコードが格納されます。エラーコードはWin32エラーコードが返ります。関数返却値＝ XWSIWSAPI_ERR (2) のとき WSAPI のエラーコード一覧を参照してください。関数返却値＝ XWSIWSAPI_GOOD (0) のとき意味を持たないのでアプリケーションで参照する必要はありません。
emu_end_status		DSPEMU終了情報 ESTARTでディスプレイエミュレータを起動中に、ディスプレイエミュレータの終了キーが押されたかどうかを通知します。正常終了またはエラーコード X'2001'・X'2010' のときに有効です。 XWSIEMU_ENDOFF (0): ディスプレイエミュレータの終了キーは押されていない。 XWSIEMU_ENDON (1): ディスプレイエミュレータの終了キーが押された。
dev_status		デバイス状態情報通常ディスプレイエミュレータの25行目に表示される情報をコード化したものです。正常終了、またはエラーコード X'2001'・X'2010' のときに有効です。「表(3) デバイス状態情報」を参照してください。
recv_buffer		画面バッファデータのアドレス。正常終了のとき有効です。「表(1)画面バッファの構造」を参照してください。
	1)curs_adr	カーソルアドレス。現在のカーソル位置 (0～1919)。
	2)buf_length	バッファ長（1920固定）。
	3)data	画面データ格納領域のアドレス。
	4)f_num	フィールドアトリビュート情報の個数。
	5)f_inf	フィールドアトリビュート情報格納領域のアドレス。注） f_num が0のときはこのアドレスは不定になりますので参照しないでください。
	6)j_num	システムリザーブ領域。参照しないでください。
	7)j_inf	システムリザーブ領域。参照しないでください。

注意

ホストから受け取ったデータはEBCDICおよびJEF なので、WSMGR はアプリケーションに画面データを渡す場合はコード変換を行います。このときにコード変換エラーが発生した場合、1バイト系コードは'-'、2バイトコード系は'■'に変換してアプリケーションに渡します。

表(1)画面バッファの構造

ATR0、および以下のコードはスペース（X'20'）に変換してAPLに渡されます。

NULL(X'00')、DUP(X'1C')、FM(X'1E'）

NL(X'15')、FF(X'0C')、CR(X'0D')、EM(X'19')

表(2)フィールドアトリビュート情報バッファの構造

・フィールドアトリビュート情報

1) フィールド定義アドレス

画面バッファ上のフィールド位置（0 ～ 1919)

2) ATR0

フィールドの論理属性を示します。

構成

1： U/P （Unprotect/Protect）: 0：非保護フィールド
1：保護フィールド

2： A/N （Alphameric/Numeric）: 0：自由フィールド
1：数字フィールド

3： I/LPD: 00：低輝度表示/ライトペン検知不可
01：低輝度表示/ライトペン検知可
10：高輝度表示/ライトペン検知可
11：非表示/ライトペン検知不可

4：MDT: 0：フィールドの内容がオペレータにより変更されていないことを示します。
1：フィールドの内容がオペレータにより変更されていることを示します。

3)ATR1

フィールドの表示属性を示します。各ビットは”1”の時意味を持ち、同時に複数の設定が可能です。

構成

1： BLK (BLINK）: ブリンクフィールドを意味します。

2： RVS（REVERSE）: リバースフィールドを定義します。

3： OVL（OVER LINE): フィールドの上側の行間に水平ラインを表示します。

4： UDL（UNDER LINE）: フィールドの下側の行間に水平ラインを表示します。

5： VL（VARTICAL LINE）: このフィールドアトリビュート文字の位置に垂直ラインを表示します。

6： KF（カナフィールド）: カナフィールドを定義する。本ビットはATR0のA/Nが0（自由フィールド）のときにのみ有効です。

表(3) デバイス状態情報

注意

各状態においてWSAPI では、未サポート状態はXWSIDEV_NOTSPOTED (X'FF') が返されます。

パラメータ	定義
ready	READY XWSIDEV_READY (X'00'): Ready ディスプレイ、および制御装置が動作可能であることを示します。 XWSIDEV_NOTREADY (X'01'): Not Ready ディスプレイ、および制御装置が動作不可能であることを示します。
rule	通信ルール XWSIDEV_UNCNCTED (X'00'): Unconnected ホストと接続していないことを示します。 XWSIDEV_RULE_A (X'01'): Rule A BSC接続またはチャネル接続であることを示します。 XWSIDEV_RULE_B (X'02'): Rule B HDLC接続であることを示します。 XWSIDEV_RULE_D (X'03'): Rule D DDX接続であることを示します。 XWSIDEV_OFFLINE (X'04'): off Line デバイスがオフライン状態であることを示します。
conect	接続状態 XWSIDEV_AC_UNCNCT (X'00'): Unconnected HDLC接続でSYSREQキーを押して、ログオン／ログオフが可能になる状態であることを示します。 XWSIDEV_APLPGM (X'01'): Application Program ディスプレイがホストプログラムと結合していることを示します。 XWSIDEV_SYSCTLPGM (X'02'): System Control Program HDLC接続でログオン／ログオフが可能な状態であることを示します。 XWSIDEV_CALLREADY (X'03'): Call Ready DDX接続で発着呼可能な状態であることを示します。 XWSIDEV_CALL (X'04'): Call DDX接続で呼が確立した状態であることを示します。
inp_proh	入力禁止状態 XWSIDEV_INPPOSBL (X'00'): Input Possible 入力可能な状態であることを示します。 XWSIDEV_LOCK (X'01'): Lock デバイスのリクエストをホストプログラムまたは制御装置が実行中であることを示します。 XWSIDEV_PGMLOCK (X'02'): Program Lock ホストプログラムがデータを受け取り、入力禁止状態を解除しません。（RESET KEYで解除可） XWSIDEV_UNAVLBLFUNC (X'03'): Unavailable Function デバイスのリクエストが使用できません。（RESET KEYで解除可） XWSIDEV_UNACEPTED (X'04'): Unaccepted 入力禁止状態で入力操作が行われました。（RESET KEYで解除可） XWSIDEV_PGMERROR (X'05'): Program Error ホストより受信したデータにエラーを検出しました。（RESET KEYで解除可） XWSIDEV_CNCLEDREQ (X'06'): Communication Error 通信エラーによりリクエストがキャンセルされました。（RESET KEYで解除可） XWSIDEV_CALLERROR (X'07'): Call Error DDX接続で接続エラーが検出されました。（RESET KEYで解除可） XWSIDEV_MUCHENT (X'08'): Too Much Enter フィールドで指定されている以上の入力データが指定されました。（RESET KEYで解除可） XWSIDEV_WRONGPLACE (X'09'): Wrong Place 入力不可位置（アトリビュート／保護フィールド）に入力が指定されました。（RESET KEYで解除可） XWSIDEV_NUMRICLOCK (X'0A'): Numeric Lock 数字フィールドに0－9、マイナス（－）、ピリオド(.)、DUP以外の入力データが指定されました。（RESET KEYで解除可） XWSIDEV_SHORTENT (X'0B'): Too Short Enter フィールドのサイズ以下の入力データが指定されました。 XWSIDEV_NOENT (X'0C'): No Data フィールドに入力データが指定されていません。 XWSIDEV_NETERROR (X'0D'): Network Error DDX手順で発呼操作に誤りがありました。
resv1	リザーブ
comsts	通信エラー XWSIDEV_NORM (X'00'): Normal 正常な通信状態であることを示します。 XWSIDEV_COMUERROR (X'01'): Communication Error 通信エラーが発生していることを示します。
resv2	リザーブ