Class: WMQ::Queue

Public Class methods

new(...)

Note:

It is not recommended to create instances of Queue directly, rather user Queue.open. Which creates the queue, opens the queue, executes a supplied code block and then ensures the queue is closed.

Parameters:

Since the number of parameters can vary dramatically, all parameters are passed by name in a hash
See Queue.open for details on all parameters

open(...)

Open a queue, then close the queue once the supplied code block completes

Parameters:

Since the number of parameters can vary dramatically, all parameters are passed by name in a hash
Summary of parameters and their WebSphere MQ equivalents:

 queue = Queue.new(                                     # WebSphere MQ Equivalents:
  :queue_manager      => queue_manager,                 # n/a : Instance of QueueManager
  :q_name             => 'Queue Name',                  # MQOD.ObjectName
  :q_name             => { queue_manager=>'QMGR_name',  # MQOD.ObjectQMgrName
                           q_name       =>'q_name'}
  :mode               => :input or :input_shared or :input_exclusive or :output,
  :fail_if_quiescing  => true                           # MQOO_FAIL_IF_QUIESCING
  :fail_if_exists     => true, # For dynamic queues, fail if it already exists
  :open_options       => WMQ::MQOO_BIND_ON_OPEN | ...   # MQOO_*
  :close_options      => WMQ::MQCO_DELETE_PURGE         # MQCO_*
  :dynamic_q_name     => 'Name of Dynamic Queue'        # MQOD.DynamicQName
  :alternate_user_id  => 'userid',                      # MQOD.AlternateUserId
  :alternate_security_id => ''                          # MQOD.AlternateSecurityId
  )

Mandatory Parameters

:queue_manager
- An instance of the WMQ::QueueManager class. E.g. QueueManager.new
- Note: This is not the queue manager name!
:q_name => String
- Name of the existing WebSphere MQ local queue, model queue or remote queue to open
- To open remote queues for which a local remote queue definition is not available pass a Hash as q_name (see q_name => Hash)
```
  OR
```
:q_name => Hash
- q_name => String
  - Name of the existing WebSphere MQ local queue, model queue or remote queue to open
- :q_mgr_name => String
  - Name of the remote WebSphere MQ queue manager to send the message to.
  - This allows a message to be written to a queue on a remote queue manager where a remote queue definition is not defined locally
  - Commonly used to reply to messages from remote systems
  - If q_mgr_name is the same as the local queue manager name then the message is merely written to the local queue.
  - Note: q_mgr_name should only be supplied when putting messages to the queue.
```
  It is not possible to get messages from a queue on a queue manager other
  than the currently connected queue manager
```
:mode => Symbol
- Specify how the queue is to be opened
  - :output
    - Open the queue for output. I.e. WMQ::Queue#put will be called
```
 Equivalent to: MQOO_OUTPUT
```
  - :input
    - Open the queue for input. I.e. WMQ::Queue#get will be called.
    - Queue sharing for reading from the queue is defined by the queue itself. By default most queues are set to shared. I.e. Multiple applications can read and/or write from the queue at the same time
```
 Equivalent to: MQOO_INPUT_AS_Q_DEF
```
  - :input_shared
    - Open the queue for input. I.e. WMQ::Queue#get will be called.
    - Explicitly open the queue so that other applications can read or write from the same queue
```
 Equivalent to: MQOO_INPUT_SHARED
```
  - :input_exclusive
    - Open the queue for input. I.e. WMQ::Queue#get will be called.
    - Explicitly open the queue so that other applications cannot read from the same queue. Does not affect applications writing to the queue.
    - Note: If :input_exclusive is used and connectivity the queue manager is lost. Upon restart the queue can still be "locked". The application should retry every minute or so until the queue becomes available. Otherwise, of course, another application has the queue open exclusively.
```
 Equivalent to: MQOO_INPUT_EXCLUSIVE
```
  - :browse
    - Browse the messages on the queue without removing them from the queue
    - Open the queue for input. I.e. WMQ::Queue#get will be called.
    - Note: It is necessary to specify WMQ::MQGMO_BROWSE_FIRST before the first get, then set WMQ::MQGMO_BROWSE_NEXT for subsequent calls.
    - Note: For now it is also necessary to specify these options when calling WMQ::Queue#each. A change will be made to each to address this.
