Update for MQ 9.3.1

Author: ibmmqmet

CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 Newest updates are at the top of this file.
 
+## Oct 17 2022 - v5.3.2
+- Update for MQ 9.3.1
+- mqmetric - New metric channel_cur_inst. All instances of a given channel name have this aggregated value.
+             Done this way because the other labels for a channel object (eg jobname) make them unique so harder
+             to see how many exist with the same basic name
+- mqmetric - Add metrics for AMQP channels
+- mqmetric - Add cluster name as tag for queues (#191)
+- Rewrite README to better match recent compiler versions and module management
+- Update expected Go compiler version 
+
 ## Jul 23 2022 - v5.3.1
 - Fix #189 compile problem
 

Dockerfile

@@ -16,7 +16,7 @@ ARG BASE_IMAGE=ubuntu:18.04
 FROM $BASE_IMAGE
 
 ARG GOPATH_ARG="/go"
-ARG GOVERSION=1.13.15
+ARG GOVERSION=1.17      
 
 ENV GOVERSION=${GOVERSION}   \
     GOPATH=$GOPATH_ARG \
@@ -58,7 +58,7 @@ RUN mkdir -p $GOPATH/src $GOPATH/bin $GOPATH/pkg \
 # Location of the downloadable MQ client package \
 ENV RDURL="https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqdev/redist" \
     RDTAR="IBM-MQC-Redist-LinuxX64.tar.gz" \
-    VRMF=9.3.0.0
+    VRMF=9.3.1.0
 
 # Install the MQ client from the Redistributable package. This also contains the
 # header files we need to compile against. Setup the subset of the package

README.md

@@ -2,13 +2,10 @@
 
 This repository demonstrates how you can call IBM MQ from applications written in the Go language.
 
-This repository previously contained programs that exported MQ statistics to
-some monitoring packages. These have now been moved to a
-[GitHub repository called mq-metric-samples](https://github.com/ibm-messaging/mq-metric-samples).
+The repository originally also contained programs that exported MQ statistics to
+monitoring systems. These programs have been moved to a GitHub repository called [mq-metric-samples](https://github.com/ibm-messaging/mq-metric-samples).
 
-A minimum level of MQ V8 is required to build these packages. However, note that
-the monitoring data published by the queue manager and exploited in the mqmetric package
-is not available before MQ V9. A limited set of metrics can be monitored for MQ V8 instances by setting `ibmmq.usePublications=false`.
+A minimum level of MQ V8 is required to build these packages, although it should be possible to connect as a client to even older versions of queue manager.
 
 ## Health Warning
 
@@ -24,30 +21,31 @@ See the [DEPRECATIONS](DEPRECATIONS.md) file for any planned changes to the API.
 
 ## MQI Description
 
-The ibmmq directory contains a Go package, exposing an MQI-like interface.
+The `ibmmq` directory contains a Go package, exposing an MQI-like interface.
 
 The intention is to give an API that is more natural for Go programmers than the
 common procedural MQI. For example, fixed length string arrays from the C API such
 as MQCHAR48 are represented by the native Go string type. Conversion between these
-types is handled within the ibmmq package itself, removing the need for Go programmers
+types is handled within the `ibmmq` package itself, removing the need for Go programmers
 to know about it.
 
 Sample programs are provided to demonstrate various features of using the MQI. See the
-README in the `samples` directory for more information about those programs.
+README in the `samples` directory for more information about those programs. Detailed information about the MQI and application design can be found in the MQ product
+documentation. Although that doesn't mention Go as a language, the principles for all
+applications apply.
 
-The mqmetric directory contains functions to help monitoring programs access MQ status and
-statistics. This package is not needed for general application programs.
+The `mqmetric` directory contains functions to help monitoring programs access MQ status and statistics. This package is not needed for general application programs.
 
 ## Using the package
 
 To use code in this repository, you will need to be able to build Go applications, and
-have a copy of MQ installed to build against. It uses cgo to access the MQI C
+have a copy of MQ installed to build against. It uses `cgo` to access the MQI C
 structures and definitions. It assumes that MQ has been installed in the default
 location (on a Linux platform this would be `/opt/mqm`) but this can be changed
 with environment variables if necessary.
 
-Windows compatibility is also included. This has been tested with Go 1.10 compiler,
-which now permits standard Windows paths (eg including spaces) so the CGO directives
+Windows compatibility is also included. Current versions of the Go compiler
+permit standard Windows paths (eg including spaces) so the CGO directives
 can point at the normal MQ install path.
 
 ## Getting started
@@ -56,129 +54,105 @@ If you are unfamiliar with Go, the following steps can help create a working env
 with source code in a suitable tree. Initial setup tends to be platform-specific,
 but subsequent steps are independent of the platform.
 
-### Linux
-
-* Install the Go runtime and compiler. On Linux, the packaging may vary but a typical
-directory for the code is `/usr/lib/golang`. If you see an error similar to "ld: NULL not defined"
-when building a program then it is likely you need to upgrade your compiler.
-
-
-* Create a working directory. For example, ```mkdir $HOME/gowork```
-
-* Set environment variables. Based on the previous lines,
+### MQ Client SDK
+The MQ Client SDK for C programs is required in order to compile and run Go programs. You may have this from an MQ Client installation image (eg rpm, dep for Linux; msi for
+Windows). 
 
-```
-  export GOROOT=/usr/lib/golang
-  export GOPATH=$HOME/gowork
-```
+For Linux x64 and Windows systems, you may also choose to use the 
+MQ Redistributable Client package which is a simple zip/tar file that does not need
+any privileges to install:
 
-* On Linux, some versions of the compiler have required that you set environment variables to permit some compile/link flags. Recent versions of Go seem to effectively include this fix in the compiler so that the export is no longer necessary.
+* Download [IBM MQ redistributable client](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqdev/redist)
+* Unpack archive to fixed directory. E.g. `c:\IBM-MQC-Redist-Win64`  or `/opt/mqm`.
 
-```
-export CGO_LDFLAGS_ALLOW="-Wl,-rpath.*"
-```
+### Linux
 
-* Install the git client
+* Install the Go runtime and compiler. On Linux, the packaging may vary but a typical
+directory for the code is `/usr/lib/golang`. 
+* Create a working directory. For example, ```mkdir $HOME/gowork```
+* Install the git client and the gcc C compiler
 
 ### Windows
 
 * Install the Go runtime and compiler. On Windows, the common directory is `c:\Go`
-* Ensure you have a gcc-based compiler. The variant that now seems to be recommended for cgo is
+* Ensure you have a gcc-based compiler. The variant that seems to be recommended for cgo is
 the [tdm-gcc-64](https://jmeubank.github.io/tdm-gcc/download/) 64-bit compiler suite.
 The default `gcc` compiler from Cygwin does not work because it tries to build a
 Cygwin-enabled executable but the MQ libraries do not work in that model;
 the `mingw` versions build Windows-native programs.
 * Create a working directory. For example, `mkdir c:\Gowork`
-* Set environment variables. Based on the previous lines,
-
+* Set an environment variable for the compiler
 ```
-set GOROOT=c:\Go
-set GOPATH=c:\Gowork
 set CC=x86_64-w64-mingw32-gcc.exe
 ```
 
-* The `CGO_LDFLAGS_ALLOW` variable is not needed on Windows
-* Install the git client
-
-#### (Optional) Prepare without installed MQ Server or MQ Client
-
-* Download [IBM MQ redistributable client for Windows](https://www.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm%7EWebSphere&product=ibm/WebSphere/WebSphere+MQ&release=All&platform=All&function=fixId&fixids=*IBM-MQC-Redist-*&includeSupersedes=0)
-* Unpack archive to fixed directory. E.g. `c:\IBM-MQC-Redist-Win64`
-* Set environment variables (overrides vars in following section **Common**):
-```
-set CGO_CFLAGS=-Ic:\IBM-MQC-Redist-Win64\tools\c\include -D_WIN64
-set CGO_LDFLAGS=-L c:\IBM-MQC-Redist-Win64\bin64 -lmqm
-```
 ### Common
 
-* Make sure your PATH includes routes to the Go compiler (`$GOROOT/bin`), the Git client, and the C compiler.
-* Change directory to the workspace you created earlier. (`cd $GOPATH`)
+* Make sure your PATH includes routes to the Go compiler, the Git client, and the C compiler.
+* Change to the directory you created earlier.
 * Use git to get a copy of the MQ components into a new directory in the workspace.
 
-  `git clone https://github.com/ibm-messaging/mq-golang.git src/github.com/ibm-messaging/mq-golang`
+  `git clone git@github.com:ibm-messaging/mq-golang.git src/github.com/ibm-messaging/mq-golang`
 
 * If you have not installed MQ libraries into the default location, then set environment variables
-for the C compiler to recognise those directories. You may get messages from the compiler
+for the C compiler to recognise those directories. You may then get messages from the compiler
 saying that the default MQ directories cannot be found, but those warnings can be ignored.
 The exact values for these environment variables will vary by platform, but follow the
 corresponding CFLAGS/LDFLAGS values in `mqi.go`
 
-For example,
+For example, on Linux:
 
 ```
    export MQ_INSTALLATION_PATH=/my/mq/dir  # This will also be set from the setmqenv command
-
    export CGO_CFLAGS="-I$MQ_INSTALLATION_PATH/inc"
-
    export CGO_LDFLAGS="-L$MQ_INSTALLATION_PATH/lib64 -Wl,-rpath,$MQ_INSTALLATION_PATH/lib64"
 ```
 
-* Compile the `ibmmq` component:
-*
-  `go install ./src/github.com/ibm-messaging/mq-golang/ibmmq`
+Or on Windows:
 
-* If you plan to use monitoring functions, then compile the `mqmetric` component:
-
-  `go install ./src/github.com/ibm-messaging/mq-golang/mqmetric`
+```
+  set CGO_CFLAGS=-Ic:\IBM-MQC-Redist-Win64\tools\c\include -D_WIN64
+  set CGO_LDFLAGS=-L c:\IBM-MQC-Redist-Win64\bin64 -lmqm
+```
 
-* Sample programs can be compiled in this way
+* Sample programs can be compiled directly:
 
-  `go build -o bin/mqitest ./src/github.com/ibm-messaging/mq-golang/samples/mqitest/*.go`
+ ```
+ cd src/github.com/ibm-messaging/mq-golang/samples
+ go build -o /tmp/mqitest mqitest/*.go
+ ```
 
-At this point, you should have a compiled copy of the program in `$GOPATH/bin`. See the
+At this point, you should have a compiled copy of the program in `/tmp`. See the
 `samples` directory for more sample programs.
 
-### Build errors
-If you get errors such as `cannot find package v5/ibmmq` then one solution is to go to
-the repository directory itself: `cd ./src/github.com/ibm-messaging/mq-golang`. And
-then compile directly from that directory: `go install ./ibmmq`, `go install ./samples/amqsput.go`.
-
-An alternative is to set GOPATH to the directory you have tried to compile
-from: `export GOPATH=$HOME/gowork`.
 
 ## Building in a container
 The `buildSamples.sh` script in this directory can also be used to create a container which will
-compile the samples and copy them to a local directory. If you use this approach, you do not need
-to install a local copy of the compiler and associated toold, though you will still need a copy of
-the MQ runtime libraries for wherever you execute the programs.
+install the MQ Client SDK, compile the samples and copy them to a local directory. If you use this approach, you do not need
+to install a local copy of the compiler and associated tools, though you will still need a copy of
+the MQ C client runtime libraries for wherever you execute the programs.
 
 ## Go Modules
-The packages in this repository are now set up to be used as Go modules. See the `go.mod` file in
-the root of the repository. This required a major version bump in the release stream.
+The packages in this repository are set up to be used as Go modules. See the `go.mod` file in
+the root of the repository.
 
 Support for modules started to be introduced around Go 1.11 and has been firmed up in various
-modification level updates in each of the compiler levels since then. The module changes for this
-package were developed and tested with Go 1.13.6.
+modification level updates in each of the compiler levels since then. It is now recommended to 
+use at least version 1.17 of the compiler.
+
+Use of modules means that packages do not need to be independently compiled or
+installed. Environment variables such as `GOROOT` and `GOPATH` that were previously required are
+now redundant in module mode.
 
 To use the MQ module in your application, your `go.mod` file contains
 
 ```
   require (
-    github.com/ibm-messaging/mq-golang/v5 v5.0.0
+    github.com/ibm-messaging/mq-golang/v5 v5.x.y
   )
 ```
 
-and your application code will include
+and your application code includes
 
 ```
   import ibmmq "github.com/ibm-messaging/mq-golang/v5/ibmmq"
@@ -192,6 +166,7 @@ of these packages. For example, you can continue to use `dep` with `Gopkg.toml`
   name = "github.com/ibm-messaging/mq-golang"
   version = "4.1.4"
 ```
+Those older versions are not maintained, so it is strongly recommended you do move to using modules.
 
 ## Related Projects
 
@@ -209,15 +184,15 @@ let me know, via an issue, if you have another project that might be suitable fo
 ## Limitations
 
 ### Package 'ibmmq'
-All regular MQI verbs are now available through the `ibmmq` package.
-
-The only unimplemented area of MQI function is the use of Distribution Lists: they were
+* All regular MQI verbs are available through the `ibmmq` package.
+* The only unimplemented area of MQI function is the use of Distribution Lists: they were
 rarely used, and the Publish/Subscribe operations provide similar capability.
+* Go is not supported for writing MQ Exits, so structures and methods for those features
+are not included.
 
 ### Package 'mqmetric'
-* There is currently a queue manager limitation which does not permit resource publications to
-be made about queues whose name includes '/'. Attempting to monitor such a queue will result in a warning
-logged by the mqmetric package.
+* The monitoring data published by the queue manager and exploited in the mqmetric package is not available before MQ V9. A limited set of metrics can be monitored for MQ V8 instances by setting the `ConnectionConfig.UsePublications` configuration option to `false`.
+* There is currently a queue manager limitation which does not permit resource publications to be made about queues whose name includes '/'. Attempting to monitor such a queue will result in a warning logged by the mqmetric package.
 
 ## History
 
@@ -238,4 +213,4 @@ in the CLA.
 
 ## Copyright
 
-© Copyright IBM Corporation 2016, 2021
+© Copyright IBM Corporation 2016, 2022

buildInDocker.sh

@@ -30,24 +30,29 @@ cd $GOPATH/src
 echo "Using compiler:"
 go version
 
+# No longer need to explicitly build packages as
+# modules manage the download/installation. And the latest 
+# compilers have the original version of commands as 
+# errors. So we comment out that phase.
 for pkg in $ORG/$REPO/ibmmq $ORG/$REPO/mqmetric
 do
   lib=`basename $pkg`
-  echo "Building package: $lib"
-  go install  $pkg
+  : echo "Building package: $lib"
+  : go install  $pkg
 done
 
-# And do the sample program builds into the bin directory
+# Do the sample program builds into the bin directory
 cd $GOPATH
 srcdir=src/$ORG/$REPO/samples
 
-for samp in $srcdir/*.go
+cd $srcdir
+for samp in *.go
 do
   exe=`basename $samp .go`
   echo "Building program: $exe"
-  go build -o bin/$exe $samp
+  go build -o $GOPATH/bin/$exe $samp
 done
 
 echo "Building program: mqitest"
-go build -o bin/mqitest $srcdir/mqitest/mqitest.go
+go build -o $GOPATH/bin/mqitest mqitest/mqitest.go
 

go.mod

@@ -1,3 +1,3 @@
 module github.com/ibm-messaging/mq-golang/v5
 
-go 1.13
+go 1.16