Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

imqcmd


NAME
     imqcmd - manage Message Queue brokers

SYNOPSIS
     /usr/bin/imqcmd subcommand argument [option...]


     /usr/bin/imqcmd [-h | -H]


     /usr/bin/imqcmd -v


DESCRIPTION
     imqcmd manages the Message Queue broker, including resources
     such  as connection services, physical destinations, durable
     subscriptions, and  transactions.  The  utility  provides  a
     number of subcommands for managing these resources.


     imqcmd  supports  many  subcommands.  Basic  connection  and
     authentication is required for the execution of every imqcmd
     subcommand. Use the -secure option to specify secure connec-
     tions.  Subcommands  and  their  corresponding arguments and
     options follow the imqcmd command on the command  line.  See
     USAGE and OPTIONS.

OPTIONS
     The following options are supported:

     -b hostName:port      Specify the name of the host on  which
                           the broker instance is running and the
                           port number it is using.

                           The default value  is  localhost:7676.
                           If  you  do not specify the -b option,
                           imqcmd uses the default.

                           To specify port only, use:  -b  :7878.
                           This     is     equivalent    to    -b
                           localhost:7878

                           To  specify   name   only,   use:   -b
                           somehost.  This  is  equivalent  to -b
                           somehost:7676.


     -c clientID           Specify the ID  of  the  durable  sub-
                           scriber to a topic.



     -d topicName          Specify the name of the topic.

                           Use this option with the list dur  and
                           destroy dur subcommands.


     -f                    Perform action without user  confirma-
                           tion.

                           Use this option with any subcommand.


     -h                    Display usage  help.  Execute  nothing
                           else on the command line.


     -H                    Display usage  help,  attribute  list,
                           and  examples. Execute nothing else on
                           the command line.


     -int interval         Specify the interval, in  seconds,  at
                           which  the  metrics  bkr, metrics dst,
                           and metrics  svc  subcommands  display
                           metrics output.

                           Use this option with the metrics  sub-
                           command.


     -javahome             Specify an alternate Java 2 compatible
                           runtime to use.


     -m metricType         Specify the type of metric information
                           to diplay.

                           Use this option with the metrics  bkr,
                           metrics  dst,  and metrics svc subcom-
                           mands. The value of metricType depends
                           on  whether  the metrics are generated
                           for a destination,  a  service,  or  a
                           broker.

                           Use one of  the  following  values  to
                           specify metricType:

                           ttl    Total of messages in and out of
                                  the broker (default)



                           rts    Provides the  same  information
                                  as   ttl,   but  specifies  the
                                  number of messages per second


                           cxn    Connections,   virtual   memory
                                  heap, threads

                           The following command displays connec-
                           tion,  VM  heap,  and  threads  metric
                           information  for  the  default  broker
                           instance  (localhost:7676)  every five
                           seconds:

                             imqcmd metrics bkr -m cxn -int 5




     -msp numSamples       Specify  the  number  of  samples  the
                           metrics  bkr, metrics dst, and metrics
                           svc subcommands display in the metrics
                           output.


     -n argumentName       Specify the  name  of  the  subcommand
                           argument. Depending on the subcommand,
                           this might be the name of a service, a
                           physical  destination,  a durable sub-
                           scription, or a transaction ID.


     -o attribute=value    Specify the  value  of  an  attribute.
                           Depending  on the subcommand argument,
                           this  might  be  the  attribute  of  a
                           broker, service, or destination.


     -p password           Specify the administrator password.

                           This option  is  deprecated.  Use  the
                           -passfile option instead.


     -passfile             Specify the administrator password.


     -pst pauseType        Specify whether producers,  consumers,
                           or both are paused when pausing a des-
                           tination.

                           Use this option  with  the  pause  dst
                           subcommand.  Use  one of the following
                           values:

                           CONSUMERS    Pause  delivery  of  mes-
                                        sages to consumers.


                           PRODUCERS    Pause  delivery  of  mes-
                                        sages from producers.


                           ALL          Pause  delivery  of  mes-
                                        sages  to  consumers  and
                                        from producers.

                           If the -pst option is  not  specified,
                           pauses  both  consumers  and producers
                           (the equivalent of -pst ALL).


     -rtm timeout          Specify the timeout period in  seconds
                           of  an  imqcmd subcommand. The default
                           value is 10.


     -rtr numRetries       Specify   the   number   of    retries
                           attempted  after  an imqcmd subcommand
                           times out.

                           The default value is 5.


     -s                    Silent mode. No output is displayed.

                           Use this option with any subcommand.


     -secure               Specify a secure  administration  con-
                           nection  to  the  broker instance. You
                           must first  configure  the  broker  to
                           enable a secure connection service.

                           Use this option whenever  you  want  a
                           secure communication with the broker.


     -svn serviceName      Specify the service for which the con-
                           nections are listed.

                           Use this option with the list cxn sub-
                           command.

     -t destinationType    Specify the type of a  destination:  t
                           (topic) or q (queue).


     -tmp                  Include  temporary  destinations  when
                           listing  destinations  using  the list
                           dst subcommand.


     -u name               Specify the administrator user name.

                           If  you  omit  this  value,  you   are
                           prompted for it.


     -v                    Display version  information.  Execute
                           nothing else on the command line.