```
 Equivalent to: MQOO_BROWSE
```

Optional Parameters

:fail_if_quiescing => true or false
- Determines whether the WMQ::Queue#open call will fail if the queue manager is in the process of being quiesced.
- Note: If set to false, the MQOO_FAIL_IF_QUIESCING flag will not be removed if it was also supplied in :open_options. However, if set to true it will override this value in :open_options
- Note: This interface differs from other WebSphere MQ interfaces, they do not default to true.
```
 Default: true
 Equivalent to: MQOO_FAIL_IF_QUIESCING
```

:open_options => FixNum

One or more of the following values:

  WMQ::MQOO_INQUIRE
  WMQ::MQOO_SET
  WMQ::MQOO_BIND_ON_OPEN
  WMQ::MQOO_BIND_NOT_FIXED
  WMQ::MQOO_BIND_AS_Q_DEF
  WMQ::MQOO_SAVE_ALL_CONTEXT
  WMQ::MQOO_PASS_IDENTITY_CONTEXT
  WMQ::MQOO_PASS_ALL_CONTEXT
  WMQ::MQOO_SET_IDENTITY_CONTEXT
  WMQ::MQOO_SET_ALL_CONTEXT

Multiple values can be or’d together. E.g.

  :open_options=>WMQ::MQOO_BIND_ON_OPEN | WMQ::MQOO_SAVE_ALL_CONTEXT

Please see the WebSphere MQ documentation for more details on the above options

:close_options => FixNum
- One of the following values:
```
  WMQ::MQCO_DELETE
  WMQ::MQCO_DELETE_PURGE
```
- Please see the WebSphere MQ documentation for more details on the above options
:dynamic_q_name => String
- If a model queue name is supplied to :q_name then the final queue name that is created is specified using :dynamic_q_name
- A complete queue name can be specified. E.g. ‘MY.LOCAL.QUEUE‘
- Or, a partial queue name can be supplied. E.g. ‘MY.REPLY.QUEUE.*’ In this case WebSphere MQ will automatically add numbers to the end of ‘MY.REPLY.QUEUE.’ to ensure this queue name is unique.
- The most common use of :dynamic_q_name is to create a temporary dynamic queue to which replies can be posted for this instance of the program
- When opening a model queue, :dynamic_q_name is optional. However it’s use is recommended in order to make it easier to identify which application a dynamic queue belongs to.
:fail_if_exists => true or false
- Only applicable when opening a model queue
- When opening a queue dynamically, sometimes the :dynamic_q_name already exists. Under this condition, if :fail_if_exists is false, the queue is automatically re-opened using the :dynamic_q_name. The :q_name field is ignored.
- This feature is usefull when creating permanent dynamic queues. (The model queue has the definition type set to Permanent: DEFTYPE(PERMDYN) ).
  - In this way it is not necessary to create the queues before running the program.
```
 Default: true
```
:alternate_user_id [String]
- Sets the alternate userid to use when messages are put to the queue
- Note: It is not necessary to supply WMQ::MQOO_ALTERNATE_USER_AUTHORITY since it is automatically added to the :open_options when :alternate_user_id is supplied
- See WebSphere MQ Application Programming Reference: MQOD.AlternateUserId
:alternate_security_id [String]
- Sets the alternate security id to use when messages are put to the queue
- See WebSphere MQ Application Programming Reference: MQOD.AlternateSecurityId

Note:

It is more convenient to use WMQ::QueueManager#open_queue, since it automatically supplies the parameter :queue_manager
That way :queue_manager parameter is not required

Example:

  # Put 10 Hello World messages onto a queue
  require 'wmq/wmq_client'

  WMQ::QueueManager.connect(:q_mgr_name=>'REID', :connection_name=>'localhost(1414)') do |qmgr|
    WMQ::Queue.open(:queue_manager=>qmgr,
                    :q_name       =>'TEST.QUEUE',
                    :mode         =>:output) do |queue|
      10.times { |counter| queue.put(:data => "Hello World #{counter}") }
    end
  end

Public Instance methods

close()

Close the queue

Returns:

true : On Success
false: On Failure
comp_code and reason_code are also updated. reason will return a text description of the reason_code

Throws:

WMQ::WMQException if comp_code == MQCC_FAILED
Except if :exception_on_error => false was supplied as a parameter to QueueManager.new

