通过

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 参数指定的值小于数据记录的长度 (或小于数据记录的其余部分（如果这不是第一个接收) 读取记录）。 接收的数据量等于 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
指示合作伙伴计划发出了已请求确认的 Deallocate 。 对于本地程序，对话现在处于CONFIRM_DEALLOCATE状态。

收到此值后，本地程序通常会发出 “已确认 ”调用。

CM_CONFIRM_RECEIVED
指示合作伙伴计划发出了 确认 呼叫。 对于本地程序，对话处于 CONFIRM 状态。

收到此值后，本地程序通常会发出 “已确认 ”调用。

CM_CONFIRM_SEND_RECEIVED
指示对于合作伙伴计划，会话已进入 RECEIVE 状态，并且本地计划已收到确认请求。 对于本地程序，对话现在处于CONFIRM_SEND状态。

程序通常通过发出 “已确认 ”调用来响应。 成功执行 “已确认 ”调用后，对话将更改为本地程序的 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
主返回代码;会话已正常解除分配。 合作伙伴计划发布了 Deallocate ，会话解除分配类型设置为 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。 已发送但尚未接收的数据将被清除。

  • 当处于错误方向设置为CM_RECEIVE_ERROR的SEND_PENDING状态时，合作伙伴 计划Send_Error颁发。 未清除数据。

    CM_RESOURCE_FAILURE_NO_RETRY
    主返回代码;发生了以下情况之一：

  • 由于永久性条件，会话提前终止。 在更正错误之前不要重试。

  • 合作伙伴计划在正常终止之前未解除分配对话。

    CM_RESOURCE_FAILURE_RETRY
    主返回代码;由于临时情况（例如调制解调器故障），会话提前终止。 重试对话。

    CM_DEALLOCATED_ABEND
    主返回代码;由于以下原因之一，已解除分配会话：

  • 远程程序使用类型参数集发出 Deallocate 以CM_DEALLOCATE_ABEND，或者远程 LU 由于远程程序异常结束条件而这样做。 如果在发出呼叫时远程程序的会话处于 RECEIVE 状态，则会清除本地程序发送但远程程序尚未接收的信息。

  • 远程 TP 已正常终止，但在终止之前未解除分配会话。 远程 LU 中的节点服务代表远程 TP 解除分配了会话。

    CM_DEALLOCATED_ABEND_SVC
    主返回代码;由于以下原因之一，已解除分配会话：

  • 合作伙伴计划发布了 Deallocate ，类型参数设置为 ABEND_SVC。

  • 合作伙伴计划在终止之前未解除分配对话。

    如果本地程序发出此呼叫时，合作伙伴计划的会话处于 RECEIVE 状态，则会清除本地程序发送但尚未由合作伙伴计划接收的数据。

    CM_DEALLOCATED_ABEND_TIMER
    主返回代码;会话已被解除分配，因为合作伙伴计划发布了 Deallocate ，类型参数设置为 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发出。 本地程序可能已通过 Receive 调用接收了逻辑记录的第一部分。

    CM_SVC_ERROR_TRUNC
    主返回代码;当处于 RECEIVE 或 CONFIRM 状态时，合作伙伴计划或合作伙伴 LU 在完成发送完整的逻辑记录之前发出 Send_Error ，并将类型参数设置为 SVC。 本地程序可能已收到逻辑记录的第一部分。

    状态更改

    会话可以处于 RECEIVE、SEND 或 SEND_PENDING 状态。

    如果 receive_type 设置为 CM_RECEIVE_IMMEDIATE，则会话必须处于 RECEIVE 状态。

    当会话处于 SEND 或SEND_PENDING状态时发出 Receive 会导致本地 LU 在其发送缓冲区中发送信息，并将发送指示器发送到合作伙伴计划。 根据 data_received 和 status_received ，对话可以更改为本地程序的 RECEIVE 状态。

    新会话状态由以下项确定：

  • 当程序发出呼叫时，会话处于的状态。

  • return_code 参数。

  • data_received和status_received参数。

    如果当前没有可用的数据，并且Set_Receive_Type) 设置的接收 类型 (设置为CM_RECEIVE_AND_WAIT，则本地程序将等待数据到达。 如果接收类型设置为 CM_RECEIVE_IMMEDIATE，则本地程序不会等待。

    接收数据的过程如下：

  • 本地程序发出接收调用，直到它完成接收完整的数据单元。 本地程序可能需要多次发出 Receive 才能接收完整的数据单位。 data_received 参数指示是否完成数据接收。

    接收的数据可以是：

    • 在映射对话中传输的一条数据记录。

    • 在基本会话中传输的一条逻辑记录，对话填充特征设置为CM_FILL_LL。

    • 在基本对话中接收的独立于其逻辑记录格式的数据的缓冲区，填充特征设置为CM_FILL_BUFFER。

      收到完整的数据单元后，本地程序可以对其进行操作。

  • 本地程序根据通过 status_received 收到的控制信息确定要执行的下一个操作。 本地程序可能必须重新发出 Receive 才能接收控制信息。

    聊天类型由 Set_Conversation_Type设置。 填充特征由 Set_Fill设置。

    下表总结了当 使用 RECEIVE 状态的会话发出 Receive 并且 CM_OK return_code 时可能发生的状态更改。

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且没有可用数据，则不会更改状态。

下表汇总了在 发送“接收 ”时，会话处于 SEND 状态且 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状态且CM_OK return_code时可能发生的状态更改。

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

以下主题总结了在以任何允许状态发出 Receive 时可能发生的状态更改。

本节内容