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
傳回的參數。提供交談識別碼。它會識別兩個合作夥伴 TP 之間建立的對話 APPC。

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 別名。必須提供以註冊附加管理員。主機整合伺服器子域內的指定本機 LU 別名只能註冊一個附加管理員。如果已經為此lu_alias註冊另一個附加管理員程式，將會傳回下列錯誤：

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

這表示主機整合伺服器無法註冊此附加管理員。

plu_alias
傳回的參數。提供合作夥伴 LU (起始傳入配置的別名，) 本機 TP 已知。它是 ASCII 字元字串。

mode_name
傳回的參數。提供合作夥伴 TP 中 MC_ALLOCATE 或 ALLOCATE 所指定的模式名稱。這是組態期間定義的一組網路特性名稱。 mode_name是 EBCDIC 字元字串類型。

reserv3
保留參數。

conv_group_id
交談群組識別碼。

fqplu_name
這個傳回的參數會提供完整的 LU 名稱。

pip_incoming
提供的參數。如果此附加管理員將接受包含 PIP 資料的傳入 FMH-5 Attach，請將此設定為 AP_YES。否則，請將此設定為 AP_NO。

傳回的參數：如果傳入的 Attach 中有 PIP 資料，這會設定為 AP_YES。如果沒有 PIP 資料存在，這會設定為 AP_NO。

timeout
逾時，以秒為單位。 0xFFFFFFFF的值可用來永遠等候。

password
傳回的參數：這是遠端系統所傳送的 EBCDIC 密碼。如果遠端系統支援「密碼替代」 (密碼加密) ，則會在 RECEIVE_ALLOCATE_EX收到加密的密碼。沒有任何功能可將此密碼解密，因此應用程式將無法驗證使用者認證。

reserv5
保留參數。

attach_id
傳回的參數。一律設為 0。此欄位是針對與非 Microsoft SNA 產品的來源相容性所定義。

備註

主機整合伺服器支援 APPC RECEIVE_ALLOCATE_EX 和 RECEIVE_ALLOCATE_EX_END ，以簡化某些可叫用交易程式的設計和實作。此函式可讓 APPC 應用程式接收主機整合伺服器透過特定本機 APPC LU 接收的所有傳入 FMH-5 附加要求，讓應用程式成為「附加管理員」。附加管理員是處理傳入 FMH-5 附加要求以啟動 LU6.2 交談的程式。當 APPC 應用程式呼叫 RECEIVE_ALLOCATE ( ，而不是 RECEIVE_ALLOCATE_EX) 時，主機整合伺服器會處理附加管理員功能。若要在 APPC 應用程式中實作附加管理員功能，會發生下列情況：

應用程式會將本機 APPC LU 別名提供給 RECEIVE_ALLOCATE_EX 函式，其中具有TP_NAME的 EBCDIC 空格 (十六進位 X'40') 。
當主機整合伺服器使用該本機 APPC LU 透過 LU6.2 會話收到傳入 FMH-5 附加要求時，主機整合伺服器會將要求路由傳送至應用程式。
當 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，但不能同時呼叫兩者。

應用程式無法將傳入附加要求分派至另一個進程，因為交談識別碼只在自己的應用程式內容內有效。

注意

：主機整合伺服器不支援自動啟動附加管理員應用程式。換句話說，如果應用程式呼叫 RECEIVE_ALLOCATE_EX，則必須在傳入的 Attach 要求通過本機 LU 之前啟動應用程式。

目前的規格不會傳回 FMH-5 附加) (位元組 4 的安全性指標。因此，應用程式必須容納包含下列專案的連入附加要求：

未在附加) 中傳送任何安全性時，user_id或密碼 (，
user_id僅 (，例如「已驗證」附加) 或
如果需要使用者) 授權，user_id和密碼 (。

在 LU6.2 BIND 要求中，主機整合伺服器表示支援內送 FMH-5 附加要求，這些要求包含使用者安全性、已驗證和密碼替代。主機整合伺服器不支援要求持續驗證的連入附加。

如果tp_name設定為 X'40') 的所有 EBCDIC (空間，且本機 LU 別名是在 [lu_alias] 欄位中提供，RECEIVE_ALLOCATE_EX函式可讓應用程式註冊為附加管理員。註冊為指定lu_alias的附加管理員時，主機整合伺服器會將透過lu_alias接收的所有連入連結路由傳送至應用程式。如需主機整合伺服器如何路由傳入 FMH-5 附加要求的詳細資訊，請參閱下方。

應用程式可以多次呼叫 RECEIVE_ALLOCATE_EX ，以註冊為一或多個本機 LU 的附加管理員。不過，在 SNA 子 (域內，只有一個附加管理員可以在指定的lu_alias上註冊，也就是在所有主機整合伺服器和連結的主機整合伺服器用戶端) 。應用程式無法提供空白tp_name和空白lu_alias。換句話說，應用程式無法註冊為預設附加管理員，以接收 SNA 子域的所有連入附加要求。

RECEIVE_ALLOCATE_EX完成時，應用程式會負責下列事項：

決定是否接受附加。主機整合伺服器不提供設定交易程式 (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 附加要求時，在傳送給遠端系統的 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 上執行，則 Host Integration Server 會針對應用程式排入最多 2,048 個連入連結，如果應用程式是在 Host Integration Server 上執行，則為 256。如果超過限制，主機整合伺服器會拒絕具有意義代碼 X'084B6031' 或 AP_TRANS_PGM_NOT_AVAIL_RETRY的附加要求。

共用方式為

RECEIVE_ALLOCATE_EX

語法

成員

備註

其他資源