comp_code()

Return the completion code for the last MQ operation on this queue instance

Returns => FixNum

WMQ::MQCC_OK 0
WMQ::MQCC_WARNING 1
WMQ::MQCC_FAILED 2
WMQ::MQCC_UNKNOWN -1

each(...)

For each message found on the queue, the supplied block is executed

Note:

If no messages are found on the queue during the supplied wait interval, then the supplied block will not be called at all
If :mode=>:browse is supplied when opening the queue then Queue#each will automatically set MQGMO_BROWSE_FIRST and MQGMO_BROWSE_NEXT as required

Returns:

true: If at least one message was succesfully processed
false: If no messages were retrieved from the queue

Example:

  require 'wmq/wmq'

  WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
    qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:input) do |queue|
      queue.each do |message|
        puts "Data Received: #{message.data}"
      end
    end
    puts 'Completed.'
  end

get(...)

Get a message from the opened queue

Parameters:

a Hash consisting of one or more of the named parameters
Summary of parameters and their WebSphere MQ equivalents:

 queue.get(                                             # WebSphere MQ Equivalents:
  :message            => my_message,                    # n/a : Instance of Message
  :sync               => false,                         # MQGMO_SYNCPOINT
  :wait               => 0,                             # MQGMO_WAIT, duration in ms
  :match              => WMQ::MQMO_NONE,                # MQMO_*
  :convert            => false,                         # MQGMO_CONVERT
  :fail_if_quiescing  => true                           # MQOO_FAIL_IF_QUIESCING
  :options            => WMQ::MQGMO_FAIL_IF_QUIESCING   # MQGMO_*
  )

Mandatory Parameters

:message => Message
- An instance of the WMQ::Message

Optional Parameters

:sync => true or false
- Determines whether the get is performed under synchpoint. I.e. Under the current unit of work
```
 Default: false
```
:wait => FixNum
- The time in milli-seconds to wait for a message if one is not immediately available on the queue
- Note: Under the covers the put option MQGMO_WAIT is automatically set when :wait is supplied
```
 Default: Wait forever
```

:match => FixNum

One or more of the following values:

  WMQ::MQMO_MATCH_MSG_ID
  WMQ::MQMO_MATCH_CORREL_ID
  WMQ::MQMO_MATCH_GROUP_ID
  WMQ::MQMO_MATCH_MSG_SEQ_NUMBER
  WMQ::MQMO_MATCH_OFFSET
  WMQ::MQMO_MATCH_MSG_TOKEN
  WMQ::MQMO_NONE

Multiple values can be or’d together. E.g.

  :match=>WMQ::MQMO_MATCH_MSG_ID | WMQ::MQMO_MATCH_CORREL_ID

Please see the WebSphere MQ documentation for more details on the above options
```
 Default: WMQ::MQMO_MATCH_MSG_ID | WMQ::MQMO_MATCH_CORREL_ID
```

:convert => true or false
- When true, convert results in messages being converted to the local code page. E.g. When an EBCDIC text message from a mainframe is received, it will be converted to ASCII before passing the message data to the application.
```
 Default: false
```
:fail_if_quiescing => true or false
- Determines whether the WMQ::Queue#get call will fail if the queue manager is in the process of being quiesced.
- Note: This interface differs from other WebSphere MQ interfaces, they do not default to true.
```
 Default: true
```

:options => Fixnum (Advanced MQ Use only)

Numeric field containing any of the MQ Get message options or’d together
- E.g. :options => WMQ::MQGMO_SYNCPOINT_IF_PERSISTENT | WMQ::MQGMO_MARK_SKIP_BACKOUT
Note: If :options is supplied, it is applied first, then the above parameters are applied afterwards.

One or more of the following values:

  WMQ::MQGMO_SYNCPOINT_IF_PERSISTENT
  WMQ::MQGMO_NO_SYNCPOINT
  WMQ::MQGMO_MARK_SKIP_BACKOUT
  WMQ::MQGMO_BROWSE_FIRST
  WMQ::MQGMO_BROWSE_NEXT
  WMQ::MQGMO_BROWSE_MSG_UNDER_CURSOR
  WMQ::MQGMO_MSG_UNDER_CURSOR
  WMQ::MQGMO_LOCK
  WMQ::MQGMO_UNLOCK
  WMQ::MQGMO_LOGICAL_ORDER
  WMQ::MQGMO_COMPLETE_MSG
  WMQ::MQGMO_ALL_MSGS_AVAILABLE
  WMQ::MQGMO_ALL_SEGMENTS_AVAILABLE
  WMQ::MQGMO_DELETE_MSG
  WMQ::MQGMO_NONE

