RUI_READ

  • 發行項

RUI_READ動詞會接收回應、SNA 命令和資料到 Microsoft® Windows® 邏輯單元應用程式， (LUA) 應用程式緩衝區。

下列結構描述RUI_READ所使用的動詞控制項區塊 (VCB ) LUA_COMMON成員。

語法

  
struct LUA_COMMON {  
    unsigned short lua_verb;  
    unsigned short lua_verb_length;  
    unsigned short lua_prim_rc;  
    unsigned long  lua_sec_rc;  
    unsigned short lua_opcode;  
    unsigned long  lua_correlator;  
    unsigned char  lua_luname[8];  
    unsigned short lua_extension_list_offset;  
    unsigned short lua_cobol_offset;  
    unsigned long  lua_sid;  
    unsigned short lua_max_length;  
    unsigned short lua_data_length;  
    char FAR *     lua_data_ptr;  
    unsigned long  lua_post_handle;  
    struct LUA_TH  lua_th;  
    struct LUA_RH  lua_rh;  
    struct LUA_FLAG1 lua_flag1;  
    unsigned char  lua_message_type;  
    struct LUA_FLAG2 lua_flag2;   
    unsigned char  lua_resv56[7];  
    unsigned char  lua_encr_decr_option;  
};

成員

lua_verb
提供的 參數。 包含動詞程式碼，LUA_VERB_RUI要求單位介面 (RUI) 動詞。

lua_verb_length
提供的 參數。 指定 LUA VCB 的位元組長度。 它必須包含所發出動詞記錄的長度。

lua_prim_rc
在動詞完成時，LUA 所設定的主要傳回碼。 有效的傳回碼會隨著發出的 LUA 動詞而有所不同。

lua_sec_rc
在動詞完成時，LUA 所設定的次要傳回碼。 有效的傳回碼會隨著發出的 LUA 動詞而有所不同。

lua_opcode
提供的 參數。 包含 LUA 命令程式碼 (動詞作業程式碼) ，以便發出動詞LUA_OPCODE_RUI_READ。

lua_correlator
提供的 參數。 包含使用者提供的值，可連結動詞與其他使用者提供的資訊。 LUA 不會使用或變更此資訊。 這是選擇性參數。

lua_luname
提供的 參數。 指定 Windows LUA 會話所使用的本機 LU 的 ASCII 名稱。

RUI_READ 只有在 lua_sid 為零時，才需要此參數。

此參數長度為八個位元組，如果名稱小於八個字元，則以空格填補右邊 (0x20) 。

lua_extension_list_offset
主機整合伺服器中 RUI 未使用，且應設定為零。

lua_cobol_offset
在 Microsoft® Host Integration Server 中，LUA 不會使用 ，而且應該是零。

lua_sid
提供和傳回的參數。 指定會話識別碼，並由 SLI_OPEN 和 RUI_INIT傳回。 其他動詞會使用此參數來識別用於命令的會話。 如果其他動詞使用 lua_luname 參數來識別會話，請將 lua_sid 參數設定為零。

lua_max_length
指定RUI_READ和SLI_RECEIVE的接收緩衝區長度。 其他 RUI 和 SLI 動詞未使用，且應該設定為零。

lua_data_length
傳回的參數。 指定RUI_BID動詞lua_peek_data中傳回的資料長度。

lua_data_ptr
從 RUI_READ 動詞接收資料的應用程式提供緩衝區指標。 SNA 命令和資料都會放在這個緩衝區中，而且它們可以是 EBCDIC 格式。

發出 RUI_READ 時，此參數會指向從主機接收資料的位置。

lua_post_handle
提供的 參數。 如果事件要完成非同步通知，則用於 Microsoft Windows Server。 此變數包含要發出訊號的事件控制碼或視窗控制碼。

lua_th
傳回的參數。 包含傳送或接收之訊息的 TH 傳輸標頭 (TH) 。 針對寫入函式設定各種子參數，並針對讀取和 bid 函式傳回。 其子參數如下所示：

lua_th.flags_fid

格式識別類型 2，四個位。

lua_th.flags_mpf

區隔對應欄位，兩個位。 定義資料區段的類型。 下列是有效值：

0x00 中間區段0x04 [最後一個區段]0x08 [僅限第一個區段]0x0C 區段

lua_th.flags_odai

原始位址欄位-目的地位址欄位 (OAF–DAF) 指派器指標，一位。

lua_th.flags_efi

加速流程指示器，一位。

lua_th.daf

目的地位址欄位 (DAF) ，不帶正負號的字元。

lua_th.oaf

原始位址欄位 (OAF) ，不帶正負號的字元。

lua_th.snf

序號欄位，不帶正負號的 char[2]。

lua_rh
傳回的參數。 包含傳送或接收之訊息的 SNA 要求/回應標頭 (RH) 。 它會設定為寫入函式，並由讀取和 bid 函式傳回。 其子參數如下所示：

lua_rh.rri

要求回應指標，一位。

lua_rh.ruc

RU 類別，兩個位。 下列是有效值：

LUA_RH_FMD (0x00 0x00 ) FM資料區段LUA_RH_NC () 0x20 LUA_RH_DFC 0x40 (LUA_RH_DFC) ) 資料流程控制LUA_RH_SC (0x60) 會話控制項0x60

lua_rh.fi

格式化指標，一位。

lua_rh.sdi

包含指標的感知資料，一位。

lua_rh.bci

開始鏈結指標，一位。

lua_rh.eci

結束鏈結指標，一位。

lua_rh.dr1i

明確回應 1 指標，一位。

lua_rh.dr2i

明確回應 2 指標，一個位。

lua_rh.ri

要求) 的例外狀況回應指標 (，或回應類型指標 (回應) ，一位。

lua_rh.qri

已排入佇列的回應指標，一個位。

lua_rh.pi

步調指標，一個位。

lua_rh.bbi

開始括弧指標，一個位。

lua_rh.ebi

端括弧指標，一個位。

lua_rh.cdi

變更方向指示器，一位。

lua_rh.csi

程式碼選取指標，一位。

lua_rh.edi

加密的資料指標，一個位。

lua_rh.pdi

填補的資料指標，一個位。

lua_flag1
提供的參數。 包含資料結構，其中包含應用程式所提供之訊息的旗標。 其子參數如下所示：

lua_flag1.bid_enable

啟用標號指標，一位。

lua_flag1.close_abend

關閉立即指標，一個位。

lua_flag1.nowait

沒有等候資料旗標，一個位。

lua_flag1.sscp_exp

SSCP 加速流程，一位。

lua_flag1.sscp_norm

SSCP 一般流程，一個位。

lua_flag1.lu_exp

LU 加速流程，一位。

lua_flag1.lu_norm

LU 一般流程，一位。

將 lua_flag1.nowait 設定為 1，表示您想要 RUI_READ 立即傳回資料是否可供讀取，或如果您希望動詞在傳回之前等候資料，請將它設定為零。

將 lua_flag1.bid_enable 設定為 1，以重新啟用最近 RUI_BID (相當於再次發出 RUI_BID 與) 完全相同的參數，如果您不想重新啟用 RUI_BID，請將它設定為零。

重新啟用先前 RUI_BID 重複使用原先為其配置的 VCB，因此此 VCB 不得已釋出或修改。

將下列一或多個旗標設定為 1，以指出要從哪個訊息流程讀取資料：

lua_flag1.sscp_exp

lua_flag1.lu_exp

lua_flag1.sscp_norm

lua_flag1.lu_norm

如果設定多個旗標，則會傳回可用的最高優先順序資料。 優先順序 (最高的第一個) 順序為：SSCP 加速、LU 加速、SSCP 正常、LU 正常。 lua_flag2群組中的對等旗標會設定為指出讀取資料的流程。

lua_message_type
指定輸入或輸出 SNA 命令和資料的類型。 傳回的參數。 指定指出 給RUI_READ的 SNA 訊息類型。 可能的值包括：

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RQR

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_CLEAR

LUA_MESSAGE_TYPE_CRV

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SHUTD

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_SDT

LUA_MESSAGE_TYPE_STSN

LUA_MESSAGE_TYPE_UNBIND

LU_DATA、LUSTAT_LU、LUSTAT_SSCP和SSCP_DATA不是 SNA 命令。

lua_flag2
傳回的參數。 包含 LUA 所傳回之訊息的旗標。 其子參數如下所示：

lua_flag2.bid_enable

指出 如果設定為 1，RUI_BID 已成功重新啟用。

lua_flag2.async

表示如果設為 1，則 LUA 介面動詞命令會以非同步方式完成。

lua_flag2.sscp_exp

如果設定為 1，表示 SSCP 加速流程。

lua_flag2.sscp_norm

如果設定為 1，表示 SSCP 正常流程。

lua_flag2.lu_exp

如果設定為 1，表示 LU 加速流程。

lua_flag2.lu_norm

如果設定為 1，則表示 LU 一般流程。

lua_resv56
保留 且 應設定為零。

lua_encr_decr_option
保留 且 應設定為零。

傳回碼

LUA_OK
主要傳回碼;已成功執行動詞。

LUA_DATA_INCOMPLETE

次要傳回碼;RUI_READ無法傳回收到的所有資料，因為應用程式的資料緩衝區 (lua_max_length) 不夠大。 後續 RUI_READ 要求可以發出，以擷取剩餘的 RUI 資料。

這不是RUI_READ的預設行為，只有在會話建立期間呼叫RUI_INIT時，lua_resv56[3]設定為動詞控制項區塊中的非零值時才會啟用。 如需詳細資訊，請參閱備註。

LUA_CANCELED
主要傳回碼;動詞未順利完成，因為已由另一個動詞或內部錯誤取消。

LUA_PURGED

次要傳回碼; RUI_PURGE 已取消 RUI_READ。

LUA_TERMINATED

次要傳回碼; RUI_READ 擱置時發出 RUI_TERM 。

LUA_PARAMETER_CHECK
主要傳回碼;動詞未執行，因為發生參數錯誤。

LUA_BAD_DATA_PTR

次要傳回碼; lua_data_ptr 參數包含不正確值。

LUA_BAD_SESSION_ID

次要傳回碼;lua_sid在 VCB 中指定了不正確值。

LUA_BID_ALREADY_ENABLED

次要傳回碼; lua_flag1.bid_enable 設定為重新啟用 RUI_BID ，但先前 的RUI_BID 仍在進行中。

LUA_DUPLICATE_READ_FLOW

次要傳回碼; lua_flag1 群組中的流程旗標指定了一或多個會話流程 ，RUI_READ 尚未完成。 一次只能有一個 RUI_READ 可以等候每個會話流程。

LUA_INVALID_FLOW

次要傳回碼;未設定 任何lua_flag1 流程旗標。 至少必須將其中一個旗標設定為 1，以指出要讀取的流程或流程。

LUA_INVALID_POST_HANDLE

次要傳回碼;對於使用事件做為非同步張貼方法的 Windows 作業系統，Windows LUA VCB 不包含有效的事件控制碼。

LUA_NO_PREVIOUS_BID_ENABLED

次要傳回碼; lua_flag1.bid_enable 設定為重新啟用 RUI_BID，但先前沒有可啟用 的RUI_BID 。 (如需詳細資訊，請參閱＜備註＞)。

LUA_RESERVED_FIELD_NOT_ZERO

次要傳回碼;動詞記錄中的保留字段或這個動詞未使用的參數設定為非零值。

LUA_VERB_LENGTH_INVALID

次要傳回碼;LUA 動詞發出時，LUA 的值 lua_verb_length非預期 。

LUA_STATE_CHECK
主要傳回碼;指令動詞未執行，因為發出狀態無效。

LUA_NO_RUI_SESSION

次要傳回碼; RUI_INIT 尚未針對 在 RUI_READ上指定的 LU 名稱順利完成。

LUA_NEGATIVE_RSP
主要傳回碼;表示下列兩種案例之一，可透過次要傳回碼來區別：

  • LUA 偵測到從主機接收的資料發生錯誤。 LUA 不會在 RUI_READ上將收到的訊息傳遞至應用程式，而是捨棄訊息 (，如果訊息位於鏈結) 中，則會捨棄其餘的鏈結，並將負回應傳送給主機。 LUA 會在後續 RUI_READ 或 RUI_BID 通知應用程式已傳送負回應。

  • LUA 應用程式先前已將負面回應傳送至鏈結中間的訊息。 LUA 已清除此鏈結中的後續訊息，現在會向應用程式報告已接收和清除來自鏈結的所有訊息。

    LUA_SEC_RC

    次要傳回碼;此參數是非零次要傳回碼，其中包含在負回應上傳送至主機的感知碼。 這表示 LUA 在主機資料中偵測到錯誤，並將負回應傳送給主機。 如需解譯可能傳回之感知碼值的相關資訊，請參閱 使用 LUA 的 SNA 考慮。

    零的次要傳回碼表示，在鏈結中間對訊息的先前 RUI_WRITE 回應之後，LUA 現在已接收並捨棄此鏈結中的所有訊息。

    LUA_UNSUCCESSFUL
    主要傳回碼;提供的動詞記錄有效，但動詞未順利完成。

    LUA_DATA_TRUNCATED

    次要傳回碼; lua_data_length 參數小於訊息上所接收資料的實際長度。 只有 lua_data_length 位元組的資料會傳回動詞動詞;剩餘的資料已捨棄。 如果取得這個次要傳回碼，也會傳回其他參數。

    LUA_NO_DATA

    次要傳回碼; lua_flag1.nowait 已設定為表示立即傳回而不等候資料，而且指定的會話流程或流程目前沒有可用的資料。

    LUA_INVALID_PROCESS

    次要傳回碼;發出此動詞命令的 OS/2 程式與發出此會話 RUI_INIT 的程式不同。 只有啟動會話的程式可以發出該會話的動詞命令。

    LUA_COMM_SUBSYSTEM_ABENDED
    主要傳回碼;表示下列其中一個條件：

  • 此交談所使用的節點遇到 ABEND。

  • 交易程式 (TP) 與實體單位 (PU) 2.1 節點之間的連線中斷， (LAN 錯誤) 。

  • TP 電腦上的 SnaBase 遇到 ABEND。

    LUA_SESSION_FAILURE
    主要傳回碼;必要的主機整合伺服器元件已終止。

    LUA_LU_COMPONENT_DISCONNECTED

    次要傳回碼;表示 LUA 會話因為連結服務或主機 LU 發生問題而失敗。

    LUA_RUI_LOGIC_ERROR

    次要傳回碼;在 LUA 內偵測到內部錯誤。 在正常作業期間不應該發生此錯誤。

    LUA_INVALID_VERB
    主要傳回碼;動詞程式碼或作業程式碼或兩者無效。 動詞未執行。

    LUA_STACK_TOO_SMALL
    主要傳回碼;應用程式的堆疊大小太小，無法執行動詞。 增加應用程式的堆疊大小。

    LUA_COMM_SUBSYSTEM_NOT_LOADED
    主要傳回碼;無法載入必要的元件，或已在處理動詞時終止。 因此，無法進行通訊。 請連絡系統管理員以取得更正動作。

    LUA_UNEXPECTED_DOS_ERROR
    主要傳回碼;發出作業系統呼叫之後，收到非預期的作業系統傳回碼，並在次要傳回碼中指定。

備註

RUI_INIT 必須先順利完成 ，才能發出RUI_READ 。

當現有的 RUI_READ 擱置中時，只有當它指定不同的會話流程或從擱置RUI_READ動詞命令發出另一個 RUI_READ 時，才可以發出另一個 RUI_READ 。 相同的會話流程不能有一個以上的 RUI_READ 未處理。

您可以指定特定訊息流程， (LU 正常、LU 加速、SSCP 正常或 SSCP 加速) 讀取資料，或者您可以指定多個訊息流程。 您可以有多個 未處理的RUI_READ 動詞，前提是兩個動詞都未指定相同的流程。

應用程式會在四個會話流程的其中一個上接收資料。 四個會話流程，從最高優先順序到最低優先順序為：

  • SSCP 加速

  • LU 加速

  • SSCP 一般

  • LU 一般

    RUI_READ的資料流程類型是在lua_flag1參數中指定。 應用程式也可以指定它是否想要查看多個類型的資料流程。 設定多個流程位時，會先收到最高優先順序。 當RUI_READ完成處理時，lua_flag2會指出 Windows LUA 應用程式已接收資料的特定流程類型。

    如果在發出RUI_READ之前順利完成RUI_BID，則可以指示 Windows LUA 介面重複使用最後一個RUI_BID動詞 VCB。 若要這樣做，請發出 RUI_READ ，並設定 lua_flag1.bid_enable 。

    只有在下列條件成立時，才能使用 lua_flag1.bid_enable 參數：

  • RUI_BID 已順利發出，且已完成。

  • 配置給 RUI_BID 的儲存體尚未釋放或修改。

  • 沒有其他 RUI_BID擱置 中。

    使用 lua_flag1.bid_enable時，不得釋放 RUI_BID 儲存體，因為會使用最後 一個RUI_BID 動詞 VCB。 此外，使用 lua_flag1.bid_enable時，將會張貼成功完成 RUI_BID 。

    如果 RUI_READ 在無法接收任何資料時發出 lua_flag1.nowait，LUA_NO_DATA 將會是 Windows LUA 介面所設定的次要傳回碼。

    如果收到的資料超過 lua_max_length，則會被截斷。 只會傳回 lua_max_length 位元組的資料。 也會傳回主要傳回碼LUA_UNSUCCESSFUL和次要傳回碼LUA_DATA_TRUNCATED。 RUI 程式庫會盡可能將資料傳回至應用程式的資料緩衝區，但 RUI 中的剩餘資料會捨棄，而且無法在後續 的RUI_READ 要求上擷取。 這會強制 RUI 應用程式佈建足以處理完整 RU 大小的 RUI_READ 資料緩衝區。

    在會話建立期間呼叫RUI_INIT時，可以將lua_resv56[3]的值設定為動詞控制項區塊中的非零值，即可變更此預設行為。 在此情況下，如果收到的資料超過lua_max_length，RUI_READ要求會傳回LUA_OK的主要傳回碼，以及LUA_DATA_INCOMPLETE的次要傳回碼。 RUI 應用程式接著可以發出新的 RUI_READ呼叫， 並接收其餘的資料。

    這項增強功能尚未在 Microsoft Windows Open Services Architecture (WOSA) LUA API 標準中採用，與 IBM 的 RUI 實作不同。

    使用 RUI_READ 讀取訊息之後 ， 它會從傳入訊息佇列中移除，而且無法再次存取。 (RUI_BID 可作為非破壞性讀取。應用程式可以使用它來檢查可用的資料類型，但資料會保留在傳入佇列上，而且不需要立即使用。)

    步調可用於主機組態) 中指定的主要到次要半會話 (，以保護 LUA 應用程式不受訊息攻擊。 如果 LUA 應用程式讀取訊息的速度很慢，主機整合伺服器會延遲傳送步調回應給主機，使其變慢。

另請參閱

RUI_BID
RUI_INIT
RUI_TERM
RUI_WRITE
SLI_OPEN
SLI_PURGE
SLI_RECEIVE
SLI_SEND