|
|
|
|
The MC_ALLOCATE or ALLOCATE verb is issued by the invoking TP. This verb allocates a session between the local LU and partner LU and (in conjunction with the RECEIVE_ALLOCATE verb) establishes a conversation between the invoking TP and the invoked TP.
The MC_ALLOCATE verb establishes a mapped conversation. The ALLOCATE verb can establish either a basic or mapped conversation. The use of the ALLOCATE verb to establish a mapped conversation enables the TP to use basic conversation verbs to communicate with a mapped-conversation partner TP.
Upon successful execution of this verb, APPC generates a conversation identifier (conv_id). This identifier is a required parameter for all other APPC conversation verbs.
The [MC_]ALLOCATE request will not usually be sent to the partner LU immediately; it will be queued at the local LU until a full buffer can be sent. This means that errors in allocating a conversation are usually not reported on the [MC_]ALLOCATE verb but on a subsequent verb.
The definition of the VCB structure for the MC_ALLOCATE verb is as follows:
typedef struct mc_allocate
{
AP_UINT16 opcode;
unsigned char opext;
unsigned char format;
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char tp_id[8];
AP_UINT32 conv_id;
unsigned char reserv3;
unsigned char sync_level;
unsigned char reserv4[2];
unsigned char rtn_ctl;
unsigned char reserv4a[1];
AP_UINT32 conv_group_id;
AP_UINT32 sense_data;
unsigned char plu_alias[8];
unsigned char mode_name[8];
unsigned char tp_name[64];
unsigned char security;
unsigned char reserv6[11];
unsigned char pwd[10];
unsigned char user_id[10];
AP_UINT16 pip_dlen;
unsigned char *pip_dptr;
unsigned char reserv6a;
unsigned char fqplu_name[17];
unsigned char reserv7[8];
} MC_ALLOCATE;
The definition of the VCB structure for the ALLOCATE verb is as follows:
typedef struct allocate
{
AP_UINT16 opcode;
unsigned char opext;
unsigned char format;
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char tp_id[8];
AP_UINT32 conv_id;
unsigned char conv_type;
unsigned char sync_level;
unsigned char reserv3[2];
unsigned char rtn_ctl;
unsigned char reserv3a;
AP_UINT32 conv_group_id;
AP_UINT32 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];
AP_UINT16 pip_dlen;
unsigned char *pip_dptr;
unsigned char reserv5a;
unsigned char fqplu_name[17];
unsigned char reserv6[8];
} ALLOCATE;
The definition of the VCB structure for the MC_ALLOCATE verb is as follows:
typedef struct mc_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 char reserv3;
unsigned char sync_level;
unsigned char reserv4[2];
unsigned char rtn_ctl;
unsigned char reserv5;
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 reserv6[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];
} MC_ALLOCATE;
The definition of the VCB structure for the ALLOCATE verb is as follows:
typedef 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 char conv_type;
unsigned char sync_level;
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];
} ALLOCATE;
The TP supplies the following parameters to APPC:
Possible values are:
For the MC_ALLOCATE verb.
For the ALLOCATE verb.
Possible values are:
For the MC_ALLOCATE verb.
For the ALLOCATE verb.
Identifier for the local TP.
The value of this parameter was returned by the TP_STARTED verb for an invoking TP, or by the RECEIVE_ALLOCATE verb for an invoked TP.
Type of conversation to allocate. This parameter is used only by the ALLOCATE verb.
Possible values are:
If the ALLOCATE verb 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 implementation of APPC the partner TP is using supports mapped-conversation verbs). For further information, refer to the IBM publication Systems Network Architecture Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2.
Synchronization level of the conversation.
This parameter determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. Possible values are:
Confirmation processing will not be used in this conversation.
The TPs can use confirmation processing in this conversation.
The TPs can use LU 6.2 Syncpoint functions in this conversation. Set this value only if you have a Syncpoint Manager (SPM) and Conversation Protected Resource Manager (C-PRM) in addition to the standard SNAP-IX product. For more information see Syncpoint Support.
Specifies when the local LU acting on a session request from the local TP is to return control to the local TP. For information about sessions, see LU-to-LU Sessions. Whatever the value of this parameter, the LU returns control to the TP immediately if it encounters certain errors such as a zero session limit (which mean that a session will never be allocated).
Possible values are:
If the auto_act parameter of the DEFINE_MODE
verb or the define_mode command is set to
If the auto_act parameter of the DEFINE_MODE verb or the define_mode command is set to any other value, SNAP-IX will attempt to activate a session or sessions.
For more information, refer to the description of the DEFINE_MODE verb in the SNAP-IX NOF Programmer's Guide or define_mode command in the SNAP-IX Administration Command Reference.
If a session is immediately available (active and not being used by another conversation), the LU allocates this conversation to it. If a session is not immediately available but one can be activated, the LU activates it and allocates the conversation to it; if it cannot activate a session, it waits for one to become free.
If a session is immediately available (active and not being used by
another conversation), the LU allocates this conversation to it. If a session
is not immediately available but one can be activated, the LU activates it
and allocates the conversation to it. If no active session is free and another
session cannot be activated, control is returned to the TP with the primary
return code AP_ALLOCATION_ERROR and secondary return
code AP_ALLOCATION_FAILURE_RETRY. This is similar
to
As for
As for
Use this value if you want the new conversation to use the same session as a previous conversation; set the conv_group_id parameter to the conversation group ID of the previous conversation, which was returned on the [MC_]ALLOCATE or RECEIVE_ALLOCATE verb.
If the session identified by the conv_group_id parameter is immediately available (active and not being used by another conversation), the LU allocates this conversation to it and returns control to the TP immediately. If the session is being used by another conversation, the LU waits for it to become free. If the session is no longer active, control is returned to the TP with the primary return code AP_ALLOCATION_ERROR and secondary return code AP_ALLOCATION_FAILURE_NO_RETRY.
Conversation group ID of the requested session for the conversation.
This parameter is used only if rtn_ctl is set to
Alias by which the partner LU is known to the local TP.
This parameter is an 8-byte ASCII character string, padded on the right with ASCII blanks (0x20) if the alias is shorter than eight characters. It can consist of any of the following characters:
Uppercase letters
Numerals 0-9
Blanks
Special characters $, #, %, and @
The first character of this string cannot be a blank.
To identify the LU by its LU name instead of its LU alias, set this parameter to eight binary zeros, and specify the LU name in the fqplu_name parameter.
Name of a set of networking characteristics defined during configuration.
This parameter is an 8-byte EBCDIC character string. It can consist of characters from the type-A EBCDIC character set. These characters are as follows:
Uppercase letters
Numerals 0-9
Special characters $, #, and @
The first character in the string must be an uppercase letter or special character. If the mode name is fewer than eight characters long, pad it on the right with EBCDIC blanks (0x40).
A mode name can also be all EBCDIC blanks (0x40).
In a mapped conversation, the name cannot be SNASVCMG (a reserved mode name used internally by APPC). Using this name in a basic conversation is not recommended.
If the specified mode name does not match either an SNA-defined mode or a mode defined in the SNAP-IX configuration, SNAP-IX creates a new mode based on the default specified in the configuration (or on the SNA-defined mode with a blank mode name, if no default mode is defined).
The value of tp_name specified by the [MC_]ALLOCATE verb in the invoking TP must match the value of tp_name specified by the RECEIVE_ALLOCATE verb in the invoked TP.
This parameter is a 64-byte EBCDIC character string; it is case-sensitive. The tp_name parameter normally consists of characters from the type-AE EBCDIC character set (except when naming a service TP). These characters are as follows:
Uppercase and lowercase letters
Numerals 0-9
Special characters $, #, @, and period (.)
If the TP name is fewer than 64 bytes, use EBCDIC blanks ( 0x40) to pad it on the right.
The SNA convention for naming a service TP is an exception to the above; the name consists of up to four characters, of which the first character is a hexadecimal byte between 0x00 and 0x3F. The other characters are from the EBCDIC AE character set.
Specifies the information the partner LU requires in order to validate access to the invoked TP.
Based on the conversation security established for the invoked TP during configuration, use one of the following values:
The invoked TP does not use conversation security. (If you use this value, the invoked TP must be configured not to use conversation security.)
The invoked TP uses conversation security and thus requires a user ID and password. Supply this information through the user_id and pwd parameters.
The invoked TP uses conversation security and thus requires a user ID
and password. In addition, setting
Use this value when your TP was invoked by another TP, using a valid user ID and password, and is now invoking a third TP that also requires conversation security. (The situation in which one TP invokes a second TP which then invokes a third TP is illustrated in Multiple Conversations.) This value tells the third TP (the invoked TP) that conversation security has already been verified for the first invoking TP.
If you use this value, the tp_id supplied on this [MC_]ALLOCATE verb must be the same as the one that was returned on the RECEIVE_ALLOCATE verb when this TP was invoked.
This value can also be used if your TP was not invoked by another TP, but has obtained and verified the appropriate security information by another means (for example from the Solaris user name and password supplied during logon). In this case, APPC uses the Solaris user name with which the application is running, truncated to 10 characters if necessary, as the user ID for conversation security; ensure that this name consists of valid AE-string characters (see the description of the user_id parameter for more information) and is a valid user name for the TP being invoked.
If the TP has obtained the security information by another means (for example by requesting the user to type in a valid user ID and password before allocating the conversation), it should use SET_TP_PROPERTIES to specify this user ID to APPC before issuing [MC_]ALLOCATE.
Password associated with user_id.
This parameter is required only if the security
parameter is set to
The pwd and user_id parameters must match a user ID/password pair configured on the computer where the invoked TP is located.
This parameter is a 10-byte EBCDIC character string; it is case-sensitive. The pwd parameter can consist of characters from the type-AE EBCDIC character set. These characters are as follows:
Uppercase and lowercase letters
Numerals 0-9
Special characters $, #, @, and period (.)
If the password is fewer than 10 bytes, use EBCDIC blanks ( 0x40) to pad it on the right.
User ID required to access the partner TP.
This parameter is required only if the security
parameter is set to
The pwd and user_id parameters must match a user ID/password pair configured on the computer where the invoked TP is located.
This parameter is a 10-byte EBCDIC character string; it is case-sensitive. The user_id parameter can consist of characters from the type-AE EBCDIC character set. These characters are as follows:
Uppercase and lowercase letters
Numerals 0-9
Special characters $, #, @, and period (.)
If the user ID is fewer than 10 bytes, use EBCDIC blanks ( 0x40) to pad it on the right.
Length of the program initialization parameters (PIP) to be passed to the partner TP. The range for this value is 0- 32,767.
Not all APPC implementations support PIP data. Set pip_dlen to 0 (zero) if the partner TP is using an implementation of APPC that does not support PIP data, or if the partner is a CPI-C application.
Address of buffer containing PIP data.
Use this parameter only if pip_dlen is greater than 0 (zero).
PIP data can consist of initialization parameters or environment setup information required by a partner TP or remote operating system. The PIP data must follow the General Data Stream format. For further information, refer to the IBM publication Systems Network Architecture Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2.
The PIP data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.
Fully qualified LU name of the partner LU. This parameter is used only if plu_alias is set to zeros.
This name is a 17-byte EBCDIC string, padded on the right with EBCDIC spaces, containing one of the following:
A network ID of 1-8 A-string characters, an EBCDIC dot (period) character, and an LU name of 1-8 A-string characters
An LU name of 1-8 A-string characters (without the network ID or the EBCDIC dot)
After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
If the verb executes successfully, APPC returns the following parameters:
If the verb does not execute successfully, APPC returns a primary return code parameter to indicate the type of error and a secondary return code parameter to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, APPC returns the following parameters:
AP_PARAMETER_CHECK
Possible values are:
(Returned for basic-conversation ALLOCATE only) The value specified for conv_type was not valid.
One of the following has occurred:
The plu_alias parameter did not match any defined partner LU alias.
The value specified for fqplu_name was not valid.
The value specified for rtn_ctl was not valid.
The value specified for security was not valid.
The value specified for sync_level was not valid.
The value specified for tp_id was not valid.
The PIP data was longer than the allocated data segment, or the address of the PIP data buffer was incorrect.
(Returned for MC_ALLOCATE only) SNASVCMG is not a valid value for mode_name.
The value of pip_dlen was greater than 32,767.
The value specified for mode_name was not valid.
The format byte was set to a value that was not valid.
The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point.
No state check errors occur for this verb.
Depending on the value specified for rtn_ctl, APPC may return the following parameter:
The supplied parameter rtn_ctl specified immediate
(
If SNAP-IX cannot allocate the conversation, APPC returns the following parameters:
AP_ALLOCATION_ERROR
Possible values are:
The conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the System Administrator should examine the error log file. Do not attempt to retry the allocation until the error has been corrected.
This value is also returned if the session corresponding to the requested conversation group ID is no longer active.
The conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation, preferably after a timeout to allow the condition to clear.
For information about these secondary return codes, see Common Return Codes.
SNA sense data giving more information about the cause of the allocation failure.
If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Common Return Codes.
Possible return codes are:
APPC does not return secondary return codes with these primary return codes.
The conversation state is Reset when the TP issues this verb. It can be issued during an existing conversation which is in any state, since it always implies the start of a new conversation which is in Reset state.
Upon successful execution of this verb (primary_rc is AP_OK), the state of the new conversation is Send. If the verb fails, the state remains unchanged.
Several parameters of the [MC_]ALLOCATE verb are EBCDIC or ASCII strings. A TP can use the Common Service Verb CONVERT to translate a string from one character set to the other. For further information, refer to the SNAP-IX CSV Programmer's Guide.
To ensure that the conversation with the partner is started immediately, the invoking TP can issue the [MC_]FLUSH or [MC_]CONFIRM verb immediately after the [MC_]ALLOCATE verb. Otherwise, the [MC_]ALLOCATE request accumulates with other data in the local LU's send buffer until the buffer is full.
By issuing the [MC_]CONFIRM verb after [MC_]ALLOCATE, the invoking TP
can immediately determine whether the allocation was successful (if
sync_level is set to
|
|
|
 |
|