通过

RECEIVE_IMMEDIATE

  • 项目

RECEIVE_IMMEDIATE谓词接收当前从合作伙伴事务计划 (TP) 提供的任何数据。 如果没有可用的数据，则本地 TP 不会等待。 为了避免阻止对话，Microsoft Windows 操作系统可以与 WinAsyncAPPC 一起发出RECEIVE_AND_WAIT。

以下结构描述了 RECEIVE_IMMEDIATE 谓词使用的谓词控件块。

语法

  
struct receive_immediate {  
    unsigned short      opcode;  
    unsigned char       opext;  
    unsigned char       reserv2;  
    unsigned short      primary_rc;  
    unsigned long       secondary_rc;  
    unsigned char       tp_id[8];  
    unsigned long       conv_id;  
    unsigned short      what_rcvd;  
    unsigned char       rtn_status;  
    unsigned char       fill;  
    unsigned char       rts_rcvd;  
    unsigned char       reserv4;  
    unsigned short      max_len;  
    unsigned short      dlen;  
    unsigned char FAR * dptr;  
    unsigned char       reserv5[5];  
};

成员

opcode
提供的参数。 指定谓词操作代码，AP_B_RECEIVE_IMMEDIATE。

opext
提供的参数。 指定谓词操作扩展，AP_BASIC_CONVERSATION。

reserv2
一个保留字段。

primary_rc
返回的参数。 指定在谓词完成时由 APPC 设置的主要返回代码。 有效的返回代码因发出的 APPC 谓词而异。 有关此谓词的有效错误代码，请参阅“返回代码”。

secondary_rc
返回的参数。 指定在谓词完成时由 APPC 设置的次要返回代码。 有效的返回代码因发出的 APPC 谓词而异。 有关此谓词的有效错误代码，请参阅“返回代码”。

tp_id
提供的参数。 标识本地 TP。 此参数的值由调用 TP 中的 TP_STARTED 或调用的 TP 中的 RECEIVE_ALLOCATE 返回。

conv_id
提供的参数。 提供会话标识符。 此参数的值由调用 TP 中的 ALLOCATE 或调用的 TP 中的 RECEIVE_ALLOCATE 返回。

what_rcvd
返回的参数。 包含随传入数据一起接收的信息。 “成员”部分后列出了可能的值。

rtn_status
提供的参数。 指示是否应在一次 API 调用中返回数据和会话状态指示器。

使用 AP_NO 指定应在单独调用谓词时单独返回指示器。

