通过

DEALLOCATE

DEALLOCATE 谓词解除分配两个事务程序之间的会话 (TP) 。

以下结构描述了 DEALLOCATE 谓词使用的谓词控制块 (VCB) 。

语法

  
struct deallocate {  
    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 char        reserv3;  
    unsigned char        dealloc_type;  
    unsigned short       log_dlen;  
    unsigned char FAR *  log_dptr;  
    void                 (WINAPI *callback)();  
    void                 *correlator;  
    unsigned char        reserv6[4];  
};

成员

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

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 之间建立的会话。 此参数的值由调用 TP 中的 ALLOCATE 或调用的 TP 中的 RECEIVE_ALLOCATE 返回。

reserv3
一个保留字段。

dealloc_type
提供的参数。 指定如何执行解除分配。

使用以下值之一会异常地解除分配会话：

  • AP_ABEND_PROG

  • AP_ABEND_SVC

  • AP_ABEND_TIMER

    如果本地 TP 发出 DEALLOCATE 时会话处于 SEND 状态，APPC 会在解除分配会话之前将本地逻辑单元 (LU) 缓冲区发送到合作伙伴 TP 的内容。 如果会话处于 RECEIVE 或PENDING_POST状态，APPC 会在解除分配会话之前清除任何传入数据。

    应用程序或服务 TP 在遇到阻止事务成功完成的错误时，应指定AP_ABEND_PROG。

    当服务 TP 遇到由其合作伙伴服务 TP (引起的错误时，应指定AP_ABEND_SVC，例如，合作伙伴服务 TP) 发送的控制信息的格式错误。 当服务 TP 遇到需要立即解除分配的错误时，服务 TP 应指定 (AP_ABEND_TIMER，例如，运算符提前结束程序) 。

    AP_FLUSH在解除分配会话之前，将本地 LU 的发送缓冲区的内容发送到合作伙伴 TP。 仅当会话处于 SEND 状态时，才允许使用此值。

    AP_SYNC_LEVEL使用 由 ALLOCATE) 建立 (会话的同步级别来确定如何解除分配会话。 仅当会话处于 SEND 状态时，才允许使用此值。

    如果会话的同步级别AP_NONE，APPC 会在解除分配会话之前将本地 LU 的发送缓冲区的内容发送到合作伙伴 TP。

    如果同步级别AP_CONFIRM_SYNC_LEVEL，APPC 会将本地 LU 的发送缓冲区的内容和确认请求发送到合作伙伴 TP。 收到合作伙伴 TP 的确认后，APPC 将解除分配对话。 但是，如果合作伙伴 TP 报告错误，则聊天仍被分配。

    log_dlen
    提供的参数。 指定要发送到错误日志文件的数据字节数。 范围为 0 到 32767。

    如果dealloc_type设置为AP_ABEND_PGM、 AP_ABEND_SVC或AP_ABEND_TIMER ，则可以将此参数设置为大于零的数字。 否则，此参数必须为零。

    log_dptr
    提供的参数。 提供包含错误信息的数据缓冲区的地址。 数据将发送到本地错误日志和合作伙伴 LU。

    如果log_dlen大于零，则 DEALLOCATE 将使用此参数。

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

    对于 OS/2，日志数据缓冲区必须驻留在未命名的共享段上，该段由函数 DosAllocSeg 分配，标志等于 1。 日志数据缓冲区必须完全适合段。

    TP 必须将错误数据格式化为 GDS 错误日志变量。 有关详细信息，请参阅 IBM SNA 手册 () 。

    回调 (callback)
    提供的参数。 仅当 opext 成员中设置了AP_EXTD_VCB位，表示支持同步点时，才存在。 此参数是用户提供的回调函数的地址。 如果此字段为 NULL，则不会提供任何通知。

    回调例程的原型如下所示：

void WINAPI callback_proc(  
    struct appc_hdr *vcb,  
    unsigned char tp_id[8],  
    unsigned long conv_id,  
    unsigned short type,  
    void *correlator  
   );

回调过程可以采用任何名称，因为该过程的地址将传递给 APPC DLL。 传递给函数的参数如下所示：

vcb

指向 DEALLOCATE 谓词控制块的指针，该块导致会话被解除分配。

tp_id

拥有已解除分配的会话的 TP 的 TP 标识符。

conv_id

已解除分配的会话的会话标识符。

类型

导致调用回调的消息流的类型。 可能的值为：

AP_DATA_FLOW

会话上的正常数据流。

AP_UNBIND

会话正常未绑定。

AP_FAILURE

会话因中断而终止。

相关

此值是在 DEALLOCATE 谓词上指定的关联器。

相关
提供的参数。 仅当 opext 成员中设置了AP_EXTD_VCB位（指示对同步点 API 的支持）时才存在。 此 关联器 字段允许 TP 指定一个值，该值可用于将回调函数的调用与其自己的内部数据结构（例如）相关联。 此值在调用时作为回调例程的参数之一返回到 TP。

reserv4
一个保留字段。

返回代码

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

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

AP_BAD_CONV_ID

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

AP_BAD_TP_ID

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

AP_DEALLOC_BAD_TYPE

辅助返回代码; dealloc_type 参数未设置为有效值。

AP_DEALLOC_LOG_LL_WRONG

辅助返回代码;GDS 错误日志变量的 LL 字段与日志数据的实际长度不匹配。

AP_INVALID_DATA_SEGMENT

辅助返回代码;日志文件的错误数据比为包含错误数据而分配的段长，或者错误数据缓冲区的地址不正确。

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

AP_DEALLOC_CONFIRM_BAD_STATE

辅助返回代码;会话未处于 SEND 状态，并且 TP 尝试刷新发送缓冲区并发送确认请求。 之所以发生此尝试是因为 dealloc_type 的值已AP_SYNC_LEVEL，并且会话的同步级别已AP_CONFIRM_SYNC_LEVEL。

AP_DEALLOC_FLUSH_BAD_STATE

辅助返回代码;会话未处于 SEND 状态，并且 TP 尝试刷新发送缓冲区。 之所以进行这种尝试，是因为 dealloc_type 的值是 AP_FLUSH 或者 dealloc_type 的值是 AP_SYNC_LEVEL，而对话的同步级别是 AP_NONE 。 在任一情况下，对话都必须处于 SEND 状态。

AP_DEALLOC_NOT_LL_BDY

辅助返回代码;会话处于 SEND 状态，并且 TP 未完成发送逻辑记录。 dealloc_type 参数设置为 AP_SYNC_LEVEL 或 AP_FLUSH。

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
    主要返回代码；处理谓词时无法加载或终止某个必需的组件。 因此无法通信。 请联系系统管理员以执行纠正措施。

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

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

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

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

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

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

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

    AP_THREAD_BLOCKING
    主要返回代码；调用线程已在某个阻塞调用中。

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

注解

根据 dealloc_type 参数的值，当 TP 发出 DEALLOCATE 时，会话可能处于下表中指示的状态之一。

dealloc_type 允许的状态
AP_FLUSH SEND
AP_SYNC_LEVEL SEND
AP_ABEND 除 RESET 外的任何
AP_ABEND_PROG 除 RESET 外的任何
AP_ABEND_SVC 除 RESET 外的任何
AP_ABEND_TIMER 除 RESET 外的任何

下表中汇总的状态更改基于 primary_rc的值。

primary_rc 新状态
AP_OK RESET
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_PROG_ERROR_PURGING RECEIVE
AP_SVC_ERROR_PURGING RECEIVE

在解除分配会话之前，此谓词执行等效的下列操作之一：

  • FLUSH，方法是将本地 LU 的发送缓冲区的内容发送到伙伴 LU (和 TP) 。

  • CONFIRM，方法是将本地 LU 的发送缓冲区的内容和确认请求发送到合作伙伴 TP。

    成功执行此谓词后，会话标识符不再有效。

    LU 6.2 同步点可以使用称为隐式忘记的消息流的优化。 当协议指定需要 FORGET PS 标头时，会话上的下一个数据流表示已收到 FORGET。 在正常情况下，当在其某个同步点会话上接收或发送数据时，TP 会知道下一个数据流。

    但是，最后一条消息流可能是由解除分配的会话引起的。 在这种情况下，TP 不知道会话上的下一个数据流何时发生。 为了向 TP 提供此通知，修改 DEALLOCATE 谓词以允许 TP 注册将调用的回调函数：

  • 在第一个正常流传输 (请求或响应) 会话使用的会话。

  • 如果会话在任何其他数据流之前未绑定。

  • 如果会话因 DLC 中断而异常终止。

    DEALLOCATE 谓词还包含一个关联器字段成员，该成员在调用回调函数时作为参数之一返回。 应用程序可以以任何方式使用此参数， (例如，作为指向应用程序) 中的控制块的指针。

    TP 可以使用传递给回调函数 的类型 参数来确定消息流是否指示已收到隐含的忘记。

    请注意， DEALLOCATE 谓词可能在调用回调例程之前完成。 会话被视为处于 RESET 状态，并且无法使用会话标识符发出进一步的谓词。 如果应用程序在会话的下一个数据流之前发出 TP_ENDED 谓词，则不会调用回调例程。

    Host Integration Server 允许 TP 在发送数据后立即解除分配会话，方法是将 SEND_DATA 上的 type 参数指定为 AP_SEND_DATA_DEALLOC_*。 但是，SEND_DATA谓词不包含隐含的 forget 回调函数。 想要接收隐式忘记通知的 TP 必须显式发出 DEALLOCATE 。