QUERY_CONVERSATION

QUERY_CONVERSATION returns information about conversations using a particular local LU. This verb can be used to obtain information about a specific conversation or a range of conversations, depending on the options used.

This verb must be issued to a running node.

VCB Structure

typedef struct query_conversation 
{  AP_UINT16       opcode;                    /* verb operation code        */
   unsigned char   reserv2;                   /* reserved                   */
   unsigned char   format;                    /* reserved                   */
   AP_UINT16       primary_rc;                /* primary return code        */
   AP_UINT32       secondary_rc;              /* secondary return code      */
   unsigned char  *buf_ptr;                   /* pointer to buffer          */
   AP_UINT32       buf_size;                  /* buffer size                */
   AP_UINT32       total_buf_size;            /* total buffer size required */
   AP_UINT16       num_entries;               /* number of entries          */
   AP_UINT16       total_num_entries;         /* total number of entries    */
   unsigned char   list_options;              /* listing options            */
   unsigned char   reserv3;                   /* reserved                   */
   unsigned char   lu_name[8];                /* LU Name                    */
   unsigned char   lu_alias[8];               /* LU Alias                   */
   AP_UINT32       conv_id;                   /* Conversation ID            */
   unsigned char   session_id[8];             /* Session ID                 */
   unsigned char   reserv4[12];               /* reserved                   */
 } QUERY_CONVERSATION;  typedef struct conv_summary 
{  AP_UINT16      overlay_size;                 /*overlay size              */
   AP_UINT32      conv_id;                      /* conversation ID          */
   unsigned char  local_tp_name[64];            /local TP name              */
   unsigned char  partner_tp_name[64];          /partner TP name            */
   unsigned char  tp_id[8];                     /TP ID                      */
   unsigned char  sess_id[8];                   /Session ID                 */
   AP_UINT32      conv_start_time;              /Conversation start time    */
   AP_UINT32      bytes_sent;                   /Number of bytes sent       */
   AP_UINT32      bytes_received;               /Number of bytes received   */
   unsigned char  conv_state;                   /conversation state         */
   unsigned char  reserv1;                      /reserved                   */
 } CONV_SUMMARY;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_CONVERSATION

buf_ptr

A pointer to a data buffer that SNAplus2 will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of conversations for which data should be returned. To request data for a specific conversation rather than a range, specify the value 1. To return as many entries as possible, sepcify zero; in this case, SNAplus2 will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list from which SNAplus2 should begin to return data.

Specify one of the following values:

AP_FIRST_IN_LIST

Start at the first entry in the list.

AP_LIST_INCLUSIVE

Start at the entry specified by the combination of local LU and conversation ID.

AP_LIST_FROM_NEXT

Start at the entry immediately following the entry specified by the combination of local LU and conversation ID.

The combination of the local LU (lu_name or lu_alias and conversation ID (conv_id) specified is used as an index into the list of sessions if the list_options parameter is set to AP_LIST_INCLUSIVE or AP_LIST_FROM_NEXT.

For more information about how the list is ordered and how the application can obtain specific entries from it, see “List Options For QUERY_* Verbs”.

lu_name

LU name. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters. To specify that the LU is identified by its alias rather than its LU name, set this parameter to 8 binary zeros and specify the LU alias in the following parameter. To specify the LU associated with the local CP (the default LU), set both lu_name and lu_alias to binary zeros.

lu_alias

Locally defined LU alias. This is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 bytes. This parameter is used only if lu_name is set to 8 binary zeros; it is ignored otherwise. To specify the LU associated with the local CP (the default LU), set both lu_name and lu_alias to binary zeros.

conv_id

Identifier of the conversation for which information is required, or the conversation ID to be used as an index into the list of conversations. The conversation ID was returned by the ALLOCATE verb in the invoking TP, or by the RECEIVE_ALLOCATE verb in the invoked TP.

This parameter is ignored if list_options is set to AP_FIRST_IN_LIST.

session_id

8-byte identifier of the session. To list only information about conversations associated with a specific session, specify the session identifier. To obtain a complete list for all sessions, set this field to binary zeros.

Returned Parameters: Successful Execution

If the verb executes successfull, SNAplus2 returns the following parameters:

primary_rc

AP_OK

buf_size

Length of the information returned in the supplied buffer.

total_buf_size

REturned value indicating the size of buffer that would have been required to return all the list information requested. A value greater than buf_size indicates that not all the available entries were returned.

num_entries

Number of entries returned in the data buffer.

total_num_entries

Total number of entries available. A value greater than num_entries indicates that not all the vailable entries were returned.

Each entry in the data buffer consists of the following parameters:

conv_summary.overlay_size

The size of the returned conv_summary structure, and therefore the offset to the start of the next entry in the data buffer.

When you r application needs to go through the returned buffer to find each conv_summary structure in turn, it must use this value to move to the correct offset for the next data structure, and must not use the C sizeof () operator. This is because the size of the returned overlay may increase in furutre releases of SNAplus2; using the returned overlay size ensures that your application will continue to work with future releases.

conv_summary.conv_id

Conversation identifier. The conversation ID was returned by the ALLOCATE verb in the invoking TP, or by the RECEIVE_ALLOCATE verb in the invoked TP.

conv_summary.local_tp_name

The name of the local TP in the conversation.

conv_summary.partner_tp_name

The name of the partner TP in the conversation. This parameter is returned only if the conversation was started by the local TP; it is reserved if the conversation was started by the remote TP.

conv_summary.tp_id

The TP identifier of the conversation.

conv_summary.session_id

The session identifier of the session allocated to the conversation.

conv_summary.conv_start_time

The elapsed time in hundredths of seconds between the time when the SNAplusw node was started and the time when the conversation was started.

conv_summary.bytes_sent

The number of bytes that have been sent from the local TP to the partner TP since the start of the conversation.

conv_summary.bytes_received

The number of bytes that have been received from the partner TP by the local TP since the start of the conversation.

conv_summary.conv_state

The current state of the conversation. Values are:

AP_CONFIRM_STATE
AP_CONFIRM_DEALL_STATE
AP_CONFIRM_SEND_STATE
AP_END_CONV_STATE
AP_PEND_DEALL_STATE
AP_PEND_POST_STATE
AP_POST_ON_RECEIPT_STATE
AP_RECEIVE_STATE
AP_RESET_STATE
AP_SEND_STATE
AP_SEND_PENDING_STATE

Returned Parameters: Parameter Check

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

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_BAD_CONV_ID: The list_options parameter was set to AP_LIST_INCLUSIVE to list all entries starting from the supplied value, but the conv_id parameter was not valid
AP_INVALID_LU_ALIAS: The specivied lu_name parameter was not valid.
AP_INVALID_LU_NAME: The specified lu_name parameter was not valid.
AP_INVALID_LIST_OPTION: The list_options parameter was not set to a valid value.

Appendix A “Common Return Codes”lists further secondary return codes asociated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

QUERY_CONVERSATION

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Other Conditions