使用 AP_YES 指定应同时返回指示器（前提是两者都可用）。 在以下情况下，可以返回两者：

  • 接收缓冲区足够大，可以保存状态指示器前面的所有数据。

  • fill 参数指定 BUFFER 或 LL，数据是状态指示器之前的最后一条逻辑记录。

    fill
    提供的参数。 指定本地 TP 接收数据的方式。 它仅用于 RECEIVE_IMMEDIATE。

    使用 AP_BUFFER 指示本地 TP 在达到 max_len 指定的字节数或数据结束之前接收数据。 接收数据时不考虑逻辑记录格式。

    使用 AP_LL 指示以逻辑记录格式接收数据。 接收的数据可以是完整的逻辑记录、 逻辑记录的max_len 字节部分或逻辑记录的末尾。

    rts_rcvd
    返回的参数。 包含请求发送指示器。 可能的值为：

  • AP_YES指示合作伙伴 TP 已发出 REQUEST_TO_SEND，请求本地 TP 将会话更改为 RECEIVE 状态。

  • AP_NO指示合作伙伴 TP 尚未发出 REQUEST_TO_SEND。

    max_len
    提供的参数。 指示本地 TP 可以接收的最大数据字节数。 范围为 0 到 65535。

    对于 Windows 操作系统，此值不得超过包含接收数据的缓冲区长度。

    通过将 max_len 设置为零发出 RECEIVE_IMMEDIATE ，本地 TP 可以确定合作伙伴 TP 是否有要发送的数据、寻求确认或更改了会话状态。

    dlen
    返回的参数。 提供收到的数据的字节数。 数据存储在 dptr 指定的缓冲区中。 长度为零表示未收到任何数据。

    dptr
    提供的参数。 要包含本地 TP 接收的数据的缓冲区的地址。

    对于 Windows 操作系统，数据缓冲区可以驻留在静态数据区域或全局分配区域中。 数据缓冲区必须完全适合此区域。

    what_rcvd 参数返回的值

  • AP_CONFIRM_DEALLOCATE指示合作伙伴 TP 已发出 DEALLOCATE，dealloc_type设置为 AP_SYNC_LEVEL，并且会话的同步级别（由 ALLOCATE 建立）AP_CONFIRM_SYNC_LEVEL。 收到此值后，本地 TP 通常会发出 CONFIRMED。

  • AP_CONFIRM_SEND指示合作伙伴 TP 已发出PREPARE_TO_RECEIVE，ptr_type设置为 AP_SYNC_LEVEL，并且会话的同步级别（由 ALLOCATE 建立）AP_CONFIRM_SYNC_LEVEL。 收到此值后，本地 TP 通常会发出 CONFIRMED，并开始发送数据。

  • AP_CONFIRM_WHAT_RECEIVED指示合作伙伴 TP 已发出 CONFIRM。 收到此值后，本地 TP 通常会发出 CONFIRMED。

  • 如果 fill 设置为 AP_BUFFER，则通过RECEIVE_IMMEDIATE为基本对话返回AP_DATA。 本地 TP 在达到 数据max_len 或结尾之前已接收数据。 有关详细信息，请参阅本主题末尾的“RECEIVE_IMMEDIATE数据结束”。

  • AP_DATA_COMPLETE 指示，对于 在基本对话中 填充 设置为AP_LL RECEIVE_IMMEDIATE，本地 TP 已收到完整的逻辑记录或逻辑记录的末尾。

    收到此值后，本地 TP 通常会重新发出 RECEIVE_IMMEDIATE 或发出另一个接收谓词。 如果合作伙伴 TP 发送了更多数据，则本地 TP 将开始接收新的数据单位。

    否则，如果 primary_rc 包含AP_OK并且 what_rcvd 包含以下任何值，则本地 TP 会检查状态信息：

    AP_SEND

    AP_CONFIRM_SEND

    AP_CONFIRM_DEALLOCATE

    AP_CONFIRM_WHAT_RECEIVED

    有关本地 TP 通常执行的下一个操作，请参阅本主题中的返回代码中的值说明。

    如果 primary_rc 包含AP_DEALLOC_NORMAL，则会话已解除分配，以响应合作伙伴 TP 颁发的 DEALLOCATE 。

  • AP_DATA_INCOMPLETE指示映射对话中的 RECEIVE_IMMEDIATE 本地 TP 收到了不完整的数据记录。 如果不是第一个读取记录) 的接收谓词，则 max_len 参数指定的值小于数据记录的长度 (或小于数据记录的其余部分。

    对于在基本对话中填充设置为AP_LL的RECEIVE_IMMEDIATE，此值指示本地 TP 已收到不完整的逻辑记录。

    收到此值后，本地 TP 通常会重新发出RECEIVE_IMMEDIATE (或发出另一个接收谓词) 来接收记录的下一部分。

  • AP_NONE指示 TP 未收到数据或会话状态指示器。

  • AP_SEND指示，对于合作伙伴 TP，会话已进入 RECEIVE 状态。 对于本地 TP，会话现在处于“发送”状态。 收到此值后，本地 TP 通常使用 SEND_DATA开始发送数据。

返回代码

AP_OK
主要返回代码；谓词已成功执行。

当rtn_status AP_YES时，可以返回前面的返回代码或以下返回代码之一。

AP_DATA_COMPLETE_SEND
主返回代码;这是AP_DATA_COMPLETE和AP_SEND的组合。

AP_DATA_COMPLETE_CONFIRM_SEND
主返回代码;这是AP_DATA_COMPLETE和AP_CONFIRM_SEND的组合。

AP_DATA_COMPLETE_CONFIRM
主返回代码;这是AP_DATA_COMPLETE和AP_CONFIRM_WHAT_RECEIVED的组合。

AP_DATA_COMPLETE_CONFIRM_DEALL
主返回代码;这是AP_DATA_COMPLETE和AP_CONFIRM_DEALLOCATE的组合。

AP_DATA_SEND
主返回代码;这是AP_DATA和AP_SEND的组合。

AP_DATA_CONFIRM_SEND
主返回代码;这是AP_DATA和AP_CONFIRM_SEND的组合。

AP_DATA_CONFIRM
主返回代码;这是AP_DATA和AP_CONFIRM_WHAT_RECEIVED的组合。

AP_DATA_CONFIRM_DEALLOCATE
主返回代码;这是AP_DATA和AP_CONFIRM_DEALLOCATE的组合。

AP_UNSUCCESSFUL
主返回代码;合作伙伴 TP 没有立即提供任何数据。

AP_DEALLOC_NORMAL
主返回代码;合作伙伴 TP 已解除分配对话，但未请求确认。 合作伙伴 TP 发布了 DEALLOCATE ， 其中dealloc_type 设置为以下项之一：

  • AP_FLUSH

  • 使用指定为 AP_NONE 的会话的同步级别AP_SYNC_LEVEL

    如果 AP_YES rtn_status，则还要检查 what_rcvd 。

    AP_PARAMETER_CHECK
    主要返回代码；由于参数错误，谓词未执行。

    AP_BAD_CONV_ID

    辅助返回代码; conv_id 的值与 APPC 分配的会话标识符不匹配。

    AP_BAD_TP_ID

    辅助返回代码; tp_id 的值与 APPC 分配的 TP 标识符不匹配。

    AP_BAD_RETURN_STATUS_WITH_DATA

    辅助返回代码;APPC 无法识别指定的 rtn_status 值。

    AP_INVALID_DATA_SEGMENT

    辅助返回代码;为数据缓冲区指定的长度长于为包含该缓冲区而分配的段。

    AP_RCV_IMMD_BAD_FILL

    基本对话的辅助返回代码; fill 参数设置为无效值。

    AP_STATE_CHECK
    主要返回代码；谓词未执行，因为它是在无效状态下发出的。

    AP_RCV_IMMD_BAD_STATE

    辅助返回代码;会话未处于 RECEIVE 状态。

    AP_ALLOCATION_ERROR

    辅助返回代码;APPC 未能分配会话。 会话状态设置为 RESET。

    此代码可以通过 ALLOCATE 后发出的谓词返回。

    AP_ALLOCATION_FAILURE_NO_RETRY

    辅助返回代码;由于配置错误或会话协议错误等永久性条件，无法分配会话。 若要确定发生了哪种错误，系统管理员应检查错误日志文件。 请仅在更正错误之后才重试分配。

    AP_ALLOCATION_FAILURE_RETRY

    辅助返回代码;由于临时条件（如链接失败），无法分配会话。 失败的原因已记录在系统错误日志中。 重试分配。

    AP_CONVERSATION_TYPE_MISMATCH

    辅助返回代码;lu) 或 TP (伙伴逻辑单元不支持分配请求中指定的基本或映射) (会话类型。

    AP_PIP_NOT_ALLOWED

    辅助返回代码;分配请求指定了 PIP 数据，但合作伙伴 TP 不需要此数据，或者合作伙伴 LU 不支持这些数据。

    AP_PIP_NOT_SPECIFIED_CORRECTLY

    辅助返回代码;合作伙伴 TP 需要 PIP 数据，但分配请求未指定 PIP 数据或参数数量不正确。

    AP_SECURITY_NOT_VALID

    辅助返回代码;合作伙伴 LU 不接受分配请求中指定的用户标识符或密码。

    AP_SYNC_LEVEL_NOT_SUPPORTED

    辅助返回代码;合作伙伴 TP 不支持分配请求 中指定的sync_level (AP_NONE 或AP_CONFIRM_SYNC_LEVEL) ，或者无法识别 sync_level 。

    AP_TP_NAME_NOT_RECOGNIZED

    辅助返回代码;伙伴 LU 无法识别分配请求中指定的 TP 名称。

    AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

    辅助返回代码;远程 LU 拒绝分配请求，因为它无法启动请求的伙伴 TP。 条件是永久性的。 出错原因可能已记录在远程节点上。 请仅在更正错误之后才重试分配。

    AP_TRANS_PGM_NOT_AVAIL_RETRY

    辅助返回代码;远程 LU 拒绝分配请求，因为它无法启动请求的伙伴 TP。 这种状况可能是暂时性的，例如只是超时。出错原因可能已记录在远程节点上。 重试分配。

    AP_COMM_SUBSYSTEM_ABENDED
    主要返回代码；指示以下状况之一：

  • 此对话使用的节点遇到了 ABEND。

  • TP 与 PU 2.1 节点之间的连接已断开（LAN 错误）。

  • TP 计算机上的 SnaBase 遇到了 ABEND。

    系统管理员应检查错误日志以确定发生 ABEND 的原因。

    AP_COMM_SUBSYSTEM_NOT_LOADED
    主返回代码;处理谓词时，无法加载或终止所需的组件。 因此无法通信。 请联系系统管理员以执行纠正措施。

    当此返回代码与 ALLOCATE 一起使用时，它可以指示找不到支持本地 LU 的通信系统。 (例如，使用 TP_STARTED 指定的本地 LU 别名不正确或尚未配置。) 请注意，如果 lu_alias 或 mode_name 少于 8 个字符，则必须确保用右侧空格填充这些字段。 如果未用空格填充这些参数，则返回此错误，因为没有可用于满足 ALLOCATE 请求的节点。

    当 ALLOCATE 为配置了多个节点的 Host Integration Server 客户端系统生成此返回代码时，有两个辅助返回代码，如下所示：

    0xF0000001

    辅助返回代码;尚未启动任何节点。

    0xF0000002

    辅助返回代码;至少已启动一个节点，但发出 TP_STARTED 时本地 LU () 未在任何活动节点上配置。 问题可能出在以下任一方面：

  • 未启动具有本地 LU 的节点。

  • 未配置本地 LU。

    AP_CONV_FAILURE_NO_RETRY
    主返回代码;会话因永久条件（例如会话协议错误）而终止。 系统管理员应检查系统错误日志以确定错误原因。 在更正错误之前，不要重试该对话。

    AP_CONV_FAILURE_RETRY
    主返回代码;由于临时错误，会话已终止。 重启 TP 以查看问题是否再次出现。 如果存在，系统管理员应检查错误日志以确定错误原因。

    AP_CONVERSATION_TYPE_MIXED
    主返回代码;TP 已发出基本和映射对话谓词。 在单个会话中只能发出一种类型。

    AP_INVALID_VERB_SEGMENT
    主要返回代码；VCB 超出了数据段的末尾。

    AP_PROG_ERROR_NO_TRUNC
    主返回代码;当会话处于 SEND 状态时，合作伙伴 TP 已发出 SEND_ERROR，err_type 设置为 AP_PROG。 数据未被截断。

    AP_PROG_ERROR_PURGING
    主返回代码;在 RECEIVE、PENDING、PENDING_POST、CONFIRM、CONFIRM_SEND 或 CONFIRM_DEALLOCATE 状态下，合作伙伴 TP 颁发SEND_ERROR，err_type设置为 AP_PROG。 已发送但尚未接收的数据将被清除。

    AP_PROG_ERROR_TRUNC
    主返回代码;在 SEND 状态中，在发送不完整的逻辑记录后，合作伙伴 TP 发出SEND_ERROR，err_type设置为 AP_PROG。 本地 TP 可能已通过接收谓词接收了逻辑记录的第一部分。

    AP_STACK_TOO_SMALL
    主要返回代码；应用程序的堆栈大小太小，无法执行谓词。 增加应用程序的堆栈大小。

    AP_CONV_BUSY
    主返回代码;任何对话一次只能有一个未完成的对话谓词。 如果本地 TP 具有多个线程，并且多个线程使用相同的 conv_id发出 APPC 调用，则可能会发生这种情况。

    AP_UNEXPECTED_DOS_ERROR
    主要返回代码；操作系统在处理来自本地 TP 的 APPC 调用时向 APPC 返回了错误。 已通过 secondary_rc 返回了操作系统返回代码。 此返回代码是以 Intel 字节交换顺序显示的。 如果问题持续出现，请咨询系统管理员。

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

  • 合作伙伴 TP 已发布 DEALLOCATE，dealloc_type设置为 AP_ABEND_PROG。

  • 合作伙伴 TP 遇到 ABEND，导致合作伙伴 LU 发送 DEALLOCATE 请求。

    AP_DEALLOC_ABEND_SVC
    主返回代码;会话已被解除分配，因为合作伙伴 TP 发布了 DEALLOCATE，dealloc_type设置为 AP_ABEND_SVC。

    AP_DEALLOC_ABEND_TIMER
    主返回代码;会话已被解除分配，因为合作伙伴 TP 发布了 DEALLOCATE，dealloc_type设置为 AP_ABEND_TIMER。

    AP_SVC_ERROR_NO_TRUNC
    主返回代码;处于 SEND 状态时，合作伙伴 TP (或合作伙伴 LU) 颁发SEND_ERROR，err_type设置为 AP_SVC。 数据未被截断。

    AP_SVC_ERROR_PURGING
    主返回代码;在 RECEIVE、PENDING_POST、CONFIRM、CONFIRM_SEND 或 CONFIRM_DEALLOCATE 状态时， err_type设置为AP_SVC 的合作伙伴 TP (或合作伙伴 LU) 颁发SEND_ERROR。 发送到伙伴 TP 的数据可能已被清除。

    AP_SVC_ERROR_TRUNC
    主返回代码;在 SEND 状态中，在发送不完整的逻辑记录后，合作伙伴 TP (或合作伙伴 LU) 发出SEND_ERROR。 本地 TP 可能已收到逻辑记录的第一部分。

注解

本地 TP 通过以下过程接收数据：

  1. 本地 TP 发出接收谓词，直到它完成接收完整的数据单元。 接收的数据可以是：

    • 一条逻辑记录。

    • 接收的数据缓冲区，独立于其逻辑记录格式。

      本地 TP 可能需要多次发出接收谓词才能接收完整的数据单元。 收到完整的数据单元后，本地 TP 可以对其进行操作。

      接收谓词是 RECEIVE_AND_POST、 RECEIVE_AND_WAIT和 RECEIVE_IMMEDIATE。

  2. 本地 TP 再次发出接收谓词。 这具有以下效果之一：

    • 如果合作伙伴 TP 发送了更多数据，则本地 TP 将开始接收新的数据单位。

    • 如果合作伙伴 TP 已完成发送数据或正在等待确认，则状态信息 (通过 what_rcvd) 指示本地 TP 通常采取的下一步操作。

    当 TP 发出此谓词时，会话必须处于 RECEIVE 状态。

    新状态由 primary_rc确定。 如果 AP_OK primary_rc，则新状态由 what_rcvd确定。

    下表详细介绍了AP_OK primary_rc 时的状态更改。

what_rcvd 新状态
AP_CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE
AP_DATA_COMPLETE_CONFIRM_DEALL CONFIRM_DEALLOCATE
AP_DATA_CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE
AP_CONFIRM_SEND CONFIRM_SEND
AP_DATA_COMPLETE_CONFIRM_SEND CONFIRM_SEND
AP_DATA_CONFIRM_SEND CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED 确认
AP_DATA_COMPLETE_CONFIRM 确认
AP_DATA_CONFIRM 确认
AP_DATA 没有变化
AP_DATA_COMPLETE 没有变化
AP_DATA_INCOMPLETE 没有变化
AP_SEND SEND
AP_DATA_COMPLETE_SEND SEND_PENDING

下表详细说明了未 AP_OK primary_rc 时的状态更改。

primary_rc 新状态
AP_ALLOCATION_ERROR RESET
AP_CONV_FAILURE_RETRY RESET
AP_CONV_FAILURE_NO_RETRY RESET
AP_DEALLOC_ABEND RESET
AP_DEALLOC_ABEND_PROG RESET
AP_DEALLOC_ABEND_SVC RESET
AP_DEALLOC_ABEND_TIMER RESET
AP_DEALLOC_NORMAL RESET
AP_PROG_ERROR_PURGING 没有变化
AP_PROG_ERROR_NO_TRUNC 没有变化
AP_SVC_ERROR_PURGING 没有变化
AP_SVC_ERROR_NO_TRUNC 没有变化
AP_PROG_ERROR_TRUNC 没有变化
AP_SVC_ERROR_TRUNC 没有变化
AP_UNSUCCESSFUL 没有变化

RECEIVE 立即结束数据

在基本对话中，如果本地 TP 问题 RECEIVE_IMMEDIATE 并将 填充 设置为AP_BUFFER，则数据接收将在 到达max_len 或数据末尾时结束。 数据的结尾由以下任一项指示：

  • 具有 除AP_OK ( 以外的值的primary_rc参数，例如，AP_DEALLOC_NORMAL) 。

  • 具有以下值之一 的 what_rcvd 参数：

    AP_SEND

    AP_CONFIRM_SEND

    AP_CONFIRM_DEALLOCATE

    AP_CONFIRM_WHAT_RECEIVED

    AP_DATA_CONFIRM_SEND

    AP_DATA_CONFIRM_DEALLOCATE

    AP_DATA_CONFIRM

    若要确定是否已到达数据的末尾，本地 TP 会重新颁发 RECEIVE_IMMEDIATE。 如果新的 primary_rc 参数包含 AP_OK 且 what_rcvd 包含 AP_DATA，则尚未到达数据的末尾。 但是，如果已到达数据末尾， primary_rc 或 what_rcvd 将指示数据结束的原因。