[MC_]ALLOCATE

The [MC_]ALLOCATE verb is issued by the invoking transaction program. This verb allocates a session between the local LU and the partner LU and then (in conjunction with the RECEIVE_ALLOCATE verb) establishes a conversation between the invoking transaction program and the invoked transaction program.

The ALLOCATE verb can establish either a basic or mapped conversation. Using the ALLOCATE verb to establish a mapped conversation enables the transaction program to use basic conversation verbs to communicate with a mapped conversation partner transaction program.

Personal Communications generates a conversation identifier (conv_id) when this verb executes successfully. This identifier is a parameter that is required for all other APPC conversation verbs.

VCB Structure

typedef struct allocate
{
 unsigned short    opcode;                   /* verb operation code           */
 unsigned char     opext;                    /* verb extension code           */
 unsigned char     format;                   /* format                        */
 unsigned short    primary_rc;               /* primary return code           */
 unsigned long     secondary_rc;             /* secondary return code         */
 unsigned char     tp_id[8];                 /* TP identifier                 */
 unsigned long     conv_id;                  /* conversation identifier       */
 unsigned char     conv_type;                /* conversation type             */
 unsigned char     sync_level;               /* sync level                    */
 unsigned char     reserv3[2];               /* reserved                      */
 unsigned char     rtn_ctl;                  /* return control                */
 unsigned char     conversation_style;       /* conversation style            */
 unsigned long     conv_group_id;            /* conversation group identifier */
 unsigned long     sense_data;               /* sense data                    */
 unsigned char     plu_alias[8];             /* partner LU alias              */
 unsigned char     mode_name[8];             /* mode name                     */
 unsigned char     tp_name[64];              /* partner TP name               */
 unsigned char     security;                 /* security level                */
 unsigned char     reserv5[11];              /* reserved                      */
 unsigned char     pwd[10];                  /* security password             */
 unsigned char     user_id[10];              /* security user_id              */
 unsigned short    pip_dlen;                 /* PIP data length               */
 unsigned char    *pip_dptr;                 /* pointer to PIP data           */
 unsigned char     reserv5a;                 /* reserved                      */
 unsigned char     fqplu_name[17];           /* fully qualified partner LU    */
                                             /* name                          */
 unsigned char     reserv6[8];               /* reserved                      */
} ALLOCATE;

typedef struct mc_allocate
{
 unsigned short     opcode;               /* verb operation code           */
 unsigned char      opext;                /* verb extension code           */
 unsigned char      format;               /* format                        */
 unsigned short     primary_rc;           /* primary return code           */
 unsigned long      secondary_rc;         /* secondary return code         */
 unsigned char      tp_id[8];             /* TP identifier                 */
 unsigned long      conv_id;              /* conversation identifier       */
 unsigned char      reserv3;              /* reserved                      */
 unsigned char      sync_level;           /* sync level                    */
 unsigned char      reserv4[2];           /* reserved                      */
 unsigned char      rtn_ctl;              /* return control                */
 unsigned char      conversation_style;   /* conversation style            */
 unsigned long      conv_group_id;        /* conversation group identifier */
 unsigned long      sense_data;           /* sense data                    */
 unsigned char      plu_alias[8];         /* partner LU alias              */
 unsigned char      mode_name[8];         /* mode name                     */
 unsigned char      tp_name[64];          /* partner TP name               */
 unsigned char      security;             /* security level                */
 unsigned char      reserv6[11];          /* reserved                      */
 unsigned char      pwd[10];              /* security password             */
 unsigned char      user_id[10];          /* security user_id              */
 unsigned short     pip_dlen;             /* PIP data length               */
 unsigned char     *pip_dptr;             /* pointer to PIP data           */
 unsigned char      reserv6a;             /* reserved                      */
 unsigned char      fqplu_name[17];       /* fully qualified partner LU    */
                                          /* name                          */
 unsigned char      reserv7[8];           /* reserved                      */
} MC_ALLOCATE;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:

opcode

AP_B_ALLOCATE

AP_M_ALLOCATE

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

opext

AP_BASIC_CONVERSATION or AP_MAPPED_CONVERSATION. For nonblocking operation, this flag can be ORed together with AP_NON_BLOCKING.

tp_id

Identifier for the local transaction program.

The value of this parameter was returned by the TP_STARTED verb for an invoking transaction program, or by the RECEIVE_ALLOCATE verb for an invoked transaction program.

conv_type

Type of conversation to allocate.

AP_BASIC_CONVERSATION
AP_MAPPED_CONVERSATION

If the ALLOCATE verb establishes a mapped conversation, the local transaction program 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 transaction program can issue basic-conversation verbs and provide the mapping layer, or it can use mapped-conversation verbs (if the implementation of APPC that the partner transaction program is using supports mapped-conversation verbs). For further information, refer to IBM® Systems Network Architecture: LU 6.2 Reference: Peer Protocols.

sync_level

Synchronization level of the conversation.

AP_CONFIRM_SYNC_LEVEL
AP_NONE

rtn_ctl

Specifies when the local LU acting on a session request from the local transaction program is to return control to the local transaction program.

