Michigan iSeries Technical Education Conference

MQ SeriesIBM’s Middleware

Solution

Presented by

Ryan Technology Resources

Michael Ryan

michael@ryantechnology.com

(C)opyright 2006(C)opyright 2006Michael RyanMichael Ryan

What is Middleware?• Middleware is software that

manages several parts of a connection between systems• Physical and logical communications

• Data translation

• Error recovery

• Message sequencing

MQ Series

‘Proper name’ is Websphere MQ Framework for communications

Multiple levels Different operating systems Different hardware platforms Different communication protocols

Ubiquitous connectivity

Multiple Platforms AIX Compaq NSK DOS DYNIX/ptx HP-UX Linux MacOS MVS/ESA NUMA-Q OpenVMS Alpha OpenVMS VAX

OS/2 OS/390 OS/400 Sun Solaris UNIX Unisys 2200 Series Unisys A Series VM/ESA VSE/ESA Windows Java

Access

Programmatically accessed through Application Programming Interfaces (API) Same concept for each system

‘Store and Forward’ Not unlike SNADS Guaranteed delivery

Asynchronous communication

Components

Four main components of MQ Series Queue manager Queues Channels Messages

Messages The data being sent between applications

Has meaning to the application – no particular meaning to MQ Series

Two parts – the application data and a message descriptor Application data is what the applications are sending

and receiving with each other Message descriptor is something that is not seen by

the application programmer. It contains information such as the from and to queue names, the priority, levels of MQ Series, security information and so on

Queues Message repository - sent to or received from Not unlike data queues (*DTAQ)

Use APIs to access MQ Series data queues Independent of the application

Characteristics Put-enabled (messages can be placed on the queue) Get enabled (messages may be retrieved from the

queue) Queue depth Queue size

Queue Manager Responsible for queues Every queue belongs to a queue manager,

whether the queue is local or remote A local queue managed by a local queue manager –

a queue manager on the same system as a queue A remote queue is manager by a remote queue

manager – a queue manager on a different system A local application puts messages on a remote

queue (which is a local queue to the remote system) and the remote application puts messages on a local queue (which is remote to the local application)

Queue Manager

Local System Remote System

Remote Queue Local Queue

Local QueueRemote Queue

Managed by remote system queue manager

Managed by local system queue manager

Channels Link between the actual communications and

the MQ Series queue managers Type of communications (TCP/IP or SNA) Two types – message channels and client channels

• A message channel is used for server-to-server communication

• Unidirectional

• Two channels - a sending channel and a receiving channel

• A client channel connects a client to a server• Bi-directional

• Queues exist on the server – there are no client queues

MQ Configuration Use RSTLICPGM

5733-A38 Developed in Hurlsley, supported from Raleigh

(Software Group) Loads

QMQM library Objects in the IFS User profiles QMQM and QMQMADM

Read the instructions…

MQ Configuration - WRKMQM

MQ Configuration - CRTMQM

MQ Configuration -CRTMQMCHL

MQ Configuration -CRTMQMQ

MQ Programming The programming model for MQ Series

applications is similar to any communications program One system (usually the client) sends a message (a

request for services) to the other system (usually the server)

The server then replies with the information desired by the client. This process continues until the client or the server desire to end the communication.

MQ Programming

Contrast MQ Series with sockets programming Amount of code needed for an MQ Series

program is much less than a socket program• Don’t need to code for ‘low-level’ handshaking• Low-level error recovery is performed by MQ

Don’t need to ‘connect’ or ‘accept’• Just read and write to queues

MQ Programming - APIs Application Programming Interface

• Relatively few APIs• Most commonly used

MQCONN – Connect to a Queue Manager MQDISC – Disconnect from a Queue Manager MQOPEN – Open an MQ object (Queue) MQCLOSE – Close an MQ object (Queue) MQPUT – Put a message to an MQ Queue MQGET – Get a message from an MQ Queue

MQ Programming - APIs Other APIs are available but usually not needed

MQINQ – Inquire about an MQ object (Queue, Queue Manager, Channel…)

MQSET – Set some of the attributes of a Queue MQBEGIN – Begin a Unit of Work in a Commitment

Control environment MQCMIT – Commit a Unit of Work in a Commitment

Control environment MQBACK - Rollback a Unit of Work in a Commitment

Control environment

MQ Programming - Model The general flow of events in an MQ Series

application program is:

1.Connect to a queue manager with MQCONN2.Open the queues needed for communication with

MQOPEN3.Use MQPUT and MQGET to send and receive

messages4.Close the opened queues with MQCLOSE5.Disconnect from the queue manager with MQDISC

MQ Programming - RPG MQ Series applications usually follow the model Using MQ Series in an RPG application is

simple Procedures called by the APIs are in service

program QMQM/LIBMQM Ensure this service program is bound by reference

with your RPG program

The data structures and prototype definitions can be found in library QMQM

MQ Programming - RPG Here’s an example of /INCLUDEs I use in my

MQ Series programs: * MQI Named Constants /COPY QMQM/QRPGLESRC,CMQG * Object Descriptor D MQOD DS /COPY QMQM/QRPGLESRC,CMQODG * Message Descriptor D MQMD DS /COPY QMQM/QRPGLESRC,CMQMDG * Get Message Options D MQGMO DS /COPY QMQM/QRPGLESRC,CMQGMOG * Put message options D MQPMO DS /COPY QMQM/QRPGLESRC,CMQPMOG

