[IBM i]

MQSTS (Status reporting structure) on IBM i

The MQSTS structure describes the data in the status structure returned by the MQSTAT command.

Overview

Character set and encoding: Character data in MQSTS is in the character set of the local queue manager; this is given by the CodedCharSetId queue manager attribute. Numeric data in MQSTS is in the native machine encoding; this is given by ENNAT.

Usage: The MQSTAT command is used to retrieve status information. This information is returned in an MQSTS structure. For information about MQSTAT, see MQSTAT (Retrieve status information) on IBM i.

Fields

The MQSTS structure contains the following fields; the fields are described in alphabetical order:

STSCC (10-digit signed integer)

This is the completion code resulting from the first error reported in the MQSTS structure.

This is always an output field. The initial value of this field is CCOK.

STSFC (10-digit signed integer)

This is the number of asynchronous put calls that failed.

This is an output field. The initial value of this field is 0.

STSOBJN (48-byte character string)

This is the local name of the object involved in the first failure.

This is an output field. The initial value of this field is 48 blank characters.

STSOQMGR (48-byte character string)

This is the name of the queue manager on which the STSOBJN object is defined. A name that is entirely blank up to the first null character or the end of the field denotes the queue manager to which the application is connected (the local queue manager).

This is an output field. The initial value of this field is 48 blank characters.

STSOO (10-digit signed integer)

The STSOO used to open the object being reported upon. Present only in version 2 of MQSTS or higher.

The value of STSOO depends on the value of the MQSTAT STYPE parameter.
STATAPT

Zero.

STATREC

Zero.

STATRER

The STSOO used when the failure occurred. The reason for the failure is reported in the STSCC and STSRC fields in the MQSTS structure.

STSOO is an output field. Its initial value is zero.

STSOS (MQCHARV)

Long object name of failing object being reported on. Present only in version 2 of MQSTS or higher.

STSOS is a MQCHARV field with a maximum length of 10240. See MQCHARV for a description of how to use the MQCHARV structure.

The interpretation of STSOS depends on the value of the MQSTAT STYPE parameter.

STATAPT

This is the long object name of the queue or topic used in the MQPUT operation, which failed.

STATREC

Zero length string

STATRER

This is the long object name of the object that caused the reconnection to fail.

STSOS is an output field. Its initial value is a zero length string.

STSOT (10-digit signed integer)
The type of object being named in ObjectName. Possible values are:
OTALSQ
Alias queue.
OTLOCQ
Local queue.
OTMODQ
Model queue.
OTQ
Queue.
OTREMQ
Remote queue.
OTTOP
Topic.

This is always an output field. The initial value of this field is OTQ.

STSRC (10-digit signed integer)

This is the reason code resulting from the first error reported in the MQSTS structure

This is always an output field. The initial value of this field is RCNONE.

STSROBJN (48-byte character string)

This is the name of the destination queue named in STSOBJN after the local queue manager resolves the name. The name returned is the name of a queue that exists on the queue manager identified by STSRQMGR.

A nonblank value is returned only if the object is a single queue opened for browse, input, or output (or any combination). If the object opened is any of the following, STSROBJN is set to blanks:
  • A topic
  • A queue, but not opened for browse, input, or output

This is an output field. The initial value of this field is 48 blank characters.

STSRQMGR (48-byte character string)

This is the name of the destination queue manager after the local queue manager resolves the name. The name returned is the name of the queue manager that owns the queue identified by STSROBJN. STSRQMGR can be the name of the local queue manager.

If STSROBJN is a shared queue that is owned by the queue sharing group to which the local queue manager belongs, STSRQMGR is the name of the queue sharing group. If the queue is owned by some other queue sharing group, STSROBJN can be the name of the queue sharing group or the name of a queue manager that is a member of the queue sharing group (the nature of the value returned is determined by the queue definitions that exist at the local queue manager).

A nonblank value is returned only if the object is a single queue opened for browse, input, or output (or any combination). If the object opened is any of the following, STSRQMGR is set to blanks:
  • A topic
  • A queue, but not opened for browse, input, or output
  • A cluster queue with OOBNDN specified (or with OOBNDQ in effect when the DefBind queue attribute has the value OOBNDN)

