MQ Series for OS/390

INTRODUCTION TO MQ SERIES FOR OS/390MQ stands for Messaging and QueuingIt is a middleware that enables applications to communicate with one another irrespective of their operating system, processors, communication protocol. It allows applications to run independently of each other, at different speeds, different times, different locations, without having a logical connection between them. Messaging & QueuingTo pass data to another application, it can send a message rather than call the other application directlyMessages are placed on queues in storage and forwarded to the receiving application. The messages remain in the queue until the application is ready to process them.Messaging can be one-way or two-way (Request and Reply).When applications communicate across different platforms, the application programs are shielded from the networking complexities.

INTRODUCTION TO MQ SERIES FOR OS/390Message :A message is mainly a string of bytes to be sent from one program/application to anotherA message can take any one of the following types :Datagram A simple messageRequest A message for which a Reply is expectedReply A reply to a Request messageReport An event descriptor (For eg., delivery confirmation, error occurances)A message consists of:Message Descriptor: Contains the control information such as message type, unique identifier (24 byte string), priority. This is a fixed structure of 256 bytesMessage Application Data: Contains the actual data to be passed on to other applications.

INTRODUCTION TO MQ SERIES FOR OS/390Message :FIFOThe first message that is read out of a queue is normally the first message that was put into the queue. However, if the application program is looking for a particular message in the queue, an identifier can be passed while reading the queue. PersistencePersistent messages are logged or backed up so that they can be restored during system-restartNon-persistent messages are lost when the system goes down

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsQueue ManagerIs a system program that provides queuing services to application programsMessage queues reside in and are managed by the Queue Manager. The queue manager provides an Application Program Interface for the programs to acess the queues. The queue manager also provides administrative functions such as :Creating new queuesAltering properties of a queueControl operations of a queueINTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsQueue ManagerA program must be connected to a queue manager before it can start accessing the queues. If there are multiple queue managers connected to a system, the queue manager name must be provided during the connect MQ API call. If there is a single queue manager connected to a system, then the program automatically connects to it during the connect MQ API call. Batch environment can have multiple queue managers, while CICS applications can be connected only to a single queue manager.INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsMessage QueueA queue is the named storage destination to which a message can be sent to or received fromA queue is a container for the messagesMessages remain in these queues until they are retrieved by programs that process these queuesMessage queues physically reside on data setsA queue must have a unique name within a queue manager.Temporary or Permanent queues can be created dynamically through the application. Attributes of queues:Queue name, Queue type, description, Priority, Persistence, InhibitGet and InhibitPutINTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsMessage Queue - Types of queuesLocal and Remote Queues Local queues are message queues that reside in the local queue manager where the application resides. Remote queues are message queues that reside in queue managers other than the local queue manager.Shared Queues Is a local queue that can be accessed by other queue managers in a queue sharing groupModel Queues A template queue based on which you can create queues for your application, either dynamically or through the MQ Series control panelCluster Queues A Cluster is a network of logically associated queue managers. A cluster queue is managed by a cluster queue manager and is available to all queue managers within that cluster INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsProcessesEvent-driven processing can be achieved by defining a Process on a message queue. An application can be started based on an event, like a message arriving in a queue. For this purpose, the queue manager should be aware of the attributes of the application to be startedChannelsIs a communication link between queue managersA message channel is unidirectional and are used to transfer data from one queue manager to another. There should exist one Send Channel and one Receive Channel between two queue managers.An MQI channel is a bidirectional link to tranfer MQI calls between MQ Client and ServerINTRODUCTION TO MQ SERIES FOR OS/390

MQ Series ObjectsRules for defining MQ Series ObjectsUpper case and Lower case are differentNumbers can be usedOther characters such as . _ / % can be usedBlanks are not allowedQueue names can be upto 48 characters longChannels can be upto 20 characters longINTRODUCTION TO MQ SERIES FOR OS/390

MQ APIMQ Series provides a set of API calls with which the programmer can access the message queues. The available APIs are :Connect / Disconnect from a queue managerOpen Or Close a QueuePut message into a QueueRead or Browse messages from a QueueInquire and Set attributes of a QueuePerform Queue Commit and Rollback operationsAll APIs have the following returncodesCompcode :- Completion CodeMQCC_OK Successful CompletionMQCC_WARNING Partial CompletionMQCC_FAILED Error occurredReason : Reason for warning or FailureFor Eg., MQRC_HCONN_ERROR, MQRC_STORAGE_NOT_AVAILABLEApplication Programming using MQ Series

MQ APIA typical program will have the structure as shown below in the procedure division Putting messages into a Queue[ Connect Queue Manager ]Open Queue NamePut Queue Data into Queue Name Close Queue Name[ Disconnect Queue Manager ] Getting messages from a Queue[ Connect Queue Manager ]Open Queue NameGet Queue Data from Queue Name Close Queue Name[ Disconnect Queue Manager ]Application Programming using MQ Series

MQ APIPutting a single message into a Queue[ Connect Queue Manager ]Put1 Queue Data into Queue Name[ Disconnect Queue Manager ] Putting a request message and Getting a reply message[ Connect Queue Manager ]Open Queue NamePut Queue Data into Request Queue NameGet Queue Data from Reply Queue NameClose Queue Name[ Disconnect Queue Manager ]Application Programming using MQ Series

MQ APIMQ ConnectThe program can connect either to a specific queue manager or to the default queue manager. The queue manager should be local to the application.To connect to a specific queue manager, the name of the queue manager should be supplied. Whereas, for the default queue manager, the name of the queue manager should be blanks or nulls.For MVS Batch region, MQCONN call must be made to connect to the queue manager.For CICS region, it is not necessary to issue this call because the CICS system itself is connected to the default queue manager.Syntax Call MQCONN Using Qmanager (I) Q Manager name 48 bytes HConn (O) Connection Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ DisconnectThe MQDISC call must be issued to disconnect from the queue managerApplications running in CICS region need not issue this call.The field HConn represents the connection to the queue manager. The value in this field is returned to the application during the MQCONN call. This value must be used by the application in all the subsequent calls to MQ until the MQDISC call is issued.Syntax Call MQDISC Using HConn (I) Connection Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ OpenThe MQ Open command establishes access to a Message Queue for Put message, Get message, Inquiry, Set attributes.During the MQOpen call, the options for the action to be done with the message queue should be set.The MQOpen statement returns an Object Handle.Syntax For Put Action: Move MQOO-OUTPUT to MQOptions Move MQNAME to MQOD-OBJECTNAME Call MQOPEN Using HConn (I) Connection Handle ObjDesc (O) Object Descriptor MQOptions (I) Options for opening queue HObj (O) Object Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ CloseThe MQ Open call returns the Object Handle which must be used in all the subsequent calls to MQ for the Opened Queue, until the MQ Close call is issue.The MQ Close call releases the Object Handle so that the queue can no more be accessed. Syntax Call MQCLOSE Using HConn (I) Connection Handle MQOptions (I) Close options (Dynamic) HObj (I) Object Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ PutThe MQ Put call puts a message into the queue.The Queue should already be open in Output mode to put the message.This call can be issued repeatedly between the MQOPEN and MQCLOSE call. Syntax Call MQPUT Using HConn (I) Connection Handle HObj (I) Object Handle MsgDesc (I) Message Descriptor PMOptions (I) Put Message Options LenPutData (I) Length of data to be Put PutData (I) Data to be Put Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ Put1The MQ Put1 call puts ONE message into the queue. The queue need not be opened or closed for this purpose. Syntax Call MQPUT1 Using HConn (I) Connection Handle HObj (I) Object Handle MsgDesc (I) Message Descriptor PMOptions (I) Put Message Options LenPutData (I) Length of data to be Put PutData (I) Data to be Put Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ GetThe MQ Get call retrieves a message from the queueThe Queue should already be open in Input mode to Get the message.This call can be issued repeatedly between the MQOPEN and MQCLOSE call to retrieve all messages from the queueMQ Get with Read option will delete the message from the queue and with Browse option will retain the message in the queueSyntax Call MQGET Using HConn (I) Connection Handle HObj (I) Object Handle MsgDesc (I) Message Descriptor GMOptions (I) Get Message Options LenGetData (I) Length of data expected GetData (O) Data Structure to be read LenGetData (O) Length of data read Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ InqThe MQ Inq call returns the attributes of an MQ Object in the form of integers / charactersInquiry can be made on Queues, Processes, Queue managersThe Queue should already be open in Inquiry mode to get the attributes of a queue.Syntax Call MQINQ Using HConn (I) Connection Handle HObj (I) Object Handle SelCount (I) No. of Attr to be inquiredSelectors (I) Array of Attr to be inquired IntAttrCnt (I) No.of Integer Attributes IntAttr (O) Array of Integer Attributes CharAttrLen (I) No. of Char Attributes CharAttr (O) Array of Char Attributes Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ SetThe MQ Set call sets the attributes of an MQ ObjectAttribute setting can be made only on Queues.The Queue should already be open in Set mode to change the attributes of a queue.Syntax Call MQSET Using HConn (I) Connection Handle HObj (I) Object Handle SelCount (I) No. of Attr to be set Selectors (I) Array of Attr to be set IntAttrCnt (I) No.of Integer Attributes IntAttr (O) Array of Integer Attributes CharAttrLen (I) No. of Char Attributes CharAttr (O) Array of Char Attributes Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ CommitThe MQ Commit call commits the unit of work. All queue operations done since the beginning of the UOW or since the previous Commit, are committed.In case of triggered-events, the message is available to subsequent applications only when the Put operation has been committed. This call should be made only from batch programs. In CICS region, commit is achieved using EXEC CICS SYNCPOINT statement.Syntax Call MQCMIT Using Hconn (I) Connection Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ RollbackThe MQ Rollback calls rolls back the unit of work. All queue operations done since the beginning of the UOW or since the previous UOW are rolled back.All Put messages are deleted and all Get messages go back into the queue.This call should be made only from batch programs. In CICS region, rollback is achieved using EXEC CICS SYNCPOINT ROLLBACK statement.Syntax Call MQBACK Using Hconn (I) Connection Handle Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

