{"id":441,"date":"2015-11-23T21:22:38","date_gmt":"2015-11-23T21:22:38","guid":{"rendered":"https:\/\/marketaylor.synology.me\/?p=441"},"modified":"2019-11-20T21:31:57","modified_gmt":"2019-11-20T21:31:57","slug":"mq-8-0-0-4-events-and-mqi-formatting","status":"publish","type":"post","link":"https:\/\/marketaylor.synology.me\/?p=441","title":{"rendered":"MQ 8.0.0.4 Events and MQI Formatting"},"content":{"rendered":"

This article is going to talk about some new code shipped with the V8.0.0.4 FixPack to make it easier to see what a queue manager is doing, simplify investigation of possible problems, and to assist with writing your own MQ applications. Formatting MQ Events is now available as part of the MQ product.<\/p>\n

To start with, we need to talk a little about MQ\u2019s event generation.<\/p>\n

<\/p>\n

Command and configuration events<\/h2>\n

One of the mechanisms used to monitor what is going on in MQ is to look at events that the queue manager emits. There are many different types, for example showing that a queue is full or that there has been a failure authorising some kind of access. A pair of events, the command and configuration events, can be used to get an audit trail of configuration changes. These events are written in a binary format known as PCF, and need some tool to transform them into a readable format.<\/p>\n

The command events describe who issued a command and what kind of command it was (MQSC or PCF); configuration events show what has changed. When taken together you can use them to get a history of administrative actions.<\/p>\n

However there were a couple of gaps in these events. In particular, changes to the security authorisations were not always recorded. Which is why, in V8.0.0.4, that has been sorted out. Now, whether you use the setmqaut<\/strong> command, the SET AUTHREC<\/strong> command in an MQSC session, or the equivalent PCF command for programmatic control, both command and configuration events get generated.<\/p>\n

For example,<\/p>\n

$ setmqaut -m V8004_A -t qmgr -p db2inst1 +connect\nThe setmqaut command completed successfully.\n<\/pre>\n
will generate events that can be formatted as<\/p>\n
**** Message #1 (324 Bytes) on Queue SYSTEM.ADMIN.COMMAND.EVENT ****\nEvent Type                       : Command Event\nReason                           : Command MQSC\nEvent created                    : 2015\/07\/07 10:26:47.82 GMT\nCorrelation Id                   : 414D5120563830335F41202020202CC001F03\nCOMMAND CONTEXT\nEvent User Id                : metaylor\nEvent Origin                 : Console\nEvent Queue Mgr              : V8004_A\nCommand                      : Set Auth Rec\nCOMMAND DATA\nAuth Profile Name            : self\nObject Type                  : Queue Mgr\nPrincipal Entity Names       : db2inst1\nAuth Add Auths               : Connect\n\n**** Message #2 (316 Bytes) on Queue SYSTEM.ADMIN.CONFIG.EVENT ****\nEvent Type                       : Config Event\nReason                           : Config Change Object\nObject state                     : Before Change\nCorrelation Id                   : 414D5120563830335F41202020202CC001F03\nEvent created                    : 2015\/07\/07 10:26:47.82 GMT\nEvent User Id                  : metaylor\nEvent Origin                   : Console\nEvent Queue Mgr                : V8004_A\nObject Type                    : Auth Rec\nAuth Profile Name              : self\nAuth Rec Type                  : Queue Mgr\nEntity Name                    : db2inst1\nEntity Type                    : Principal\nAuthorization List             : None\n\n**** Message #3 (316 Bytes) on Queue SYSTEM.ADMIN.CONFIG.EVENT ****\nEvent Type                       : Config Event\nReason                           : Config Change Object\nObject state                     : After Change\nCorrelation Id                   : 414D5120563830335F41202020202CC001F03\nEvent created                    : 2015\/07\/07 10:26:47.82 GMT\nEvent User Id                  : metaylor\nEvent Origin                   : Console\nEvent Queue Mgr                : V8004_A\nObject Type                    : Auth Rec\nAuth Profile Name              : self\nAuth Rec Type                  : Queue Mgr\nEntity Name                    : db2inst1\nEntity Type                    : Principal\nAuthorization List             : Connect\n<\/pre>\n
From this we can see that the userid dbinst1 previously had no authorisations to the queue manager, but is now allowed to connect.<\/p>\n
A sample event-handling program<\/h2>\n
Now that I\u2019ve shown what the new events are, I can get to the part that I particularly wanted to write about in this blog post – the processing of these events.<\/p>\n
In order to test that the queue manager was correctly generating these new command and configuration events, I needed a tool to format them. There have been many SupportPacs, and the KnowledgeCenter itself contains source code that you could copy and paste, but these were not able to handle some of the tasks I needed for the testing. So I started to write a program that could understand the new events, and display them in a way that proved they were being built properly inside the queue manager. Very quickly I realised that what started as a program specifically for testing could be turned into a sample program and shipped with the product. And so amqsevt<\/strong> was created, to sit alongside amqsmon<\/strong> and amqsact<\/strong> as a program and source code that takes MQ\u2019s PCF messages and turns them into something useful.<\/p>\n
Because MQ\u2019s events can be sent to several different queues, depending on which specific event it is, this sample gets messages from multiple queues. It makes use of the MQCB verb to simplify that job; rather than looping round all of the queues in turn, we can let MQCB call back into the program whenever a message appears on any of the queues of interest.
\nBeyond that, I think the most interesting thing about this sample is how it makes the contents of the events readable.<\/p>\n
Making the messages readable<\/h2>\n
The MQ API defines a lot of numbers that can be referenced in application programs, and these symbolic constants are often used to describe parameters of the API or attributes of objects. For example, MQBND_BIND_ON_GROUP is a definition whose value is 0. Programmers can refer to these constants by name, rather than worrying about the actual value. This makes program source code easy to understand. You can write if (reasonCode == MQRC_NOT_AUTHORIZED)\u2026<\/code> instead of if (reasonCode == 2035)\u2026<\/code>.<\/p>\n
But the opposite mapping, from a number to a meaningful name, is more problematic. With the event formatter, there needed to be a way to convert the integer that describes the default bind option for a queue into something that has a meaning. Otherwise, many events would just appear as lists of numbers which an administrator would have to decode by hand to see what was going on.<\/p>\n
There is a method for Java programs, MQConstants.<\/strong>lookup<\/em>()<\/strong>, which returns the symbolic names for a value. That could not be used from the C sample program. The solution chosen was to create lists of all of the symbolic names, and have functions that find the right string for a given value.<\/p>\n
A new header file, cmqstrc.h<\/em>, contains these functions. While an application developer still has to know which function to call to interpret a particular value (just as they have to know the correct filter in the Java lookup<\/em>() method), the hard work of managing the mappings has been done in the product.<\/p>\n
For all MQ developers<\/h2>\n
This new header file solves a problem that many application developers have, not just those working on event processing. It has been very common for developers to write their own version of a strerror-like function to handle MQ return codes in order to report failed API calls in a meaningful way. Now they can use the MQRC_STR function directly, and not need to keep their own similar tables updated. New versions of MQ will get new versions of these mapping functions; the maps are kept in step with all the other MQI definitions.
\nHere is an example of a few calls to the MQI mapping operations, showing how easy it is to make application output more readable.<\/p>\n
  printf(\"Error is %s\\n\",MQRC_STR(2035));\n  printf(\"Completion Code is %s\\n\",MQCC_STR(CompCode));\n  printf(\"%s is %s\\n\",\n  MQIA_STR(MQIA_PLATFORM),MQPL_STR(MQPL_UNIX));\n<\/pre>\n
will show<\/p>\n
  MQRC_NOT_AUTHORIZED\n  MQCC_OK\n  MQIA_PLATFORM is MQPL_UNIX\n<\/pre>\n
Conclusion<\/h2>\n
What began as a requirement primarily to help MQ administrators evolved into something that can also help application developers. I hope I\u2019ve shown how you can use the new sample program and header file to make your own programs easier to write and to use.<\/p>\n
This post was last updated on November 20th, 2019 at 09:31 pm<\/p>","protected":false},"excerpt":{"rendered":"
This article is going to talk about some new code shipped with the V8.0.0.4 FixPack to make it easier to see what a queue manager is doing, simplify investigation of possible problems, and to assist with writing your own MQ applications. Formatting MQ Events is now available as part of the MQ product. To start … Continue reading “MQ 8.0.0.4 Events and MQI Formatting”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[5],"tags":[54,41,35,20,40],"class_list":["post-441","post","type-post","status-publish","format-standard","hentry","category-mq","tag-application-development","tag-events","tag-ibmmq","tag-mqseries","tag-pcf"],"yoast_head":"\nMQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog<\/title>\n<meta name=\"description\" content=\"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/marketaylor.synology.me\/?p=441\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"MQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog\" \/>\n<meta property=\"og:description\" content=\"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/marketaylor.synology.me\/?p=441\" \/>\n<meta property=\"og:site_name\" content=\"Mark Taylor's Blog\" \/>\n<meta property=\"article:published_time\" content=\"2015-11-23T21:22:38+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2019-11-20T21:31:57+00:00\" \/>\n<meta name=\"author\" content=\"Mark\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@marketaylor\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Mark\" \/>\n\t<meta name=\"twitter:label2\" content=\"Estimated reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"6 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441\"},\"author\":{\"name\":\"Mark\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/#\\\/schema\\\/person\\\/2d6f4113ff54187023e20c20186bbb3c\"},\"headline\":\"MQ 8.0.0.4 Events and MQI Formatting\",\"datePublished\":\"2015-11-23T21:22:38+00:00\",\"dateModified\":\"2019-11-20T21:31:57+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441\"},\"wordCount\":984,\"commentCount\":0,\"keywords\":[\"application development\",\"events\",\"ibmmq\",\"mqseries\",\"pcf\"],\"articleSection\":[\"IBM MQ\"],\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441\",\"url\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441\",\"name\":\"MQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/#website\"},\"datePublished\":\"2015-11-23T21:22:38+00:00\",\"dateModified\":\"2019-11-20T21:31:57+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/#\\\/schema\\\/person\\\/2d6f4113ff54187023e20c20186bbb3c\"},\"description\":\"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/?p=441#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/marketaylor.synology.me\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"MQ 8.0.0.4 Events and MQI Formatting\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/#website\",\"url\":\"https:\\\/\\\/marketaylor.synology.me\\\/\",\"name\":\"Mark Taylor's Blog\",\"description\":\"Messaging, Music and Moving Around\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/marketaylor.synology.me\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/marketaylor.synology.me\\\/#\\\/schema\\\/person\\\/2d6f4113ff54187023e20c20186bbb3c\",\"name\":\"Mark\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g\",\"caption\":\"Mark\"},\"sameAs\":[\"https:\\\/\\\/x.com\\\/marketaylor\"],\"url\":\"https:\\\/\\\/marketaylor.synology.me\\\/?author=1\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"MQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog","description":"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/marketaylor.synology.me\/?p=441","og_locale":"en_GB","og_type":"article","og_title":"MQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog","og_description":"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.","og_url":"https:\/\/marketaylor.synology.me\/?p=441","og_site_name":"Mark Taylor's Blog","article_published_time":"2015-11-23T21:22:38+00:00","article_modified_time":"2019-11-20T21:31:57+00:00","author":"Mark","twitter_card":"summary_large_image","twitter_creator":"@marketaylor","twitter_misc":{"Written by":"Mark","Estimated reading time":"6 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/marketaylor.synology.me\/?p=441#article","isPartOf":{"@id":"https:\/\/marketaylor.synology.me\/?p=441"},"author":{"name":"Mark","@id":"https:\/\/marketaylor.synology.me\/#\/schema\/person\/2d6f4113ff54187023e20c20186bbb3c"},"headline":"MQ 8.0.0.4 Events and MQI Formatting","datePublished":"2015-11-23T21:22:38+00:00","dateModified":"2019-11-20T21:31:57+00:00","mainEntityOfPage":{"@id":"https:\/\/marketaylor.synology.me\/?p=441"},"wordCount":984,"commentCount":0,"keywords":["application development","events","ibmmq","mqseries","pcf"],"articleSection":["IBM MQ"],"inLanguage":"en-GB","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/marketaylor.synology.me\/?p=441#respond"]}]},{"@type":"WebPage","@id":"https:\/\/marketaylor.synology.me\/?p=441","url":"https:\/\/marketaylor.synology.me\/?p=441","name":"MQ 8.0.0.4 Events and MQI Formatting - Mark Taylor's Blog","isPartOf":{"@id":"https:\/\/marketaylor.synology.me\/#website"},"datePublished":"2015-11-23T21:22:38+00:00","dateModified":"2019-11-20T21:31:57+00:00","author":{"@id":"https:\/\/marketaylor.synology.me\/#\/schema\/person\/2d6f4113ff54187023e20c20186bbb3c"},"description":"A new tool amqsevt makes it easy to format IBM MQ event messages. You no longer need a separate monitoring tool to view these.","breadcrumb":{"@id":"https:\/\/marketaylor.synology.me\/?p=441#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/marketaylor.synology.me\/?p=441"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/marketaylor.synology.me\/?p=441#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/marketaylor.synology.me\/"},{"@type":"ListItem","position":2,"name":"MQ 8.0.0.4 Events and MQI Formatting"}]},{"@type":"WebSite","@id":"https:\/\/marketaylor.synology.me\/#website","url":"https:\/\/marketaylor.synology.me\/","name":"Mark Taylor's Blog","description":"Messaging, Music and Moving Around","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/marketaylor.synology.me\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"},{"@type":"Person","@id":"https:\/\/marketaylor.synology.me\/#\/schema\/person\/2d6f4113ff54187023e20c20186bbb3c","name":"Mark","image":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/secure.gravatar.com\/avatar\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/9a5ae091c43730194cba7cabb5d65c1dc3f48d05caaddec6ff2319a1ce66376f?s=96&d=mm&r=g","caption":"Mark"},"sameAs":["https:\/\/x.com\/marketaylor"],"url":"https:\/\/marketaylor.synology.me\/?author=1"}]}},"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/posts\/441","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=441"}],"version-history":[{"count":4,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/posts\/441\/revisions"}],"predecessor-version":[{"id":445,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=\/wp\/v2\/posts\/441\/revisions\/445"}],"wp:attachment":[{"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=441"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=441"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/marketaylor.synology.me\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=441"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}