ferocia-rubywmq 1.1.0

data/examples/put_group_a.rb

@@ -0,0 +1,51 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put multiple Messages to a queue under the same group Id
+#          Open the queue so that multiple puts can be performed
+#          Ensure that all messages have the same group id
+#          Allow MQ to create the unique group id and let it automatically
+#          assign message sequence numbers for each message in the group
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+# Put 5 messages in a single group onto the queue
+total = 5
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    total.times do |count|
+      message.data = "Hello:#{count}"
+
+      # Set the message flag to indicate message is in a group
+      # On the last message, set the last message flag
+      message.descriptor[:msg_flags] = (count < total-1) ? WMQ::MQMF_MSG_IN_GROUP : WMQ::MQMF_LAST_MSG_IN_GROUP
+
+      # new_id => true causes subsequent messages to have unique message and
+      # correlation id's. Otherwise all messages will have the same message and
+      # correlation id's since the same message object is being
+      # re-used for all put calls.
+      #
+      # By setting the put :options => WMQ::MQPMO_LOGICAL_ORDER then MQ will supply a unique Group Id
+      # and MQ will automatically set the message sequence number for us.
+      queue.put(:message => message, :new_id => true, :options => WMQ::MQPMO_LOGICAL_ORDER)
+      p message.descriptor
+    end
+  end
+end

data/examples/put_group_b.rb

@@ -0,0 +1,53 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put multiple Messages to a queue under the same group Id
+#          Open the queue so that multiple puts can be performed
+#          Ensure that all messages have the same group id
+#          Supply our own user-defined group Id.
+#          We also have to supply the message sequence number which starts at 1
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+# Put 5 messages in a single group onto the queue
+total = 5
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    # Supply a unique Group Id, truncated to the MQ maximum for Group Id.
+    message.descriptor[:group_id] = 'MyUniqueGroupId'
+    total.times do |count|
+      #   new_id => true causes subsequent messages to have unique message and
+      #   correlation id's. Otherwise all messages will have the same message and
+      #   correlation id's since the same message object is being
+      #   re-used for all put calls
+      message.data = "Hello:#{count}"
+
+      # Set the message flag to indicate message is in a group
+      # On the last message, set the last message flag
+      message.descriptor[:msg_flags] = (count < total-1) ? WMQ::MQMF_MSG_IN_GROUP : WMQ::MQMF_LAST_MSG_IN_GROUP
+      message.descriptor[:msg_seq_number] = count + 1
+
+      # By setting the put :options => WMQ::MQPMO_LOGICAL_ORDER then MQ will supply a unique Group Id
+      # and MQ will automatically set the message sequence number for us.
+      queue.put(:message => message, :new_id => true)
+      p message.descriptor
+    end
+  end
+end

data/examples/put_rfh.rb

@@ -0,0 +1,67 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+# The Rules Format header (MQRFH) allows a list of name value pairs to be sent along
+# with a WMQ message. These name value pairs are represented as follows on the "wire":
+#   Name1 Value1 Name2 Value2 Name3 Value3
+#   
+# Ruby WMQ converts the above string of data into a Ruby hash by
+# using the name as the key, as follows:
+# data = {
+#    'Name1' => 'Value1',
+#    'Name2' => 'Value2',
+#    'Name3' => 'Value3'
+# }
+# 
+# Since a name can consist of any character except null, it is stored as a String
+# 
+# Note: It is possible to send or receive the same Name with multiple values using an array.
+#   E.g.   Name1 Value1 Name2 Value2 Name1 Value3
+#   Becomes:
+# data = {
+#    'Name1' => ['Value1', 'Value3'],
+#    'Name2' => 'Value2'
+# }
+# 
+# Note: Since a Hash does not preserve order, reading a Rules Format Header and then writing
+#       it out immediately again could result in re-ordering of the name value pairs.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header,
+      :name_value => {'name1' => 'value1', 
+                      'name2' => 'value2', 
+                      'name3' => ['value 3a', 'value 3b']} 
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_rfh2_a.rb

@@ -0,0 +1,43 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+# The Rules Format header2 (MQRFH2) allows a an XML-like string to be passed as a header
+# to the data.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header_2,
+      :xml => '<hello>to the world</hello>'
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_rfh2_b.rb

@@ -0,0 +1,43 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+# The Rules Format header2 (MQRFH2) allows a an XML-like string to be passed as a header
+# to the data.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header_2,
+      :xml => ['<hello>to the world</hello>', '<another>xml like string</another>'],
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_xmit_q.rb