Please see the WebSphere MQ documentation for more details on the above options
```
 Default: WMQ::MQGMO_NONE
```

Returns:

true : On Success
false: On Failure, or if no message was found on the queue during the wait interval
comp_code and reason_code are also updated. reason will return a text description of the reason_code

Throws:

WMQ::WMQException if comp_code == MQCC_FAILED
Except if :exception_on_error => false was supplied as a parameter to QueueManager.new

Example:

  require 'wmq/wmq'

  WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
    qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:input) do |queue|
      message = WMQ::Message.new
      if queue.get(:message => message)
        puts "Data Received: #{message.data}"
      else
        puts 'No message available'
      end
    end
  end

name()

Returns the queue name => String

open()

Open the queue

Note:

It is not recommended to use this method to open a queue, since the queue will have to be closed explicitly.
Rather use WMQ::QueueManager#open_queue
If the queue is already open, it will be closed and re-opened. Any errors that occur while closing the queue are ignored.

Custom behavior for Dynamic Queues:

  When :dynamic_q_name is supplied and MQ fails to
  open the queue with MQRC_OBJECT_ALREADY_EXISTS,
  this method will automatically open the existing
  queue by replacing the queue name with :dynamic_q_name

  This technique allows programs to dynamically create
  queues, without being concerned with first checking if
  the queue is already defined.
    I.e. Removes the need to have to explicitly create
         required queues in advance
  However, in order for this approach to work a
  Permanent model queue must be used. A Temporary
  model queue is automatically erased by WMQ when the
  queue is closed.

  Persistent messages cannot be put to a
  temporary dynamic queue!

Returns:

true : On Success
false: On Failure
comp_code and reason_code are also updated. reason will return a text description of the reason_code

Throws:

WMQ::WMQException if comp_code == MQCC_FAILED
Except if :exception_on_error => false was supplied as a parameter to QueueManager.new

Example:

  require 'wmq/wmq_client'
  queue_manager = WMQ::QueueManager.new(:q_mgr_name     =>'REID',
                                        :connection_name=>'localhost(1414)')
  begin
    queue_manager.connect

    # Create Queue and clear any messages from the queue
    in_queue = WMQ::Queue.new(:queue_manager =>queue_manager,
                              :mode          =>:input,
                              :dynamic_q_name=>'UNIT.TEST',
                              :q_name        =>'SYSTEM.DEFAULT.MODEL.QUEUE',
                              :fail_if_exists=>false)
    begin
      in_queue.open
      in_queue.each { |message| p message.data }
    ensure
      # Note: Very important: Must close the queue explicitly
      in_queue.close
    end
  rescue => exc
    queue_manager.backout
    raise exc
  ensure
    # Note: Very important: Must disconnect from the queue manager explicitly
    queue_manager.disconnect
  end

open?()

Returns whether this queue is currently open

Returns:

true : The queue is open
false: The queue is not open

put(...)

Put a message to the WebSphere MQ queue

Parameters:

A Hash consisting of one or more of the named parameters
Summary of parameters and their WebSphere MQ equivalents

 queue.put(                                             # WebSphere MQ Equivalents:
  :message            => my_message,                    # n/a : Instance of Message
  :data               => "Hello World",                 # n/a : Data to send
  :sync               => false,                         # MQGMO_SYNCPOINT
  :new_id             => true,                          # MQPMO_NEW_MSG_ID & MQPMO_NEW_CORREL_ID
  :new_msg_id         => true,                          # MQPMO_NEW_MSG_ID
  :new_correl_id      => true,                          # MQPMO_NEW_CORREL_ID
  :fail_if_quiescing  => true,                          # MQOO_FAIL_IF_QUIESCING
  :options            => WMQ::MQPMO_FAIL_IF_QUIESCING   # MQPMO_*
  )

Mandatory Parameters:

Either :message or :data must be supplied
- If both are supplied, then :data will be written to the queue. The data in :message will be ignored

