RECEIVE_ALLOCATE

The RECEIVE_ALLOCATE verb requests information needed to establish a new transaction program for a conversation with a partner transaction program that has issued an ALLOCATE or MC_ALLOCATE verb.

VCB Structure

typedef struct receive_allocate
{
 unsigned shor    opcode;                   /* verb operation code             */
 unsigned char    opext;                    /* verb extension code             */
 unsigned char    format;                   /* format                          */
 unsigned shor    primary_rc;               /* primary return code             */
 unsigned long    secondary_rc;             /* secondary return code           */
 unsigned char    tp_name[64];              /* TP name                         */
 unsigned char    tp_id[8];                 /* TP identifier                   */
 unsigned long    conv_id;                  /* conversation identifier         */
 unsigned char    sync_level;               /* sync Level                      */
 unsigned char    conv_type;                /* conversation type               */
 unsigned char    user_id[10];              /* user ID                         */
 unsigned char    lu_alias[8];              /* LU alias                        */
 unsigned char    plu_alias[8];             /* partner LU alias                */
 unsigned char    mode_name[8];             /* mode name                       */
 unsigned char    reserv3[2];               /* reserved                        */
 unsigned long    conv_group_id;            /* conversation group ID           */
 unsigned char    fqplu_name[17];           /* fully qualified partner LU name */
 unsigned char    pip_incoming;             /* received PIP data               */
 unsigned char    conversation_style;       /* conversation style              */
 unsigned char    reserv4[3];               /* reserved                        */
 unsigned char    password[10];             /* security password               */
 unsigned char    reserv5[2];               /* reserved                        */
 unsigned char    dload_id[8];              /* user ID                         */
} RECEIVE_ALLOCATE;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:
opcode
AP_RECEIVE_ALLOCATE
opext
AP_BASIC_CONVERSATION
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
tp_name
Name of the transaction program. Personal Communications does not check the character set of this field.

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameters:
primary_rc
AP_OK
tp_id
Identifier for the local transaction program. This value is assigned by Personal Communications to the transaction program. The transaction program passes this identifier to Personal Communications on all subsequent APPC verbs.
conv_id
Conversation identifier. This value identifies the conversation established between the two transaction programs.
sync_level
Synchronization level of the conversation.

AP_CONFIRM_SYNC_LEVEL

AP_NONE

conv_type
Conversation type of the conversation identified by conv_id.

AP_BASIC_CONVERSATION
AP_MAPPED_CONVERSATION

user_id
User ID supplied by the partner transaction program. This is a 10-byte type-AE EBCDIC character string, padded to the right with EBCDIC spaces.
lu_alias
Alias by which the local LU is known. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set.
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.
mode_name
Name of a set of networking characteristics defined during configuration. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
conv_group_id
Conversation group identifier for the session being used by this conversation.
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, omit the dot.)
pip_incoming
Specifies whether the partner transaction program-supplied Program Initialization Parameters (PIP) on the [MC_]ALLOCATE request. Set to AP_YES or AP_NO. If AP_YES, the PIP data will be received on the first [MC_]RECEIVE_* verb issued on this conversation.
conversation_style
Conversation style of the conversation identified by conv_id.

AP_HALF_DUPLEX
AP_FULL_DUPLEX

password
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.
dload_id
This field can only be set if the format field is set to 1. If the RECEIVE_ALLOCATE is issued in response to a DYNAMIC_LOAD_INDICATION, then this field can be used to correlate the two signals in the following ways.
The RECEIVE_ALLOCATE will only be correlated with the DYNAMIC_LOAD_INDICATION if the dload_id is set to one of the following:
  • All zeros
  • The dload_id field on the DYNAMIC_LOAD_INDICATION.
Note:
This parameter is not supported on the SNA API clients.
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_UNDEFINED_TP_NAME
The conditions generating the following possible primary return codes (primary_rc) are described in APPC Common Return Codes.
  • AP_UNEXPECTED_SYSTEM_ERROR