[MC_]SEND_CONVERSATION

The [MC_]SEND_CONVERSATION verb allocates a conversation to a session between the local LU and partner LU (causing a transaction program on the partner LU to start), sends a single data record on this conversation, then deallocates the conversation without waiting for confirmation. It is equivalent to an [MC_]ALLOCATE, [MC_]SEND_DATA, [MC_]DEALLOCATE (FLUSH) sequence of verbs (commonly termed a single one-way bracket).

VCB Structure

typedef struct send_conversation
{
 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 char    reserv3[8];             /* reserved                      */
 unsigned char    rtn_ctl;                /* return control                */
 unsigned char    reserv4;                /* reserved                      */
 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];            /* TP name                       */
 unsigned char    security;               /* security                      */
 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                      */
 unsigned short   dlen;                   /* data length                   */
 unsigned char   *dptr;                   /* pointer to data buffer        */
} SEND_CONVERSATION;
typedef struct mc_send_conversation
{
 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 char     reserv3[8];             /* reserved                      */
 unsigned char     rtn_ctl;                /* return control                */
 unsigned char     reserv4;                /* reserved                      */
 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];            /* TP name                       */
 unsigned char     security;               /* security                      */
 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                      */
 unsigned short    dlen;                   /* data length                   */
 unsigned char    *dptr;                   /* pointer to data buffer        */
} MC_SEND_CONVERSATION;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:
opcode
AP_B_SEND_CONVERSATION
Displays a basic verb icon.
AP_M_SEND_CONVERSATION
Displays a mapped verb icon.
opext
AP_BASIC_CONVERSATION or AP_MAPPED_CONVERSATION. For nonblocking operation, this flag can be ORed together with AP_NON_BLOCKING.
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
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.

rtn_ctl
Specifies when the local LU acting on a session request from the local transaction processor 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

conv_group_id
The 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.

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.
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
  • AP_PGM
  • AP_SAME
  • AP_PGM_STRONG
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
The 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.
dlen
Number of bytes of data to send.

Range: 0–65535

dptr
Address of the buffer containing the data to send. The application can append data to the end of the VCB, in which case dptr must be set to NULL.

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameters:
primary_rc
AP_OK
conv_group_id
The conversation group identifier of the session allocated to the conversation.
If the verb is nonblocking and has not completed, Personal Communications returns the following parameter:
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 parameters:
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_TP_ID

AP_BAD_LL
Displays a basic verb icon.

AP_BAD_RETURN_CONTROL
AP_BAD_SECURITY
AP_PIP_LEN_INCORRECT

AP_NO_USE_OF_SNASVCMG
Displays a mapped verb icon.

AP_UNKNOWN_PARTNER_MODE

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_UNSUCCESSFUL
Displays a basic verb icon.

AP_ALLOCATION_ERROR

  • AP_ALLOCATION_FAILURE_NO_RETRY
  • AP_ALLOCATION_FAILURE_RETRY
  • AP_SEC_REQUESTED_NOT_SUPPORTED
    Displays a basic verb icon.

AP_TP_BUSY

AP_CONVERSATION_TYPE_MIXED
Displays a mapped verb icon.

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.