Optional Parameters:

:data => String
- Data to be written to the queue. Can be binary or text data
- Takes precendence over the data in :message
:message => Message
- An instance of the WMQ::Message
- The Message descriptor, headers and data is retrieved from :message
  - message.data is ignored if :data is supplied
:sync => true or false
- Determines whether the get is performed under synchpoint. I.e. Under the current unit of work
```
 Default: false
```
:new_id => true or false
- Generate a new message id and correlation id for this message. :new_msg_id and :new_correl_id will be ignored if this parameter is true
```
 Default: false
```
:new_msg_id => true or false
- Generate a new message id for this message
- Note: A blank message id will result in a new message id anyway. However, for subsequent puts using the same message descriptor, the same message id will be used.
```
 Default: false
```
:new_correl_id => true or false
- Generate a new correlation id for this message
```
 Default: false
```
:fail_if_quiescing => true or false
- Determines whether the WMQ::Queue#put call will fail if the queue manager is in the process of being quiesced.
- Note: This interface differs from other WebSphere MQ interfaces, they do not default to true.
```
 Default: true
 Equivalent to: MQGMO_FAIL_IF_QUIESCING
```
- Note: As part of the application design, carefull consideration should be given as to when to allow a transaction or unit of work to complete or fail under this condition. As such it is important to include this option where appropriate so that MQ Administrators can shutdown the queue managers without having to resort to the ‘immediate’ shutdown option.
:options => Fixnum (Advanced MQ Use only)
- Numeric field containing any of the MQ Put message options or’d together
  - E.g. :options => WMQ::MQPMO_PASS_IDENTITY_CONTEXT | WMQ::MQPMO_ALTERNATE_USER_AUTHORITY
- Note: If :options is supplied, it is applied first, then the above parameters are applied afterwards.
- One or more of the following values:
```
  WMQ::MQPMO_NO_SYNCPOINT
  WMQ::MQPMO_LOGICAL_ORDER
  WMQ::MQPMO_NO_CONTEXT
  WMQ::MQPMO_DEFAULT_CONTEXT
  WMQ::MQPMO_PASS_IDENTITY_CONTEXT
  WMQ::MQPMO_PASS_ALL_CONTEXT
  WMQ::MQPMO_SET_IDENTITY_CONTEXT
  WMQ::MQPMO_SET_ALL_CONTEXT
  WMQ::MQPMO_ALTERNATE_USER_AUTHORITY
  WMQ::MQPMO_RESOLVE_LOCAL_Q
  WMQ::MQPMO_NONE
```
- Please see the WebSphere MQ documentation for more details on the above options
```
 Default: WMQ::MQPMO_NONE
```

Returns:

true : On Success
false: On Failure
comp_code and reason_code are also updated. reason will return a text description of the reason_code

Throws:

WMQ::WMQException if comp_code == MQCC_FAILED
Except if :exception_on_error => false was supplied as a parameter to QueueManager.new

Example:

  require 'wmq/wmq_client'

  WMQ::QueueManager.connect(:q_mgr_name=>'REID', :connection_name=>'localhost(1414)') do |qmgr|
    qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|

      # First message
      queue.put(:data => 'Hello World')

      # Set Format of message to string
      message = WMQ::Message.new
      message.descriptor[:format] = WMQ::MQFMT_STRING
      queue.put(:message=>message, :data => 'Hello Again')

      # Or, pass the data in the message
      message = WMQ::Message.new
      message.descriptor[:format] = WMQ::MQFMT_STRING
      message.data = 'Hello Again'
      queue.put(:message=>message)
    end
  end

reason()

Returns a textual representation of the reason_code for the last MQ operation on this queue instance

Returns => String

For a complete list of reasons, please see WMQ Constants or the WebSphere MQ documentation for Reason Codes

Note

The list of Reason Codes varies depending on the version of WebSphere MQ and the operating system on which Ruby WMQ was compiled

reason_code()

Return the reason code for the last MQ operation on this queue instance

Returns => FixNum

For a complete list of reason codes, please see WMQ Constants or the WebSphere MQ documentation for Reason Codes

Note

The list of Reason Codes varies depending on the version of WebSphere MQ and the operating system on which Ruby WMQ was compiled

Methods

Public Class methods

Public Instance methods