The ALLOCATE verb is issued by the invoking TP. It allocates a session between the local LU and partner LU and (in conjunction with RECEIVE_ALLOCATE) establishes a conversation between the invoking TP and the invoked TP. After this verb executes successfully, APPC generates a conversation identifier (conv_id). The conv_id is a required parameter for all other APPC conversation verbs.
For the Microsoft® Windows® version 3.x system, it is recommended that you use WinAsyncAPPC rather than the blocking version of this call.
The following structure describes the verb control block used by the ALLOCATE verb.
struct allocate {
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 long conv_type;
unsigned char synclevel;
unsigned char reserv3[2];
unsigned char rtn_ctl;
unsigned char reserv4;
unsigned long conv_group_id;
unsigned long sense_data;
unsigned char plu_alias[8];
unsigned char mode_name[8];
unsigned char tp_name[64];
unsigned char security;
unsigned char reserv5[11];
unsigned char pwd[10];
unsigned char user_id[10];
unsigned short pip_dlen;
unsigned char FAR * pip_dptr;
unsigned char reserv7;
unsigned char fqplu_name[17];
unsigned char reserv8[8];
unsigned long proxy_user;
unsigned long proxy_domain;
unsigned char reserv9[16];
};
If ALLOCATE establishes a mapped conversation, the local TP must issue basic-conversation verbs and provide its own mapping layer to convert data records to logical records and logical records to data records. The partner TP can issue basic-conversation verbs and provide the mapping layer, or it can use mapped-conversation verbs (if the partner TP is using an implementation of APPC that supports mapped-conversation verbs). For more information, see your IBM SNA manual(s).
Note that AP_IMMEDIATE is the only value for rtn_ctl that will never cause a new session to start. For values other than AP_IMMEDIATE, if an appropriate session is not immediately available, Microsoft® SNA Server will try to start one. This will cause the on-demand connection to be activated.
The plu_alias must match the name of a partner LU established during configuration.
The parameter is an 8-byte ASCII character string. It can consist of the following ASCII characters:
The first character of this string cannot be a space.
If the value of this parameter is fewer than eight bytes, pad it on the right with ASCII spaces (0x20).
If you want to specify the partner LU with the fqplu_name parameter, fill this parameter with binary zeros.
For a user or group using TPs, 5250 emulators, and/or APPC applications, the system administrator can assign default local and remote LUs. In this case, the field is left blank or null and the default LUs are accessed when the user or group member starts an APPC program. For more information on default LUs, see the Microsoft SNA Server Administration Guide.
The value of mode_name must match the name of a mode associated with the partner LU during configuration.
The parameter is an 8-byte EBCDIC character string. It can consist of characters from the type A EBCDIC character set:
The first character in the string must be an uppercase letter or a special character.
Do not use SNASVCMG in a mapped conversation. SNASVCMG is a reserved mode_name used internally by APPC. Using this name in a basic conversation is not recommended.
The parameter is a 64-byte EBCDIC character string and is case-sensitive. The tp_name parameter can consist of the following EBCDIC characters:
If tp_name is fewer than 64 bytes, use EBCDIC spaces (0x40) to pad it on the right.
The SNA convention is that a service TP name can have up to four characters. The first character is a hexadecimal byte between 0x00 and 0x3F. The other characters are from the type AE EBCDIC character set.
Based on the conversation security established for the invoked TP during configuration, use one of the following values:
For example, assume that TP A invokes TP B with a valid user identifier and password supplied by the privileged proxy, and TP B in turn invokes TP C. If TP B specifies the value AP_PROXY_SAME, APPC will send the LU for TP C the user identifier from TP A and an already-verified indicator. This indicator tells TP C to not require the password (if TP C is configured to accept an already-verified indicator).
For example, assume that TP A invokes TP B with a valid user identifier and password, and TP B in turn invokes TP C. If TP B specifies the value AP_SAME, APPC will send the LU for TP C the user identifier from TP A and an already-verified indicator. This indicator tells TP C to not require the password (if TP C is configured to accept an already-verified indicator).
If the APPC automatic logon feature is to be used, security must be set to AP_PGM. See the Remarks section for details.
The pwd parameter is required only if security is set to AP_PGM. It must match the password for user_id that was established during configuration.
The pwd parameter is a 10-byte EBCDIC character string and is case-sensitive. It can consist of the following EBCDIC characters:
If the password is fewer than 10 bytes, use EBCDIC spaces (0x40) to pad it on the right.
If the APPC automatic logon feature is to be used, the pwd character string must be hard-coded to MS$SAME. See the Remarks section for details.
The user_id parameter is a 10-byte EBCDIC character string and is case-sensitive. It must match one of the user identifiers configured for the partner TP.
The parameter can consist of the following EBCDIC characters:
If user_id is fewer than 10 bytes, use EBCDIC spaces (0x40) to pad it on the right.
If the APPC automatic logon feature is to be used, the user_id character string must be hard-coded to MS$SAME. See the Remarks section for details.
PIP data can consist of initialization parameters or environmental setup information required by a partner TP or remote operating system. The PIP data must follow the general data stream (GDS) format. For more information, see SNA LU6.2 Reference: Peer Protocols published by IBM.
For Microsoft® Windows NT®, Windows 95, and Windows version 3.x, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.
For OS/2, the PIP data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The PIP data buffer must fit entirely on the segment.
This name must be provided if no plu_alias is specified. It can consist of the following EBCDIC characters:
If the value of this parameter is fewer than 17 bytes, pad it on the right with EBCDIC spaces (0x40).
This code can be returned through a verb issued after ALLOCATE.
The system administrator should examine the error log to determine the reason for the ABEND.
When this return code is used with ALLOCATE, it can indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there is no node available that can satisfy the ALLOCATE request.
When ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:
| · The node with the local LU is not started. |
| · The local LU is not configured. |
ALLOCATE can establish either a basic or mapped conversation.
The conversation state is RESET when the TP issues this verb. After successful execution (primary_rc is ap_ok), the state changes to SEND. If the verb does not execute, the state remains unchanged.
Several parameters of ALLOCATE are EBCDIC or ASCII strings. A TP can use the CSV CONVERT to translate a string from one character set to the other.
To send the ALLOCATE request immediately, the invoking TP can issue FLUSH or CONFIRM immediately after ALLOCATE. Otherwise, the ALLOCATE request accumulates with other data in the local LU's send buffer until the buffer is full.
By issuing CONFIRM after ALLOCATE, the invoking TP can immediately determine whether the allocation was successful (if synclevel is set to AP_CONFIRM_SYNC_LEVEL).
Normally, the value of the ALLOCATE verb's mode_name parameter must match the name of a mode configured for the invoked TP's node and associated during configuration with the partner LU.
If one of the modes associated with the partner LU on the invoked TP's node is an implicit mode, the session established between the two LUs will be of the implicit mode when no mode name associated with the partner LU matches the value of mode_name.
SNA Server supports a feature called password substitution. This is a security feature supported by the latest version of the OS/400 operating system (V3R1) which encrypts any password that flows between two nodes on an Attach message. A password flows on an Attach whenever someone invokes an APPC transaction program specifying a user identifier and password. For example, this happens whenever anyone logs on to an AS/400.
Support for password substitution is indicated by setting bit 5 in byte 23 of the BIND request to 1 (which indicates that password substitution is supported). If the remote system sets this bit in the BIND response, SNA Server automatically encrypts the LU 6.2 conversation security password included in the FMH-5 Attach message. SNA Server APPC applications automatically take advantage of this feature by setting the security field of the VCB to AP_PGM or AP_STRONG in the ALLOCATE request.
If an APPC application wants to force an encrypted password to flow, the application can specify AP_STRONG for the security field in the VCB in the ALLOCATE request. This option is implemented as defined in OS/400 V3R1, and is documented in the OS/400 CPIC programmer reference as CM_SECURITY_PROGRAM_STRONG, where the LU 6.2 pwd (password) field is encrypted before it flows over the physical network.
The password substitution features is currently only supported by OS/400 V3R1 or later. If the remote system does not support this feature, SNA Server will UNBIND the session with the sense code of 10060006. The two nodes negotiate whether or not they support this feature in the BIND exchange. SNA Server sets a bit in the BIND, and also adds some random data on the BIND for encryption. If the remote node supports password substitution, it sets the same bit in the BIND response, and adds some (different) random data for decryption.
SNA Server version 3.0 with Service Pack 1 or later and SNA Server version 4.0 support automatic logon for APPC applications. This feature requires specific configuration by the network administrator: The APPC application must be invoked on the LAN side from a client of SNA Server. The client must be logged into a Windows NT domain, but can be any platform that supports SNA Server's APPC APIs.
The client application is coded to use "program" level security, with a special hard-coded APPC user name MS$SAME and password MS$SAME. When this session allocation flows from client to SNA Server, the SNA Server looks up the host account and password corresponding to the Windows NT account under which the client is logged in, and substitutes the host account information into the APPC attach message it sends to the host.
Note It is illegal for the remote node to set the bit specifying password substitution and not add the random data.
According to IBM, there are implementations of LU 6.2 password substitution that do not support password substitution but do echo the password substitution bit back to SNA Server, without specifying any random data. When they do this, SNA Server will UNBIND the session with the sense code 10060006.This sense code is interpreted as:
SNA Server should also log an Event 17 (APPC session activation failure: BIND negative response sent).
The correct solution is for the failing implementation to be fixed. However, as a short-term workaround, the following SNA Server service registry setting can be set:
HKEY_LOCAL_MACHINE\\SYSTEM\CurrentControlSet\Services\snaservr\parameters\NOPWDSUB: REG_SZ: YES
When this parameter is specified in the registry, SNA Server's password substitution support will be disabled.
Several updates have been made to SNA Server to allow a privileged APPC application to open an APPC conversation using the Single Signon feature on behalf of any defined Windows NT user. This is referred to as the privileged proxy feature. An extension has been added to the APPC ALLOCATE verb to invoke this feature.
An APPC application becomes privileged by being started in a Windows NT user account that is a member of a special Windows NT group. When a Host Security Domain is configured, SNA Server Manager will define a second Windows NT group for use with the host security features of SNA Server. If the user account under which the actual client is running is a member of this second Windows NT group, the client is privileged to initiate an APPC conversation on behalf of any user account defined in the Host Account Cache.
The following illustrates how the privileged proxy feature works:
The SNA Server administrator creates a Host Security Domain called APP. SNA Server Manager now creates two Windows NT groups. The first group is called APP and the second is called APP_PROXY for this example. Users that are assigned to the APP group are enabled for single signon. Users assigned to the APP_PROXY group are privileged proxies. The administrator adds the Windows NT user AppcUser to the APP_PROXY group using the Users button on the Host Security Domain property dialog box in SNA Server Manager.
The administrator then sets up an APPC application on the SNA Server to run as a Windows NT service called APPCAPP and that service has been setup to operate under the AppcUser user account. When APPCAPP runs, it opens an APPC session via an ALLOCATE verb using the extended VCB format and specifies the Windows NT username of the desired user, UserA (for example).
The SNA Server service sees the session request coming from a connection that is a member of the Host Security Domain APP. The Client/Server interface tells the SNA Server service that the actual client is AppcUser.
The SNA Server service checks to see if AppcUser is a member of the APP_PROXY group. Because AppcUser is a member of APP_PROXY, the SNA Server service inserts the Username/Password for UserA in the APPC Attach (FMH-5) command and sends it off to the partner TP.
In order to support the privileged proxy feature, the APPC application must implement the following program logic:
The APPC application must determine the Windows NT user ID and domain name that it wishes to impersonate.
The APPC application must set the following parameters before calling the ALLOCATE verb:
Enable the use of the extended ALLOCATE verb control block structure by setting the AP_EXTD_VCB flag in the opext field.
Set security to AP_PROXY_SAME, AP_PROXY_PGM or AP_PROXY_STRONG.
Set up the pointers for proxy_user and proxy_domain to point to UNICODE strings containing the user name and domain name of the user to be impersonated.
NOTE: The application does not need to set up the user_id and pwd fields in the ALLOCATE VCB.
When the APPC application performs the above steps and issues the ALLOCATE verb, the SNA Server will perform a lookup in the host security domain for the specified Windows NT user and set the user ID and password fields in the FMH-5 Attach message sent to the remote system.