This is an output field. The initial value of this field is 48 blank characters.

STSSC (10-digit signed integer)

This is the number of asynchronous put calls that succeeded.

This is an output field. The initial value of this field is 0.

STSSID (4-byte character string)
This is the structure identifier. The value must be:
STSSID
Identifier for status reporting structure.

The initial value of this field is STSSID.

STSSO (10 digit signed integer)

The STSSO used to open the failing subscription. Present only in version 2 of MQSTS or higher.

The interpretation of STSSO depends on the value of the MQSTAT STYPE parameter.
STATAPT

Zero.

STATREC

Zero.

STATRER

The STSSO used when the failure occurred. The reason for the failure is reported in the STSCC and STSRC fields in the MQSTS structure. If the failure is not related to subscribing to a topic, the value returned is zero.

STSSO is an output field. Its initial value is zero.

STSSUN (MQCHARV)

The name of the failing subscription. Present only in version 2 of MQSTS or higher.

STSSUN is a MQCHARV field with a maxiumum length of 10240. See MQCHARV for a description of how to use the MQCHARV structure.

The interpretation of STSSUN depends on the value of the MQSTAT STYPE parameter.
STATAPT

Zero length string.

STATREC

Zero length string.

STATRER

The name of the subscription that caused reconnection to fail. If no subscription name is available, or the failure is not related to a subscription, this is a zero-length string.

STSSUN is an output field. Its initial value is a zero length string.

STSVER (10-digit signed integer)
This is the structure version number. The value must be:
STSVR1
Version number for status reporting structure.
The following constant specifies the version number of the current version:
STSVRC
Current version of status reporting structure.

The initial value of this field is STSVR1.

STSWC (10-digit signed integer)

This is the number of asynchronous put calls that completed with a warning.

This is an output field. The initial value of this field is 0.

Initial values

Table 1. Fields in MQSTS
Field name Name of constant Value of constant
STSSID STSID  
STSVER STSVRC STSVR1
STSCC CCOK 0
STSRC RCNONE 0
STSSC None 0
STSWC None 0
STSFC None 0
STSOT None 0
STSOBJN None Blanks
STSOQMGR None Blanks
STSROBJN None Blanks
STSRQMGR None Blanks
STSOS Names and values as defined for MQCHARV  
STSSUN Names and values as defined for MQCHARV  
STSOO None 0
STSSO None 0

RPG declaration

         D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
         D* MQSTS Structure
         D*
         D* Structure identifier
         D  STSSID                 1      4
         D* Structure version number
         D  STSVER                 5      8I 0
         D* Completion code
         D  STSCC                  9     12I 0
         D* Reason code
         D  STSRC                 13     16I 0
         D* Success count
         D  STSSC                 17     20I 0
         D* Warning count
         D  STSWC                 21     24I 0
         D* Failure count
         D  STSFC                 25     28I 0
         D* Object type
         D  STSOT                 29     32I 0
         D* Object name
         D  STSOBJN               33     80
         D* Object queue manager
         D  STSOQMGR              81     128
         D* Resolved object name
         D  STSROBJN             129     176
         D* Resolved object queue manager name
         D  STSRQMGR             177     224
         D* Ver:1 **
         D* Failing object long name
         D* Address of variable length string
         D  STSOSCHRP            225    240*  
         D* Offset of variable length string
         D  STSOSCHRO            241    244I 0
         D* Size of buffer
         D  STSOSVSBS            245    248I 0
         D* Length of variable length string
         D  STSOSCHRL            249    252I 0
         D* CCSID of variable length string
         D  STSOSCHRC            253    256I 0
         D* Failing subscription name
         D* Address of variable length string
         D  STSSUNCHRP           257    272*  
         D* Offset of variable length string
         D  STSSUNCHRO           273    276I 0
         D* Size of buffer
         D  STSSUNVSBS           277    280I 0
         D* Length of variable length string
         D  STSSUNCHRL           281    284I 0
         D* CCSID of variable length string
         D  STSSUNCHRC           285    288I 0
         D* Failing open options
         D  STSOO                289    292I 0
         D* Failing subscription options
         D  STSSO                293    296I 0
         D* Ver:2 **