rubywmq 0.3.0

data/ext/generate/wmq_structs.erb

@@ -0,0 +1,388 @@
+<% 
+################################################################################
+#  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.
+################################################################################
+
+    symbols = {
+          'descriptor='=>nil,
+          'headers='=>nil,
+          'data='=>nil,
+          'header_type'=>nil,
+          'to_s'=>nil,
+          'xml'=>nil,
+          'name_value'=>nil,
+    }
+    wmq_structs = [
+      # Message Descriptor
+      {:file=>'cmqc.h', :struct=>'MQMD'},
+
+      # Message Descriptor 1
+      {:file=>'cmqc.h', :struct=>'MQMD1', :other_keys=>[:remote_q_name, :remote_q_mgr_name]},
+
+      # Rules and formatting header2
+      {:file=>'cmqc.h', :struct=>'MQRFH2', :header=>'rf_header_2', :struct_id=>'MQRFH_STRUC_ID',
+       :other_keys=>[:xml],
+       :custom=>true }, # Implement custom Message_build_rf_header_2 and Message_deblock_rf_header_2
+
+      # Rules and formatting header
+      {:file=>'cmqc.h', :struct=>'MQRFH', :header=>'rf_header', :other_keys=>[:name_value],
+       :custom=>true }, # Implement custom Message_build_rf_header and Message_deblock_rf_header
+
+      # Dead Letter Header
+      {:file=>'cmqc.h', :struct=>'MQDLH', :header=>'dead_letter_header',
+       :defaults=>'MQDLH_DEF.CodedCharSetId = MQCCSI_INHERIT;'},
+
+      # CICS bridge header
+      {:file=>'cmqc.h', :struct=>'MQCIH', :header=>'cics'},
+
+      # Distribution header
+      {:file=>'cmqc.h', :struct=>'MQDH',  :header=>'dist_header'},
+
+      # IMS information header
+      {:file=>'cmqc.h', :struct=>'MQIIH', :header=>'ims'},
+
+      # Reference message header (send large files over channels)
+      {:file=>'cmqc.h', :struct=>'MQRMH', :header=>'ref_msg_header'},
+
+      # Trigger Message
+      {:file=>'cmqc.h', :struct=>'MQTM', :header=>'trigger', :format=>false},
+
+      # Trigger Message 2 (character format)
+      {:file=>'cmqc.h', :struct=>'MQTMC2'},
+
+      # Work Information header
+      {:file=>'cmqc.h', :struct=>'MQWIH', :header=>'work_info_header'},
+
+      # Transmission-queue header - Todo: Need to deal with MQMDE
+      {:file=>'cmqc.h', :struct=>'MQXQH', :header=>'xmit_q_header', :format=>'MsgDesc.Format'},
+    ]
+    
+    wmq_structs.each do |struct|
+      # Parse WebSphere MQ 'C' Header file and extract elements
+      elements = extract_struct(@path+'/'+struct[:file], struct[:struct])
+      struct[:elements] = elements
+
+      # Add symbol for each struct name
+      symbols[struct[:header]]=nil if struct[:header]
+
+      # Add symbols for each element in C Struct
+      elements.each do |item|
+        symbols[rubyize_name(item[1])] = nil unless @@field_ignore_list.include?(item[1])
+      end
+    end
+%>
+/* --------------------------------------------------------------------------
+ *  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.
+ * --------------------------------------------------------------------------
+ *
+ *  WARNING: DO NOT MODIFY THIS FILE
+ *
+ *  This file was generated by generate_structs.rb.
+ *
+ * --------------------------------------------------------------------------*/
+
+#include "wmq.h"
+
+/* --------------------------------------------------------------------------
+ *  Static's to hold Symbols
+ * --------------------------------------------------------------------------*/
+<% 
+    header_file = 'cmqc.h'
+    struct = 'MQMD'
+
+    # Define static variables to hold Ruby symbols
+    key_list = symbols.keys.sort
+    key_list.each do |key, value| 
+      %><%="static ID ID_#{key.sub('=', '_set')};\n" %><%
+    end
+    
+    # initialize symbols
+    %>
+/* --------------------------------------------------------------------------
+ *  Initialize Symbols
+ * --------------------------------------------------------------------------*/
+void wmq_structs_id_init()
+{
+<%  key_list.each do |key, value| 
+      %><%="    ID_%-20s = rb_intern(\"%s\");\n"% [key.sub('=', '_set'), key] %><%
+    end
+%>}
+<%
+    # Generate functions to move to/from a Ruby Hash of the symbols defined above
+    wmq_structs.each do |struct|
+      elements = struct[:elements]
+      struct_name = struct[:struct]
+      variable = 'p'+struct_name.downcase
+%>
+/* --------------------------------------------------------------------------
+ *  Convert between <%=struct_name%> and Hash
+ * --------------------------------------------------------------------------*/
+void Message_from_<%=struct_name.downcase%>(VALUE hash, <%=struct_name%>* <%=variable%>)
+{
+    VALUE  str;
+    size_t size;
+    size_t length; 
+    size_t i;
+    char*  pChar;
+        
+<%
+      elements.each do |item|
+        type = item[0]
+        name = item[1]
+          
+        next if @@field_ignore_list.include?(name) ||
+                (name=='Format' && struct[:header])
+          
+        match = /(MQ\D+)/.match(type)
+        type = "#{match[1]}S" if match[1] != type
+%><%=   if type == 'MQMDS'
+          "    %-16s(hash, &#{variable}->%s);\n" % ['Message_from_mqmd1', name]
+        else
+          "    %-16s(hash, %-30s #{variable}->%s)\n" % ["WMQ_#{type}2HASH", rubyize_name(name)+',',name]
+        end %><%
+      end 
+%>}
+
+#if RUBY_VERSION_CODE > 183
+static int Message_to_<%=struct_name.downcase%>_each (VALUE key, VALUE value, <%=struct_name%>* p<%=struct_name.downcase%>)
+{
+#else
+static int Message_to_<%=struct_name.downcase%>_each (VALUE array, <%=struct_name%>* p<%=struct_name.downcase%>)
+{
+    VALUE key   = rb_ary_shift(array);
+    VALUE value = rb_ary_shift(array);
+#endif
+    VALUE str;
+    size_t size;
+    size_t length; 
+    VALUE  val;
+    ID     id = rb_to_id(key);
+    
+   <% contains = nil
+      elements.each do |item|
+        type = item[0]
+        name = item[1]
+          
+        next if @@field_ignore_list.include?(name) ||
+                (name=='Format' && struct[:header])
+          
+        match = /(MQ\D+)/.match(type)
+        type = "#{match[1]}S" if match[1] != type
+%><%=   if type == 'MQMDS'
+          contains = 'mqmd1'
+          ""
+        else
+          "%-35s { %-16s(value,#{variable}->#{name}) }\n    else" % [" if(id == ID_#{rubyize_name(name)})", "WMQ_STR2#{type}"]
+        end%><%
+      end
+      if struct[:other_keys]
+        struct[:other_keys].each do |key|
+        %> if(id == ID_<%=key.to_s%>) {}
+    else<%   end
+      end
+%><%=struct[:header]?" if(id != ID_header_type)":""%><%
+      if contains 
+%> {
+#if RUBY_VERSION_CODE > 183
+      Message_to_<%= contains%>_each(key, value, &pmqxqh->MsgDesc); 
+#else
+      rb_ary_push(array, key);
+      rb_ary_push(array, value);
+      Message_to_<%= contains%>_each(array, &pmqxqh->MsgDesc); 
+#endif
+   }<%
+      else%>
+    {
+        val = rb_funcall(key, ID_to_s, 0);
+        rb_raise(rb_eArgError, "WMQ::Message#to_<%=struct_name.downcase%> Unknown symbol :%s supplied", RSTRING(val)->ptr);
+    }
+<%    end%>
+    return 0;
+}
+
+void Message_to_<%=struct_name.downcase%>(VALUE hash, <%=struct_name%>* p<%=struct_name.downcase%>)
+{
+#if RUBY_VERSION_CODE > 183
+    rb_hash_foreach(hash, Message_to_<%=struct_name.downcase%>_each, (VALUE)p<%=struct_name.downcase%>);
+#else
+    rb_iterate (rb_each, hash, Message_to_<%=struct_name.downcase%>_each, (VALUE)p<%=struct_name.downcase%>);
+#endif
+}
+<%  end # wmq_structs.each 
+%>
+
+/* --------------------------------------------------------------------------
+ *  Extract message data and headers
+ * --------------------------------------------------------------------------*/
+void Message_deblock(VALUE self, PMQMD pmqmd, PMQBYTE p_buffer, MQLONG total_length, MQLONG trace_level)
+{
+    PMQCHAR p_format   = pmqmd->Format;               /* Start with format in MQMD     */
+    PMQBYTE p_data     = p_buffer;                    /* Pointer to start of data      */
+    MQLONG  data_length= total_length;                /* length of data portion        */
+    VALUE   headers    = rb_ary_new();
+    VALUE   descriptor = rb_hash_new();
+    MQLONG  size       = 0;
+
+    while (p_format)
+    {
+<%
+    wmq_structs.each do |struct|
+      if struct[:header]
+%>        /* <%=struct[:struct]%>: <%=struct[:header]%> */
+        if(strncmp(p_format, MQFMT_<%=struct[:header].upcase%>, MQ_FORMAT_LENGTH) == 0)
+        {
+            VALUE hash = rb_hash_new();
+            P<%=struct[:struct]%> p_header = (P<%=struct[:struct]%>)p_data;
+            
+            if(trace_level>2)
+                printf("WMQ::Message#deblock Found <%=struct[:header]%>\n");
+                
+            if(memcmp(p_header->StrucId, <%=struct[:struct_id] || "#{struct[:struct].upcase}_STRUC_ID"%>, sizeof(p_header->StrucId)) != 0)
+            {
+                break;    /* Bad Message received, do not deblock headers */
+                if(trace_level>1)
+                    printf("WMQ::Message#deblock MQFMT_<%=struct[:header].upcase%> received, but message does not contain <%=struct[:struct].upcase%>\n");
+            }
+            else
+            {
+                Message_from_<%=struct[:struct].downcase%>(hash, p_header);
+                rb_hash_aset(hash, ID2SYM(ID_header_type), ID2SYM(ID_<%=struct[:header]%>));
+                rb_ary_push(headers, hash);
+                size        = <%=if struct[:custom] then
+                                   "Message_deblock_#{struct[:header]} (hash, p_data, data_length);\n"+
+                                   "                if (!size) break; /* Poison Message */"
+                                 elsif struct[:elements].include?(['MQLONG', 'StrucLength'])
+                                   'p_header->StrucLength;'
+                                 else
+                                   "sizeof(#{struct[:struct]});"
+                                 end %>
+                p_data      += size;
+                data_length -= size;
+                <%=if struct[:format] == nil
+                     'p_format    = p_header->Format'
+                   elsif struct[:format] == false
+                     'break'
+                   else
+                     "p_format    = p_header->#{struct[:format]}"
+                   end %>;
+            }
+        }
+        else
+<%
+      end
+    end # wmq_structs.each 
+%>        {
+            break;
+        }
+    }
+    /* Copy the last recognised header found to the Descriptor */
+    if(p_format && p_format != pmqmd->Format)
+    {
+        strncpy(pmqmd->Format, p_format, MQ_FORMAT_LENGTH);
+    }
+    
+    Message_from_mqmd(descriptor, pmqmd);
+    rb_funcall(self, ID_descriptor_set, 1, descriptor);
+    rb_funcall(self, ID_headers_set, 1, headers);
+    rb_funcall(self, ID_data_set, 1, rb_str_new(p_data, data_length));
+}
+
+void Message_build_set_format(ID header_type, PMQBYTE p_format)
+{
+<%
+    wmq_structs.each do |struct|
+      if struct[:header]
+%>    if(header_type == ID_<%=struct[:header]%>) { memcpy(p_format, MQFMT_<%=struct[:header].upcase%>, MQ_FORMAT_LENGTH); return;}
+<%
+      end
+    end # wmq_structs.each 
+    
+%>
+    rb_raise(rb_eArgError, "Invalid/Unknown header_type supplied in WMQ::Message#headers array");
+}
+
+/* --------------------------------------------------------------------------
+ *  Build message headers
+ * --------------------------------------------------------------------------*/
+int Message_build_header (VALUE hash, struct Message_build_header_arg* parg)
+{
+    VALUE   val = rb_hash_aref(hash, ID2SYM(ID_header_type));
+    PMQBYTE p_data = 0;
+
+    if (!NIL_P(val) && (TYPE(val) == T_SYMBOL))
+    {
+        ID header_id = rb_to_id(val);
+<%
+    wmq_structs.each do |struct|
+      if struct[:header]
+%>        if (header_id == ID_<%=struct[:header]%>)  /* Build <%=struct[:struct]%> */
+        { <%
+        if struct[:custom] %>
+            Message_build_<%=struct[:header]%> (hash, parg);
+<%      else %>
+            static <%=struct[:struct]%> <%=struct[:struct]%>_DEF = {<%=struct[:struct]%>_DEFAULT};
+            <%=struct[:defaults]%>
+
+            if(parg->trace_level>2)
+                printf ("WMQ::Message#build_header Found <%=struct[:header]%>\n");
+                
+            p_data = Message_autogrow_data_buffer(parg, sizeof(<%=struct[:struct]%>));
+
+            memcpy(p_data, &<%=struct[:struct]%>_DEF, sizeof(<%=struct[:struct]%>));
+            Message_to_<%=struct[:struct].downcase%>(hash, (P<%=struct[:struct]%>)p_data);
+<%          if struct[:format] != false%>
+            if(parg->next_header_id)
+            {
+                Message_build_set_format(parg->next_header_id, ((P<%=struct[:struct]%>)p_data)-><%=struct[:format] || 'Format'%>);
+            }
+            else
+            {
+                memcpy(((P<%=struct[:struct]%>)p_data)-><%=struct[:format] || 'Format'%>, parg->data_format, MQ_FORMAT_LENGTH);
+            }
+<%          end %>
+            *(parg->p_data_offset) += sizeof(<%=struct[:struct]%>);
+
+            if(parg->trace_level>2)
+                printf ("WMQ::Message#build_header data offset:%ld\n", *(parg->p_data_offset));
+<%      end 
+%>        }
+        else
+<%
+      end
+    end # wmq_structs.each 
+    
+%>        {
+            rb_raise(rb_eArgError, "Unknown :header_type supplied in WMQ::Message#headers array");
+        }
+    }
+    else
+    {
+        rb_raise(rb_eArgError, "Mandatory parameter :header_type missing from header entry in WMQ::Message#headers array");
+    }
+
+    return 0;                                         /* Continue */
+}

data/ext/lib/wmq_temp.rb

@@ -0,0 +1,197 @@
+################################################################################
+#  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.
+################################################################################
+
+module WMQ
+
+  # Temporary placeholder until the following code is moved to 'C'
+
+  #
+  class QueueManager
+    def method_missing(name, *args)
+      if args.size == 1
+        self.execute({:command=>name}.merge(args[0]))
+      elsif args.size == 0
+        self.execute({:command=>name})
+      else
+        raise("Invalid arguments supplied to QueueManager#:#{name}, args:#{args}")
+      end
+    end
+
+    # Execute any MQSC command against the queue manager
+    #
+    # Example
+    #   require 'wmq/wmq'
+    #   require 'wmq/wmq_const_admin'
+    #   WMQ::QueueManager.connect(:q_mgr_name=>'REID', :connection_name=>'localhost(1414)') do |qmgr|
+    #     qmgr.mqsc('dis ql(*)').each {|item| p item }
+    #   end
+    def mqsc(mqsc_text)
+      self.execute(:command=>:escape, :escape_type=>WMQ::MQET_MQSC, :escape_text=>mqsc_text).collect {|item| item[:escape_text] }
+    end
+
+    # Put a reply message back to the sender
+    #
+    #   The :message is sent to the queue and queue manager specified in the
+    #   :reply_to_q and :reply_to_q_mgr propoerties of the :request_message.
+    #
+    #   The following rules are followed before sending the reply:
+    #   - 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
+    #
+    # Parameters:
+    #   * :request_message The message originally received
+    #   * All the other parameters are the same as QueueManager#put
+    #
+    def put_to_reply_q(parms)
+      # Send replies only if message type is request
+      if parms[:request_message].descriptor[:msg_type] == WMQ::MQMT_REQUEST
+        request = parms.delete(:request_message)
+
+        reply = parms[:message] ||= Message.new(:data=>parms[:data])
+        reply.descriptor[:msg_type]   = WMQ::MQMT_REPLY
+        reply.descriptor[:expiry]     = request.descriptor[:expiry]
+        reply.descriptor[:priority]   = request.descriptor[:priority]
+        reply.descriptor[:persistence]= request.descriptor[:persistence]
+        reply.descriptor[:format] = request.descriptor[:format]
+
+        # Set Correlation Id based on report options supplied
+        if request.descriptor[:report] & WMQ::MQRO_PASS_CORREL_ID != 0
+          reply.descriptor[:correl_id] = request.descriptor[:correl_id]
+        else
+          reply.descriptor[:correl_id] = request.descriptor[:msg_id]
+        end
+
+        # Set Message Id based on report options supplied
+        if request.descriptor[:report] & WMQ::MQRO_PASS_MSG_ID != 0
+          reply.descriptor[:msg_id] = request.descriptor[:msg_id]
+        end
+
+        parms[:q_name]    = request.descriptor[:reply_to_q]
+        parms[:q_mgr_name]= request.descriptor[:reply_to_q_mgr]
+        return put(parms)
+      else
+        return false
+      end
+    end
+
+    # Put a message to the Dead Letter Queue
+    #
+    #   If an error occurs when processing a datagram message
+    #   it is necessary to move the message to the dead letter queue.
+    #   I.e. An error message cannot be sent back to the sender because
+    #        the original message was not a request message.
+    #          I.e. msg_type != WMQ::MQMT_REQUEST
+    #
+    #   All existing message data, message descriptor and message headers
+    #   are retained.
+    #
+    def put_to_dead_letter_q(parms)
+      message = parms[:message] ||= Message.new(:data=>parms[:data])
+      dlh = {
+        :header_type     =>:dead_letter_header,
+        :reason          =>parms.delete(:reason),
+        :dest_q_name     =>parms.delete(:q_name),
+        :dest_q_mgr_name =>self.name}
+
+      message.headers.unshift(dlh)
+      parms[:q_name]='SYSTEM.DEAD.LETTER.QUEUE'  #TODO Should be obtained from QMGR config
+      return self.put(parms)
+    end
+
+  end
+
+  # Message contains the message descriptor (MQMD), data
+  # and any headers.
+  #
+  # Note:
+  # * The format in the descriptor applies only to the format of the data portion,
+  #   not the format of any included headers
+  # * The message format can ONLY be supplied in the descriptor.
+  #   * I.e. It is the format of the data, Not the headers.
+  #   * On the wire formats are determined automatically by the :header_type key for 
+  #     each header
+  #   * Other WebSphere MQ interfaces require that the formats be "daisy-chained"
+  #     * I.e. The MQMD.Format is actually the format of the first header
+  #     * Ruby WMQ removes this tedious requirement and performs this
+  #       requirement automatically under the covers
+  #   * The format of any header should not be supplied in the descriptor or any header
+  #
+  # Message has the following attributes:
+  # * descriptor = {
+  #                                                           # WebSphere MQ Equivalent
+  #     :format             => WMQ::MQFMT_STRING,             # MQMD.Format - Format of data only
+  #                            WMQ::MQFMT_NONE                #   Do not supply header formats here
+  #     :original_length    => Number                         # MQMD.OriginalLength
+  #     :priority           => 0 .. 9                         # MQMD.Priority
+  #     :put_time           => String                         # MQMD.PutTime
+  #     :msg_id             => String                         ...
+  #     :expiry             => Number
+  #     :persistence        => Number
+  #     :reply_to_q         => String
+  #     :correl_id          => String
+  #     :feedback           => Number
+  #     :offset             => Number
+  #     :report             => Number
+  #     :msg_flags          => Number
+  #     :reply_to_q_mgr     => String
+  #     :appl_identity_data => String
+  #     :put_appl_name      => String
+  #     :user_identifier    => String
+  #     :msg_seq_number     => Number
+  #     :appl_origin_data   => String
+  #     :accounting_token   => String
+  #     :backout_count      => Number
+  #     :coded_char_set_id  => Number
+  #     :put_appl_type      => Number
+  #     :msg_type           => Number
+  #     :group_id           => String
+  #     :put_date           => String
+  #     :encoding           => Number
+  #   }
+  # * data => String
+  # * headers => Array of Hashes
+  #   * Note: Do not supply the format of any header. Ruby WMQ does this for you.
+  #   
+  #    The following headers are supported:
+  #   * Rules And Formatting Header (RFH)
+  #       :header_type => :rf_header
+  #       :....
+  #   * Rules and Formatting V2 Header (RFH2)
+  #       ....
+  #   * Dead Letter Header
+  #   * CICS Header
+  #   * IMS Header
+  #   * Transmission Queue Header
+  #   * ...
+  class Message
+    attr_reader :data, :descriptor, :headers
+    attr_writer :data, :descriptor, :headers
+  end
+
+end