Add GetSlice verb (for #110)

Author: ibmmqmet

CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 Newest updates are at the top of this file.
 
+## August 2 2019 - v4.1.0
+* ibmmq - Add new verb GetSlice to mirror Get() but which returns ready-sized buffer (#110)
+  * See updated sample amqsget.go
+* Some comment tidying up. Make CMQC constants constant.
+
 ## July 30 2019 - v4.0.10
 * ibmmq - Add error checking to some structure fields (#111)
 

ibmmq/cmqc_darwin.go

@@ -36,7 +36,7 @@ package ibmmq
 *   <END_BUILDINFO>
  */
 
-var (
+const (
 	MQACH_CURRENT_LENGTH           int32  = 72
 	MQACH_CURRENT_VERSION          int32  = 1
 	MQACH_LENGTH_1                 int32  = 72

ibmmq/cmqc_linux_amd64.go

@@ -36,7 +36,7 @@ package ibmmq
 *   <END_BUILDINFO>
  */
 
-var (
+const (
 	MQACH_CURRENT_LENGTH           int32  = 72
 	MQACH_CURRENT_VERSION          int32  = 1
 	MQACH_LENGTH_1                 int32  = 72

ibmmq/cmqc_linux_ppc64le.go

@@ -36,7 +36,7 @@ package ibmmq
 *   <END_BUILDINFO>
  */
 
-var (
+const (
 	MQACH_CURRENT_LENGTH           int32  = 72
 	MQACH_CURRENT_VERSION          int32  = 1
 	MQACH_LENGTH_1                 int32  = 72

ibmmq/cmqc_linux_s390x.go

@@ -36,7 +36,7 @@ package ibmmq
 *   <END_BUILDINFO>
  */
 
-var (
+const (
 	MQACH_CURRENT_LENGTH           int32  = 72
 	MQACH_CURRENT_VERSION          int32  = 1
 	MQACH_LENGTH_1                 int32  = 72

ibmmq/cmqc_windows.go

@@ -36,7 +36,7 @@ package ibmmq
 *   <END_BUILDINFO>
  */
 
-var (
+const (
 	MQACH_CURRENT_LENGTH           int32  = 72
 	MQACH_CURRENT_VERSION          int32  = 1
 	MQACH_LENGTH_1                 int32  = 72

ibmmq/mqi.go

@@ -1,5 +1,5 @@
 /*
-Package ibmmq provides a wrapper to a the IBM MQ procedural interface (the MQI).
+Package ibmmq provides a wrapper to the IBM MQ procedural interface (the MQI).
 
 The verbs are given mixed case names without MQ - Open instead
 of MQOPEN etc.
@@ -9,8 +9,8 @@ constants and structures, see the MQ Knowledge Center
 at https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.dev.doc/q023720_.htm#q023720_
 
 If an MQI call returns MQCC_FAILED or MQCC_WARNING, a custom error
-type is returned containing the MQCC/MQRC values as
-a formatted string. Use mqreturn:= err(*ibmmq.MQReturn) to access
+type is returned containing the MQCC/MQRC values as well as
+a formatted string. Use 'mqreturn:= err(*ibmmq.MQReturn)' to access
 the particular MQRC or MQCC values.
 
 The build directives assume the default MQ installation path
@@ -607,6 +607,36 @@ The length of the retrieved message is returned.
 */
 func (object MQObject) Get(gomd *MQMD,
 	gogmo *MQGMO, buffer []byte) (int, error) {
+	return object.getInternal(gomd, gogmo, buffer, false)
+}
+
+/*
+GetSlice is the same as Get except that the buffer gets returned
+ready-sliced based on the message length instead of just returning the
+length. The real length is also still returned in case of truncation.
+*/
+func (object MQObject) GetSlice(gomd *MQMD,
+	gogmo *MQGMO, buffer []byte) ([]byte, int, error) {
+	realDatalen, err := object.getInternal(gomd, gogmo, buffer, true)
+
+	// The datalen will be set even if the buffer is too small - there
+	// will be one of MQRC_TRUNCATED_MSG_ACCEPTED or _FAILED depending on the
+	// GMO options. In any case, we return the available data along with the
+	// error code but need to make sure that the real untruncated
+	// message length is also returned. Also ensure we don't try to read past the
+	// end of the buffer.
+	datalen := realDatalen
+	if datalen > cap(buffer) {
+		datalen = cap(buffer)
+	}
+	return buffer[0:datalen], realDatalen, err
+}
+
+/*
+This is the real function that calls MQGET.
+*/
+func (object MQObject) getInternal(gomd *MQMD,
+	gogmo *MQGMO, buffer []byte, useCap bool) (int, error) {
 
 	var mqrc C.MQLONG
 	var mqcc C.MQLONG
@@ -624,12 +654,23 @@ func (object MQObject) Get(gomd *MQMD,
 		return 0, err
 	}
 
-	bufflen := len(buffer)
+	bufflen := 0
+	if useCap {
+		bufflen = cap(buffer)
+	} else {
+		bufflen = len(buffer)
+	}
 
 	copyMDtoC(&mqmd, gomd)
 	copyGMOtoC(&mqgmo, gogmo)
 
 	if bufflen > 0 {
+		// There has to be something in the buffer for CGO to be able to
+		// find its address. We know there's space backing the buffer so just
+		// set the first byte to something.
+		if useCap && len(buffer) == 0 {
+			buffer = append(buffer, 0)
+		}
 		ptr = (C.PMQVOID)(unsafe.Pointer(&buffer[0]))
 	} else {
 		ptr = nil
@@ -652,7 +693,7 @@ func (object MQObject) Get(gomd *MQMD,
 	}
 
 	if mqcc != C.MQCC_OK {
-		return 0, &mqreturn
+		return godatalen, &mqreturn
 	}
 
 	return godatalen, nil
@@ -724,14 +765,14 @@ func (object MQObject) Inq(goSelectors []int32, intAttrCount int, charAttrLen in
 */
 
 /*
- * Inq is the function to inquire on an attribute of an object
- *
- * This has a much simpler API than the original implementation.
- * 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
- */
+Inq is the function to inquire on an attribute of an object
+
+This has a much simpler API than the original implementation.
+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) Inq(goSelectors []int32) (map[int32]interface{}, error) {
 	var mqrc C.MQLONG
 	var mqcc C.MQLONG
@@ -841,18 +882,18 @@ func (object MQObject) Inq(goSelectors []int32) (map[int32]interface{}, error) {
 }
 
 /*
-* The InqMap function was the migration path when the original Inq was
-* deprecated. It is kept here as a tempoary wrapper to the new Inq() version.
- */
+The InqMap function was the migration path when the original Inq was
+deprecated. It is kept here as a temporary wrapper to the new Inq() version.
+*/
 func (object MQObject) InqMap(goSelectors []int32) (map[int32]interface{}, error) {
 	return object.Inq(goSelectors)
 }
 
 /*
- * Set is the function that wraps MQSET. The single parameter is a map whose
- * elements contain an MQIA/MQCA selector with either a string or an int32 for
- * the value.
- */
+Set is the function that wraps MQSET. The single parameter is a map whose
+elements contain an MQIA/MQCA selector with either a string or an int32 for
+the value.
+*/
 func (object MQObject) Set(goSelectors map[int32]interface{}) error {
 	var mqrc C.MQLONG
 	var mqcc C.MQLONG

ibmmq/mqicb.go

@@ -1,3 +1,5 @@
+package ibmmq
+
 /*
   Copyright (c) IBM Corporation 2018
 
@@ -20,7 +22,6 @@
 /*
 This file deals with asynchronous delivery of MQ messages via the MQCTL/MQCB verbs.
 */
-package ibmmq
 
 /*
 #include <stdlib.h>

ibmmq/mqicb_c.go

@@ -1,3 +1,5 @@
+package ibmmq
+
 /*
   Copyright (c) IBM Corporation 2018
 
@@ -16,7 +18,6 @@
    Contributors:
      Mark Taylor - Initial Contribution
 */
-package ibmmq
 
 /*
 #include <stdlib.h>

samples/amqsget.go

@@ -139,27 +139,64 @@ func mainWithRc() int {
 			msgAvail = false
 		}
 
-		// Create a buffer for the message data. This one is large enough
-		// for the messages put by the amqsput sample.
-		buffer := make([]byte, 1024)
-
-		// Now we can try to get the message
-		datalen, err = qObject.Get(getmqmd, gmo, buffer)
-
-		if err != nil {
-			msgAvail = false
-			fmt.Println(err)
-			mqret := err.(*ibmmq.MQReturn)
-			if mqret.MQRC == ibmmq.MQRC_NO_MSG_AVAILABLE {
-				// If there's no message available, then I won't treat that as a real error as
-				// it's an expected situation
-				err = nil
+		// There are now two forms of the Get verb.
+		// The original Get() takes
+		// a buffer and returns the length of the message. The user can then
+		// use a slice operation to extract just the relevant data.
+		//
+		// The new GetSlice() returns the message data pre-sliced as an extra
+		// return value.
+		//
+		// This boolean just determines which Get variation is demonstrated in the sample
+		useGetSlice := true
+		if useGetSlice {
+			// Create a buffer for the message data. This one is large enough
+			// for the messages put by the amqsput sample. Note that in this case
+			// the make() operation is just allocating space - len(buffer)==0 initially.
+			buffer := make([]byte, 0, 1024)
+
+			// Now we can try to get the message. This operation returns
+			// a buffer that can be used directly.
+			buffer, datalen, err = qObject.GetSlice(getmqmd, gmo, buffer)
+
+			if err != nil {
+				msgAvail = false
+				fmt.Println(err)
+				mqret := err.(*ibmmq.MQReturn)
+				if mqret.MQRC == ibmmq.MQRC_NO_MSG_AVAILABLE {
+					// If there's no message available, then I won't treat that as a real error as
+					// it's an expected situation
+					err = nil
+				}
+			} else {
+				// Assume the message is a printable string, which it will be
+				// if it's been created by the amqsput program
+				fmt.Printf("Got message of length %d: ", datalen)
+				fmt.Println(strings.TrimSpace(string(buffer)))
 			}
 		} else {
-			// Assume the message is a printable string, which it will be
-			// if it's been created by the amqsput program
-			fmt.Printf("Got message of length %d: ", datalen)
-			fmt.Println(strings.TrimSpace(string(buffer[:datalen])))
+			// Create a buffer for the message data. This one is large enough
+			// for the messages put by the amqsput sample.
+			buffer := make([]byte, 1024)
+
+			// Now we can try to get the message
+			datalen, err = qObject.Get(getmqmd, gmo, buffer)
+
+			if err != nil {
+				msgAvail = false
+				fmt.Println(err)
+				mqret := err.(*ibmmq.MQReturn)
+				if mqret.MQRC == ibmmq.MQRC_NO_MSG_AVAILABLE {
+					// If there's no message available, then I won't treat that as a real error as
+					// it's an expected situation
+					err = nil
+				}
+			} else {
+				// Assume the message is a printable string, which it will be
+				// if it's been created by the amqsput program
+				fmt.Printf("Got message of length %d: ", datalen)
+				fmt.Println(strings.TrimSpace(string(buffer[:datalen])))
+			}
 		}
 	}