query_active_transaction

The query_active_transaction command 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 command may be used to obtain information about a single transaction or about multiple transactions, depending on the options used. It must be issued to a running node.

Supplied Parameters

Parameter name              Type           Length      Default
[query_active_transaction]
num_entries                 decimal                    1
list_options                constant                   LIST_INCLUSIVE
fq_req_loc_cp_name          character      17          (null string)
req_agent_appl_name         character      8           (null string)
seq_num_dt                  hex array      17          (null array)

Supplied parameters are:

num_entries

Maximum number of transactions for which data should be returned. You can specify 1 to return data for a specific transaction, a number greater than 1 to return data for multiple transactions, or 0 (zero) to return data for all transactions.

list_options

The position in the list of transactions from which SNAplus2 begins to return data. 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.

Possible values are:

FIRST_IN_LIST: Start at the first entry in the list
LIST_INCLUSIVE: Start at the entry specified by the fq_req_loc_cp_name, req_agent_appl_name, and seq_num_dt parameters
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

fq_req_loc_cp_name

Fully qualified control point name of the transaction requester. This parameter is ignored if list_options is set to FIRST_IN_LIST. The name is a type-A character string. It consists of a 1-8 character network name, followed by a period, followed by a 1-8 character control point name.

req_agent_appl_name

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

This name is normally a type-1134 character string (using 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.

seq_num_dt

Sequence number date/time correlator (17 bytes long) of the original transaction, as defined in Systems Network Architecture: Formats. This parameter is ignored if list_options is set to FIRST_IN_LIST.

Returned Parameters

Parameter name           Type           Length
fq_origin_cp_name        character      17
origin_ms_appl_name      character      8
fq_dest_cp_name          character      17
dest_ms_appl_name        character      8 
fq_req_loc_cp_name       character      17 
req_agent_appl_name      character      8
seq_num_dt               hex array      17

If the command executes successfully, SNAplus2 returns the following parameters:

fq_origin_cp_name: Fully qualified control point name of the CP initiating the transaction.
origin_ms_appl_name: Name of the application from which the transaction originates. This name is usually a type-1134 character string; alternatively, it can also be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services.
fq_dest_cp_name: Fully qualified control point name of the transaction destination.
dest_ms_appl_name: Application name of the destination application for the transaction. This name is usually a type-1134 character string; alternatively, it can be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services.
fq_req_loc_cp_name: Fully qualified control point name of the transaction requestor.
req_agent_appl_name: Application name of the transaction requester. This name is usually a type-1134 character string; alternatively, it can be one of the MS Discipline-Specific Application Programs specified in Systems Network Architecture: Management Services.
seq_num_dt: Sequence number date/time correlator (17 bytes long) of the original transaction, as defined in Systems Network Architecture: Formats.

Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

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

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_ACTIVE_TRANSACTION: The fq_req_loc_cp_name, req_agent_appl_name, and seq_num_dt parameter values did not match the parameter values specified for an active transaction.

State Check

No specific state errors, other than those listed in Appendix A “Common Return Codes from snapadmin Commands” occur for this command.

Function Not Supported

If the command does not execute because the node's configuration does not support it, SNAplus2 returns the following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED: The local node does not support MS network management functions; support is defined by the mds_supported parameter on the define_node command.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A “Common Return Codes from snapadmin Commands” lists combinations of primary and secondary return codes that are common to all commands.