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.
There are three classes of data available for channel status. These are saved, current, and (on z/OS only) short.
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
- On AIX, HP OpenVMS, HP-UX, Linux, i5/OS, Solaris, and Windows,
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:
Therefore, a channel that has never been current cannot have any
saved status.
Note:
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.
Note:
On Compaq NonStop Kernel, channel status is updated only at the boundaries
of batch processing. Channel status information is not updated for every message
transfer because of the potential impact on the performance of channels. This
means that the common status data values are identical for both the current
and saved sets.
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.
- WHERE
- Specify a filter condition to display status information for those channels
that satisfy the selection criterion of the filter condition. The filter condition
is in three parts: filter-keyword, operator, and filter-value:
- filter-keyword
- The parameter to be used to display attributes for this DISPLAY command.
However, you cannot use the following parameters as filter keywords: CHLDISP,
CMDSCOPE, COMPRATE, COMPTIME, CURRENT, EXITTIME, JOBNAME (on z/OS), MCASTAT
(on z/OS), MONITOR, NETTIME, SAVED, SHORT, XBATCHSZ, or XQTIME as filter
keywords.
You cannot use CONNAME or XMITQ
as filter keywords if you also use them to select channel status.
Status information for channels of a type for which the filter keyword is
not valid is not displayed.
- operator
- This is used to determine whether a channel satisfies the filter value
on the given filter keyword. The operators are:
- LT
- Less than
- GT
- Greater than
- EQ
- Equal to
- NE
- Not equal to
- LE
- Less than or equal to
- GE
- Greater than or equal to
- LK
- Matches a generic string that you provide as a filter-value
- NL
- Does not match a generic string that you provide as a filter-value
- CT
- Contains a specified item. If the filter-keyword is a list,
you can use this to display objects the attributes of which contain the specified
item.
- EX
- Does not contain a specified item. If the filter-keyword is
a list, you can use this to display objects the attributes of which do not
contain the specified item.
- filter-value
- The value that the attribute value must be tested against using the
operator. Depending on the filter-keyword, this can be:
- An explicit value, that is a valid value for the attribute being tested.
You can use operators LT, GT, EQ, NE, LE or GE only. However, if the attribute
value is one from a possible set of values on a parameter (for example, the
value SDR on the CHLTYPE parameter), you can only use EQ or NE.
- A generic value. This is a character string with an asterisk at the end,
for example ABC*. If the operator is LK, all items where the attribute
value begins with the string (ABC in the example) are listed. If the operator
is NL, all items where the attribute value does not begin with the string
are listed.
You cannot use a generic filter-value for parameters with numeric
values or with one of a set of values.
- An item in a list of values. Use CT or EX as the operator. For example,
if the value DEF is specified with the operator CT, all items where one of
the attribute values is DEF are listed.
-
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.
- CHLDISP
- This parameter applies to z/OS only and specifies the disposition of
the channels for which information is to be displayed, as used in the START
and STOP CHANNEL commands, and not that set by QSGDISP
for the channel definition. Values are:
- ALL
- This is the default value and displays requested status information
for private channels.
If there is a shared queue manager environment and
the command is being executed on the queue manager where it was issued, or
if CURRENT is specified, this option also displays the requested status information
for shared channels.
- PRIVATE
- Display requested status information for private channels.
- SHARED
- Display requested status information for shared channels. This is allowed
only if there is a shared queue manager environment, and either:
- CMDSCOPE is blank or the local queue manager
- CURRENT is specified
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.
- CMDSCOPE
- This parameter applies to z/OS only and specifies how the command is
executed when the queue manager is a member of a queue-sharing group.
- ' '
- The command is executed on the queue manager on which it was entered.
This is the default value.
- qmgr-name
- The command is executed on the queue manager you specify, providing
the queue manager is active within the queue-sharing group.
You can specify
a queue manager name, other than the queue manager on which it was entered,
only if you are using a queue-sharing group environment and if the command
server is enabled.
- *
- The command is executed on the local queue manager and is also passed
to every active queue manager in the queue-sharing group. The effect of this
is the same as entering the command on every queue manager in the queue-sharing
group.
You cannot use CMDSCOPE as a filter
keyword.
Note:
See
Table 8,
Table 9,
and
Table 10 for the permitted combinations of CHLDISP and CMDSCOPE.
-
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, when using TCP, if CONNAME in the channel definition
:
- Is blank or is in "host name" format, the channel status value has
the resolved IP address.
- Includes the port number, the current channel status value includes the
port number (except on z/OS), 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.
- MONITOR
- Specify this to return the set of online monitoring parameters. These
are COMPRATE, COMPTIME, EXITTIME, MONCHL, NETTIME, XBATCHSZ, XQMSGSA, and
XQTIME. If you specify this parameter, any of the monitoring parameters that
you request specifically have no effect; all monitoring parameters are still
displayed.
-
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.
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, and for all channel types except server-connection channels)
- The remote partner application name (for server-connection channels)
- The type of status information returned (CURRENT, SAVED, or on z/OS only,
SHORT)
- STATUS (except SAVED on z/OS)
- On z/OS, CHLDISP
- STOPREQ (only for current status)
- SUBSTATE
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.
- CHLTYPE
- The channel type. This is one of the following:
- SDR
- A sender channel
- SVR
- A server channel
- RCVR
- A receiver channel
- RQSTR
- A requester channel
- CLUSSDR
- A cluster-sender channel
- CLUSRCVR
- A cluster-receiver channel
- SVRCONN
- A server-connection channel
-
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. This is valid
only on AIX, HP OpenVMS, HP-UX, Linux, i5/OS, Solaris, Windows,
and z/OS. On z/OS, this is displayed as INITIALIZI.
- 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. This is not valid on z/OS.
- 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.
On z/OS, STATUS is not displayed if saved data is requested.
Note:
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 (valid only on AIX, HP OpenVMS, HP-UX, Linux, i5/OS, Solaris, Windows,
and z/OS).
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).
- COMPHDR
- The technique used to compress the header data sent by the channel.
Two values are displayed:
- The default header data compression value negotiated for this channel.
- The header data compression value used for the last message sent. The
header data compression value can be altered in a sending channels message
exit. If no message has been sent, the second value is blank.
- COMPMSG
- The technique used to compress the message data sent by the channel.
Two values are displayed:
- The default message data compression value negotiated for this channel.
- The message data compression value used for the last message sent. The
message data compression value can be altered in a sending channels message
exit. If no message has been sent, the second value is blank.
- COMPRATE
- The compression rate achieved displayed to the nearest percentage. Two
values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values are reset every time the channel is started and are displayed
only when the STATUS of the channel is RUNNING. If monitoring data is not
being collected, or if no messages have been sent by the channel, the values
are shown as blank.
- COMPTIME
- The amount of time per message, displayed in microseconds, spent during
compression or decompression. Two values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values are reset every time the channel is started and are displayed
only when the STATUS of the channel is RUNNING. If monitoring data is not
being collected, or if no messages have been sent by the channel, the values
are shown as blank.
- EXITTIME
- Amount of time, displayed in microseconds, spent processing user exits
per message. Two values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values depend on the configuration and behavior of your system,
as well as the levels of activity within it, and serve as an indicator that
your system is performing normally. A significant variation in these values
may indicate a problem with your system. They are reset every time the channel
is started and are displayed only when the STATUS of the channel is RUNNING.
This parameter is also displayed when you specify the MONITOR parameter.
-
HBINT
- The heartbeat interval being used for this session.
-
JOBNAME
- Name of job currently serving the channel.
- On HP OpenVMS, this is the process identifier, displayed in hexadecimal.
- On i5/OS, UNIX systems, and Windows, this is the concatenation of the
process identifier and the thread identifier of the MCA program, displayed
in hexadecimal.
- On Compaq NSK, this is the CPU ID and PID, displayed in hexadecimal.
This information is not available on z/OS. The parameter is ignored
if specified.
You cannot use JOBNAME as a filter
keyword on z/OS.
- KAINT
- The keepalive interval being used for this session. This is valid only
on z/OS.
- 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.
-
MAXMSGL
- The maximum message length being used for this session (valid only on z/OS).
-
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.
This information
is not available on z/OS. The parameter is ignored if specified.
You cannot use MCASTAT as a filter keyword on z/OS.
- MCAUSER
- The user ID used by the MCA. This may be the user ID set in the channel
definition, the default user ID for MCA channels, a user ID transferred from
a client if this is a server-connection channel, or a user ID specified by
a security exit.
This parameter applies only to server-connection, receiver,
requester, and cluster-receiver channels.
The maximum length is 12 characters
on z/OS; on other platforms, it is 64 characters.
- MONCHL
- Current level of monitoring data collection for the channel.
This
parameter is also displayed when you specify the MONITOR parameter.
-
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).
- NETTIME
- Amount of time, displayed in microseconds, to send a request to the
remote end of the channel and receive a response. Two values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values depend on the configuration and behavior of your system,
as well as the levels of activity within it, and serve as an indicator that
your system is performing normally. A significant variation in these values
may indicate a problem with your system. They are reset every time the channel
is started and are displayed only when the STATUS of the channel is RUNNING.
This parameter applies only to sender, server, and cluster-sender channels.
This parameter is also displayed when you specify the MONITOR parameter.
-
NPMSPEED
- The nonpersistent message handling technique being used for this session.
- RAPPLTAG
- The remote partner application name. This is the name of the client
application at the remote end of the channel. This parameter applies only
to server-connection channels.
- RQMNAME
- The queue manager name, or queue-sharing group name, of the remote system.
This parameter does not apply to server-connection channels.
-
SHORTRTS
- Number of short retry wait start attempts left. This applies only to
sender or server channels.
- SSLCERTI
- The full Distinguished Name of the issuer of the remote certificate.
The issuer is the Certificate Authority that issued the certificate.
The
maximum length is 256 characters. This limit might mean that exceptionally
long Distinguished Names are truncated.
- SSLCERTU
- The local user ID associated with the remote certificate. This is valid
on z/OS only.
- SSLKEYDA
- Date on which the previous successful SSL secret key reset was issued.
- SSLKEYTI
- Time at which the previous successful SSL secret key reset was issued.
- 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.
- SSLRKEYS
- Number of successful SSL key resets. The count of SSL secret key resets
is reset when the channel instance ends.
-
STOPREQ
- Whether a user stop request is outstanding. This is either YES or NO.
- SUBSTATE
- Action being performed by the channel when this command is issued. The
following substates are listed in precedence order, starting with the substate
of the highest precedence:
- ENDBATCH
- Channel is performing end-of-batch processing.
- SEND
- A request has been made to the underlying communication subsystem to
send some data.
- RECEIVE
- A request has been made to the underlying communication subsystem to
receive some data.
- SERIALIZE
- Channel is serializing its access to the queue manager. This is valid
on z/OS only.
- RESYNCH
- Channel is resynchronizing with the partner.
- HEARTBEAT
- Channel is heartbeating with the partner.
- SCYEXIT
- Channel is running the security exit.
- RCVEXIT
- Channel is running one of the receive exits.
- SENDEXIT
- Channel is running one of the send exits.
- MSGEXIT
- Channel is running one of the message exits.
- MREXIT
- Channel is running the message retry exit.
- CHADEXIT
- Channel is running through the channel auto-definition exit.
- NETCONNECT
- A request has been made to the underlying communication subsystem to
connect a partner machine.
- SSLHANDSHK
- Channel is processing an SSL handshake.
- NAMESERVER
- A request has been made to the name server.
- MQPUT
- A request has been made to the queue manager to put a message on the
destination queue.
- MQGET
- A request has been made to the queue manager to get a message
from the transmission queue (if this is an MCA channel) or from an application
queue (if this is an MQI channel).
- MQICALL
- A MQ API call, other than MQPUT and MQGET, is being executed.
- COMPRESS
- Channel is compressing or decompressing data.
Not all substates are valid for all channel types or channel states.
There are occasions when no substate is valid, at which times a blank value
is returned.
For channels running on multiple threads, this parameter displays
the substate of the highest precedence.
- XBATCHSZ
- Size of the batches transmitted over the channel. Two values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values depend on the configuration and behavior of your system,
as well as the levels of activity within it, and serve as an indicator that
your system is performing normally. A significant variation in these values
may indicate a problem with your system. They are reset every time the channel
is started and are displayed only when the STATUS of the channel is RUNNING.
This parameter does not apply to server-connection channels.
This parameter is also displayed when you specify the MONITOR parameter.
- XQMSGSA
- Number of messages queued on the transmission queue available to the
channel for MQGETs.
This parameter has a maximum displayable value of 999.
If the number of messages available exceeds 999, a value of 999 is displayed.
On z/OS, if the transmission queue is not indexed by CorrelId, this value is shown as blank.
This parameter applies to
cluster-sender channels only.
This parameter is also displayed when
you specify the MONITOR parameter.
- XQTIME
- The time, in microseconds, that messages remained on the transmission
queue before being retrieved. The time is measured from when the message is
put onto the transmission queue until it is retrieved to be sent on the channel
and, therefore, includes any interval caused by a delay in the putting application.
Two values are displayed:
- A value based on recent activity over a short period of time.
- A value based on activity over a longer period of time.
These values depend on the configuration and behavior of your
system, as well as the levels of activity within it, and serve as an indicator
that your system is performing normally. A significant variation in these
values may indicate a problem with your system. They are reset every time
the channel is started and are displayed only when the STATUS of the channel
is RUNNING.
This parameter applies only to sender, server, and cluster-sender
channels.
This parameter is also displayed when you specify the MONITOR
parameter.
Short status
The following information applies only to current channel instances.
- QMNAME
- The name of the queue manager that owns the channel instance.