QUERY_CONVERSATION

QUERY_CONVERSATION returns list information about conversations running over the specified LU. To obtain information about a specific conversation or to obtain the list information in several chunks, the conv_id field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. Note that the lu_alias field must always be set. The lu_name, if nonzero, will be used in preference to the lu_alias.

See Querying the Node for background on how the list formats are used.

This list is ordered by the conv_id. If AP_LIST_FROM_NEXT is selected, the returned list starts from the next entry according to the index (whether the specified entry exists or not).

VCB Structure

typedef struct query_conversation
{
        unsigned short  opcode;            /* Verb operation code        */
        unsigned char   reserv2;           /* reserved                   */
        unsigned char   format;            /* format                     */
        unsigned short  primary_rc;        /* Primary return code        */
        unsigned long   secondary_rc;      /* Secondary return code      */
        unsigned char   *buf_ptr;          /* pointer to buffer          */
        unsigned long   buf_size;          /* buffer size                */
        unsigned long   total_buf_size;    /* total buffer size required */
        unsigned short  num_entries;       /* number of entries          */
        unsigned short  total_num_entries; /* total number of entries    */
        unsigned char   list_options;      /* listing options            */
        unsigned char   reserv3;           /* reserved                   */
        unsigned char   lu_name[8];        /* local LU name              */
        unsigned char   lu_alias[8];       /* local LU alias             */
        unsigned long   conv_id;           /* conversation identifier    */
        unsigned char   session_id[8];     /* session identifier         */
        unsigned char   reserv4[12];       /* reserved                   */
} QUERY_CONVERSATION;
typedef struct conv_summary
{
        unsigned short  overlay_size;      /* size of this entry         */
        unsigned long   conv_id;           /* conversation identifier    */
        unsigned char   local_tp_name[64]; /* Name of local TP           */
        unsigned char   partner_tp_name[64];
                                           /* Name of partner TP         */
        unsigned char   tp_id[8];          /* TP identifier              */
        unsigned char   sess_id[8];        /* session identifier         */
        unsigned long   conv_start_time;   /* time conversation was      */
                                           /* started                    */
        unsigned long   bytes_sent;        /* bytes sent so far          */
        unsigned long   bytes_received;    /* bytes received so far      */
        unsigned char   conv_state;        /* conversation state         */
        unsigned char   duplex_type;       /* conversation duplex type   */
} CONV_SUMMARY;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_CONVERSATION
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr
Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information. The index specified (see following) represents an index value that is used to specify the starting point of the actual information to be returned.
AP_FIRST_IN_LIST
The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE
The returned list starts from the entry specified by the index value.
lu_name
Name of the local LU. This is an 8–byte alphanumeric type A EBCDIC string (not starting with a number), and is right-padded with EBCDIC spaces.
lu_alias
Alias by which the local LU is known by the local TP. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set.
conv_id
Conversation ID.
session_id
If this is all binary zeroes, this field is not used to filter the returned conversations. If it is not zeroes, only those conversations whose session IDs match the supplied value are returned.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries
Number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
conv_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
conv_summary.conv_id
Conversation ID.

The value of this parameter was returned by the ALLOCATE verb in the invoking transaction action or by RECEIVE_ALLOCATE in the invoked transaction program.

conv_summary.local_tp_name
Name of the local transaction program.
conv_summary.partner_tp_name
Name of the partner transaction program. This is only valid for a locally-initiated conversation. For a remotely initiated conversation, it is blank.
conv_summary.tp_id
The transaction program identifier assigned to the transaction program. This identifier is either assigned by the API stub, or by the NOF transaction program manager.
conv_summary.sess_id
Identifier of the session allocated to this conversation.
conv_summary.conv_start_time
The elapsed time in centiseconds from the time the node was started to the time the conversation was started.
conv_summary.bytes_sent
The number of bytes sent so far on this conversation.
conv_summary.bytes_received
The number of bytes received so far on this conversation.
conv_summary_conv_state
Current state of the conversation that is identified by conv_id. For half-duplex conversations, it is one of the following:
AP_RESET_STATE

AP_SEND_STATE
AP_RECEIVE_STATE
AP_CONFIRM_STATE
AP_CONFIRM_SEND_STATE
AP_CONFIRM_DEALL_STATE
AP_PEND_POST_STAT
AP_PEND_DEALL_STATE
AP_END_CONV_STATE
AP_SEND_PENDING_STATE
AP_POST_ON_RECEIPT_STATE

For full-duplex conversations, it is one of the following:

AP_RESET_STATE
AP_SEND_RECEIVE_STATE
AP_SEND_ONLY_STATE
AP_RECEIVE_ONLY_STATE

conv_summary.duplex_type
Specifies whether this conversation is half or full-duplex.

AP_HALF_DUPLEX
AP_FULL_DUPLEX

If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_BAD_CONV_ID

AP_INVALID_LU_ALIAS
AP_INVALID_LU_NAME

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR