MQCB/MQCTL and MQBEGIN complete the MQI implementation

Author: ibmmqmet

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## December 2018 - v3.3.0
+* All relevant API calls now automatically set FAIL_IF_QUIESCING
+* Samples updated to use "defer" instead of just suggesting it
+* Add support for MQCB/MQCTL callback functions
+* Add support for MQBEGIN transaction management
+
 ## November 2018 - v3.2.0
 * Added GetPlatform to mqmetric so it can be used as a label/tag in collectors
 * Added sample programs demonstrating specific operations such as put/get of message

README.md

@@ -123,12 +123,9 @@ At this point, you should have a compiled copy of the program in `$GOPATH/bin`.
 
 ## Limitations
 
-Almost all of the MQI verbs are now available through the `ibmmq` package.
-Currently unavailable verbs include:
+All regular MQI verbs are now available through the `ibmmq` package.
 
-* MQCB/MQCTL
-
-There are also no structure handlers for message headers such as MQRFH2 or MQDLH.
+There are no structure handlers for message headers such as MQRFH2 or MQDLH.
 
 ## History
 

ibmmq/mqi.go

@@ -51,6 +51,7 @@ package ibmmq
 #include <string.h>
 #include <cmqc.h>
 #include <cmqxc.h>
+
 */
 import "C"
 
@@ -219,6 +220,7 @@ func (x *MQQueueManager) Disc() error {
 	var mqrc C.MQLONG
 	var mqcc C.MQLONG
 
+	savedConn := x.hConn
 	C.MQDISC(&x.hConn, &mqcc, &mqrc)
 
 	mqreturn := MQReturn{MQCC: int32(mqcc),
@@ -230,6 +232,8 @@ func (x *MQQueueManager) Disc() error {
 		return &mqreturn
 	}
 
+	cbRemoveConnection(savedConn)
+
 	return nil
 }
 
@@ -248,7 +252,7 @@ func (x *MQQueueManager) Open(good *MQOD, goOpenOptions int32) (MQObject, error)
 	}
 
 	copyODtoC(&mqod, good)