USAGE
  Subcommands and Options
     The  following  subcommands  and  associated  arguments  and
     options are supported:

     compact dst [-t type -n destName]

         Compact the flat-file data store for the destination  of
         the  specified  type  and  name. If no type and name are
         specified, all destinations are compacted.  Destinations
         must be paused before they can be compacted.


     commit txn -n transaction_id

         Commit the specified transaction


     create dst -t destinationType -n destName [-o
     attribute=value] [-o attribute=value1]...

         Create a destination of the  specified  type,  with  the
         specified  name,  and the specified attributes. Destina-
         tion names must contain only alphanumeric characters (no
         spaces)  and  can  begin with an alphabetic character or
         the underscore character (_).


     destroy dst -t destinationType -n destName

         Destroy the destination of the specified type and name.


     destroy dur -n subscrName -c client_id

         Destroy  the  specified  durable  subscription  for  the
         specified Client Identifier.


     list cxn [-svn serviceName] [-b hostName:port]

         List all connections of the specified  service  name  on
         the  default broker or on a broker at the specified host
         and port. If the service name is not specified, all con-
         nections are listed.


     list dst [-tmp]

         List all destinations, with option of listing  temporary
         destinations as well .


     list dur -d destination

         List all durable subscriptions for the specified  desti-
         nation.


     list svc

         List all connection services on the broker instance.


     list txn

         List all transactions, being tracked by the broker.


     metrics bkr [-m metricType] [-int interval] [-msp numSam-
     ples]

         Display broker metrics for the broker instance.

         Use the -m option to  specify  the  type  of  metric  to
         display.  Use  one  of  the  following values to specify
         metricType:

         ttl    Specifies the total of messages in and out of the
                broker (default) .


         rts    Provides the same information as ttl, but  speci-
                fies the number of messages per second.

         cxn    Connections, virtual memory heap, threads.

         Use the -int option to specify the interval (in seconds)
         at  which  to  display  the  metrics.  The  default is 5
         seconds.

         Use the -msp option to specify  the  number  of  samples
         displayed  in  the output. A value of -1 means an unlim-
         ited number. The default value is -1.


     metrics dst -t type -n destName [-m metricType] [-int inter-
     val] [-msp numSamples]

         Displays metrics information for the destination of  the
         specified type and name.

         Use the -m option to specify  the  type  of  metrics  to
         display.  Use  one  of  the  following values to specify
         metricType:

         ttl    Specifies the number of messages flowing  in  and
                out of the broker and residing in memory.


         rts    Provides the same information as ttl, but  speci-
                fies the number of messages per second.


         con    Displays consumer related metrics.


         dsk    Displays disk usage metrics.

         Use the -int option to specify the interval (in seconds)
         at  which  to  display  the  metrics.  The  default is 5
         seconds.

         Use the -msp option to specify  the  number  of  samples
         displayed  in  the output. A value of -1 means an unlim-
         ited number. The default value is 5.


     metrics svc -n serviceName [-m metricType] [-int interval]
     [-msp numSamples]

         List metrics for the specified  service  on  the  broker
         instance.  Use  the  -m  option  to  specify the type of
         metric to display. Use one of the  following  values  to
         specify metricType:


         ttl    Total of  messages  in  and  out  of  the  broker
                (default)


         rts    Provides the same information as ttl, but  speci-
                fies the number of messages per second


         cxn    Connections, virtual memory heap, threads

         Use the -int option to specify the interval (in seconds)
         at  which  to  display  the  metrics.  The  default is 5
         seconds.

         Use the -msp option to specify  the  number  of  samples
         displayed  in  the output. A value of -1 means an unlim-
         ited number. The default value is -1.


     pause bkr

         Pause the broker instance.


     pause dst [-t type -n destName] [-pst pauseType]

         Pause the delivery of messages to consumers (-pst CONSU-
         MERS), or from producers (-pst PRODUCERS), or both (-pst
         ALL), for the destination  of  the  specified  type  and
         name.  If no destination type or name are specified, all
         destinations are paused.


     pause svc -n serviceName

         Pause  the  specified  service  running  on  the  broker
         instance. You cannot pause the administative service.


     purge dst -t destinationType -n destName

         Purge messages at the  destination  with  the  specified
         type and name.


     purge dur -n subscrName -c client_id

         Purge all messages for the specified client identifier.


     query bkr

         List the current settings of properties  of  the  broker
         instance.  Show the list of running brokers (in a multi-
         broker cluster) that  are  connected  to  the  specified
         broker.


     query dst -t destinationType -n destName

         List information about the destination of the  specified
         type and name.


     query svc -n serviceName

         Display information about the specified service  running
         on the broker instance.


     query txn -n transaction_id

         List information about the specified transaction.


     reload cls

         Forces all the  brokers  in  a  cluster  to  reload  the
         imq.cluster.brokerlist   property   and  update  cluster
         information. This  subcommand  only  applies  to  broker
         clusters.


     restart bkr

         Shut down and restart the broker instance. This  command
         restarts the broker using the options specified when the
         broker was first started. If you want different  options
         to  be in effect, you must shut down the broker and then
         start it again, specifying the options you want.


     resume bkr

         Resume the broker instance.


     resume dst [-t type] [-n -destName]

         Resumes the delivery of messages for the paused destina-
         tion  of  the specified type and name. If no destination
         type  and  name  are  specified,  all  destinations  are
         resumed.

     resume svc -n serviceName

         Resume the  specified  service  running  on  the  broker
         instance.


     rollback txn -n transaction_id

         Roll back the specified transaction.


     shutdown bkr

         Shut down the broker instance


     update bkr -o attribute=value [-o attribute=value]...

         Change the specified attributes for the broker instance.


     update dst -t destinationType -n destName -o attribute=value
     [-o attribute=value1]...

         Update the value of  the  specified  attributes  at  the
         specified destination..


     update svc -n serviceName -o attribute=value [-o
     attribute=value1]...

         Update the specified attribute of the specified  service
         running on the broker instance.


  Attribute Value Pairs
     You can specify attributes with the create and  update  sub-
     commands.  Applicable  attributes  depend  on the subcommand
     arguments.


     The following attributes are supported:


     Queue (dst):

     maxTotalMsgBytes          Value: Integer (maximum total size
                               of messages, in bytes)

                               Default: 0 (unlimited)


     maxBytesPerMsg            Value: Integer (maximum size of  a
                               single message, in bytes)

                               Default: 0 (unlimited)


     maxNumMsgs                Value:  Integer   (maximum   total
                               number of messages)

                               Default: 0 (unlimited)


     consumerFlowLimit         Value: Integer Initial  number  of
                               queued  messages  sent  to  active
                               consumers  before   load-balancing
                               starts  A  value  of  -1  means an
                               unlimited number.

                               Default: 1000


     isLocalOnly               Value: Boolean  (destination  lim-
                               ited  to  delivering  messages  to
                               local  consumers  only)   Default:
                               false


     limitBehavior             Value: Specify how broker responds
                               when  memory-limit is reached. Use
                               one of the following values:

                               FLOW_CONTROL     Slows  down  pro-
                                                ducers


                               REMOVE_OLDEST    Purges     oldest
                                                messages


                               REJECT_NEWEST    Rejects       the
                                                newest messages

                               Default: REJECT_NEWEST


     localDeliveryPreferred    Value: Boolean Specify messages be
                               delivered to remote consumers only
                               if there are no consumers  on  the
                               local  broker.  Requires  that the
                               destination not be  restricted  to
                               local-only delivery (isLocalOnly =
                               false)
                               Default: false


     maxNumActiveConsumers     Value: Integer (maximum number  of
                               active  consumers in load-balanced
                               delivery) A value of -1  means  an
                               unlimited number.

                               Default: 1


     maxNumBackupConsumers     Value: Integer (maximum number  of
                               backup  consumers in load-balanced
                               delivery) A value of -1  means  an
                               unlimited number.

                               Default: 0


     maxNumProducers           Value: (maximum  total  number  of
                               producers)  A value of -1 means an
                               unlimited number.

                               Default: -1


     useDMQ                    Specify  whether  a  destination's
                               dead messages are discarded or put
                               on the dead message queue.

                               Default: true



     Topic (dst):

     consumerFlowLimit    Value: Integer Maximum number  of  mes-
                          sages delivered to a consumer in a sin-
                          gle batch.  A  value  of  -1  means  an
                          unlimited number.

                          Default: 1000


     isLocalOnly          Value: Boolean (destination limited  to
                          delivering  messages to local consumers
                          only)

                          Default: false



     limitBehavior        Value: Specify how broker responds when
                          memory-limit is reached. Use one of the
                          following values:

                          FLOW_CONTROL     Slows down producers


                          REMOVE_OLDEST    Purges the oldest mes-
                                           sages


                          REJECT_NEWEST    Rejects   the   newest
                                           messages

                          Default: REJECT_NEWEST


     maxBytesPerMsg       Value: Integer (maximum size of a  sin-
                          gle message, in bytes)

                          Default: 0 (unlimited)


     maxNumMsgs           Value: Integer (maximum total number of
                          messages) A value of -1 means an unlim-
                          ited number.

                          Default: -1


     maxNumProducers      Value: (maximum total number of produc-
                          ers)

                          Default: 0 (unlimited)


     maxTotalMsgBytes     Value: Integer (maximum total  size  of
                          messages, in bytes) A value of -1 means
                          an unlimited number.

                          Default: -1


     useDMQ               Specify whether  a  destination's  dead
                          messages  are  discarded  or put on the
                          dead message queue.

                          Default: true




     Broker (bkr):

     imq.autocreate.destination.useDMQ

         Value: Boolean. Set the  useDMQ  attribute  to  true  to
         enable all autocreated physical destinations on a broker
         to use the dead message queue. Set the useDMQ  attribute
         to  false  to  disable all autocreated physical destina-
         tions on a broker from using the dead message queue.

         Default: true


     imq.autocreate.queue

         Value: Boolean

         Default: true


     imq.autocreate.queue.maxNumActiveConsumers

         Value: Integer (maximum number of consumers that can  be
         active  in  load-balanced  delivery  from an autocreated
         queue destination) A value  of  -1  means  an  unlimited
         number.

         Default: 1


     imq.autocreate.queue.maxNumBackupConsumers

         Value: Integer (maximum number of backup consumers  that
         can  take  the  place of active consumers) A value of -1
         means an unlimited number.

         Default: 0


     imq.autocreate.topic

         Value: Boolean

         Default: true


     imq.cluster.url

         Value: String (location of cluster configuration file)

         Default: none

     imq.log.file.rolloverbytes

         Value: Integer (maximum size of a log file, in bytes)

         Default: 0 (no rollover based on size)


     imq.log.file.rolloversecs

         Value: Integer (maximum age of a log file, in seconds)

         Default: 0 (no rollover based on age)


     imq.log.level

         Value: String (NONE, ERROR, WARNING, INFO)

         Default: INFO


     imq.message.max_size

         Value: Integer (maximum size of  a  single  message,  in
         bytes)

         Default: 70m


     imq.portmapper.port

         Value: Integer

         Default: 7676


     imq.system.max_count

         Value: Integer (maximum total number of messages)

         Default: 0 (no limit)


     imq.system.max_size

         Value: Integer  (maximum  total  size  of  messages,  in
         bytes)

         Default: 0 (no limit)



     Service (svc):

     maxThreads    Value: Integer (maximum threads assigned)

                   Default: Depends on service


     minThreads    Value: Integer (minimum threads assigned)

                   Default: Depends on service


     port          Value: Integer

                   Default: 0 (dynamically allocated)


