Receive (CPI-C)

接收呼叫 (函式名稱cmrcv) 接收夥伴計畫目前可用的任何資料。 針對 Microsoft Windows,請針對所有 CPI-C 通訊執行背景執行緒,並只針對使用者介面保留前景執行緒。

語法

  
CM_ENTRY Receive(   
unsigned char FAR *conversation_ID,    
unsigned char FAR *buffer,             
CM_INT32 FAR *requested_length,        
CM_INT32 FAR *data_received,           
CM_INT32 FAR *received_length,         
CM_INT32 FAR *status_received,         
CM_INT32 FAR *request_to_send_received,    
CM_INT32 FAR *return_code              
);  

參數

conversation_ID
提供的參數。 指定交談的識別碼。 此參數的值由 Initialize_ConversationAccept_Conversation傳回。

緩衝區
傳回的參數。 指定要包含本機程式所接收之資料的緩衝區位址。

如果下列條件成立,緩衝區會包含資料:

  • Data_received參數設定為 CM_NO_DATA_RECEIVED 以外的值。

  • Return_code參數設定為 CM_OK 或 CM_DEALLOCATED_NORMAL。

    requested_length
    提供的參數。 指出本機程式要接收之資料的最大位元組數目。 範圍是從0到32767。

    data_received
    傳回的參數。 指出程式是否收到資料。 可能的值會列在 [參數] 區段後面。

    received_length
    傳回的參數。 指出本機程式在此 接收 呼叫上收到的資料位元組數。 若 return_codedata_received 指出該程式未收到任何資料,則此編號與不相關。

    status_received
    傳回的參數。 表示交談狀態中的變更。 以下是可能的值。 除非 return_code 設定為 CM_OK,否則這些程式碼不相關。 可能的值會列在 [參數] 區段後面。

    request_to_send_received
    傳回的參數。 指定要求對傳送接收指標。 值會列在 [參數] 區段後面。

    return_code
    從此呼叫傳回的程式碼。 值會列在 [參數] 區段後面。

Data_received 參數中傳回的值

除非 return_code 設定為 CM_OK 或 CM_DEALLOCATED_NORMAL,否則這些程式碼不相關。

CM_DATA_RECEIVED
如果 [交談填滿] 特性設定為 [CM_FILL_BUFFER],表示程式收到的資料與其邏輯格式無關,就可以針對基本對話傳回。 本機程式收到資料的時間,直到到達 requested_length 或結束資料為止。

資料的結尾是根據 return_codestatus_receiveddata_received 參數或錯誤狀況,以變更為另一個交談狀態來表示。 如果交談接收類型設定為 [CM_RECEIVE_IMMEDIATE],則如果從夥伴計畫抵達的資料量較少,則接收的資料可能小於 requested_length

CM_COMPLETE_DATA_RECEIVED
在對應的交談中,表示本機程式已收到完整的資料記錄或資料記錄的最後一個部分。

在填滿特性設定為 CM_FILL_LL 的基本對話中,此值表示本機程式已收到完整的邏輯記錄或邏輯記錄的結尾。

