共用方式為

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_Conversation 或 Accept_Conversation傳回。

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

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

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

  • return_code參數會設定為 CM_OK 或 CM_DEALLOCATED_NORMAL。

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

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

    received_length
    傳回的參數。 指出在此 接收 呼叫上接收本機程式所接收的資料位元組數目。 如果 return_code 或 data_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_code、 status_received和 data_received 參數或錯誤條件，變更為另一個交談狀態。 如果交談接收類型設定為 CM_RECEIVE_IMMEDIATE，如果來自合作夥伴計畫的資料量較小，則收到的資料可能會小於 requested_length 。

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

在填滿特性設定為 CM_FILL_LL 的基本交談中，這個值表示本機程式已收到完整的邏輯記錄或邏輯記錄的結尾。

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

在填滿特性設定為 CM_FILL_LL 的基本交談中，這個值表示本機程式已收到不完整的邏輯記錄。 收到的資料量等於 requested_length 參數。 (如果收到的資料遭到截斷，資料的長度將會小於 requested_length.)

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

CM_NO_DATA_RECEIVED
程式未收到資料。

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

status_received 參數中傳回的值

CM_NO_STATUS_RECEIVED
此通話未收到任何交談狀態變更。

CM_SEND_RECEIVED
表示對合作夥伴計畫而言，交談已進入 RECEIVE 狀態。 針對本機程式，如果在此呼叫上未收到任何資料，則交談現在處於 SEND 狀態，如果在此呼叫上收到資料，則SEND_PENDING狀態。

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

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

收到此值時，本機程式通常會發出 Confirmed 呼叫。

CM_CONFIRM_RECEIVED
表示合作夥伴計畫已發出 Confirm 通話。 針對本機程式，交談處於 CONFIRM 狀態。

收到此值時，本機程式通常會發出 Confirmed 呼叫。

CM_CONFIRM_SEND_RECEIVED
指出，針對合作夥伴計畫，交談已進入 RECEIVE 狀態，且本機計畫已收到確認要求。 針對本機程式，交談現在處於CONFIRM_SEND狀態。

程式通常會透過發出 Confirmed 呼叫來回應。 成功執行 確認 呼叫時，交談會變更為本機程式的 SEND 狀態。

request_to_send_received 參數中傳回的值

CM_REQ_TO_SEND_RECEIVED
合作夥伴計畫發出 Request_To_Send 呼叫，要求本機程式將交談變更為 RECEIVE 狀態。

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，且交談狀態不是 RECEIVE、SEND 或 SEND_PENDING。

  • 接收類型設定為 CM_RECEIVE_IMMEDIATE，且交談狀態不是 RECEIVE。

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

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

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

    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 狀態或處於SEND_PENDING狀態，且錯誤方向設定為 CM_SEND_ERROR 時，合作夥伴計畫會 發出Send_Error。 資料未截斷。

    CM_PROGRAM_ERROR_PURGING
    主要傳回碼;發生下列其中一項：

  • 處於 RECEIVE 或 CONFIRM 狀態時，合作夥伴計畫會 發出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 因為遠端程式異常結束狀況而發出。 如果在發出呼叫時，遠端程式的交談處於 RECEIVE 狀態，則會清除本機程式所傳送且尚未由遠端程式接收的資訊。

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

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

  • 合作夥伴計畫發出 解除配置 ，並將 type 參數設定為 ABEND_SVC。

  • 合作夥伴計畫在終止之前未解除配置交談。

    如果在本機計畫發出此呼叫時，合作夥伴計畫的交談處於 RECEIVE 狀態，則會清除本機程式所傳送且尚未由合作夥伴計畫接收的資料。

    CM_DEALLOCATED_ABEND_TIMER
    主要傳回碼;交談已解除配置，因為合作夥伴計畫已發出 Deallocate ，並將 type 參數設定為 ABEND_TIMER。 如果在本機計畫發出此呼叫時，合作夥伴計畫的交談處於 RECEIVE 狀態，則會清除本機程式所傳送且尚未由合作夥伴計畫接收的資料。

    CM_SVC_ERROR_PURGING
    主要傳回碼;處於 SEND 狀態時，合作夥伴計畫或合作夥伴 LU 會 發出Send_Error 類型參數設定為 SVC。 傳送給合作夥伴計畫的資料可能已經清除。

    CM_SVC_ERROR_NO_TRUNC
    主要傳回碼;處於 SEND 狀態時，合作夥伴計畫或合作夥伴 LU 會 發出Send_Error 類型參數設定為 SVC。 傳送給合作夥伴計畫的資料可能已經清除。

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

    CM_SVC_ERROR_TRUNC
    主要傳回碼;處於 RECEIVE 或 CONFIRM 狀態時，合作夥伴計畫或合作夥伴 LU 會 發出Send_Error 類型參數設定為 SVC，再傳送完整的邏輯記錄。 本機程式可能已收到邏輯記錄的第一個部分。

    狀態變更

    交談可以處於 RECEIVE、SEND 或 SEND_PENDING 狀態。

    如果 receive_type設為 CM_RECEIVE_IMMEDIATE ，交談必須處於 RECEIVE 狀態。

    當交談處於 SEND 或SEND_PENDING狀態時發出 接收 ，會導致本機 LU 在其傳送緩衝區中傳送資訊，並將傳送指示器傳送給合作夥伴計畫。 根據 data_received 和 status_received 交談可以變更為本機程式的 RECEIVE 狀態。

    新的交談狀態取決於：

  • 當程式發出呼叫時，交談所在的狀態。

  • 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所設定。

    下表摘要說明 在 RECEIVE 狀態與交談發出 Receive 時可能發生的狀態變更， 而return_code CM_OK。

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

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

下表摘要說明在傳送狀態與交談發出 Receive 時可能發生的狀態變更， 而return_code CM_OK。

data_received status_received 新增狀態
CM_DATA_RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
CM_COMPLETE_DATA_ RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
CM_INCOMPLETE_DATA_ RECEIVED 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_ RECEIVED CM_NO_STATUS_RECEIVED RECEIVE
CM_INCOMPLETE_DATA_ RECEIVED CM_SEND_RECEIVED 沒有變更
CM_NO_DATA_RECEIVED CM_SEND_RECEIVED SEND

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

本節內容