EXAMPLES
     Example 1 Shutting Down a Broker


     The following command  shuts  down  a  broker  for  hostname
     myserver on port 7676:


       mqcmd shutdown bkr -b myserver:7676



     Example 2 Restarting a Broker


     The  following  command  restarts  a  broker  for   hostname
     myserver:


       imqcmd restart bkr -b myserver



     Example 3 Pausing a Service


     The following command pauses a broker for hostname localhost
     on port 7676, with a serviceName of jms:


       imqcmd pause svc -n jms -b :7676




     Example 4 Resuming a Service


     The  following  command  resumes  a  service  for   hostname
     localhost on port 7676, with a serviceName of jms:


       imqcmd resume svc -n jms -b myserver:7676



     Example 5 Creating a Queue Destination


     The following command creates a queue destination for  host-
     name  myserver  on  port  7676,  with  a destName of myFQ, a
     queueDeliveryPolicy of Failover,  and  a  maxBytesPerMsg  of
     10000:


       imqcmd create dst -n myFQ -t q -o "queueDeliveryPolicy=f" \
           -o "maxBytesPerMsg=10000" -b myserver:7676



     Example 6 Purging a Queue Destination


     The following command purges a queue destination  for  host-
     name myserver on port 7676, with a destName of myFQ:


       imqcmd purge dst -n myFQ -t q -b myserver:7676



     Example 7 Listing Destinations on a Broker


     The  following  command  lists  destinations  for   hostname
     myserver on port 7676:


       imqcmd list dst -b myserver:7676



     Example 8 Updating a Portmapper Port


     The following command updates a portmapper port on  hostname
     myserver from port 7676 to 7878:
       imqcmd update bkr -o "imq.portmapper.port=7878"



     Example 9 Updating the Maximum Number  of  Messages  in  the
     Queue


     The following command updates the maximum number of messages
     in  the queue to 2000 for myserver on port 8080 with a dest-
     Name of TestQueue:


       imqcmd update dst -b myserver:8080 -n TestQueue -t q -o "maxNumMsgs=2000"



     Example 10 Updating the Maximum Threads


     The following command updates the maximum threads  jms  con-
     nection service to 200 for hostname localhost on port 7676:


       imqcmd update svc -n jms -o "minThreads=200"



     Example 11 Listing Durable Subscriptions


     The following command  lists  durable  subscriptions  for  a
     topic  with  hostname localhost on port 7676 with a destName
     of myTopic:


       imqcmd list dur -d myTopic



     Example 12 Destroying Durable Subscriptions


     The following command destroys  subscriptions  for  hostname
     localhost  on  port 7676 with a dursubName of myDurSub and a
     client_ID of 111.222.333.444:


       imqcmd destroy dur -n myDurSub -c "111.222.333.444"



     Example 13 Listing All Transactions


     The following command lists all  transactions  on  a  broker
     with hostname localhost on port 7676:


       imqcmd list txn



     Example 14 Displaying Information About a Transaction


     The following command displays information about a  transac-
     tion  with  hostname  localhost on port 7676, and a transac-
     tionID of 1234567890


       imqcmd query txn -n 1234567890



     Example 15 Committing a Transaction


     The following command commits a  transaction  with  hostname
     localhost on port 7676, and a transactionID of 1234567890:


       imqcmd commit txn -n 1234567890



ENVIRONMENT VARIABLES
     The following environment variables affect the execution  of
     this command:

     IMQ_JAVAHOME    Specify the Java 2 compatible runtime.  When
                     this  environment  variable  is  not  set it
                     defaults to /usr/j2se.


EXIT STATUS
     The following exit values are returned:

     0     Successful completion.


     >0    An error occurred.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWiqu                     |
    |_____________________________|_____________________________|


SEE ALSO
     imqadmin(1M), imqbrokerd(1M), imqdbmgr(1M),  imqkeytool(1M),
     imqobjmgr(1M), imqusermgr(1M), attributes(5)


     Sun Java System Message Queue Administrator's Guide










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments