WebSphere MQ Programming
Cincom MANTIS WebSphere MQ ProgrammingP39-1365-13Version 3.5.01 and 6.5.01
Cincom MANTIS WebSphere MQ ProgrammingPublication Number P39-1365-13 2001, 2004-2006, 2008, 2010, 2011, 2013, 2015, 2018, 2019 Cincom Systems, Inc.All Rights ReservedThis document contains unpublished, confidential, and proprietary information of Cincom. Nodisclosure or use of any portion of the contents of these materials may be made without the expresswritten consent of Cincom.See https://www.cincom.com/us/company/terms-policies for a list of Cincom trademarks and othertrademarks that may appear in Cincom product documentation.All other trademarks are trademarks or registered trademarks of their respective companies.Cincom Systems, Inc.55 Merchant StreetCincinnati, Ohio 45246-3732USAPHONE: 1 513 612 2300FAX: 1 513 612 2000WORLD WIDE WEB: http://www.cincom.comAttention:Some Cincom products, programs, or services referred to in this publication may not be available in allcountries in which Cincom does business. Additionally, some Cincom products, programs, or servicesmay not be available for all operating systems or all product releases. Contact your Cincomrepresentative to be certain the items are available to you.External Web site disclaimer:Cincom Systems, Inc. does not own, nor does it warrant the accuracy, adequacy or completeness of,the information and materials contained in linked documentation, and expressly disclaims liability forany errors or omissions in the information and materials. No warranty of any kind, implied, express orstatutory, including but not limited to the warranties of non-infringement of third party rights, title,merchantability, fitness for a particular purpose and freedom from computer virus, is given inconjunction with the information and materials contained in this linked documentation. Nothingcontained herein constitutes nor is intended to constitute an offer, inducement, promise, or contractof any kind. The data, information, and materials contained herein are for informational purposes onlyand are not represented to be error free. Any links are provided as a courtesy. They are not intendedto nor do they constitute an endorsement by Cincom Systems, Inc. of the linked materials.
Release information for this manualCincom MANTIS WebSphere MQ Programming, P39-1365-13, is dated June 1, 2019.This document supports release 3.5.01 and 6.5.01 of MANTIS .Cincom Technical Support for MANTIS To contact support, please visit https://supportWeb.cincom.com.
Contents1. Overview . 7Description of WebSphere MQ Programming . 8Development cycle figure . 8Using an Interface layout as a template for your Interface . 9Generalized Interface program . 10MQI and WebSphere MQ Programming . 11Reference materials . 12Internal Interfaces for MQSeries support . 132. Fundamental usage . 15Common fields in MQSeries Interface views . 163. Field naming conventions. 19Field prefixes. 20Adding another level of prefixing . 20Different kinds of fields, requiring different actions . 214. Errors . 22General error categories . 23Negative REASON codes . 245. Constants. 33Including MQ INIT in a user program . 34Categories of MQSeries constants in MQ INIT . 356. Building a MANTIS MQSeries application . 37Creating a program that reads a message queue . 38Creating a program that writes to a message queue. 39Initializing Interfaces that do not require special initialization . 40How to use the CLEAR statement to initialize an Interface . 40What the CLEAR statement does . 40Initializing Interfaces that require special initialization . 41Sample code for initializing an Interface that requires special initialization . 41Using the MQSeries Interface layouts . 42Using the MQBEGIN Interface to start a unit of work . 43Using the MQCOMMIT Interface to establish a sync point and commit all previous message GETsand PUTs . 44Using the MQCONNECT Interface to open and connect to an MQSeries object . 45Using the MQDISCONNECT Interface to close and disconnect from an MQSeries object .47Using the MQEXIT Interface to close all open handles . 48Using the MQGET Interface to read an MQSeries message . 49Using the MQPUT Interface to send an MQSeries message . 51WebSphere MQ Programming, P39-1365Contents4
Using the MQROLLBACK Interface to rollback to a previous sync point and reverse all previousmessage GETs and PUTs . 53Using the MQTM Interface to map the MQSeries trigger data to the MANTIS MQTM Interface. 547. MQSeries/MANTIS triggering . 57General MANTIS trigger considerations . 58Procedure for using MANTIS as a trigger handler . 58Programs that illustrate the trigger-handling process . 58Writing a MANTIS application program to handle the triggered event . 58Sample program for sending a message to a trigger queue . 59Sample program for handling an MQSeries trigger event . 59UNIX MQSeries/MANTIS trigger considerations . 60The trigger.sh script as a model for your trigger handler . 60Steps required for trigger handling . 60Procedure for constructing a trigger handler . 60MQSeries and MANTIS procedure for handling the triggered event . 60Mainframe MQSeries/MANTIS trigger considerations . 62The CSOXTRIG front-end application as a model for your trigger handler . 62Steps required for trigger handling . 62Procedure for constructing a trigger handler . 62MQSeries and MANTIS procedure for handling the triggered event . 628. MQSeries/MANTIS example programs . 65MQ INIT . 66MQ SAMPLE . 67Uses for MQ SAMPLE . 67Queue used for sending and receiving messages . 67UNIX screen shot of MQ SAMPLE . 67MQ SAMPLE’s errors for COMMIT and ROLLBACK functions under mainframe CICS . 67MQ HANDLER . 68Abilities necessary for any handler to possess . 68MEMADDR argument to MQ HANDLER . 68Running MQ HANDLER interactively vs. running it automatically . 68MQ TRIGGER . 69MQ TRIGGER . 69MQ TRIGGER sample output screen . 69GETERR(2033) . 699. MQSeries/MANTIS diagnostic considerations . 71Diagnosing a MANTIS program error . 72Dumping MQSeries Interface views . 73UNIX sample of a dumped MQCONNECT Interface . 73Procedure for dumping the failing Interface layout. 73System-specific dump file descriptions . 74Dump length . 74WebSphere MQ Programming, P39-1365Contents5
10. General UNIX and Mainframe considerations . 76MQSeries Client Configuration for UNIX MANTIS . 77Installation considerations . 78UNIX . 78Mainframe . 78MQCONNECT . 80UNIX . 80Mainframe . 80MQDISCONNECT . 82UNIX . 82Mainframe . 82MQGET . 83UNIX . 83Mainframe . 83MQPUT . 84UNIX . 84Mainframe . 84MQROLLBACK . 85UNIX . 85Mainframe . 85MQCOMMIT . 86UNIX . 86Mainframe . 86MQBEGIN . 87UNIX . 87Mainframe . 87MQEXIT . 88UNIX and Mainframe . 88MQTM . 89UNIX . 89Mainframe . 89Index . 90WebSphere MQ Programming, P39-1365Contents6
1. OverviewThis chapter provides a detailed description of MQSeries support, in order to help youdevelop a MANTIS application.WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Description of WebSphere MQ Programming7
Description of WebSphere MQ ProgrammingWebSphere MQ Programming is a MANTIS feature that adds support for IBM’s MQSeriesmessaging product. This feature enables MANTIS application programmers to sendMQSeries messages to, and receive MQSeries messages from, any local or remotemachine that supports MQSeries.Cincom has implemented WebSphere MQ Programming differently from other MANTISfacilities. It is implemented as the following: A set of Interfaces. These are stored under the MASTER user and serve astemplates.A generalized Interface program. This program is invoked when a MANTIS programCALLs one of the Interfaces.Development cycle figureBelow is a figure representing a typical development cycle that uses MANTIS and theMQSeries Interface:WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Description of WebSphere MQ Programming8
Using an Interface layout as a template for your InterfaceThe Interface layouts that (along with the generalized Interface program) make upWebSphere MQ Programming are templates for your Interfaces. To use an Interfacelayout as a template, perform the following:1. Use the Interface Design Facility Library Functions to fetch the appropriateInterface template.2. As appropriate for your application, customize the copy of the Interface layoutFor example, a possible change you can make is to add fields for user data at theend of the Interface layout.3. Use Library Functions to save the Interface template under a new name.WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Using an Interface layout as a template for your Interface9
Generalized Interface programThe major component of MQSeries support is a generalized Interface program. For allenvironments, the name of the “Program to be Called” is MANTISMQ. This name is thenprocessed as follows, according to operating system: Mainframe. Consider the following:- In CICS—The name MANTISMQ is translated internally to CSOXWMQS.- In BATCH—The name MANTISMQ is translated to a program called CSOXBMQS.UNIX. MANTISMQ is the entry point name, which is located in a shared librarycalled libmanmqs.so.Under both mainframe CICS and UNIX, this program performs the following:1. Processes the requests from the MANTIS application2. Makes the corresponding MQI calls to MQSeriesWebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Generalized Interface program10
MQI and WebSphere MQ ProgrammingCincom has modeled WebSphere MQ Programming after the standard MQSeries APIcalled “MQI.” Application programmers who are familiar with MQI in either the C orCOBOL programming languages will find this feature to be simple and easy to use.WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: MQI and WebSphere MQ Programming11
Reference materialsProgrammers who are not familiar with the MANTIS INTERFACE and MANTIS CALLstatements should refer to the following: For information on Interface design:- If you use OpenVMS or UNIX—MANTIS Facilities, P39-1301.- If you use z/OS or z/VSE—MANTIS Facilities for z/OS and z/VSE, P39-5301.For information on the CALL and INTERFACE statements:- If you use OpenVMS or UNIX—MANTIS Language, P39-1311.- If you use z/OS or z/VSE—MANTIS Language for z/OS and z/VSE, P39-5302.WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Reference materials12
Internal Interfaces for MQSeries supportMANTIS provides the following internal Interfaces for MQSeries support.These internal Interfaces are located on the MASTER user library.InterfaceDescriptionCommentsMQBEGINStarts a unit of work. Optional.Unix only.MQCOMMITEstablishes a sync point andends a unit of work. Optional.Unix and Mainframe Batchonly.MQCONNECTOpens an MQSeries objectand connects to it. This interface requiresspecial initialization,performed with the“INITCONN” function.Creates a handle that allother Interfaces use. MQDISCONNECTCloses an MQSeries objectand disconnects from it.MQEXITCloses all open handles. MQGETReads an MQSeries message. MQPUTSends an MQSeries message. WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Internal Interfaces for MQSeries supportOptional.This Interface does notcorrespond to anMQSeries function; thisInterface is an extraCincom feature.The user should performthe following:1. Modify the Interface.2. Save the Interface under adifferent name. This interface requiresspecial initialization,performed with the“INITGET” function.The user should performthe following:1. Modify the Interface.2. Save the Interface under adifferent name. This interface requiresspecial initialization,performed with the“INITPUT” function.13
InterfaceDescriptionCommentsMQROLLBACKReverse GETs and PUTs backto a prior sync point or a unitof work begin. Optional.Unix and Mainframe Batchonly.MQTMRetrieves the z/OS MQTMmessages or the UNIXMQTMC2 Trigger message. Optional.Unix and Mainframe CICSonly.WebSphere MQ Programming, P39-1365Chapter: 1. OverviewSection: Internal Interfaces for MQSeries support14
2. Fundamental usageThis chapter provides a detailed discussion of common fields in MQSeries Interfaceviews. All MQSeries Interface views start with the same common fields. Although theInterface type may prefix each of these fields, the order and meaning of the fieldsremains the same across all MQSeries Interface layouts.WebSphere MQ Programming, P39-1365Chapter: 2. Fundamental usageSection: Internal Interfaces for MQSeries support15
Common fields in MQSeries Interface viewsSee the following syntax definition:CALL mqinterface(function, handle, compcode, reason, ident, dmplength,dmpfilename )For explanations of the parameters in this syntax definition, see the rest of thischapter.functionDescriptionRequired. The desired operation request.Format3–8 character text expression.OptionsThe allowable function strings are: NN”“INITMQTM”*†* Unix† Mainframe CICSb Mainframe BatchConsideration An invalid function is a function that does not equal one of the strings listed above (forexample, NULL is an invalid function). If the function is invalid, MANTIS returns an errorin the REASON and COMPCODE fields.handleDescriptionRequired. The MQSeries handle that MQSeries sets and uses for subsequent MQI calls.FormatA MANTIS symbolic name, defined as a BIG.Consideration Retain this value for subsequent calls.compcodeWebSphere MQ Programming, P39-1365Chapter: 2. Fundamental usageSection: Common fields in MQSeries Interface views16
DescriptionRequired. The MQSeries compcode, where MQSeries sets a high-level completion codefor the prior CALL.FormatA MANTIS symbolic name, defined as a BIG.Consideration The MQSeries Interface sets this value to: 1. Successful.2. Warning.3. Error.General Considerations All Interfaces call the same entry point, which is named MQS ENTRY. TheFUNCTION field in each Interface points the MANTIS/MQSeries executable to theappropriate handler.Prior to making any Interface calls, set all information pertaining to the call in theInterface layout that includes the following:- HANDLE (usually)- FUNCTIONAfter the call completes, check the Interface symbolic name for an indication of awarning or error. If the Interface symbolic name returns a non-NULL value,interrogate the REASON field.You may connect to multiple MQSeries objects. When you do this, the calledInterface program generates multiple HANDLES (one HANDLE for each connection).You can disconnect from these handles by explicitly calling the MQDISCONNECTInterface that has the corresponding HANDLE and settings. Another disconnectionmethod is to call the MQEXIT routine, which disconnects the application from allconnected objects.For UNIX, to preserve data integrity, when MANTIS terminates (either normally orabnormally), MANTIS automatically calls the MQEXIT Interface as though theInterface was called by the user’s application.reasonDescriptionRequired. The MQSeries reason code that MQSeries sets. If a non-zero COMPCODE isreturned, the reason field further defines the problem.This field will contain the exact MQSeries reason code when an error occurs. For errorsdetected internally by the MQSeries Interface, a negative reason code will be returned.These codes will be further defined later in this documentation.FormatA MANTIS symbolic name, defined as a BIG.Consideration For a description of each reason code, refer to MQSERIES Application ProgrammingReference, SC33-1673.identDescriptionInternal. The Interface identification field.FormatA MANTIS symbolic name, defined as a BIG.Consideration This field is used internally to identify the Interface type and requires no usermodification.dmplengthDescriptionOptional. The length of the Interface layout to dump.FormatA MANTIS symbolic name, defined as a BIG.WebSphere MQ Programming, P39-1365Chapter: 2. Fundamental usageSection: Common fields in MQSeries Interface views17
Consideration For more information, see 9. MQSeries/MANTIS diagnostic considerations.dmpfilenameDescriptionOptional. Name of the dump file being generated.FormatA MANTIS symbolic name, defined as a TEXT for a length of 80 bytes.Consideration For more information, see 9. MQSeries/MANTIS diagnostic considerations.WebSphere MQ Programming, P39-1365Chapter: 2. Fundamental usageSection: Common fields in MQSeries Interface views18
3. Field naming conventionsWebSphere MQ Programming, P39-1365Chapter: 3. Field naming conventionsSection: Common fields in MQSeries Interface views19
Field prefixesFor most Interface layouts, many fields within the Interface layout have the sameprefix. For example, in the MQPUT Interface layout, many fields are prefixed with“MQMD ”. This prefix precedes the name of each field in the MQMD structure layout foran MQPUT MQI call to MQSeries.You will find many similarly named fields in MQSeries Interface layouts. To prevent theautomatic mapping feature of MANTIS from reusing these fields, all fields in allInterface layouts are prefixed to indicate in which Interface they are contained.For example, consider the MQPUT Interface layout. Since FUNCTION, HANDLE, REASON,COMPCODE, IDENT, DMPLENGTH, and DMPFILENAME can be found in all views, thesefields are all prefixed with PUT: PUT FUNCTIONPUT HANDLEPUT REASONPUT COMPCODEPUT IDENTPUT DMPLENGTHPUT DMPFILENAMEAdding another level of prefixingYou can add another level of prefixing in order to keep the functions separate. To doso, use PREFIX on the INTERFACE statement defining the Interface layout:10 INTERFACE QUEUE1("MQPUT1",PASSWORD,PREFIX)20 INTERFACE QUEUE2("MQPUT2",PASSWORD,PREFIX)30 QUEUE1 PUT FUNCTION "CONNECT"WebSphere MQ Programming, P39-1365Chapter: 3. Field naming conventionsSection: Field prefixes20
Different kinds of fields, requiring different actionsAlthough many fields exist in the MQGET and MQPUT Interface views, you need not setall of these fields prior to the Interface call. This is because fields that are sent toMQSeries from the MANTIS application are classified as one of the following: Inbound field. The MANTIS application programmer must fill in these fields.Outbound field. These fields return data to the MANTIS application. Theapplication may need to interrogate outbound fields.Inbound/Outbound field. These fields offer 2-way communication. In some cases,the MANTIS application programmer must fill in these fields. In other cases, theapplication may need to interrogate these fields.The function that is being performed dictates which fields in the Interface layout mustbe set or interrogated. To learn more about which fields must be set for a givenfunction, refer to MQSERIES Application Programming Reference, SC33-1673.WebSphere MQ Programming, P39-1365Chapter: 3. Field naming conventionsSection: Different kinds of fields, requiring different actions21
4. ErrorsAfter returning from any of the Interface calls, check the INTERFACE symbolic variablefor error conditions or warning conditions.WebSphere MQ Programming, P39-1365Chapter: 4. ErrorsSection: Different kinds of fields, requiring different actions22
General error categoriesThere are only 3 possible values that can be returned by any of the MQSeriesInterfaces, as described in the following table:Symbolicname lFunction successfullycompleted.None required.WARNINGAllA warning occurred duringthe MQSeries API call of theInterface routine.Compare the value of theREASON field to the REASON fieldvalue listed in MQSERIESApplication ProgrammingReference, SC33-1673.ERRORAllAn error occurred during theprocessing of the user’srequest. It could have beenan internal error or onegenerated by an MQSeriesAPI call.Review the value of the REASONfield in the view. If the value ispositive, compare the value tothe MQSERIES ApplicationProgramming Reference, SC331673. If the value is negative,compare the value to one of thepossible values listed below.WebSphere MQ Programming, P39-1365Chapter: 4. ErrorsSection: General error categories23
Negative REASON codesThese codes can be generated from any of the MQSeries Interface calls. They arerestricted to the internal workings of the MQSeries Interface and exclude any of thepossible error conditions returned by the MQSeries APIs.The following table lists each possible negative REASON value. The vast majority ofthese values should never be encountered but are listed here for completeness. Foreach possible error condition, the table lists the following: Name of Interface in which this error condition or warning condition occursSituation in which this error condition or warning condition occursRecommended response to this error condition or warning conditionFor information on positive REASON codes (those generated by the MQSeries API call), refer toMQSERIES Application Programming Reference, nded response-1AllAn error occurred duringinitial memory allocation.Note: This error should never occurbut is documented here for the sakeof completeness.Perform the nicalsupport.-2AllThe Interface layoutsupplied an invalid value inthe FUNCTION field.Correct the FUNCTION field so that itcontains one of the following values: BEGIN or MQBEGIN COMMIT or MQCMIT CONNECT or MQCONN DISCONN or MQDISC DUMP EXIT GET or MQGET INITCONN INITGET INITMQTM INITPUT PUT or MQPUT ROLLBACK or MQBACKWebSphere MQ Programming, P39-1365Chapter: 4. ErrorsSection: Negative REASON codes24
REASONvalue-3InterfacenameAllWebSphere MQ Programming, P39-1365Chapter: 4. ErrorsSection: Negative REASON codesSituationThe Interface layoutsupplied an invalid value ofZERO in the HANDLE field.Recommended responsePerform the following:Correct thevalue in theHANDLEfield so thatit matchesone of thevaluesreturned bytheMQCONNECTcall.Check thespelling oftheHANDLEvariable.Check tosee if youhaveassigned avalid handlevalue to theHANDLEvariable. Ifnot, assign avalidhandle.25
REASONvalueInterfacenameSituationRecommended response-4AllThe Interface layoutsupplied an invalidNONZERO value in theHANDLE field. This may bethe result of one of thefollowing: A handle wasclosed anddisconnected. The programmodified thevariable holdingthe handle. For MainframeCICS PseudoConversationalmode: A screenconverseoccurred inbetween anMQSeriesconnection andthe current useof this handle,causing the lossof theconnection.Correct the value in the HANDLE fieldso that it matches one of the valuesreturned by the MQCONNECT call.-5AllThe DUMP function failedbecause you did not set theinterface type to a validtype.Note: For the recomme
WebSphere MQ Programming, P39-1365 9 Chapter: 1. Overview Section: Using an Interface layout as a template for your Interface Using an Interface layout as a template for your Interface The Interface layouts that (along with the generalized Interface program) make up WebSphere MQ Programming are templates for your Interfaces. To use an Interface
In the three volumes of the IBM WebSphere Portal V4.1 Handbook, we cover WebSphere Portal Enable and Extend. The IBM WebSphere Portal V4.1 Handbook will help you to understand the WebSphere Portal architecture, how to install and configure WebSphere Portal, how to administer portal pages using WebSphere Portal; it will also discuss the
WebSphere 8. Welcome to the F5 Deployment Guide for IBM WebSphere. This document provides guidance for deploying the BIG-IP Local Traffic Manager (LTM) with IBM WebSphere 8. The BIG-IP system can optimize IBM WebSphere at many layers: in front of the IBM HTTP . Servers, between HTTP Servers and WebSphere Application Servers, or to eliminate .
Unit Objectives 2 This unit was designed to enable you to: Start a development project that implements WebSphere Commerce V7. Describe the Runtime architecture of WebSphere Commerce. Describe the development model for WebSphere Commerce. Explain the application of Struts in WebSphere Commerce. Describe the presentation layer for WebSphere Commerce by using both
Download and install WebSphere MQ 2. Configure WebSphere MQ 3. Install OEG Gateway . Oracle Enterprise Gateway 6 / 30 4. Configure Gateway to send messages to WebSphere MQ 5. Configure Gateway to listen for messages from WebSphere MQ queue 6. Test Setup 2. Setting up the WebSphere MQ environment
WebSphere Application Server WebSphere MQ Use the most appropriate protocol C .net Java C JMS COBOL Java Jacl JMS Jython Web-Sockets C# HTTP WebSphere Application Server is a fully compliant Java Enterprise Edition (JEE) application server. The Java Message Service (JMS) is the JEE application messaging protocol. WebSphere MQ provides a fully
Figure 2 WebSphere Manages the Middle Tier in a Three-Tier Model One of the WebSphere products, WebSphere Portal, manages a variety of enterprise applications and supports application development and delivery. In the Lean Retail WebSphere Solution, content development and document management functions of WebSphere Portal were tested.
IBM WebSphere Portal Version 5 Family Enable WebSphere Application Server IBM HTTP server WebSphere Portal Server Out-of-the-Box Portlets Collaboration Services API Portal Toolkit WebSphere Translation Server WebSphere Studio Site Developer Content Management Personalization Portal Document Manager
examples of WebSphere Application Server system configurations. v “Appendix. The library for WebSphere Application Server” on page 85 provides a complete list of the documentation available with WebSphere Application Server. Related information For further information on the topics and software discussed in this manual, see the following .
