RECEIVE_ALLOCATE_EX

项目
07/21/2023

RECEIVE_ALLOCATE_EX谓词接受新的 VCB 结构，以允许注册附加管理器。

语法

  
typedef struct receive_allocate_ex {  
    unsigned short    opcode;  
        unsigned char     opext;   
        unsigned char     format;  
        unsigned short    primary_rc;  
        unsigned long    secondary_rc;  
       unsigned char     tp_name[64];  
       unsigned char     tp_id[8];  
       unsigned long     conv_id;  
       unsigned char     sync_level;  
        unsigned char    conv_type;  
        unsigned char     user_id[10];  
       unsigned char     lu_alias[8];  
       unsigned char     plu_alias[8];  
       unsigned char     mode_name[8];  
       unsigned char     reserv3[2];  
       unsigned long     conv_group_id;  
       unsigned char     fqplu_name[17];  
       unsigned char     pip_incoming;  
       unsigned long     timeout;  
       unsigned char     password[10];  
       unsigned char     reserv5[2];  
       unsigned char     attach_id[8];  
 }

成员

opcode
提供的参数：RECEIVE_ALLOCATE_EX

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

format
保留参数。

primary_rc
返回的参数。指定在谓词完成时由 APPC 设置的主要返回代码。有效的返回代码因发出的 APPC 谓词而异。

secondary_rc
返回的参数。指定在谓词完成时由 APPC 设置的次要返回代码。有效的返回代码因发出的 APPC 谓词而异。

tp_name
提供的参数。 tp_name只是返回的参数。但是，应用程序必须分配足够的缓冲区空间来保存 tp_name (，即) 64 个字符，并将名称初始化为 EBCDIC 空格 (十六进制 X'40')

返回的谓词将包含远程系统发送的实际 TP 名称。

tp_id
返回的参数。标识本地 TP。

conv_id
返回的参数。提供会话标识符。它标识 APPC 在两个合作伙伴 TP 之间建立的对话。

sync_level
返回的参数。指定会话的同步级别。它确定 TP 是否可以请求确认接收数据并确认接收数据。

AP_NONE 指定将不在此会话中使用确认处理。
AP_CONFIRM_SYNC_LEVEL 指定 TP 可以使用此会话中的确认处理。

AP_SYNCPT 指定 TP 可以使用此会话中的同步点级别 2 确认处理。

conv_type
返回的参数。使用 MC_ALLOCATE 或 ALLOCATE 指定合作伙伴 TP 选择的对话类型。以下列出的是可能的值：

AP_BASIC_CONVERSATION

AP_MAPPED_CONVERSATION

user_id
这是远程系统发送的 EBCDIC user_id

lu_alias
提供的参数。本地 LU 别名。必须提供以注册附加管理器。在 Host Integration Server 子域中，只能为给定的本地 LU 别名注册一个附加管理器。如果已为此lu_alias注册了另一个附加管理器进程，将返回以下错误：

primary_rc = AP_STATE_CHECK (0x0002) secondary_rc = AP_LU_ALREADY_REGISTERED (0x0000050A)

这表示 Host Integration Server 无法注册此附加管理器。

plu_alias
返回的参数。提供本地 TP 知道发起传入分配) 的合作伙伴 LU (别名。它是 ASCII 字符串。

mode_name
返回的参数。在合作伙伴 TP 中 提供由 MC_ALLOCATE 或 ALLOCATE 指定的模式名称。它是在配置过程中定义的一组网络特征的名称。 mode_name类型为 A EBCDIC 字符串。

reserv3
保留参数。

conv_group_id
对话组标识符。

fqplu_name
此返回的参数提供完全限定的 LU 名称。

pip_incoming
提供的参数。如果此附加管理器将接受包含 PIP 数据的传入 FMH-5 附加，则将此设置为 AP_YES。否则，请将此设置为 AP_NO。

返回的参数：如果 PIP 数据存在于传入的附加中，则此值设置为 AP_YES。如果没有 PIP 数据，则会将其设置为 AP_NO。

timeout
超时，以秒为单位。值 0xFFFFFFFF 可用于永久等待。

password
返回的参数：这是远程系统发送的 EBCDIC 密码。如果远程系统支持“密码替换” (密码加密) ，则会在 RECEIVE_ALLOCATE_EX接收加密的密码。没有用于解密此密码的设施，因此应用程序将无法验证用户凭据。

reserv5
保留参数。

attach_id
返回的参数。总是设置为 0。定义此字段是为了与非 Microsoft SNA 产品的源兼容性。

注解

Host Integration Server 支持 APPC RECEIVE_ALLOCATE_EX 和 RECEIVE_ALLOCATE_EX_END ，以简化一些可调用事务程序的设计和实现。此函数允许 APPC 应用程序接收主机集成服务器通过特定本地 APPC LU 接收的所有传入 FMH-5 附加请求，从而允许应用程序充当“附加管理器”。附加管理器是一个程序，用于处理传入的 FMH-5 附加请求以启动 LU6.2 会话。当 APPC 应用程序调用 RECEIVE_ALLOCATE (而不是 RECEIVE_ALLOCATE_EX) 时，Host Integration Server 将处理附加管理器功能。若要在 APPC 应用程序中实现附加管理器功能，将发生以下情况：

应用程序为 RECEIVE_ALLOCATE_EX 函数提供本地 APPC LU 别名，tp_name EBCDIC 空格 (十六进制 X'40') 。
当主机集成服务器使用该本地 APPC LU 通过 LU6.2 会话收到传入的 FMH-5 附加请求时，Host Integration Server 会将请求路由到应用程序。
RECEIVE_ALLOCATE_EX完成后，应用程序负责以下事项：
1. 接受或拒绝 FMH-5 附加
2. 验证任何会话级别安全性，以及
3. 如果接受附加请求，请在其 Win32 进程上下文中完全处理请求。
若要停止侦听新的传入附加请求，应用程序调用 RECEIVE_ALLOCATE_EX_END。
进程 RECEIVE_ALLOCATE_EX发出问题后，进程不应调用具有特定 TP 名称 的RECEIVE_ALLOCATE 。同样，如果进程调用 RECEIVE_ALLOCATE，该进程以后不应调用 RECEIVE_ALLOCATE_EX。换句话说，在支持可调用 TP 的进程期间，进程应以独占 方式调用RECEIVE_ALLOCATE或 RECEIVE_ALLOCATE_EX，但不能同时调用这两者。

应用程序无法将传入的附加请求调度到另一个进程，因为会话 ID 仅在其自己的应用程序上下文中有效。

注意

：Host Integration Server 不支持自动启动附加管理器应用程序。换句话说，如果应用程序调用 RECEIVE_ALLOCATE_EX，则必须启动应用程序，然后才能通过本地 LU 到达任何传入的附加请求。

当前规范不返回 FMH-5 附加) (字节 4 的安全指示器。因此，应用程序需要适应包含以下项的传入附加请求：

当附加) 中未发送任何安全性时，user_id或密码均 (，
user_id (（例如“已验证”）附加) ，或者
如果需要) 用户授权，则user_id和密码 (。

在 LU6.2 BIND 请求中，Host Integration Server 指示支持包含用户安全性、已验证和密码替换的传入 FMH-5 附加请求。主机集成服务器不支持请求持久验证的传入附加。

如果 tp_name 设置为所有 EBCDIC 空间 (X'40') 并且本地 LU 别名在 lu_alias 字段中提供，则 RECEIVE_ALLOCATE_EX 函数允许应用程序注册为附加管理器。当注册为给定lu_alias的附加管理器时，Host Integration Server 会将通过lu_alias接收的所有传入附加路由到应用程序。有关 Host Integration Server 如何路由传入 FMH-5 附加请求的详细信息，请参阅下文。

应用程序可以多次调用 RECEIVE_ALLOCATE_EX ，以注册为一个或多个本地 LU 的附加管理器。但是，在 SNA 子域中的给定lu_alias上只能注册一个附加管理器 (，即跨所有主机集成服务器和附加的主机集成服务器客户端) 注册。应用程序无法提供空白tp_name和空白lu_alias。换句话说，应用程序无法注册为默认附加管理器来接收 SNA 子域的所有传入附加请求。

RECEIVE_ALLOCATE_EX完成后，应用程序负责执行以下操作：

确定是否接受附加。 Host Integration Server 不提供用于 (TP) 配置事务程序的机制。应用程序必须具有自己的方法来定义它将支持的 tp 名称。
如果接受，应用程序必须验证会话安全属性 (user_id、密码) 以及处理新聊天。
无法将tp_id和conv_id传递到单独的进程进行处理。所有 TP 处理必须由应用程序提供。

如果应用程序选择拒绝附加请求，则必须使用以下新的扩展代码调用 [MC_]DEALLOCATE ，指定在已完成 的RECEIVE_ALLOCATE_EX中收到的conv_id，以及dealloc_type参数中的相应原因代码：

#define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_EXPIRED 0x10

#define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_INVALID 0x11

#define AP_DEALLOC_SECURITY_NOT_VALID_USERID_REVOKED 0x12

#define AP_DEALLOC_SECURITY_NOT_VALID_USERID_INVALID 0x13

#define AP_DEALLOC_SECURITY_NOT_VALID_USERID_MISSING 0x14

#define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_MISSING 0x15

#define AP_DEALLOC_SECURITY_NOT_VALID_GROUP_INVALID 0x16

#define AP_DEALLOC_SECURITY_NOT_VALID_USERID_REVOKED_IN_GROUP 0x17

#define AP_DEALLOC_SECURITY_NOT_VALID_USERID_NOT_DEFD_TO_GROUP 0x18

#define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_AT_REMOTE_LU 0x19

#define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_FROM_LOCAL_LU 0x1A

#define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_TO_TRANSACTION_PROGRAM 0x1B

#define AP_DEALLOC_SECURITY_NOT_VALID_INSTALLATION_EXIT_FAILED 0x1C

#define AP_DEALLOC_SECURITY_NOT_VALID_PROCESSING_FAILURE 0x1D

#define AP_DEALLOC_SECURITY_NOT_VALID_PROTOCOL_VIOLATION 0x1E

当应用程序设置上述dealloc_type时，当拒绝 FMH-5 附加请求时，Host Integration Server 会将 FMH-7 错误中的相应感知代码发送到远程系统：

#define AP_SECURITY_NOT_VALID_PASSWORD_EXPIRED APPC_FLIPL(x080fff00)

#define AP_SECURITY_NOT_VALID_PASSWORD_INVALID APPC_FLIPL(x080fff01)

#define AP_SECURITY_NOT_VALID_USERID_REVOKED APPC_FLIPL(x080fff02)

#define AP_SECURITY_NOT_VALID_USERID_INVALID APPC_FLIPL(x080fff03)

#define AP_SECURITY_NOT_VALID_USERID_MISSING APPC_FLIPL(x080fff04)

#define AP_SECURITY_NOT_VALID_PASSWORD_MISSING APPC_FLIPL(x080fff05)

#define AP_SECURITY_NOT_VALID_GROUP_INVALID APPC_FLIPL(x080fff06)

#define AP_SECURITY_NOT_VALID_USERID_REVOKED_IN_GROUP APPC_FLIPL(x080fff07)

#define AP_SECURITY_NOT_VALID_USERID_NOT_DEFD_TO_GROUP APPC_FLIPL(x080fff08)

#define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_AT_REMOTE_LU APPC_FLIPL(x080fff09)

#define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_FROM_LOCAL_LU APPC_FLIPL(x080fff0A)

#define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_TO_TRANSACTION_PROGRAM APPC_FLIPL(x080fff0B)

#define AP_SECURITY_NOT_VALID_INSTALLATION_EXIT_FAILED APPC_FLIPL(x080fff0C)

#define AP_SECURITY_NOT_VALID_PROCESSING_FAILURE APPC_FLIPL(x080fff0D)

#define AP_SECURITY_NOT_VALID_PROTOCOL_VIOLATION APPC_FLIPL(x080fff0E)

在调用 RECEIVE_ALLOCATE_EX 之前，应用程序可能需要验证本地 APPC LU 的配置设置，以确定 LU 是否支持同步级别 2，还是默认 LU 池的成员。为此，请使用增强的 GET_LU_STATUS API。

若要取消注册给定本地 APPC LU 的附加管理器，应用程序必须调用 RECEIVE_ALLOCATE_EX_END，如下所述。如果应用程序已注册为多个lu_alias的附加管理器，则必须为每个 lu_alias 调用RECEIVE_ALLOCATE_EX_END。

应用程序应尝试随时挂起 RECEIVE_ALLOCATE_EX ，以便及时处理传入的附加请求。如果应用程序无法发布新 RECEIVE_ALLOCATE_EX，Host Integration Server 将针对该应用程序排队最多 2,048 个传入附加项;如果应用程序在 Host Integration Server 上运行，则为 256 个队列（如果在 HIS 客户端上运行）。如果超出限制，Host Integration Server 会拒绝带有感知代码 X'084B6031' 的附加请求，或 AP_TRANS_PGM_NOT_AVAIL_RETRY。

通过

RECEIVE_ALLOCATE_EX

语法

成员

注解

其他资源