@@ -0,0 +1,33 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Transmission header
+#
+require 'rubygems'
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = "Test message from 'LOCALQMS1'"
+    message.descriptor = {:original_length=>-1, :priority=>0, :put_time=>"18510170", :msg_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\005", :expiry=>-1, :persistence=>0, :reply_to_q=>"MQMON", :correl_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\004", :feedback=>0, :offset=>0, :report=>0, :msg_flags=>0, :reply_to_q_mgr=>"LOCALQMS1", :appl_identity_data=>"", :put_appl_name=>"LOCALQMS1", :user_identifier=>"mqm", :msg_seq_number=>1, :appl_origin_data=>"", :accounting_token=>"\026\001\005\025\000\000\000\271U\305\002\261\022\362\321\021D\3206\357\003\000\000\000\000\000\000\000\000\000\000\v", :backout_count=>0, :coded_char_set_id=>437, :put_appl_type=>7, :msg_type=>8, :group_id=>"", :put_date=>"20070109", :format=>"MQSTR", :encoding=>546}
+    message.headers = [{:priority=>0, :remote_q_mgr_name=>"OTHER.QMGR", :put_time=>"18510170", :msg_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\004", :expiry=>-1, :persistence=>0, :remote_q_name=>"OTHER.Q", :header_type=>:xmit_q_header, :reply_to_q=>"MQMON", :correl_id=>"", :feedback=>0, :report=>0, :reply_to_q_mgr=>"LOCALQMS1", :appl_identity_data=>"", :put_appl_name=>"uments\\MQ\\MQMon\\mqmonntp.exe", :user_identifier=>"mqm", :appl_origin_data=>"", :accounting_token=>"\026\001\005\025\000\000\000\271U\305\002\261\022\362\321\021D\3206\357\003\000\000\000\000\000\000\000\000\000\000\v", :backout_count=>0, :coded_char_set_id=>437, :put_appl_type=>11, :msg_type=>8, :put_date=>"20070109", :encoding=>546}]
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/q_to_files.cfg

@@ -0,0 +1,17 @@
+dev:
+  qmgr_options:
+    :q_mgr_name: REID
+  input_queue:
+    :mode: :browse
+    :q_name: TEST.QUEUE
+  target_directory: messages
+
+test:
+  qmgr_options:
+    :q_mgr_name: TEST.QMGR
+    :channel_name: SYSTEM.DEF.SVRCONN
+    :connection_name: remotehost(1414)
+  input_queue:
+    :mode: :browse
+    :q_name: TEST.QUEUE
+  target_directory: messages

data/examples/q_to_files.rb

@@ -0,0 +1,48 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Example: q_to_files:  Copy all messages in a queue to separate files in a directory
+#
+require 'rubygems'
+require 'find'
+require 'yaml'
+require 'wmq/wmq'
+require 'fileutils'
+
+# Call program passing environment name as first parameter
+#   The environment corresponds to an entry in the config file
+env = ARGV[0] || raise("Command line argument 'environment' is required")
+config = YAML::load_file('q_to_files.cfg')[env]
+
+# Create supplied path if it does not exist
+path = config['target_directory']
+FileUtils.mkdir_p(path)
+
+message = WMQ::Message.new
+message.descriptor = config['descriptor'] || {}
+tstart = Time.now
+counter = 0
+WMQ::QueueManager.connect(config['qmgr_options']) do |qmgr|
+  qmgr.open_queue(config['input_queue']) do |queue|
+    queue.each do |message|
+      counter = counter + 1
+      File.open(File.join(path, "message_%03d" % counter), 'w') {|file| file.write(message.data) }
+    end
+  end
+end
+duration = Time.now - tstart
+printf "Processed #{counter} messages in %.3f seconds. Average: %.3f messages/second\n", duration, counter/duration

data/examples/request.rb

@@ -0,0 +1,60 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : request.rb
+# 
+#          Sample program that demonstrates how to send a request message
+#          and then block until the response is received from the server.
+#          
+#          A temporary Dynamic Reply To Queue is used with non-persistent messaging
+#
+require 'rubygems'
+require 'wmq'
+
+wait_seconds = 30
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name        => 'SYSTEM.DEFAULT.MODEL.QUEUE',
+                  :dynamic_q_name=> 'REQUEST.*',
+                  :mode          => :input
+                 ) do |reply_queue|
+                 
+    message = WMQ::Message.new()
+    message.descriptor = { :msg_type      => WMQ::MQMT_REQUEST,
+                           :reply_to_q    => reply_queue.name,
+                           :reply_to_q_mgr=> qmgr.name,
+                           :format        => WMQ::MQFMT_STRING,
+                           :expiry        => wait_seconds*10}  # Measured in tenths of a second
+    message.data = 'Hello World'        
+                  
+    # Send request message
+    qmgr.put(:q_name=>'TEST.QUEUE', :message=>message)
+    
+    # Copy outgoing Message id to correlation id
+    message.descriptor[:correl_id]=message.descriptor[:msg_id]
+
+    # Wait for reply 
+    #   Only get the message that matches the correlation id set above
+    if reply_queue.get(:wait=>wait_seconds*1000, :message=>message, :match=>WMQ::MQMO_MATCH_CORREL_ID)
+      puts "Received:"
+      puts message.data
+    else
+      # get returns false when no message received. Also: message.data = nil
+      puts "Timed Out waiting for a reply from the server"
+    end
+  end
+end

data/examples/server.rb

@@ -0,0 +1,97 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+################################################################################
+
+#
+# Sample : Sample program to show how to write a server side application
+#
+#     This server times out after 60 seconds, but could be modified to
+#     run forever. Example:
+#         queue.each(:wait=>-1) do |message|
+#
+#     Note: - All calls are being performed under synchpoint control to
+#             prevent messages being if the program terminates unexpectedly
+#             or an error occurrs.
+#             Uses:  :sync=>true
+#           - Queue#each will backout any message changes if an excecption is raised 
+#             but not handled within the each block
+#           
+#     A "well-behaved" WebSphere MQ application should adhere to the following rules:
+#     - Perform puts and gets under synchpoint where applicable
+#     - Only send replies to Request messages. No reply for Datagrams
+#     - Set the message type to Reply when replying to a request message
+#     - Reply with:
+#         - Remaining Expiry (Ideally deduct any processing time since get)
+#         - Same priority as received message
+#         - Same persistence as received message
+#     - Adhere to the Report options supplied for message and correlation id's 
+#         in reply message
+#     - All headers must be returned on reply messages
+#         - This allows the calling application to store state information 
+#           in these headers
+#         - Unless of course if the relevant header is input only and used
+#           for completing the request
+#             - In this case any remaining headers should be returned
+#               to the caller
+#     - If an error occurs trying to process the message, an error message
+#       must be sent back to the requesting application
+#     - If the reply fails, it must be put to the dead letter queue
+#       with the relevant dead letter header and reason
+#     
+#     Note: - It is not recommended to run server side MQ applications over a client
+#             connection.
+#           - Client connections require substantially more error handling.
+#             - E.g. Connection to queue manager can be lost due to netowk issues
+#               - Need to go into some sort of retry state attempting
+#                 to reconnect to the queue manager
+#               - What about any work that was in progress?
+#               - Need to re-open any queues
+#               - Do any changes to other resources need to be undone first?
+#                 - E.g. Database, File etc..
+#             - etc....
+#
+require 'rubygems'
+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(:wait=>60000, :sync=>true, :convert=>true) do |request|
+      puts "Data Received:"
+      puts request.data
+      
+      begin
+        reply = WMQ::Message.new
+        reply.data = 'Echo back:'+request.data
+        
+        qmgr.put_to_reply_q(:message=>reply,
+                            :request_message=>request, # Only replies if message type is request
+                            :sync=>true)
+        
+      rescue WMQ::WMQException => exc
+        # Failed to send reply, put message to the Dead Letter Queue and add a dead letter header
+        p exc
+        puts "Failed to reply to sender, Put to dead letter queue"
+        qmgr.put_to_dead_letter_q(:message=>request, 
+                                  :reason=>WMQ::MQRC_UNKNOWN_REMOTE_Q_MGR,
+                                  :q_name=>queue.name,
+                                  :sync=>true)
+        # If it fails to put to the dead letter queue, this program will terminate and
+        # the changes will be "backed out". E.g. Queue Full, ...
+      end
+      qmgr.commit
+    end
+  end
+  puts 'No more messages found after 60 second wait interval'
+end

data/ext/build.bat

@@ -0,0 +1,3 @@
+call "C:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32.BAT"
+ruby extconf.rb --with-mqm-include="C:\Program Files\IBM\WebSphere MQ\Tools\c\include"
+nmake

data/ext/build.sh

@@ -0,0 +1,6 @@
+ruby extconf.rb --with-mqm-include=/opt/mqm/inc --with-mqm-lib=/opt/mqm/lib
+make
+# Uncomment the following lines for platforms other than Solaris, Windows and Linux
+#ruby extconf_client.rb --with-mqm-include=/opt/mqm/inc --with-mqm-lib=/opt/mqm/lib
+#make
+