MQ Programming - RPG

These includes will copy in Named constants Object descriptor information Message descriptor information Put and get option information

Review these include files to identify the field names and prototyped names you will use in your program

MQ Programming - RPG Example of connecting to a queue manager:

* Connect to MQ Series queue manager.

C CallP MQConn(QMName :

C HConn :

C OCode :

C Reason)

C If OCode = CCFail

* Error occurred...

C EndIf

MQ Programming - RPG QMName contains the name of the queue manager HConn is returned from the API call

Contains the ‘handle’ that will be used in later calls The handle identifies the specific queue manager and is used

internally by MQ Series OCode and Reason are returned by the API call and

identify if an error occurred Note: I check OCode to see if it is equal to the named constant

CCFail – if so, an error occurred Appropriate error recovery code goes here

This call completes the first step in the MQ Series application flow – connecting to the queue manager

MQ Programming - RPG Example of opening a queue: * Options are input-as-queue-def and fail-if-quiescingC Eval Opts = OOInpq + OOFIQ C Eval ODon = ReplyQue C CallP MQOpen(HConn : C MQOD : C Opts : C HInObj : C OCode : C Reason) C If Reason <> RCNone * Error occurred... C EndIf

MQ Programming - RPG Variable Opts is set to special named constant

values OOInpq and OOFIQ Open the queue as input Fail if quiescing

Variable ODon has the value of ReplyQue Contains the name of a queue Association already established between the queue

manager and the queue during creation HConn is the queue manager handle

Obtained from the MQConn call

MQ Programming - RPG MQOD variable specified in the MQOpen call is a

data structure. ODon is one of the many subfields in the data

structure HinObj is returned from the API call and contains

the handle for the opened queue Used for puts and gets

OCode and Reason are returned from the API call and indicate an error If Reason does not contain the value in named

constant RCNone, an error has occurred

MQ Programming - RPG An example of MQPut:

MQGet follows the same patternC Eval MdFmt = FmStr C Eval MDRQ = ReplyQue C Eval MDRM = QMName C CallP MQPut(HConn : C HOutObj : C MQMd : C MQPmo : C BufLen : C BufPtr : C CCode : C Reason) C If Reason <> RCNone * Error occurred... C EndIf

MQ Programming - RPG Note the MQ* variables

These are subfields in data structure MQMD and MQPMO

Set these variables to specific values that are determined by the needs of the application BufLen contains the length of the buffer of

information that we are sending BufPtr is a variable of type pointer that contains the

address of the buffer of information As before, we interrogate the Reason to determine if

an error has occurred

MQ Programming - RPG An example of MQGet:C CallP MQGet(HConn : C HInObj : C MQMd : C MQGmo : C BufLen : C BufPtr : C MsgLen : C CCode : C Reason) * Note: Reason should be 0 (RCNone). If return code = 2033 (RC2033), * no messages are available. C If Reason <> RCNone C If Reason <> RC2033 * Error occurred... C EndIf C Else * process the data…C EndIf

MQ Programming - RPG Note the MQ* variables

Contain the specific values that are used by the MQGet call to control its operation and are subfields in the MQMD and MQGMO data structures

BufLen is the length of the receive buffer BufPtr is a pointer to the buffer MsgLen is the number of bytes returned from the MQGet call Lookingfor a specific Reason code and not signaling an error if

it’s encountered• A 2033 Reason code (in named constant RC2033) indicates that

an MQGet was performed and no data was available to be read• This is certainly possible – the other system may have no data to

send at that time.

MQ Programming - RPG An example of MQClose: * Close input MQ Series connection.

C Eval Opts = CONone

C CallP MQClose(HConn :

C HInObj :

C Opts :

C CCode :

C Reason)

C If Reason <> RCNone

* Error occurred...

C EndIf

MQ Programming - RPG

Queue manager handle HConn – specified in the MQConn call

Queue handle HinObj – specified in the MQOpen call

An options field Check the returned Reason to see if an

error occurred

MQ Programming - RPG An example of MQDisc: * Disconnect from MQ Series Queue Manager.C CallP MQDisc(HConn :

C OCode :

C Reason)

* Report reason and stop if failed.

C If OCode = CCFail

* Error occurred...

C EndIf

MQ Programming - RPG

Specify the handle from the MQConn call Check for an error

MQ Programming - C

An MQOpen Example in C:

O_options = MQOO_INPUT_AS_Q_DEF /* open queue for input */

+ MQOO_FAIL_IF_QUIESCING; /* but not if stopping */

MQOPEN(Hcon, /* connection handle */

od, /* object descriptor for queue */

O_options, /* open options */

&HInobj, /* object handle */

&InOpenCode, /* completion code */

&Reason); /* reason code */

MQ Series MQ Series (or the WebSphere MQ Family)

Very strong and robust solution to middleware problems

Reliable Flexible Easy to configure Easy to program

Excellent choice for connectivity and system integration issues

Getting More Information

• IBM Websphere MQ Site

• http://www-306.ibm.com/software/integration/wmq/

• AS/400 Red Books• MQSeries Version 5.1 Administration and Programming

Examples

• http://www.redbooks.ibm.com/redbooks/SG245849.html

• Great forum for MQ stuff

• http://www.mqseries.net/