Add InqMap as simpler API for MQINQ operations

Author: ibmmqmet

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Update MQI header files for MQ V9.1.1 and give more platform variations
 * Add support for MQSTAT and MQSUBRQ functions
 * Add support and sample for Message Property functions
+* Add InqMap as alternative (simpler) MQINQ operation
 
 ## November 2018 - v3.1.0
 * Added functions to mqmetric to issue DISPLAY QSTATUS for additional stats

ibmmq/mqi.go

@@ -597,6 +597,10 @@ how long each field in that buffer will be.
 
 The caller passes in how many integer selectors are expected to be
 returned, as well as the maximum length of the char buffer to be returned
+
+This function is a direct mapping of the MQI C function. It should be considered
+deprecated. In preference, use the InqMap function which provides a more convenient
+API.
 */
 func (object MQObject) Inq(goSelectors []int32, intAttrCount int, charAttrLen int) ([]int32,
 	[]byte, error) {
@@ -646,6 +650,121 @@ func (object MQObject) Inq(goSelectors []int32, intAttrCount int, charAttrLen in
 	return goIntAttrs, goCharAttrs, nil
 }
 
+/*
+ * InqMap should be considered the replacement for the Inq() function as it
+ * has a much simpler API. Simply pass in the list of selectors for the object
+ * and the return value consists of a map whose elements are
+ * a) accessed via the selector
+ * b) varying datatype (integer, string, string array) based on the selector
+ */
+func (object MQObject) InqMap(goSelectors []int32) (map[int32]interface{}, error) {
+	var mqrc C.MQLONG
+	var mqcc C.MQLONG
+	var mqCharAttrs C.PMQCHAR
+	var goCharAttrs []byte
+	var goIntAttrs []int32
+	var ptr C.PMQLONG
+	var charOffset int
+	var charLength int
+
+	intAttrCount, _, charAttrLen := getAttrInfo(goSelectors)
+
+	if intAttrCount > 0 {
+		goIntAttrs = make([]int32, intAttrCount)
+		ptr = (C.PMQLONG)(unsafe.Pointer(&goIntAttrs[0]))
+	} else {
+		ptr = nil
+	}
+	if charAttrLen > 0 {
+		mqCharAttrs = (C.PMQCHAR)(C.malloc(C.size_t(charAttrLen)))
+		defer C.free(unsafe.Pointer(mqCharAttrs))
+	} else {
+		mqCharAttrs = nil
+	}
+
+	// Pass in the selectors
+	C.MQINQ(object.qMgr.hConn, object.hObj,
+		C.MQLONG(len(goSelectors)),
+		C.PMQLONG(unsafe.Pointer(&goSelectors[0])),
+		C.MQLONG(intAttrCount),
+		ptr,
+		C.MQLONG(charAttrLen),
+		mqCharAttrs,
+		&mqcc, &mqrc)
+
+	mqreturn := MQReturn{MQCC: int32(mqcc),
+		MQRC: int32(mqrc),
+		verb: "MQINQ",
+	}
+
+	if mqcc != C.MQCC_OK {
+		return nil, &mqreturn
+	}
+
+  // Create a map of the selectors to the returned values
+	returnedMap := make(map[int32]interface{})
+
+	// Get access to the returned character data
+	if charAttrLen > 0 {
+		goCharAttrs = C.GoBytes(unsafe.Pointer(mqCharAttrs), C.int(charAttrLen))
+	}
+
+	// Walk through the returned data to build a map of responses. Go through
+	// the integers first to ensure that the map includes MQIA_NAME_COUNT if that
+	// had been requested
+	intAttr := 0
+	for i := 0; i < len(goSelectors); i++ {
+		s := goSelectors[i]
+		if s >= C.MQIA_FIRST && s <= C.MQIA_LAST {
+			returnedMap[s] = goIntAttrs[intAttr]
+			intAttr++
+		}
+	}
+
+	// Now we can walk through the list again for the character attributes
+	// and build the map entries. Getting the list of NAMES from a NAMELIST
+	// is a bit complicated ...
+	charLength = 0
+	charOffset = 0
+	for i := 0; i < len(goSelectors); i++ {
+		s := goSelectors[i]
+		if s >= C.MQCA_FIRST && s <= C.MQCA_LAST {
+			if s == C.MQCA_NAMES {
+				count, ok := returnedMap[C.MQIA_NAME_COUNT]
+				if ok {
+					c := int(count.(int32))
+					charLength = C.MQ_OBJECT_NAME_LENGTH
+					names := make([]string, c)
+					for j := 0; j < c; j++ {
+						name := string(goCharAttrs[charOffset:charOffset+charLength])
+						idx := strings.IndexByte(name, 0)
+						if idx != -1 {
+							name = name[0:idx]
+						}
+						names[j] = strings.TrimSpace(name)
+						charOffset += charLength
+					}
+					returnedMap[s] = names
+				} else {
+					charLength = 0
+				}
+			} else {
+				charLength = getAttrLength(s)
+				name := string(goCharAttrs[charOffset:charOffset+charLength])
+				idx := strings.IndexByte(name, 0)
+				if idx != -1 {
+					name = name[0:idx]
+				}
+
+				returnedMap[s] = strings.TrimSpace(name)
+				charOffset += charLength
+			}
+		}
+	}
+
+	return returnedMap, nil
+}
+
 /*********** Message Handles and Properties  ****************/
 
 /*

ibmmq/mqiattrs.go

@@ -0,0 +1,115 @@
+package ibmmq
+
+/*
+  Copyright (c) IBM Corporation 2018
+
+  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.
+
+   Contributors:
+     Mark Taylor - Initial Contribution
+*/
+
+/*
+
+#include <stdlib.h>
+#include <string.h>
+#include <cmqc.h>
+
+*/
+import "C"
+
+/*
+ * This file deals with the lengths of attributes that may be processed
+ * by the MQSET/MQINQ calls. Only a small set of the object attributes
+ * are supported by MQINQ (and even fewer for MQSET) so it's reasonable
+ * to list them all here
+ */
+var mqInqLength = map[int32]int32{
+	C.MQCA_ALTERATION_DATE:       C.MQ_DATE_LENGTH,
+	C.MQCA_ALTERATION_TIME:       C.MQ_TIME_LENGTH,
+	C.MQCA_APPL_ID:               C.MQ_PROCESS_APPL_ID_LENGTH,
+	C.MQCA_BACKOUT_REQ_Q_NAME:    C.MQ_Q_NAME_LENGTH,
+	C.MQCA_BASE_Q_NAME:           C.MQ_Q_NAME_LENGTH,
+	C.MQCA_CF_STRUC_NAME:         C.MQ_CF_STRUC_NAME_LENGTH,
+	C.MQCA_CHANNEL_AUTO_DEF_EXIT: C.MQ_EXIT_NAME_LENGTH,
+	C.MQCA_CHINIT_SERVICE_PARM:   C.MQ_CHINIT_SERVICE_PARM_LENGTH,
+	C.MQCA_CLUSTER_NAME:          C.MQ_CLUSTER_NAME_LENGTH,
+	C.MQCA_CLUSTER_NAMELIST:      C.MQ_NAMELIST_NAME_LENGTH,
+	C.MQCA_CLUSTER_WORKLOAD_DATA: C.MQ_EXIT_DATA_LENGTH,
+	C.MQCA_CLUSTER_WORKLOAD_EXIT: C.MQ_EXIT_NAME_LENGTH,
+	C.MQCA_COMMAND_INPUT_Q_NAME:  C.MQ_Q_NAME_LENGTH,
+	C.MQCA_CREATION_DATE:         C.MQ_DATE_LENGTH,
+	C.MQCA_CREATION_TIME:         C.MQ_TIME_LENGTH,
+	C.MQCA_DEAD_LETTER_Q_NAME:    C.MQ_Q_NAME_LENGTH,
+	C.MQCA_DEF_XMIT_Q_NAME:       C.MQ_Q_NAME_LENGTH,
+	C.MQCA_DNS_GROUP:             C.MQ_DNS_GROUP_NAME_LENGTH,
+	C.MQCA_ENV_DATA:              C.MQ_PROCESS_ENV_DATA_LENGTH,
+	C.MQCA_IGQ_USER_ID:           C.MQ_USER_ID_LENGTH,
+	C.MQCA_INITIATION_Q_NAME:     C.MQ_Q_NAME_LENGTH,
+	C.MQCA_INSTALLATION_DESC:     C.MQ_INSTALLATION_DESC_LENGTH,
+	C.MQCA_INSTALLATION_NAME:     C.MQ_INSTALLATION_NAME_LENGTH,
+	C.MQCA_INSTALLATION_PATH:     C.MQ_INSTALLATION_PATH_LENGTH,
+	C.MQCA_LU62_ARM_SUFFIX:       C.MQ_ARM_SUFFIX_LENGTH,
+	C.MQCA_LU_GROUP_NAME:         C.MQ_LU_NAME_LENGTH,
+	C.MQCA_LU_NAME:               C.MQ_LU_NAME_LENGTH,
+	C.MQCA_NAMELIST_DESC:         C.MQ_NAMELIST_DESC_LENGTH,
+	C.MQCA_NAMELIST_NAME:         C.MQ_NAMELIST_NAME_LENGTH,
+	C.MQCA_NAMES:                 C.MQ_OBJECT_NAME_LENGTH * 256, // TODO: split these out
+	C.MQCA_PARENT:                C.MQ_Q_MGR_NAME_LENGTH,
+	C.MQCA_PROCESS_DESC:          C.MQ_PROCESS_DESC_LENGTH,
+	C.MQCA_PROCESS_NAME:          C.MQ_PROCESS_NAME_LENGTH,
+	C.MQCA_Q_DESC:                C.MQ_Q_DESC_LENGTH,
+	C.MQCA_Q_MGR_DESC:            C.MQ_Q_MGR_DESC_LENGTH,
+	C.MQCA_Q_MGR_IDENTIFIER:      C.MQ_Q_MGR_IDENTIFIER_LENGTH,
+	C.MQCA_Q_MGR_NAME:            C.MQ_Q_MGR_NAME_LENGTH,
+	C.MQCA_Q_NAME:                C.MQ_Q_NAME_LENGTH,
+	C.MQCA_QSG_NAME:              C.MQ_QSG_NAME_LENGTH,
+	C.MQCA_REMOTE_Q_MGR_NAME:     C.MQ_Q_MGR_NAME_LENGTH,
+	C.MQCA_REMOTE_Q_NAME:         C.MQ_Q_NAME_LENGTH,
+	C.MQCA_REPOSITORY_NAME:       C.MQ_Q_MGR_NAME_LENGTH,
+	C.MQCA_REPOSITORY_NAMELIST:   C.MQ_NAMELIST_NAME_LENGTH,
+	C.MQCA_STORAGE_CLASS:         C.MQ_STORAGE_CLASS_LENGTH,
+	C.MQCA_TCP_NAME:              C.MQ_TCP_NAME_LENGTH,
+	C.MQCA_TRIGGER_DATA:          C.MQ_TRIGGER_DATA_LENGTH,
+	C.MQCA_USER_DATA:             C.MQ_PROCESS_USER_DATA_LENGTH,
+	C.MQCA_XMIT_Q_NAME:           C.MQ_Q_NAME_LENGTH,
+}
+
+/*
+ * Return how many char & int attributes are in the list of selectors, and the
+ * maximum length of the buffer needed to return them from the MQI
+ */
+func getAttrInfo(attrs []int32) (int, int, int) {
+	var charAttrLength = 0
+	var charAttrCount = 0
+	var intAttrCount = 0
+
+	for i := 0; i < len(attrs); i++ {
+		if v, ok := mqInqLength[attrs[i]]; ok {
+			charAttrCount++
+			charAttrLength += int(v)
+		} else if attrs[i] >= C.MQIA_FIRST && attrs[i] <= C.MQIA_LAST {
+			intAttrCount++
+		}
+	}
+	return intAttrCount, charAttrCount, charAttrLength
+}
+
+func getAttrLength(attr int32) int {
+	if v, ok := mqInqLength[attr]; ok {
+		return int(v)
+	} else {
+		return 0
+	}
+
+}

samples/README.md

@@ -24,6 +24,8 @@ Current samples in this directory include
 * amqssub.go : Subscribe to a topic and receive publications
 * amqsconn.go: How to programmatically connect as an MQ client to a remote queue manager.
 Allow use of a userid/password for authentication. There are no default values for this sample.
+* amqsprop.go: Set and extract message properties
+* amqsinq.go : Demonstrate the new InqMap API for inquiring object attributes
 
 Some trivial scripts run the sample programs in matching pairs:
 * putget.sh  : Run amqsput and then use the generated MsgId to get the same message