DISPLAY CHSTATUS
Overview
Display the status of one or more channels.
Synonym: DIS CHS
Syntax
DISPLAY CHSTATUS >>-DISPLAY CHSTATUS(generic-channel-name)--+-----+--------------> '-ALL-' '-CHLDISP(PRIVATE)-----' .-CURRENT----. >--+--------------------------+--+------------+-----------------> '-CONNAME(connection-name)-' +-SAVED------+ >--+---------------+--+-------------------+---------------------> '-XMITQ(q-name)-' '-| common status |-' >--+-------------------------+--+------------------+----------->< '-| current-only status |-' '-| short status |-' Common status |--+------------------+-----------------------------------------| | .-,------------. | | V | | '---+-CURLUWID-+-+-' +-CURMSGS--+ +-CURSEQNO-+ +-INDOUBT--+ +-LSTLUWID-+ +-LSTSEQNO-+ '-STATUS---' Current-only status |--+-----------------------+------------------------------------| | .-,-----------------. | | V | | '---+-BATCHES-------+-+-' +-BATCHSZ-------+ +-BUFSRCVD------+ +-BUFSSENT------+ +-BYTSRCVD------+ +-BYTSSENT------+ +-CHSTADA-------+ +-CHSTATI-------+ +-HBINT---------+ +-JOBNAME-------+ +-LOCLADDR------+ +-LONGRTS-------+ +-LSTMSGDA------+ +-LSTMSGTI------+ +-MCASTAT-------+ +-MSGS----------+ +-NPMSPEED------+ +-RQMNAME-------+ +-SHORTRTS------+ +-SSLPEER-------+ '-STOPREQ-------'
Parameter descriptions
You must specify the name of the channel for which you want to display status information. This can be a specific channel name or a generic channel name. By using a generic channel name, you can display either:
- Status information for all channels, or
- Status information for one or more channels that match the specified name.
You can also specify whether you want:
- The current status data (of current channels only), or
- The saved status data of all channels.
Status for all channels that meet the selection criteria is given, whether the channels were defined manually or automatically.
Before explaining the syntax and options for this command, it is necessary to describe the format of the status data that is available for channels and the states that channels can have.
There are three classes of data available for channel status. These are saved and current
The status fields available for saved data are a subset of the fields available for current data and are called common status fields. Note that although the common data fields are the same, the data values might be different for saved and current status. The rest of the fields available for current data are called current-only status fields.
- Saved data consists of the common status fields noted in the syntax diagram. This data is reset at the following times:
- For all channels:
- When the channel enters or leaves STOPPED or RETRY state
- When the queue manager is ended
- For a sending channel:
- Before requesting confirmation that a batch of messages has been received
- When confirmation has been received
- For a receiving channel:
- Just before confirming that a batch of messages has been received
- For a server connection channel:
- No data is saved
Therefore, a channel that has never been current cannot have any saved status.
Status is not saved until a persistent message is transmitted across a channel, or a nonpersistent message is transmitted with a NPMSPEED of NORMAL. Because status is saved at the end of each batch, a channel does not have any saved status until at least one batch has been transmitted.
- Current data consists of the common status fields and current-only status fields as noted in the syntax diagram. The data fields are continually updated as messages are sent/received.
- Short data consists of the STATUS current data item and the short status field as noted in the syntax diagram.
This method of operation has the following consequences:
- An inactive channel might not have any saved status - if it has never been current or has not yet reached a point where saved status is reset.
- The "common" data fields might have different values for saved and current status.
- A current channel always has current status and might have saved status.
Channels can be current or inactive:
- Current channels
- These are channels that have been started, or on which a client has connected, and that have not finished or disconnected normally. They might not yet have reached the point of transferring messages, or data, or even of establishing contact with the partner. Current channels have current status and might also have saved status.
The term Active is used to describe the set of current channels that are not stopped.
- Inactive channels
- These are channels that either:
- Have not been started
- On which a client has not connected
- Have finished
- Have disconnected normally
(Note that if a channel is stopped, it is not yet considered to have finished normally - and is, therefore, still current.) Inactive channels have either saved status or no status at all.
There can be more than one instance of the same named receiver, requester, cluster-receiver, or server-connection channel current at the same time (the requester is acting as a receiver). This occurs if several senders, at different queue managers, each initiate a session with this receiver, using the same channel name. For channels of other types, there can only be one instance current at any time.
For all channel types, however, there can be more than one set of saved status information available for a given channel name. At most one of these sets relates to a current instance of the channel, the rest relate to previously-current instances. Multiple instances arise if different transmission queue names or connection names have been used in connection with the same channel. This can happen in the following cases:
- At a sender or server:
- If the same channel has been connected to by different requesters (servers only)
- If the transmission queue name has been changed in the definition
- If the connection name has been changed in the definition
- At a receiver or requester:
- If the same channel has been connected to by different senders or servers
- If the connection name has been changed in the definition (for requester channels initiating connection)
The number of sets that are displayed for a given channel can be limited by using the XMITQ, CONNAME, and CURRENT parameters on the command.
- (generic-channel-name)
- The name of the channel definition for which status information is to be displayed. A trailing asterisk (*) matches all channel definitions with the specified stem followed by zero or more characters. An asterisk (*) on its own specifies all channel definitions. The channels must all be defined to the local queue manager.
- XMITQ(q-name)
- The name of the transmission queue for which status information is to be displayed, for the specified channel or channels.
This parameter can be used to limit the number of sets of status information that is displayed. If it is not specified, the display is not limited in this way.
CHLDISP displays the following values:
- PRIVATE
- The status is for a private channel.
- SHARED
- The status is for a shared channel.
- FIXSHARED
- The status is for a shared channel, tied to a specific queue manager.
- CONNAME(connection-name)
- The connection name for which status information is to be displayed, for the specified channel or channels.
This parameter can be used to limit the number of sets of status information that is displayed. If it is not specified, the display is not limited in this way.
The value returned for CONNAME might not be the same as in the channel definition, and might differ between the current channel status and the saved channel status. (Using CONNAME for limiting the number of sets of status is therefore not recommended.)
For example, if CONNAME:
- Is blank in the channel definition or, when using TCP, is in "host name" format, the channel status value has the resolved IP address.
- Includes the port number, again when using TCP, the current channel status value includes the port number, but the saved channel status value does not.
For SAVED or SHORT status, this value could also be the queue manager name, or queue-sharing group name, of the remote system.
- CURRENT
- This is the default, and indicates that current status information as held by the channel initiator for current channels only is to be displayed.
Both common and current-only status information can be requested for current channels.
Short status information is not displayed if this parameter is specified.
- SAVED
- Specify this to display saved status information for both current and inactive channels.
Only common status information can be displayed. Short and current-only status information is not displayed for current channels if this parameter is specified.
- SHORT
- This indicates that short status information and the STATUS item for current channels only is to be displayed.
Other common status and current-only status information is not displayed for current channels if this parameter is specified.
- ALL
- Specify this to display all the status information for each relevant instance.
If SAVED is specified, this causes only common status information to be displayed, not current-only status information.
If this parameter is specified, any parameters requesting specific status information that are also specified have no effect; all the information is displayed.
The following information is always returned, for each set of status information:
- The channel name
- The transmission queue name (for sender and server channels)
- The connection name
- The remote queue-manager, or queue-sharing group, name (only for current status)
- The type of status information returned (CURRENT or SAVED)
- STATUS
If no parameters requesting specific status information are specified (and the ALL parameter is not specified), no further information is returned.
If status information is requested that is not relevant for the particular channel type, this is not an error.
Common status
The following information applies to all sets of channel status, whether or not the set is current. The information applies to all channel types except server-connection.
- CURLUWID
- The logical unit of work identifier associated with the current batch, for a sending or a receiving channel.
For a sending channel, when the channel is in doubt it is the LUWID of the in-doubt batch.
For a saved channel instance, this parameter has meaningful information only if the channel instance is in doubt. However, the parameter value is still returned when requested, even if the channel instance is not in doubt.
It is updated with the LUWID of the next batch when this is known.
- CURMSGS
- For a sending channel, this is the number of messages that have been sent in the current batch. It is incremented as each message is sent, and when the channel becomes in doubt it is the number of messages that are in doubt.
For a saved channel instance, this parameter has meaningful information only if the channel instance is in doubt. However, the parameter value is still returned when requested, even if the channel instance is not in doubt.
For a receiving channel, it is the number of messages that have been received in the current batch. It is incremented as each message is received.
The value is reset to zero, for both sending and receiving channels, when the batch is committed.
- CURSEQNO
- For a sending channel, this is the message sequence number of the last message sent. It is updated as each message is sent, and when the channel becomes in doubt it is the message sequence number of the last message in the in-doubt batch.
For a saved channel instance, this parameter has meaningful information only if the channel instance is in doubt. However, the parameter value is still returned when requested, even if the channel instance is not in doubt.
For a receiving channel, it is the message sequence number of the last message that was received. It is updated as each message is received.
- INDOUBT
- Whether the channel is currently in doubt.
This is only YES while the sending Message Channel Agent is waiting for an acknowledgment that a batch of messages that it has sent has been successfully received. It is NO at all other times, including the period during which messages are being sent, but before an acknowledgment has been requested.
For a receiving channel, the value is always NO.
- LSTLUWID
- The logical unit of work identifier associated with the last committed batch of messages transferred.
- LSTSEQNO
- Message sequence number of the last message in the last committed batch. This number is not incremented by nonpersistent messages using channels with a NPMSPEED of FAST.
- STATUS
- Current status of the channel. This is one of the following:
- STARTING
- A request has been made to start the channel but the channel has not yet begun processing. A channel is in this state if it is waiting to become active.
- BINDING
- Channel is performing channel negotiation and is not yet ready to transfer messages.
- INITIALIZING
- The channel initiator is attempting to start a channel.
- RUNNING
- The channel is either transferring messages at this moment, or is waiting for messages to arrive on the transmission queue so that they can be transferred.
- STOPPING
- Channel is stopping or a close request has been received.
- RETRYING
- A previous attempt to establish a connection has failed. The MCA will reattempt connection after the specified time interval.
- PAUSED
- The channel is waiting for the message-retry interval to complete before retrying an MQPUT operation.
- STOPPED
- This state can be caused by one of the following:
- Channel manually stopped
A user has entered a stop channel command against this channel.
- Retry limit reached
The MCA has reached the limit of retry attempts at establishing a connection. No further attempt will be made to establish a connection automatically.
A channel in this state can be restarted only by issuing the START CHANNEL command, or starting the MCA program in an operating-system dependent manner.
- REQUESTING
- A local requester channel is requesting services from a remote MCA.
For an inactive channel, CURMSGS, CURSEQNO, and CURLUWID have meaningful information only if the channel is INDOUBT. However they are still displayed and returned if requested.
Current-only status
The following information applies only to current channel instances. The information applies to all channel types, except where stated.
- BATCHES
- Number of completed batches during this session (since the channel was started).
- BATCHSZ
- The batch size being used for this session
This parameter does not apply to server-connection channels, and no values are returned; if specified on the command, this is ignored.
- BUFSRCVD
- Number of transmission buffers received. This includes transmissions to receive control information only.
- BUFSSENT
- Number of transmission buffers sent. This includes transmissions to send control information only.
- BYTSRCVD
- Number of bytes received during this session (since the channel was started). This includes control information received by the message channel agent.
- BYTSSENT
- Number of bytes sent during this session (since the channel was started). This includes control information sent by the message channel agent.
- CHSTADA
- Date when this channel was started (in the form yyyy-mm-dd).
- CHSTATI
- Time when this channel was started (in the form hh.mm.ss).
- HBINT
- The heartbeat interval being used for this session.
- JOBNAME
- Name of job currently serving the channel.
This is the concatenation of the process identifier and the thread identifier of the MCA program, displayed in hexadecimal.
- LOCLADDR
- Local communications address for the channel. The value returned depends on the TRPRYPE of the channel (currently only TCP/IP is supported).
- LONGRTS
- Number of long retry wait start attempts left. This applies only to sender or server channels.
- LSTMSGDA
- Date when the last message was sent or MQI call was handled, see LSTMSGTI.
- LSTMSGTI
- Time when the last message was sent or MQI call was handled.
For a sender or server, this is the time the last message (the last part of it if it was split) was sent. For a requester or receiver, it is the time the last message was put to its target queue. For a server-connection channel, it is the time when the last MQI call completed.
- MCASTAT
- Whether the Message Channel Agent is currently running. This is either "running" or "not running".
Note that it is possible for a channel to be in stopped state, but for the program still to be running.
- MSGS
- Number of messages sent or received (or, for server-connection channels, the number of MQI calls handled) during this session (since the channel was started).
- NPMSPEED
- The nonpersistent message handling technique being used for this session.
- RQMNAME
- The queue manager name, or queue-sharing group name, of the remote system. This parameter does not apply to server-connection channels, where no values are returned.
- SHORTRTS
- Number of short retry wait start attempts left. This applies only to sender or server channels.
- SSLPEER
- Distinguished Name of the peer queue manager or client at the other end of the channel.
The maximum length is 256 characters. This limit might mean that exceptionally long Distinguished Names are truncated.
- STOPREQ
- Whether a user stop request is outstanding. This is either YES or NO.
Short status
The following information applies only to current channel instances.
- QMNAME
- The name of the queue manager that owns the channel instance.
Examples
From queue manager TOLSTOY
dis chs(*) all 1 : dis chs(*) all AMQ8417: Display Channel Status details. CHANNEL(TO.TOLSTOY) XMITQ( ) CONNAME(192.168.1.230) CURRENT CHLTYPE(CLUSRCVR) INDOUBT(NO) LSTSEQNO(72) LSTLUWID(DE25AB3F02000010) CURMSGS(0) CURSEQNO(72) CURLUWID(DE25AB3F02000010) STATUS(RUNNING) LSTMSGTI( ) LSTMSGDA( ) MSGS(0) BYTSSENT(188) BYTSRCVD(188) BATCHES(2) BATCHSZ(50) HBINT(300) NPMSPEED(FAST) CHSTATI(22.09.03) CHSTADA(2003-11-07) BUFSSENT(3) BUFSRCVD(3) LONGRTS(999999999) SHORTRTS(10) JOBNAME(0000206100000007) MCASTAT(RUNNING) STOPREQ(NO) LOCLADDR(192.168.1.246(1414)) SSLPEER() RQMNAME(TWAIN) AMQ8417: Display Channel Status details. CHANNEL(TO.TWAIN) XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE) CONNAME(TWAIN) CURRENT CHLTYPE(CLUSSDR) INDOUBT(NO) LSTSEQNO(70) LSTLUWID(9224AB3F01000010) CURMSGS(0) CURSEQNO(70) CURLUWID(9224AB3F01010010) STATUS(RUNNING) LSTMSGTI( ) LSTMSGDA( ) MSGS(0) BYTSSENT(160) BYTSRCVD(160) BATCHES(1) BATCHSZ(50) HBINT(300) NPMSPEED(FAST) CHSTATI(22.13.34) CHSTADA(2003-11-07) BUFSSENT(2) BUFSRCVD(2) LONGRTS(999999999) SHORTRTS(10) JOBNAME(0000206100000008) MCASTAT(RUNNING) STOPREQ(NO) LOCLADDR(192.168.1.246(59084)) SSLPEER() RQMNAME(TWAIN)
From queue manager TWAIN
dis chs(*) all 1 : dis chs(*) all AMQ8417: Display Channel Status details. CHANNEL(TO.TOLSTOY) XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE) CONNAME(TOLSTOY) CURRENT CHLTYPE(CLUSSDR) INDOUBT(NO) LSTSEQNO(72) LSTLUWID(DE25AB3F02000010) CURMSGS(0) CURSEQNO(72) CURLUWID(DE25AB3F01010010) STATUS(RUNNING) LSTMSGTI( ) LSTMSGDA( ) MSGS(0) BYTSSENT(244) BYTSRCVD(244) BATCHES(4) BATCHSZ(50) HBINT(300) NPMSPEED(FAST) CHSTATI(22.14.23) CHSTADA(2003-11-07) BUFSSENT(5) BUFSRCVD(5) LONGRTS(999999999) SHORTRTS(10) JOBNAME(00007E2000000008) MCASTAT(RUNNING) STOPREQ(NO) LOCLADDR(192.168.1.230(57781)) SSLPEER() RQMNAME(TOLSTOY) AMQ8417: Display Channel Status details. CHANNEL(TO.TWAIN) XMITQ( ) CONNAME(192.168.1.246) CURRENT CHLTYPE(CLUSRCVR) INDOUBT(NO) LSTSEQNO(70) LSTLUWID(9224AB3F01000010) CURMSGS(0) CURSEQNO(70) CURLUWID(9224AB3F01000010) STATUS(RUNNING) LSTMSGTI( ) LSTMSGDA( ) MSGS(0) BYTSSENT(216) BYTSRCVD(216) BATCHES(3) BATCHSZ(50) HBINT(300) NPMSPEED(FAST) CHSTATI(22.18.55) CHSTADA(2003-11-07) BUFSSENT(4) BUFSRCVD(4) LONGRTS(999999999) SHORTRTS(10) JOBNAME(00007E2000000009) MCASTAT(RUNNING) STOPREQ(NO) LOCLADDR(192.168.1.230(1414)) SSLPEER() RQMNAME(TOLSTOY)