MQ APIMQ BeginThe MQ Begin call is used to start a Unit-Of-Work.This call is used in order to isolate MQ from other resources such as DB2, CICS.MQCMIT or MQBACK call can follow the MQBEGIN call to commit or rollback the MQ actions.Syntax Call MQBEGIN Using HConn (I) Connection Handle BeginOption (I) Options Compcode (O) Completion Code Reason (O) Reason CodeApplication Programming using MQ Series

TriggersTriggers are used for Event-driven processingCertain events are recognized by the queue manager to indicate the occurance of trigger-event. A process definition is associated with every queue which requires triggering. This process definition contains information about the application to be started.The trigger-monitor application is the program which processes and monitors triggers.When a trigger-event occurs, the queue manager moves the message from the queue to another system queue called Initiation Queue.The trigger-monitor application reads the process-definition and takes care of starting the application which will read the message in the queue.Application Programming using MQ Series

TriggersEvery application to be triggered must have one Initiation queue.In case of triggered-events, the put-message application and get-message application are not part of the same unit-of-work,even if it is a Request-Reply situation.Triggering of application is possible only for CICS and IMS. Batch programs cannot be triggered through MQ directly.Trigger events can be enabled or disabled.When enabled, trigger-events can be of three types:First Every first message in the queue must trigger the applicationDepth This option is followed by an integer value; For eg., 10. When the queue is filled with 10 messages, the application should be triggerd.Every Every message that is put into the queue must trigger the application.Application Programming using MQ Series

TriggersThe MQTM (MQ Trigger Message) data structure is passed on to the started application. When a CICS Application is started, the EXEC CICS RETRIEVE INTO command will transfer the trigger message into the application.Following are some of the main fields to be set while defining a Process :While defining the queue :Set trigger-set as YSet trigger-type as F or E or D for First, Every or Depth Mention depth count in case of DProcess nameSet initiation queue name and process definition (the initiation queue is in-turn connected to a particular CICS region).While defining the process :Process name same as the one mentioned in the queue definitionApplication type valid values are : CICS, MVS, IMS, DEF (MVS)Application Id Transaction Id for CICSApplication Programming using MQ Series

ChannelA Channel is a communication link between distributed queue managers.Message channels are unidirectional and are used to transfer messages from one queue manager to another. The two queue managers could be in the same machine or different machine, same platform or different platform.Since the channels are unidirectional, there should be two channels between two queue managers.Failure in delivery of messages result in the message being put into a dead-letter-queueMessage Channel Agent (MCA) is the program which controls the flow of messages from one queue manager to another.Inorder to use these Channels, they need to be in the Active or Started stateEvery channel is linked to a transmission queue and a connection name. The connection is normally identified by an IP Address and a PortThe name of the channel should be the same at the sending and receiving end.Application Programming using MQ Series

Request & Reply QueuesWhen an application makes a request to another application & expects a reply from that application, Request and Reply Queues are usedThe requesting and responding applications could be in completely different platformWhen the requesting and responding applications are in the same platform and use the same queue manager, a pair of Request and Reply queues along with Trigger definitions is sufficientWhen the requesting and responding applications are in different platform or they are using different queue managers, then apart from the request and reply queues, remote queues and channels are also required.The requesting and responding applications are under different UOW. If the responding application fails to provide a reply within a specified amount of time, then the requesting application will encounter a time-out error. In this case the requesting application must issue a rollback.Several copies of the requesting and responding applications can run in parallel.Application Programming using MQ Series

Request & Reply QueuesThe fields MsgId and CorrelId are used by the queue manager and the application programs to correlate the reply with the requestsIt is the responsibility of the responding application to make sure that the reply message has the same MsgId and CorrelId as the request message.Example of Putting a message into Request queue and getting a reply. The following logic will remain same irrespective of different platforms and/or different queue managers Open MQ Req.Queue in Output Mode Open MQ Rep.Queue in Input Mode Move Req.Queue To MQOD-OBJECTNAME Move MQMT-REQUEST To MQMD-MSGTYPE Move Rep.Queue To MQMD-REPLYTOQ Call MQPUT Using.. Compute MQGMO-OPTIONS = MQGMO-WAIT Move To MQGMO-WAITINTERVAL Call MQGET Using.. Application Programming using MQ Series

One Way Communucation in the same region / queue managerApplication Programming using MQ Series

Two Way Communucation in the same region / queue managerApplication Programming using MQ Series

Two Way Communucation in different region / queue managerApplication Programming using MQ Series

Two Way Communucation in different region / queue managerApplication Programming using MQ Series

Coding Considerations for MainframeCopybooks to be used : Copybook ending with V contains the Value clause. Copybook ending with L does not contain any initial values. (For eg., CMQGMOV or CMQTML)CMQGMOx Get message optionsCMQPMOx Put message optionsCMQMDx Message DescriptorCMQODx Object DescriptorCMQTMx Trigger message structure All copybooks start with 10 level 01 MQ-GetMessageOptions. Copy CMQGMOL. Interface between application programs and MQ Series is provided by adapters. These adapters enable the applications to perform the MQI calls. For Batch applications must link-edit the adapter CSQBSTUB, while CICS applications must link-edit the adapter CSQCSTUB. Application Programming using MQ Series

Coding Considerations for MainframeFor execution of jobs, use procedure MQDB2BAT / MQDB2BLE or use the following load libraries in the Steplib:MQM.SYS.QMXX.UCSQPARMMQM.SYS.QMXX.SCSQAUTHMQM.SYS.QMXX.SCSQLOAD For CICS, no special steps are required because the system is already connected to MQ.Some programming tips for CICS :A message queue triggers a CICS application with transaction id TRN1 To differentiate between a triggered start of the application and manual start of the application, the CICS Startcode command can be used.The EXEC CICS ASSIGN STARTCODE command returns a 2 byte code which indicates how the application was started. SD : With Start Data, S : Without Start Data, TD : Terminal Input Application Programming using MQ Series

Limitations of MQ SeriesPreferrably use MQ Series when the mode of communicating with other applications is asynchronousPreferrably use MQ Series when the communication is one-way. Not a good idea to use MQ Series to communicate between a Web-based front end and mainframe backendNot possible to trigger batch jobs directly

Application Programming using MQ Series

MQ Series for OS/390Authors Name : Jyoti ManiEmail : jyoti.mani@gmail.com