-	mqOpenOptions = C.MQLONG(goOpenOptions)
+	mqOpenOptions = C.MQLONG(goOpenOptions) | C.MQOO_FAIL_IF_QUIESCING
 
 	C.MQOPEN(x.hConn,
 		(C.PMQVOID)(unsafe.Pointer(&mqod)),
@@ -288,6 +292,9 @@ func (object *MQObject) Close(goCloseOptions int32) error {
 
 	mqCloseOptions = C.MQLONG(goCloseOptions)
 
+	savedHConn := object.qMgr.hConn
+	savedHObj := object.hObj
+
 	C.MQCLOSE(object.qMgr.hConn, &object.hObj, mqCloseOptions, &mqcc, &mqrc)
 
 	mqreturn := MQReturn{MQCC: int32(mqcc),
@@ -299,6 +306,7 @@ func (object *MQObject) Close(goCloseOptions int32) error {
 		return &mqreturn
 	}
 
+	cbRemoveHandle(savedHConn, savedHObj)
 	return nil
 
 }
@@ -373,6 +381,33 @@ func (subObject *MQObject) Subrq(gosro *MQSRO, action int32) error {
 	return nil
 }
 
+/*
+Begin is the function to start a two-phase XA transaction coordinated by MQ
+*/
+func (x *MQQueueManager) Begin(gobo  *MQBO) error {
+	var mqrc C.MQLONG
+	var mqcc C.MQLONG
+	var mqbo C.MQBO
+
+	copyBOtoC(&mqbo, gobo)
+
+	C.MQBEGIN(x.hConn, (C.PMQVOID)(unsafe.Pointer(&mqbo)), &mqcc, &mqrc)
+
+	copyBOfromC(&mqbo, gobo)
+
+	mqreturn := MQReturn{MQCC: int32(mqcc),
+		MQRC: int32(mqrc),
+		verb: "MQBEGIN",
+	}
+
+	if mqcc != C.MQCC_OK {
+		return &mqreturn
+	}
+
+	return nil
+
+}
+
 /*
 Cmit is the function to commit an in-flight transaction
 */

ibmmq/mqiBO.go

@@ -0,0 +1,54 @@
+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 module contains the Begin Options structure
+*/
+
+type MQBO struct {
+	Options int32
+}
+
+func NewMQBO() *MQBO {
+	bo := new(MQBO)
+	bo.Options = int32(C.MQBO_NONE)
+	return bo
+}
+
+func copyBOtoC(mqbo *C.MQBO, gobo *MQBO) {
+	setMQIString((*C.char)(&mqbo.StrucId[0]), "BO  ", 4)
+	mqbo.Version = 1
+	mqbo.Options = C.MQLONG(gobo.Options)
+}
+
+func copyBOfromC(mqbo *C.MQBO, gobo *MQBO) {
+	gobo.Options = int32(mqbo.Options)
+	return
+}

ibmmq/mqiCBC.go

@@ -0,0 +1,78 @@
+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"
+
+/*
+MQCBC is a structure containing the MQ Callback Context
+The CompCode and Reason in the C structure are not included here. They
+are set in an independent MQReturn structure passed to the callback. Similarly
+for the hObj
+*/
+type MQCBC struct {
+	CallType       int32
+	CallbackArea   []byte // These byte arrays are saved/restored in parent function
+	ConnectionArea []byte
+	State          int32
+	DataLength     int32
+	BufferLength   int32
+	Flags          int32
+	ReconnectDelay int32
+}
+
+/*
+NewMQCBC creates a MQCBC structure. There are no default values
+as the structure is created within MQ.
+*/
+func NewMQCBC() *MQCBC {
+	cbc := new(MQCBC)
+	return cbc
+}
+
+/*
+Since we do not create the structure, there's no conversion for it into
+a C format
+*/
+func copyCBCtoC(mqcbc *C.MQCBC, gocbc *MQCBC) {
+	return
+}
+
+/*
+But we do need a conversion process from C
+*/
+func copyCBCfromC(mqcbc *C.MQCBC, gocbc *MQCBC) {
+	gocbc.CallType = int32(mqcbc.CallType)
+	gocbc.State = int32(mqcbc.State)
+	gocbc.DataLength = int32(mqcbc.DataLength)
+	gocbc.BufferLength = int32(mqcbc.BufferLength)
+	gocbc.Flags = int32(mqcbc.Flags)
+	gocbc.ReconnectDelay = int32(mqcbc.ReconnectDelay)
+	// ConnectionArea and CallbackArea are restored outside this function
+
+	return
+}

ibmmq/mqiCBD.go

@@ -0,0 +1,78 @@
+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"
+
+/*
+MQCBD is a structure containing the MQ Callback Descriptor
+*/
+type MQCBD struct {
+	CallbackType     int32
+	Options          int32
+	CallbackArea     []byte
+	CallbackFunction MQCB_FUNCTION
+	CallbackName     string
+	MaxMsgLength     int32
+}
+
+/*
+NewMQCBD fills in default values for the MQCBD structure
+*/
+func NewMQCBD() *MQCBD {
+	cbd := new(MQCBD)
+	cbd.CallbackType = C.MQCBT_MESSAGE_CONSUMER
+	cbd.Options = C.MQCBDO_NONE
+	cbd.CallbackArea = nil
+	cbd.CallbackFunction = nil
+	cbd.CallbackName = ""
+	cbd.MaxMsgLength = C.MQCBD_FULL_MSG_LENGTH
+
+	return cbd
+}
+
+func copyCBDtoC(mqcbd *C.MQCBD, gocbd *MQCBD) {
+
+	setMQIString((*C.char)(&mqcbd.StrucId[0]), "CBD ", 4)
+	mqcbd.Version = C.MQCBD_VERSION_1
+
+	mqcbd.CallbackType = C.MQLONG(gocbd.CallbackType)
+	mqcbd.Options = C.MQLONG(gocbd.Options) | C.MQCBDO_FAIL_IF_QUIESCING
+	// CallbackArea is always set to NULL here. The user's values are saved/restored elsewhere
+	mqcbd.CallbackArea = (C.MQPTR)(C.NULL)
+
+	setMQIString((*C.char)(&mqcbd.CallbackName[0]), gocbd.CallbackName, 128) // There's no MQI constant for the length
+
+	mqcbd.MaxMsgLength = C.MQLONG(gocbd.MaxMsgLength)
+
+	return
+}
+
+func copyCBDfromC(mqcbd *C.MQCBD, gocbd *MQCBD) {
+	// There are no modified output parameters
+	return
+}

ibmmq/mqiCTLO.go

@@ -0,0 +1,61 @@
+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"
+
+/*
+MQCTLO is a structure containing the MQ Control Options
+*/
+type MQCTLO struct {
+	ConnectionArea []byte
+	Options        int32
+}
+
+/*
+NewMQCTLO creates a MQCTLO structure.
+*/
+func NewMQCTLO() *MQCTLO {
+	ctlo := new(MQCTLO)
+	ctlo.Options = C.MQCTLO_NONE
+	ctlo.ConnectionArea = nil
+	return ctlo
+}
+
+func copyCTLOtoC(mqctlo *C.MQCTLO, goctlo *MQCTLO) {
+	setMQIString((*C.char)(&mqctlo.StrucId[0]), "CTLO", 4)
+	mqctlo.Version = C.MQCTLO_VERSION_1
+	mqctlo.Options = (C.MQLONG)(goctlo.Options) | C.MQCTLO_FAIL_IF_QUIESCING
+	// Always pass NULL to the C function as the real array is saved/restored in the Go layer
+	mqctlo.ConnectionArea = (C.MQPTR)(C.NULL)
+	return
+}
+
+func copyCTLOfromC(mqctlo *C.MQCTLO, goctlo *MQCTLO) {
+	// There are no output fields for this structure
+	return
+}

ibmmq/mqiMQGMO.go

@@ -80,7 +80,7 @@ func copyGMOtoC(mqgmo *C.MQGMO, gogmo *MQGMO) {
 
 	setMQIString((*C.char)(&mqgmo.StrucId[0]), "GMO ", 4)
 	mqgmo.Version = C.MQLONG(gogmo.Version)
-	mqgmo.Options = C.MQLONG(gogmo.Options)
+	mqgmo.Options = C.MQLONG(gogmo.Options) | C.MQGMO_FAIL_IF_QUIESCING
 	mqgmo.WaitInterval = C.MQLONG(gogmo.WaitInterval)
 	mqgmo.Signal1 = C.MQLONG(gogmo.Signal1)
 	mqgmo.Signal2 = C.MQLONG(gogmo.Signal2)