QUERY_ACTIVE_TRANSACTION

QUERY_ACTIVE_TRANSACTION returns information about active Multiple Domain Support (MDS) transactions known to the SNAplus2 Management Services component. An active transaction is an MDS request for which a reply has not yet been received.

This verb may be used to obtain information about a single transaction, or on multiple transactions, depending on the options used.

This verb must be issued to a running node.

VCB Structure

typedef struct query_active_transaction
{
   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    fq_req_loc_cp_name[17]; /* fq cp name of transaction     */
                                            /*  requestor                    */
   unsigned char    req_agent_appl_name[8]; /* appl name of transaction      */
                                            /*  requestor                    */
   unsigned char    seq_num_dt[17];         /* sequence number date/time     */
} QUERY_ACTIVE_TRANSACTION;

typedef struct active_transaction_data
{
   AP_UINT16       overlay_size;            /* size of returned entry        */
   unsigned char   fq_origin_cp_name[17];   /* cp name of transaction origin */
   unsigned char   origin_ms_appl_name[8];  /* appl name of transaction      */
                                            /*  origin                       */
   unsigned char   fq_dest_cp_name[17];     /* cp name of transaction        */
                                            /*  destination                  */
   unsigned char   dest_ms_appl_name[8];    /* appl name of transaction dest */
   unsigned char   fq_req_loc_cp_name[17];  /* fq cp name of transaction     */
                                            /*  requestor                    */
   unsigned char   req_agent_appl_name[8];  /* appl name of transaction      */
                                            /*  requestor                    */
   unsigned char   seq_num_dt[17];          /* sequence number date/time     */
   unsigned char   reserva[20];             /* reserved                      */
} ACTIVE_TRANSACTION_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_ACTIVE_TRANSACTION

overlay_size

For compatability with future releases of SNAplus2, your application must use this field to determine the exact length of the overlay structure returned, and should not rely on the use of the sizeof()function.

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 transactions for which data should be returned. To request data for a specific transaction rather than a range, specify the value 1. To return as many entries as possible, specify 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. Possible values are:

AP_FIRST_IN_LIST: Start at the first entry in the list.
AP_LIST_INCLUSIVE: Start at the entry specified by the fq_req_loc_cp_name, req_agent_appl_name, and seq_num_dt parameters.
AP_LIST_FROM_NEXT: Start at the entry immediately following the entry specified by the fq_req_loc_cp_name, req_agent_appl_name, and seq_num_dt parameters.

The list is ordered by fq_req_loc_cp_name, then by req_agent_appl_name, and finally in numerical order of seq_num_dt. 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”.

fq_req_loc_cp_name

Fully qualified control point name of the transaction requestor. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST. The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

req_agent_appl_name

Application name of the transaction requestor. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST.

This name is normally an EBCDIC string, using type-1134 characters (uppercase A-Z and numerals 0-9); alternatively, it can be one of the MS Discipline-Specific Application Programs specified in SNA Management Services Reference. The string must be 8 characters long; pad on the right with EBCDIC space characters (0x40) if necessary.

seq_num_dt

Sequence number date/time correlator (17 bytes long) of the original transaction, as defined in the IBM SNA Formats manual. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters: Successful Execution

If the verb executes successfully, 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 available entries were returned.

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

active_transaction_data.overlay_size

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

active_transaction_data.fq_origin_cp_name

Fully qualified control point name of the origin for the transaction. The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

active_transaction_data.origin_ms_appl_name

Application name of the origin for the transaction. This name is normally an 8-character EBCDIC string, using type-1134 characters (uppercase A-Z and numerals 0-9); alternatively, it can be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services Reference (see “Related Publications”).

active_transaction_data.fq_dest_cp_name

Fully qualified control point name of the destination for the transaction. The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

active_transaction_data.dest_ms_appl_name

Application name of the destination application for the transaction. This name is normally an 8-character EBCDIC string, using type-1134 characters (uppercase A-Z and numerals 0-9); alternatively, it can be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services Reference (see “Related Publications”).

active_transaction_data.fq_req_loc_cp_name

Fully qualified control point name of the transaction requestor. The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

active_transaction_data.req_agent_appl_name

Application name of the transaction requestor. This name is normally an 8-character EBCDIC string, using type-1134 characters (uppercase A-Z and numerals 0-9); alternatively, it can be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services Reference (see “Related Publications”).

active_transaction_data.seq_num_dt

Sequence number date/time correlator (17 bytes long) of the original transaction, as defined in the IBM SNA Formats manual.

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_INVALID_ACTIVE_TRANSACTION: The control point name, application name, or sequence number correlator did not match that of an active transaction.
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 associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: Function Not Supported

If the verb does not execute successfully because the local node configuration does not support it, SNAplus2 returns the following parameters:

primary_rc

AP_FUNCTION_NOT_SUPPORTED: The local node does not support MS network management functions; this is defined by the mds_supported parameter on the DEFINE_NODE verb.

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_ACTIVE_TRANSACTION

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Function Not Supported

Returned Parameters: Other Conditions