Michigan iSeries Technical Education Conference

1

• Michigan iSeries Technical Education Conference
• MQ Series
• IBMs Middleware Solution
• Presented by
• Ryan Technology Resources
• Michael Ryan
• michael_at_ryantechnology.com

(C)opyright 2006 Michael Ryan
2
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

3
MQ Series

• Proper name is Websphere MQ
• Framework for communications
• Multiple levels
• Different operating systems
• Different hardware platforms
• Different communication protocols
• Ubiquitous connectivity

4
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

5
Access

• Programmatically accessed through Application
  Programming Interfaces (API)
• Same concept for each system
• Store and Forward
• Not unlike SNADS
• Guaranteed delivery
• Asynchronous communication

6
Components

• Four main components of MQ Series
• Queue manager
• Queues
• Channels
• Messages

7
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

8
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

9
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)

10
Queue Manager
11
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

12
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

13
MQ Configuration - WRKMQM
14
MQ Configuration - CRTMQM
15
MQ Configuration -CRTMQMCHL
16
MQ Configuration -CRTMQMQ
17
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.

18
MQ Programming

• Contrast MQ Series with sockets programming
• Amount of code needed for an MQ Series program is
  much less than a socket program
• Dont need to code for low-level handshaking
• Low-level error recovery is performed by MQ
• Dont need to connect or accept
• Just read and write to queues

19
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

20
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

21
MQ Programming - Model

• The general flow of events in an MQ Series
  application program is
• 1. Connect to a queue manager with MQCONN
• 2. Open the queues needed for communication with
  MQOPEN
• 3. Use MQPUT and MQGET to send and receive
  messages
• 4. Close the opened queues with MQCLOSE
• 5. Disconnect from the queue manager with MQDISC

22
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

23
MQ Programming - RPG

• Heres 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

24
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

25
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

26
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

27
MQ Programming - RPG

• Example of opening a queue
• Options are input-as-queue-def and
  fail-if-quiescing
• C 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 ltgt RCNone
  
• Error occurred...
  
• C EndIf
  

28
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

29
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

30
MQ Programming - RPG

• An example of MQPut
• MQGet follows the same pattern
• C 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 ltgt RCNone
• Error occurred...
• C EndIf

31
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

32
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 ltgt RCNone
  
• C If Reason ltgt RC2033
  
• Error occurred...
  
• C EndIf
  
• C Else
  
• process the data
• C EndIf

33
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 its 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.

34
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 ltgt RCNone
• Error occurred...
• C EndIf

35
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

36
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

37
MQ Programming - RPG

• Specify the handle from the MQConn call
• Check for an error

38
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 /

39
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

40
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/