AP_IMMEDIATE
AP_WHEN_SESSION_ALLOCATED
AP_WHEN_SESSION_FREE
AP_WHEN_CONV_GROUP_ALLOC
AP_WHEN_CONWINNER_ALLOC
AP_WHEN_CONLOSER_ALLOC

conversation_style

Conversation style of the conversation identified by conv_id

AP_HALF_DUPLEX
AP_FULL_DUPLEX

conv_group_id

Conversation group identifier for the session to be allocated. This parameter is only supplied if rtn_ctl is set to AP_WHEN_CONV_GROUP_ALLOC.

plu_alias

Alias by which the partner LU is known to the local transaction program. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. This name must match the name of a partner LU established during configuration. If this field is set to all zeros, Personal Communications uses the fqplu_name field to specify the required partner LU.

: The following information only applies to Communications Server Win32 SNA API clients.

The default partner LU alias for each user can be assigned using the appropriate configuration utility, either INI configuration or LDAP.

APPC programs can choose to use a default partner LU alias rather than specify one directly. When an APPC program issues an ALLOCATE verb with the partner_LU_alias field and the fully_qualified_partner_LU field set to binary zeroes, the APPC API uses the configured default partner LU alias.

mode_name

Name of a set of networking characteristics usually defined during configuration. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.

tp_name

Name of the invoked transaction program. Personal Communications does not check the character set of this field. The value of tp_name specified by the ALLOCATE verb in the invoking transaction program must match the value of tp_name specified by the RECEIVE_ALLOCATE verb in the invoked transaction program.

security

Specifies the information the partner LU requires in order to validate access to the invoked transaction program.

AP_NONE

The invoked transaction program uses no conversation security.

AP_PGM

The invoked transaction program uses conversation security, which requires a user ID and password.

AP_SAME

The invoked transaction program uses conversation security and is configured to accept an already-verified indicator. The user ID will be sent with an already-verified indicator, informing the invoked transaction program that no password is required.

AP_PGM_STRONG

Same as AP_PGM, but the ALLOCATE will only succeed if the session to the partner LU supports password substitution.

Note: If the [MC_]ALLOCATE specifies a security type of AP_SAME but does not specify a user ID and password, the user ID and password specified on a previous SET_TP_PROPERTIES verb (if any) are used. If the [MC_]ALLOCATE does carry a user ID and password, then these are always used in place of any that may have been specified on the SET_TP_PROPERTIES verb.

pwd

Password associated with user_id. This is a 10-byte type-AE EBCDIC character string, padded to the right with EBCDIC spaces. This is required if Security=Program (AP_PGM or AP_PGM_STRONG); otherwise, it is optional.

user_id

User ID required to access the partner transaction program. This is a 10-byte type-AE EBCDIC character string, padded to the right with EBCDIC spaces. This is required if Security=Program (AP_PGM or AP_PGM_STRONG); otherwise, it is optional.

pip_dlen

Length of the program initialization parameters (PIP) to be passed to the partner transaction program. Range: 0–32767

pip_dptr

Address of buffer containing PIP data. Use this parameter only if pip_dlen is greater than zero.

fqplu_name

Fully qualified LU name for the partner LU. This name is 17 bytes long and is right-padded with EBCDIC blanks. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded blanks. If the network ID is not present, then omit the dot.) This field is only significant if the plu_alias field is set to all zeros.

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameters:

primary_rc: AP_OK
conv_id: Conversation identifier. This value identifies the conversation established between the two transaction programs.
conv_group_id: Conversation group identifier of the session allocated to the conversation.

If the verb is nonblocking and has not completed, Personal Communications returns the following parameters:

primary_rc: AP_OPERATION_INCOMPLETE
opext: AP_OPERATION_INCOMPLETE_FLAG

If the rtn_ctl parameter was set to AP_IMMEDIATE, and no session is available immediately, Personal Communications returns the following parameter:

primary_rc: AP_UNSUCCESSFUL

If the verb does not execute because of a parameter error, Personal Communications returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

AP_BAD_CONV_TYPE

AP_BAD_DUPLEX_TYPE
AP_BAD_RETURN_CONTROL
AP_BAD_SECURITY
AP_BAD_SYNC_LEVEL
AP_CONFIRM_INVALID_FOR_FDX
AP_NO_USE_OF_SNASVCMG_CPSVCMG
AP_BAD_TP_ID
AP_PIP_LEN_INCORRECT
AP_UNKNOWN_PARTNER_MODE

sense_data: Provides additional information on the reason the [MC_]ALLOCATE failed.

The conditions generating the following possible primary return codes (primary_rc) and indented secondary return codes (secondary_rc) are described in APPC Common Return Codes.

AP_ALLOCATION_ERROR

AP_ALLOCATION_FAILURE_NO_RETRY
AP_ALLOCATION_FAILURE_RETRY
AP_FDX_NOT_SUPPORTED_BY_LU
AP_SEC_REQUESTED_NOT_SUPPORTED

AP_TP_BUSY
AP_UNSUCCESSFUL
AP_UNEXPECTED_SYSTEM_ERROR
AP_CANCELLED

If the primary_rc is set to AP_ALLOCATION_ERROR, the sense_data field carries more information on the failure.