CM_INCOMPLETE_DATA_RECEIVED
在對應的交談中,指出本機程式已接收到不完整的資料記錄。 如果這不是讀取記錄) 的第一個接收requested_length參數指定的值小於資料記錄的長度 (或小於資料記錄的其餘部分。 收到的資料量等於 requested_length 參數。

在填滿特性設定為 [CM_FILL_LL] 的基本對話中,此值表示本機程式收到未完成的邏輯記錄。 收到的資料量等於 requested_length 參數。 (如果已截斷接收的資料,則資料的長度將小於 requested_length。 )

收到此值時,本機程式通常會會重新發出 接收 ,以接收記錄的下一個部分。

CM_NO_DATA_RECEIVED
程式未收到資料。

請注意,如果 return_code 參數設定為 CM_OK,可透過 status_received 參數取得狀態資訊。

Status_received 參數中傳回的值

CM_NO_STATUS_RECEIVED
此呼叫未收到任何交談狀態變更。

CM_SEND_RECEIVED
表示夥伴計畫中的交談已進入 [接收] 狀態。 針對本機程式,如果在此呼叫上未收到任何資料,則交談現在會處於傳送狀態,如果在此呼叫收到資料則為 SEND_PENDING 狀態。

收到此值時,本機程式通常會使用 Send_Data 來開始傳送資料。

CM_CONFIRM_DEALLOC_RECEIVED
表示夥伴計畫發出 解除配置 ,並已要求確認。 針對本機程式,交談現在處於 CONFIRM_DEALLOCATE 狀態。

收到此值時,本機程式通常會發出 確認 的呼叫。

CM_CONFIRM_RECEIVED
指出合作夥伴計畫發出 Confirm 通話。 針對本機程式,交談處於確認狀態。

收到此值時,本機程式通常會發出 確認 的呼叫。

CM_CONFIRM_SEND_RECEIVED
表示夥伴計畫中的交談已進入接收狀態,而且本機程式已收到確認要求。 針對本機程式,交談現在處於 CONFIRM_SEND 狀態。

程式通常會藉由發出 確認 的呼叫來回應。 成功執行 確認 的呼叫時,交談會變更為 [傳送本機程式的狀態]。

Request_to_send_received 參數中傳回的值

CM_REQ_TO_SEND_RECEIVED
合作夥伴計畫發出 Request_To_Send 呼叫,要求本機程式將交談變更為「接收」狀態。

CM_REQ_TO_SEND_NOT_RECEIVED
夥伴程式未發出 Request_To_Send 通話。 如果 return_code 參數設定為 CM_PROGRAM_PARAMETER_CHECK 或 CM_PROGRAM_STATE_CHECK,則這個值是不相關的。

Return_code 參數中傳回的值

CM_OK
主要傳回碼;呼叫已成功執行。

CM_OPERATION_NOT_ACCEPTED
主要傳回碼;此交談上先前的作業不完整。

CM_OPERATION_INCOMPLETE
主要傳回碼;作業尚未完成 (處理模式僅限非封鎖) ,仍在進行中。 程式可能會發出 Wait_For_Conversation 等候作業完成,或 Cancel_Conversation 取消作業和交談。 如果已呼叫Specify_Windows_Handle ,應用程式應該等候 Windows®訊息的通知,而不是呼叫Wait_For_Conversation

CM_UNSUCCESSFUL
主要傳回碼;[接收類型] 設定為 [CM_RECEIVE_IMMEDIATE],而且不會立即從夥伴程式取得任何資料。

CM_DEALLOCATED_NORMAL
主要傳回碼;交談已正常解除配置。 夥伴 程式發行時,會 將交談解除配置型別設定為 CM_DEALLOCATE_FLUSH 或 CM_DEALLOCATE_SYNC_LEVEL,並將交談的同步處理層級指定為 CM_NONE。

CM_PROGRAM_PARAMETER_CHECK
主要傳回碼;發生下列其中一種情況:

  • Conversation_ID指定的值無效。

  • Requested_length指定的值超出範圍 (大於 32767) 。

    如果程式收到此傳回碼,則其他傳回的參數無效。

    CM_PROGRAM_STATE_CHECK
    主要傳回碼;發生下列其中一種情況:

  • 接收類型設定為 CM_RECEIVE_AND_WAIT,且交談狀態為 [不接收]、[傳送] 或 [SEND_PENDING]。

  • 接收類型設定為 CM_RECEIVE_IMMEDIATE,且交談狀態為 [未接收]。

  • 在基本對話中,交談處於傳送狀態、接收類型設定為 CM_RECEIVE_AND_WAIT,而且程式未完成傳送邏輯記錄。

    如果程式收到此傳回碼,則其他傳回的參數無效。

    CM_PRODUCT_SPECIFIC_ERROR
    主要傳回碼;發生產品特定的錯誤,並已記錄在 products 錯誤記錄檔中。

    CM_CONVERSATION_TYPE_MISMATCH
    主要傳回碼;夥伴邏輯單元 (LU) 或程式不支援配置要求中所指定 (基本或對應) 的交談類型。

    CM_PIP_NOT_SPECIFIED_CORRECTLY
    主要傳回碼;配置要求被非 CPI-C LU 6.2 交易程式拒絕 (TP) 。 夥伴計畫需要一或多個 PIP 資料變數(CPI-C 不支援)。

    CM_SECURITY_NOT_VALID
    主要傳回碼;夥伴 LU 不接受配置要求中指定的使用者識別碼或密碼。

    CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
    主要傳回碼;夥伴計畫不支援配置要求中指定的同步處理層級。

    CM_TPN_NOT_RECOGNIZED
    主要傳回碼;夥伴 LU 無法辨識配置要求中指定的程式名稱。

    CM_TP_NOT_AVAILABLE_NO_RETRY
    主要傳回碼;因為永久狀況,所以夥伴 LU 無法啟動配置要求中指定的程式。 錯誤的原因可能會記錄在遠端節點上。 請勿重試配置,直到錯誤更正為止。

    CM_TP_NOT_AVAILABLE_RETRY
    主要傳回碼;因為暫時性狀況,所以夥伴 LU 無法啟動配置要求中指定的程式。 錯誤的原因可能會記錄在遠端節點上。 重試配置。

    CM_PROGRAM_ERROR_NO_TRUNC
    主要傳回碼;當處於傳送狀態或處於 SEND_PENDING 狀態,且錯誤方向設定為 [CM_SEND_ERROR] 時,就會發出 Send_Error的夥伴程式。 資料未截斷。

    CM_PROGRAM_ERROR_PURGING
    主要傳回碼;發生下列其中一種情況:

  • 在「接收」或「確認」狀態時,會發出 Send_Error的夥伴方案。 已清除傳送但尚未接收的資料。

  • 當 SEND_PENDING 狀態時,如果將錯誤方向設定為 [CM_RECEIVE_ERROR],合作夥伴程式就會發出 Send_Error。 未清除資料。

    CM_RESOURCE_FAILURE_NO_RETRY
    主要傳回碼;發生下列其中一種情況:

  • 因為永久狀況,所以已提前終止交談。 請勿重試,直到錯誤更正為止。

  • 夥伴程式未在正常終止之前解除配置交談。

    CM_RESOURCE_FAILURE_RETRY
    主要傳回碼;交談因為暫時性狀況(例如數據機失敗)而提前終止。 請重試交談。

    CM_DEALLOCATED_ABEND
    主要傳回碼;交談已因下列其中一個原因而解除配置:

  • 遠端程式發出的 解除配置 的類型集為 CM_DEALLOCATE_ABEND,或遠端 LU 因為遠端程式異常結束條件而發生。 當發出呼叫時,如果遠端程式的交談處於接收狀態,則會清除由本機程式傳送的資訊,而且遠端程式尚未接收到的資訊。

  • 遠端 TP 正常終止,但未在結束之前解除配置交談。 遠端 LU 上的節點服務會代表遠端 TP 解除配置交談。

    CM_DEALLOCATED_ABEND_SVC
    主要傳回碼;交談已因下列其中一個原因而解除配置:

  • 夥伴計畫發出 解除配置 ,並將類型參數設定為 ABEND_SVC。

  • 夥伴程式在終止之前未解除配置交談。

    當此呼叫由本機程式發出時,如果交談處於夥伴計畫的 [接收] 狀態,則會清除由本機程式傳送的資料,而且不會由夥伴程式接收。

    CM_DEALLOCATED_ABEND_TIMER
    主要傳回碼;交談已解除配置,因為夥伴程式發行了將 type 參數設定為 ABEND_TIMER 的 解除配置 。 當此呼叫由本機程式發出時,如果交談處於夥伴計畫的 [接收] 狀態,則會清除由本機程式傳送的資料,而且不會由夥伴程式接收。

    CM_SVC_ERROR_PURGING
    主要傳回碼;在傳送狀態中,夥伴程式或夥伴 LU 發出 Send_Error ,並將類型參數設定為 SVC。 傳送給合作夥伴方案的資料可能已被清除。

    CM_SVC_ERROR_NO_TRUNC
    主要傳回碼;在傳送狀態中,夥伴程式或夥伴 LU 發出 Send_Error ,並將類型參數設定為 SVC。 傳送給合作夥伴方案的資料可能已被清除。

    CM_PROGRAM_ERROR_TRUNC
    主要傳回碼;在 [傳送狀態] 中,在完成傳送完整的邏輯記錄之前,會發出 Send_Error的夥伴程式。 本機程式可能已透過 接收 呼叫收到邏輯記錄的第一個部分。

    CM_SVC_ERROR_TRUNC
    主要傳回碼;在 [接收] 或 [確認] 狀態下,在完成傳送完整的邏輯記錄之前,會將類型參數設定為 [.SVC] 來發出 Send_Error 的夥伴程式或夥伴 LU。 本機程式可能已收到邏輯記錄的第一個部分。

    狀態變更

    交談可以是接收、傳送或 SEND_PENDING 狀態。

    如果 receive_type 設定為 CM_RECEIVE_IMMEDIATE,則交談必須處於 [接收] 狀態。

    當交談處於傳送或 SEND_PENDING 狀態時,發出 接收 會導致本機 LU 將其傳送緩衝區和傳送指標中的資訊傳送至夥伴程式。 根據 data_receivedstatus_received 交談可能會變更為 [接收本機程式的狀態]。

    新的交談狀態取決於:

  • 當程式發出呼叫時,交談的狀態。

  • Return_code參數。

  • Data_received 和 status_received 參數。

    如果目前沒有任何資料可供使用,而且 Set_Receive_Type) 設定的接收類型 (設定為 CM_RECEIVE_AND_WAIT,則本機程式會等待資料到達。 如果接收類型設定為 CM_RECEIVE_IMMEDIATE,則本機程式不會等候。

    接收資料的程式如下所示:

  • 本機程式會發出接收呼叫,直到它完成接收完整的資料單位為止。 本機程式可能需要發出接收數次,才能收到完整的資料單位。 Data_received參數會指出資料的接收是否已完成。

    收到的資料可以是:

    • 在對應的對話中傳輸的一筆資料記錄。

    • 在與交談填滿特性設定為 CM_FILL_LL 的基本對話中傳輸的一筆邏輯記錄。

    • 在將填滿特性設定為 CM_FILL_BUFFER 的基本對話中,接收到的資料緩衝區與其邏輯記錄格式無關。

      當收到完整的資料單位時,本機程式可以操控它。

  • 本機程式會根據透過 status_received收到的控制項資訊來決定要採取的下一個動作。 本機程式可能必須重新發出 接收 才能接收控制項資訊。

    交談類型是由 Set_Conversation_Type所設定。 填滿特性是由 Set_Fill設定。

    下表摘要說明在接收狀態下發出 接收return_code 為 CM_OK 時可能發生的狀態變更。

data_received status_received 新狀態
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED 沒有變更
收到 CM_COMPLETE_DATA_ CM_NO_STATUS_RECEIVED 沒有變更
收到 CM_INCOMPLETE_DATA_ CM_SEND_RECEIVED SEND_PENDING
CM_NO_DATA_RECEIVED CM_SEND_RECEIVED SEND

如果 return_code 設定為 CM_UNSUCCESSFUL,表示 receive_type 設定為 CM_RECEIVE_IMMEDIATE 且沒有任何可用的資料,則不會變更狀態。

下表摘要說明當使用傳送狀態的交談發出 接收return_code 為 CM_OK 時可能發生的狀態變更。

data_received status_received 新狀態
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
收到 CM_COMPLETE_DATA_ CM_NO_STATUS_RECEIVED RECEIVE
收到 CM_INCOMPLETE_DATA_ CM_SEND_RECEIVED SEND_PENDING
CM_NO_DATA_RECEIVED CM_SEND_RECEIVED 沒有變更

下表摘要說明在 SEND_PENDING 狀態下的交談發出 接收 時可能發生的狀態變更,而且 return_code CM_OK。

data_received status_received 新狀態
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
收到 CM_COMPLETE_DATA_ CM_NO_STATUS_RECEIVED RECEIVE
收到 CM_INCOMPLETE_DATA_ CM_SEND_RECEIVED 沒有變更
CM_NO_DATA_RECEIVED CM_SEND_RECEIVED SEND

下列主題摘要說明在任何允許狀態下發出 接收 時可能發生的狀態變更。

本節內容