MQ Summay

Overview
Summer, 2013,University Training Program

Unit objectives
After completing this unit, you should be able to:
Describe the message and queuing paradigm in detail
List the major calls used in the MQI
2
Messaging
Conversational
Call and Return
Program A
Program A Program B
Program A
Program B
Program C
Program A
call Program B
Program B
Return to
Program A
Three styles of communication
3
Business logic
Messaging and
queuing
Communication
logic
Business logic
Value
Burden
Network
MQI
Network
Value
Burden
relief
Communication and business Business
Shielding developers
4
PROGRAM PROGRAM
PROGRAM PROGRAM
WRITE
READ
MQPUT
MQGET
File or database table
Records or rows
Queue
Messages
Queues, messages, files, and records
5
Assured delivery
Queue storage
Data conversion
Administration
Recovery
Syncpoint control
Comms
Client code
IBM WebSphere MQ
application
Client system
Comms
Server code
IBM WebSphere MQ
queue manager
Server system
MQI call qmgr response
IBM WebSphere MQ clients
6
Application
IBM WebSphere MQ queue manager
MQI
Base classes for Java
Provider classes
JMS
.NET
classes
C++
binding
IBM WebSphere MQ APIs
7
Some languages are supported on several platforms; some, such
as Assembler and RPG, on only one (OS/390 and AS/400,
respectively).
Supported programming languages
C
COBOL
C++
C#
Java
PL/I
Assembler
RPG
TAL
Visual Basic
8
Message Queue Interface (MQI) calls
The MQI is a simple CALL interface; no new language skills are
required.
Table header
Major calls
frequently used
Major calls less
frequently used
New calls for MQv7 New calls for MQv7
MQCONN MQINQ MQBUFMH MQINQMP
MQOPEN MQSET MQCB MQMHBUF
MQPUT MQCONNX MQCB_FUNCTION MQSETMP
MQGET MQBEGIN MQCRTMH MQSTAT
MQCLOSE MQCMIT MQCTL MQSUB
MQPUT1 MQBACK MQDLTMH MQSUBRQ
MQDISC MQDLTMP
Summer, 2013,University Training Program 9
Message = message properties + application data
Message Descriptor (MQMD)
- MsgId
- Priority
- Reply to queue
- Expiration period
-
Your message
- Customer
- Project
- Order number
- Due date
-
Custom Message Properties
Message properties Application data
Message
Message properties Application data
Message descriptor Custom message properties
These attributes are set
by application and queue
manager. Some MQMD
fields below:
These attributes are created
and the values are set by the
application. Some possible
property fields below:
Any sequence of bytes.
Private to the sending and
receiving programs
Not meaningful to the
queue manager
Msgld
Priority
Reply to queue
Expiration period
Customer
Project
Order number
Due date
Your message
10
Structures frequently used in the MQI
The Message Descriptor (MQMD) - describes the header
which accompanies each message.
The Object Descriptor (MQOD) - used by MQOPEN and
MQPUT1 to identify the object, usually a queue, being opened.
Get Message Options (MQGMO) - used by the programmer to
specify options on an MQGET.
Put Message Options (MQPMO) - used by the programmer to
specify options on an MQPUT.
11
With initial values Without initial values
Message Descriptor CMQMDV CMQMDL
Object Descriptor CMQODV CMQODL
Get Message Options CMQGMOV CMQGMOL
Put Message Options CMQPMOV CMQPMOL
COBOL copy files
C include file
CMQC.H
One file contains declarations for all
structures.
Copy and Include files
12
EXAMPLE ANOTHER EXAMPLE
Reason Codes
MQRC_NO_MSG_AVAILABLE MQRC_NONE
Open Options MQOO_INPUT_SHARED MQOO_OUTPUT
Get Message Options MQGMO_WAIT MQGMO_SYNCPOINT
Message Types MQMT_REQUEST MQMT_REPLY
MQI constants
COBOL copy CMQV
COBOL uses hyphen not the underscore
13
Major calls - housekeeping
Unit objectives
Code an MQCONN call to connect to a local queue manager
Code an MQOPEN call to open a queue
Code an MQCLOSE call to close a queue
Code an MQDISC call to disconnect from a local queue
manager
15
MQCONN
MQCONN (name, Hconn, CompCode, Reason)
name
Hconn
CompCode
Reason
Queue Manager
16
Connection handle
MQCONN (name, Hconn, . . . . .
MQOPEN (Hconn, . . . . .
MQPUT (Hconn, . . . . .
MQGET (Hconn, . . . . .
MQCLOSE (Hconn, . . . . .
MQOPEN (Hconn, . . . . .
MQPUT (Hconn, . . . . .
MQGET (Hconn, . . . . .
MQCLOSE (Hconn, . . . . .
MQDISC (Hconn, . . . . .
17
MQCONN completion and reason codes
Completion codes
MQCC_OK
MQCC_WARNING
MQCC_FAILED
Reason codes
MQRC_NONE
MQRC_ALREADY_CONNECTED
MQRC_ANOTHER_Q_MGR_CONNECTED
MQRC_Q_MGR_QUIESCING
MQRC_NOT_AUTHORIZED
MQRC_Q_MGR_NOT_AVAILABLE
MQRC_CONNECTION_BROKEN
18
CICS connection
MQ connection
C
I
C
S

r
e
g
i
o
n
Task
CSQCSTUB
Task
CSQCSTUB
Queue manager 2
Queue manager 3
Local queue manager
19
Batch connection
CONN to A
DISC from A
CONN to B
DISC from B
CONN to A
DISC from A
CONN to C
DISC from C
Batch program
(Batch file)
On z/OS:
CSQBSTUB or
CSQBRSTB or
CSQBRRSI
Queue manager 2
Queue manager 3
Local queue manager
20
IMS connection
A
B
C
D
E
Queue manager B
Queue manager D
Queue manager C
Queue manager E
Queue manager A
IMS control region
IMS dependent region
CSQQSTUB
(MPP, IFP, BMP)
21
Scope of connection handle
Scope of the handle restricted to
smallest unit of parallel execution
Automatic MQDISC and MQCLOSE
when unit ends
Can affect logical unit of work
processing
z/OS CICS task
IMS task
(up to the next syncpoint)
Batch or TSO task
UNIX
Windows
Linux
Thread
OS/400 Job
H-P NSS
Windows Client
Process
DOS Client System
Summer, 2013,University Training Program 22
Connecting to more than one queue manager
General rule:
Can only be connected to one queue manager at a time.
OS/390 batch, TSO and IMS allow multiple concurrent connections.
On Windows, each thread can connect to a different queue manager.
Client applications can connect to more than one queue manager
within a thread.
23
MQCONNX
name
Hconn
CompCode
Reason
MQCONNX (name, ConnOpts, Hconn, CompCode, Reason)
Queue manager
ConnOpts
24
Connection options
Default option:
MQCNO_NONE
Binding options:
MQCNO_STANDARD_BINDING
MQCNO_FASTPATH_BINDING
Connection-tag options (only on z/OS):
MQCNO_SERIALIZE_CONN_TAG_Q_MGR
MQCNO_SERIALIZE_CONN_TAG_QSG
MQCNO_RESTRICT_CONN_TAG_Q_MGR
MQCNO_RESTRICT_CONN_TAG_QSG
Handle-sharing options (only on UNIX, Windows, OS/400):
MQCNO_HANDLE_SHARE_NONE
MQCNO_HANDLE_SHARE_BLOCK
MQCNO_HANDLE_SHARE_NO_BLOCK
25
Access control
Local queue manager
Application program
running under User ID
.
MQCONN
User ID check.
Connection may be denied.
Connection
26
MQCONN pseudocode
DEFINE DEFAULT_QMGR AS CONSTANT ' ' 1
2
DEFINE QMGR AS MQCHAR48 3
DEFINE CONN_HANDLE AS MQHCONN 4
DEFINE COMP_CODE AS MQLONG 5
DEFINE REASON_CODE AS MQLONG 6
7
QMGR = DEFAULT_QMGR 8
9
CALL MQCONN(QMGR, 10
CONN_HANDLE, 11
COMP_CODE, 12
REASON_CODE) 13
14
IF COMP_CODE NOT = MQCC_OK 15
write an error message detailing the REASON_CODE 16
terminate the program 17
STOP 18
END-IF 19
20
27
MQCONNX pseudocode (1 of 2)
2
7
8
9
10
11
QMGR = Queue_Manager_Name 12
13
14
15
CONNECT_OPTIONS.ClientConnPtr = CLIENT_CONN
16
17
18
19
20
DEFINE CONNECT_OPTIONS AS MQCNO
DEFINE CLIENT_CONN AS MQCD
CLIENT_CONN = MQCD_CLIENT_CONN_DEFAULT
CONNECT_OPTIONS = MQCNO_DEFAULT
CLIENT_CONN.ConnectionName = Client Connection 1
CLIENT_CONN.ChannelName = SYSTEM.DEF.SRVCONN
CONNECT_OPTIONS.Version = MQCNO_VERSION_2
28
MQCONNX pseudocode (2 of 2)
21
22
23
24
25
26
27
28
29
CALL MQCONNX(QMGR,
30
CONN_HANDLE,
31
COMP_CODE,
32
REASON_CODE)
33
34
IF COMP_CODE NOT = MQCC_OK
35
write an error message detailing the REASON_CODE
terminate the program
STOP
END-IF
CONNECT_OPTIONS,
29
MQOPEN
Hobj
CompCode
Reason
MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason)
Queue manager
Options
ObjDesc
Hconn
Program
30
Object handle
MQCONN (name, Hconn, ..........
MQOPEN (Hconn, ObjDesc, Options, Hobj, ..........
MQPUT (Hconn, Hobj, ..........
MQGET (Hconn, Hobj, ..........
MQCLOSE (Hconn, Hobj, ...........
MQOPEN (Hconn, ObjDesc, Options, Hobj, ..........
MQPUT (Hconn, Hobj, ..........
MQGET (Hconn, Hobj, ...........
MQCLOSE (Hconn, Hobj, ..........
MQDISC (Hconn, ..........
31
queue "COST"
queue "STOCK"
queue "COST"
queue "STOCK"
queue "STOCK"
queue "COST"
queue "STOCK"
queue "STOCK"
More than one object handle
MQCONN ( ,Hconn, ..........
MQOPEN (Hconn, , , Hcost, ..........
MQOPEN (Hconn, , , Hstock, ..........
MQPUT (Hconn, Hcost, ..........
MQGET (Hconn, Hstock, ..........
MQPUT (Hconn, Hstock, ..........
MQCLOSE (Hconn, Hcost, ...........
MQPUT (Hconn, Hstock, ..........
MQCLOSE (Hconn, Hstock, ..........
MQDISC (Hconn, ..........
32
Object descriptor
StrucId
Version
ObjectType
ObjectName
ObjectQMgrName
DynamicQName
AlternateUserId
33
Open options
Open options specify operations required.
Most common options:
MQOO_INPUT_SHARED
MQOO_INPUT_EXCLUSIVE
MQOO_INPUT_AS_Q_DEF
MQOO_OUTPUT
MQOO_BROWSE
MQOO_INQUIRE
MQOO_SET
MQOO_FAIL_IF_QUIESCING
Object can be opened for a combination of options.
Options must be valid for object type.
User must be authorized for all options requested.
Specified options must not be contradictory.
34
MQOPEN share options
Sharable Queue
OPEN
INPUT_SHARED
GET
GET
OPEN
INPUT_SHARED
GET
OPEN
INPUT_SHARED
OPEN
INPUT_EXCLUSIVE
GET
GET
PROGRAM PROGRAM
PROGRAM PROGRAM
Sharable Queue
INPUT_AS_Q_DEF?
35
MQOPEN reason codes
MQRC_NONE
MQRC_HANDLE_NOT_AVAILABLE
MQRC_HCONN_ERROR
MQRC_NOT_AUTHORIZED
MQRC_OBJECT_IN_USE
MQRC_OD_ERROR
MQRC_OPTION_NOT_VALID_FOR_TYPE
MQRC_OPTIONS_ERROR
MQRC_PAGESET_ERROR
MQRC_STORAGE_NOT_AVAILABLE
MQRC_UNEXPECTED_ERROR
MQRC_UNKNOWN_OBJECT_NAME
36
MQOPEN security
Application program
.
MQOPEN
MQOPEN under
User ID
Access may be
denied
Local queue manager
Connection
ID=johndoe
QUEUE
37
MQOPEN pseudocode (1 of 2)
2
DEFINE OBJ_DESC AS MQOD 7
DEFINE MYQUEUE_HANDLE AS MQHOBJ 9
DEFINE OPEN_OPTIONS AS MQLONG 10
11
13
CONN_HANDLE, 15
COMP_CODE, 16
REASON_CODE) 17
18
STOP 22
END-IF 23
24
38
MQOPEN pseudocode (2 of 2)
OBJ_DESC.StrucId = MQOD_STRUC_ID 25
OBJ_DESC.Version = MQOD_VERSION_1 26
OBJ_DESC.ObjectType = MQOT_Q 27
OBJ_DESC.ObjectName = "MYQUEUE" 28
OBJ_DESC.ObjectQMgrName= DEFAULT_QMGR 29
30
OPEN_OPTIONS = MQOO_OUTPUT + MQOO_FAIL_IF_QUIESCING 31
32
CALL MQOPEN(CONN_HANDLE, 33
OBJ_DESC, 34
OPEN_OPTIONS, 35
MYQUEUE_HANDLE, 36
COMP_CODE, 37
REASON_CODE 38
39
STOP 43
END-IF 44
39
MQCLOSE
MQCLOSE (Hconn, Hobj, Options, CompCode, Reason)
CompCode
Reason
Queue manager
Options
Hobj
Hconn
Program
40
MQCLOSE reason codes
MQRC_NONE
MQRC_HCONN_ERROR
MQRC_HOBJ_ERROR
MQRC_OPTION_NOT_VALID_FOR_TYPE
MQRC_OPTIONS_ERROR
MQRC_PAGESET_ERROR
41
MQCLOSE pseudocode
DEFINE CLOSE_OPTIONS AS MQLONG 5
6
CLOSE_OPTIONS=MQCO_NONE 7
8
CALL MQCLOSE(CONN_HANDLE, 9
MYQUEUE_HANDLE, 10
CLOSE_OPTIONS, 11
COMP_CODE, 12
REASON_CODE) 13
14
STOP 18
END-IF 19
42
MQDISC
MQDISC (Hconn, CompCode, Reason)
CompCode
Reason
Queue manager
Hconn
Program
43
MQDISC reason codes
MQRC_NONE
MQRC_HCONN_ERROR
MQRC_PAGESET_ERROR
44
MQDISC pseudocode
4
CALL MQDISC 5
(CONN_HANDLE, 6
COMP_CODE, 7
REASON_CODE) 8
9
10
STOP 14
END-IF 15
45
Major call - MQPUT
Unit objectives
Use queues to transfer data
Code the MQPUT call
47
MQPUT
MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode,
Reason)
Queue manager
Program
Hconn
Hobj
MsgDesc
PutMsgOpts
BufferLength
Buffer
CompCode
Reason
48
Message descriptor (MQMD)
StrucId
Version
MsgType
Encoding
CodedCharSetld
Format
Priority
Persistence
Msgld
Correlld
49
Put message options (MQPMO)
Strucld
Version
Options
Timeout
Context
KnownDestCount
UnknownDestCount
InvalidDestCount
ResolvedQName
ResolvedQMgrName
50
MQPUT reason codes
MQRC_NONE
MQRC_HCONN_ERROR
MQRC_HOBJ_ERROR
MQRC_MD_ERROR
MQRC_MSG_TOO_BIG_FOR_Q
MQRC_NOT_OPEN_FOR_OUTPUT
MQRC_OPTIONS_ERROR
MQRC_PMO_ERROR
MQRC_PUT_INHIBITED
MQRC_Q_FULL
51
MQPUT pseudocode (1 of 3)
DEFINE BLANKS AS CONSTANT ' ' 1
2
DEFINE MESSAGE_DESCRIPTOR AS MQMD 10
DEFINE PUT_OPTIONS AS MQPMO 11
DEFINE MESSAGE_LENGTH AS MQLONG 12
DEFINE MESSAGE AS CHAR100 13
14
CONN_HANDLE, 16
COMP_CODE, 17
REASON_CODE) 18
19
OBJ_DESC, 21
OPEN_OPTIONS, 22
MYQUEUE_HANDLE, 23
COMP_CODE, 24
REASON_CODE) 25
52
MESSAGE_DESCRIPTOR.StrucId = MQMD_STRUC_ID 26
MESSAGE_DESCRIPTOR.Version = MQMD_VERSION_1 27
MESSAGE_DESCRIPTOR.Report = MQRO_NONE 28
MESSAGE_DESCRIPTOR.MsgType = MQMT_DATAGRAM 29
MESSAGE_DESCRIPTOR.Expiry = MQEI_UNLIMITED 30
MESSAGE_DESCRIPTOR.Feedback = MQFB_NONE 31
MESSAGE_DESCRIPTOR.Encoding = MQENC_NATIVE 32
MESSAGE_DESCRIPTOR.CodedCharSetId = MQCCSI_Q_MGR 33
MESSAGE_DESCRIPTOR.Format = "STKREQ" 34
MESSAGE_DESCRIPTOR.Priority = MQPRI_PRIORITY_AS_Q_DEF 35
MESSAGE_DESCRIPTOR.Persistence = 36
MQPER_PERSISTENCE_AS_Q_DEF
MESSAGE_DESCRIPTOR.MsgId = MQMI_NONE 37
MESSAGE_DESCRIPTOR.CorrelId = MQCI_NONE 38
MESSAGE_DESCRIPTOR.ReplyToQ = BLANKS 39
MESSAGE_DESCRIPTOR.ReplyToQMgr = BLANKS 40
41
53
PUT_OPTIONS.StrucId = MQPMO_STRUC_ID 42
PUT_OPTIONS.Version = MQPMO_VERSION_1 43
PUT_OPTIONS.Options = MQPMO_NO_SYNCPOINT 44
45
MESSAGE_LENGTH = 11 46
47
MESSAGE = "Hello World" 48
49
CALL MQPUT(CONN_HANDLE, 50
MYQUEUE_HANDLE, 51
MESSAGE_DESCRIPTOR, 52
PUT_OPTIONS, 53
MESSAGE_LENGTH, 54
MESSAGE, 55
COMP_CODE, 56
REASON_CODE) 57
58
STOP 62
END_IF 63
54
Opening queues, message descriptor,
and message properties
Unit objectives
Describe the process of sending data to a remote queue
Request the appropriate reports when creating a message
Describe the role of the dead letter queue
Write a program that can operate in a remote or local
environment
Describe MQMD fields
Describe message properties and message handles
56
Queue independence
OR
OR
MQOPEN
PROGRAM
Alias
Q
Local Q
Remote Q
Transmission Q
Target Q on
the remote
Queue
Manager
Local Queue Manager
Remote Queue Manager
IBM Websphere MQ
channel moves messages
across the network
57
Alias queues
PROGRAM
MQOPEN
MQPUT or MQGET
Queue Manager
Alias Queue
Target Queue
58
Remote queuing (1 of 2)
QM1 QM2
Application
Administrator Definition
Q2 - Remote
- Owned by QM2
- Uses xmitq QM2
xmitq QM2
Application puts to Q2 but the
queue manager places the
messages in xmitq adding a
transmission-queue header
Sending
MCA
Receiving
MCA
CHANNEL
Dead Letter
Queue
Q2
possibly
hopefully
MQOPEN Q2
MQPUT Q2HOBJ
59
Remote queuing (2 of 2)
QM1 QM2
QM3
Application
Receiving
MCA
xmitq QM2
xmitq QM3
Q3 - Remote
- Owned by QM3
- Uses xmitq QM2
Channel
Q3
Definitions made by the
administrator for QM2 cause
messages intended for QM3
to be sent on via xmitq QM3
MQOPEN Q3
MQPUT Q3HOBJ
Sending
MCA
Sending
MCA
Receiving
MCA
Channel
60
Queue name resolution
MQOPEN . . . .ObjectName, ObjectQMgrName
ObjectQMgrName = blank or Local QMgr?
ObjectName = Local Queue?
ObjectName = Model Queue?
ObjectName = Alias Queue?
Yes
No
No
Find an XMITQ with the same name
as the queue manager specified.
MQPUT messages are placed on
this XMITQ.
Local queue on the local queue
manager.
Create queue from model definition
and generate name. Queue manager
is local.
Find target queue name on the local
queue manager. lt could be a local
queue or a remote queue.
Yes
Yes
Yes
No
ObjectName = Remote Queue?
No
Resolve queue name, queue manager
name and XMITQ from remote queue
definition.
Yes
MQRC_UNKNOWN_OBJECT_NAME
No
61
Dead letter queue
QM1
QM2
Application
MQOPEN Q2
MQPUT Q2HOBJ
Q2 - Remote
- Owned by QM2
- Uses xmitq QM2
Q2
hopefully
possibly
- Q2 does not exist
- Q2 is full
- Q2 is PUT inhibited
- The message is too big
- Authorization problems
Receiving
MCA
Channel
Sending
MCA
xmitq QM2
Dead Letter
Queue
Q2
62
Undelivered message
Reason
Why message was not delivered
DestQName, DestQMgrName
Where message was meant to go
PutApplType, PutApplName
Application that put the message on the Dead Letter Queue
PutDate, PutTime
When message was put on the Dead Letter Queue
Format, Encoding, CodedCharSetId
Format, encoding, codeset of the following application data
Application Data
MQMD
Dead Letter Header
(MQDLH)
63
Uses of the DLQs
IBM WebSphere MQ puts message on the DLQ:
MCA, if remote message can't be delivered
MCA, if message to be sent cannot be converted
Trigger monitor, if trigger message fails
Application DLQ choices:
The queue managers DLQ
An application DLQ
Backout requeue queue
Use of the MQDLH allows for use of the Dead Letter Handler
program no matter where the application places problem
messages.
64
Persistence (1 of 2)
Persistent messages are
recovered
Non-persistent messages
cannot be Recovered
Non-persistent messages are
expressly discarded on restart
Logging has a performance
impact
There is a default associated
with queue
Any queue may have mix of
persistent and non-persistent
messages except temporary
dynamic queues
Queue Manager
Application
Program
Logging
Persistent
message
MQPUT
Non-Persistent
Message
Queue
CC/RC
Queue
CC/RC
MQPUT
65
Persistence (2 of 2)
Non-persistent
messages
STOP QMGR
START QMGR
Persistent
messages
66
Priority
7
8
MQGET Order
controlled by priority
if set for queue.
PUT applications message
arrive randomly.
9
8
7
9
Higher Priority
Lower Priority
Get
FIFO priority 9
FIFO priority 8
FIFO priority 7
67
Message types
Request/Reply
Datagram Datagram
Request Request
Reply
Reply
send
receive
send request
receive reply
receive request
send reply
Application Queue Manager
Queue Manager Application
Application
Application
Report
Queue Manager
Queue Manager
DLQ
XMITQ
send message
Application
Message Message
Datagram
Report
68
Specifying a local reply-to queue
QM1
Requesting Application
MQMD.MsgType=MQMT_Request
Q2
MQMD.ReplyToQ=Q2
MQPUT1 to Q1
Q1
Responding Application
MQGET from Q1
MQPUT1 to Q2
MQGET from Q2
Another Application
... or another application
could handle the replies
MQGET from Q2
....processing
Q LOCAL
or
Q REMOTE
LOCAL or REMOTE
69
Specifying a remote reply-to queue
QM1 QM2
Requesting Application
Q2 - Remote
- Owned by QM2
- Uses xmitq QM2
xmitq QM2
CHANNEL
Q2
MQMD.MsgType=MQMT_Request
MQMD.ReplyToQ=Q2
MQPUT1 to Q1
Q1
MQGET from Q1
MQPUT1 to Q1
MQPUT1 to Q2/QM2
MQGET from Q2
Application Processing Replies
Q LOCAL
or
Q REMOTE
LOCAL or REMOTE
Receiving
MCA
Channel
Sending
MCA
70
Reply to queuing
Object Name
Object Qmgr Name
Reply to
Queue Name
Reply to Queue
Manager Name
Message Descriptor of Incoming Message
Object Descriptor
MQOPEN or MQPUT1 Hconn,
ObjDesc, and so on
71
Report field options
Report requests with feedback generated by queue manager
MQRO_EXCEPTION
MQRO_EXPIRATION
MQRO_COA (confirm on arrival)
MQRO_COD (confirm on delivery)
MQRO_ACTIVITY (message route information)
Report request with feedback generated by an application
program
MQRO_PAN (positive acknowledgment)
MQRO_NAN (negative acknowledgment)
Use of MQRO_ requires the reply-to-queue field to be filled
MQRO_ _WITH_DATA or MQRO_ _WITH_FULL_DATA
72
Message properties and message handles
Message
properties
Message
Descriptor
Message Selector /
Application
Message
Selected for
processing
CP MD
Selected
Custom
properties
CP MD CP MD
73
Set, inquire and delete message properties
Before setting, inquiring, or deleting the message properties
you need to define a message handle.
Following API calls are used to create and delete the message
handle respectively:
MQCRTMH create message handle
MQDLTMH delete message handle
Following API calls are used to set, inquire and delete the
message properties respectively:
MQSETMP set a message property
MQINQMP inquire message property
MQDLTMP delete message property
74
MQCRTMH - create message handle
MQCRTMH (Hconn, CrtMsgHOpts, Hmsg, CompCode, Reason)
PROGRAM QMGR
Hconn
CompCode
Reason
Hmsg
CrtMsgHOpts
75
MQCRTMH pseudocode
DEFINE CRTMSGHOPTS AS MQCMHO
6
DEFINE HMSG AS MQHMSG 7
CONN_HANDLE = MQHC_UNUSABLE_HCONN 9
COMP_CODE = MQCC_OK 10
REASON_CODE = MQRC_NONE 11
CRTMSGHOPTS = {MQCMHO_DEFAULT} 12
HMSG = MQHM_UNUSABLE_HMSG 13
CONN_HANDLE, 16
COMP_CODE, 17
REASON_CODE) 18
19
CALL MQCRTMH(MQHC_UNASSOCIATED_HCONN, 20
CRTMSGHOPTS,
21
HMSG, 22
COMP_CODE, REASON_CODE) 23
76
MQDLTMH - delete message handle
MQDLTMH (Hconn, Hmsg, DltMsgHOpts, CompCode, Reason)
PROGRAM QMGR
Hconn
CompCode
Reason
DltMsgHOpts
Hmsg
77
MQDLTMH pseudo code (1 of 2)
DEFINE CRTMSGHOPTS AS MQCMHO
6
DEFINE DLTMSGOPTS AS MQDMHO 7
HMSG = MQHM_UNUSABLE_HMSG
14
DLTMSGOPTS = {MQDMHO_DEFAULT} 15
16
CONN_HANDLE,
18
COMP_CODE, 19
REASON_CODE) 20
21
CALL MQCRTMH(MQHC_UNASSOCIATED_HCONN, 22
CRTMSGHOPTS,
23
78
MQDLTMH pseudocode (2 of 2)
HMSG, 24
COMP_CODE, 25
REASON_CODE) 26
27
CALL MQDLTMH(CONN_HANDLE, 28
HMSG,
29
DLTMSGHOPTS, 30
COMP_CODE, 31
REASON_CODE); 32
79
MQSETMP set a message property
MQSETMP (Hconn, Hmsg, SetPropOpts, Name, PropDesc, Type, ValueLength, Value,
CompCode, Reason)
Hconn
Hmsg
SetPropOpts
Name
PropDesc
PROGRAM QMGR
Type
ValueLength
Value
CompCode
Reason
80
MQSETMP pseudocode (1 of 2)
DEFINE CRTMSGHOPTS AS MQCMHO 6
DEFINE PROP_DESC AS MQPD 8
DEFINE SETPROPOPTS AS MQSPMO 9
DEFINE NAME AS MQCHARV 10
11
PROP_DESC = {MQPD_DEFAULT} 18
SETPROPOPTS = {MQSMPO_DEFAULT} 19
NAME = {MQCHARV_DEFAULT} 20
21
22
23
81
MQSETMP pseudocode (2 of 2)
CONN_HANDLE,
25
COMP_CODE, 26
REASON_CODE) 27
28
CALL MQCRTMH(CONN_HANDLE,
29
CRTMSGHOPTS, 30
HMSG, 31
COMP_CODE, 32
REASON_CODE)
33
34
NAME.VSPTR = SPORT 35
NAME.VSLENGTH = MQVS_NULL_TERMINATED 36
37
CALL MQSETMP(CONN_HANDLE,
38
HMSG, 39
SETPROPOPTS, 40
NAME, 41
PROP_DESC, 42
MQTYPE_STRING, 43
MQVL_NULL_TERMINATED,
44
Football,
45
COMP_CODE, REASON_CODE) 46
82
MQINQMP inquire a message property
MQINQMP(Hconn, Hmsg, InqPropOpts, Name, PropDesc, Type, ValueLength, Value,
DataLength, CompCode, Reason)
PROGRAM
PROGRAM
QMG
R
Hconn
Hmsg
InqPropOpts
Name
PropDesc
Type
ValueLength
Value
DataLength
CompCode
Reason
83
MQINQMP pseudocode (1 of 3)
DEFINE INQPROPOTS AS MQIMPO 6
DEFINE TYPE AS MQLONG 9
DEFINE VALUELENGTH AS MQLONG 11
DEFINE VALUE AS MQBYTEx 12
DEFINE DATALENGTH AS MQLONG 13
16
HMSG = MQHM_UNUSABLE_HMSG
22
84
INQPROPOPTS = {MQIMPO_DEFAULT} 26
TYPE = MQTYPE_AS_SET 27
28
CALL MQCONN(QMGR,
29
CONN_HANDLE, 30
COMP_CODE, 31
REASON_CODE) 32
33
CALL MQCRTMH(CONN_HANDLE, 34
CRTMSGHOPTS, 35
HMSG, 36
COMP_CODE, 37
REASON_CODE) 38
39
42
CALL MQSETMP(CONN_HANDLE, 43
HMSG, 44
SETPROPOPTS, 45
NAME,
46
85
PROP_DESC, 47
MQTYPE_STRING, 48
MQVL_NULL_TERMINATED, 49
Football, 50
COMP_CODE, 51
REASON_CODE) 52
53
CALL MQINQMP(CONN_HANDLE, 54
HMSG, 55
INQPROPOPTS, 56
NAME, 57
PROP_DESC, 58
TYPE, 59
VALUELENGTH, 60
VALUE, 61
DATALENGTH, 62
COMP_CODE, 63
REASON_CODE) 64
86
PROGRAM QMGR
Hconn
Hmsg
DltPropOpts
Name
CompCode
Reason
MQDLTMP delete a message property
MQDLTMP (Hconn, Hmsg, DltPropOpts, Names, CompCode, Reason)
87
MQDLTMP pseudocode (1 of 2)
DEFINE SETPROPOPTS AS MQSPMO 10
DEFINE DLTPROPOPTS AS MQDPMO 11
12
DLTPROPOPTS = {MQDMPO_DEFAULT} 22
23
88
MQDLTMP pseudocode (2 of 2)
CONN_HANDLE, 25
COMP_CODE, 26
REASON_CODE) 27
28
CALL MQCRTMH(CONN_HANDLE, 29
CRTMSGHOPTS, 30
HMSG, 31
COMP_CODE, 32
REASON_CODE) 33
34
37
CALL MQDLTMP(CONN_HANDLE, 38
HMSG, 39
DLTPROPOPTS, 40
NAME, 41
COMP_CODE, 42
REASON_CODE) 43
89
Major calls - MQGET and MQPUT1
3.0.3
Unit objectives
Use MQGET to remove a message from a local queue
Use MQPUT1 to put one message on a local queue
91
MQGET
MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer, DataLength,
CompCode, Reason)
PROGRAM QMGR
Hconn
Hobj
MsgDesc
GetMsgOpts
BufferLength
Buffer
CompCode
DataLength
Reason
92
Get message options (MQGMO)
Strucld
Version
Options
WaitInterval
Signal1
Signal2
ResolvedQName
MatchOptions
93
Buffer length (1 of 2)
QUEUE
DEFINE MESSAGE AS MQCHARn
DEFINE MESSAGE_LENGTH AS MQLONG
MESSAGE_LENGTH = 100
CALL MQGET(_____,
_____,
_____,
_____,
MESSAGE_LENGTH,
MESSAGE,
_____,
_____)
MESSAGE OTHER VARIABLES
N O W /b I S T H E
DISPLAY . . . . . . . . . .
0 100
1 2
/b /b
94
Buffer length (2 of 2)
T
I
M
E
TASK 1 TASK 2
BUFFER_LENGTH = 50
MQGET
MQRC_TRUNCATED_MSG_FAILED
BUFFER_LENGTH = 100
MQGET
BUFFER_LENGTH =20460
MQGET
use data length parameter
returned to get a larger
buffer, set to the size of the
message the program has
just failed to get
MQRC_NONE
Front of
Queue
Message Length 100 Message Length 200
1
2
4
3
1 2
95
MQGET reason codes
MQRC_NONE
MQRC_GET_INHIBITED
MQRC_GMO_ERROR
MQRC_HCONN_ERROR
MQRC_HOBJ_ERROR
MQRC_MD_ERROR
MQRC_NO_MSG_AVAILABLE
MQRC_NOT_CONVERTED
MQRC_NOT_OPEN_FOR_INPUT
MQRC_OPTIONS_ERROR
MQRC_TRUNCATED_MSG_ACCEPTED
96
MQGET pseudocode (1 of 3)
DEFINE BLANKS AS CONSTANT ' ' 1
2
DEFINE GET_OPTIONS AS MQGMO 7
DEFINE MESSAGE AS CHAR (100) 9
DEFINE LENGTH_OF_MESSAGE AS MQLONG 10
MYQUEUE_HANDLE AS MQHOBJ 11
CONN_HANDLE, 13
COMP_CODE, 14
REASON_CODE) 15
16
OBJ_DESC, 18
OPEN_OPTIONS, 19
MYQUEUE_HANDLE, 20
COMP_CODE, 21
REASON_CODE) 22
23
97
MESSAGE_DESCRIPTOR.StrucId=MQMD_STRUC_ID 24
MESSAGE_DESCRIPTOR.Version=MQMD_VERSION_1 25
26
GET_OPTIONS.StrucId = MQGMO_STRUC_ID 27
GET_OPTIONS.Version = MQGMO_VERSION_1 28
GET_OPTIONS.Options = MQGMO_NO_WAIT + MQGMO_NO_SYNCPOINT 29
30
MESSAGE_LENGTH =100 31
32
DO 33
34
37
98
CALL MQGET(CONN_HANDLE, 38
MYQUEUE_HANDLE, 39
GET_OPTIONS, 41
MESSAGE_LENGTH, 42
MESSAGE, 43
LENGTH_OF_MESSAGE, 44
COMP_CODE, 45
REASON_CODE) 46
47
UNTIL REASON_CODE NOT = MQRC_NO_MSG_AVAILABLE 48
49
STOP 53
END-IF 54
99
Sending replies to the reply-to queue
Incoming request message contains the names of
the ReplyToQ and ReplyToQmgr in the
Message Descriptor
MQGET
IF the message is a request
Process the data
From the MQGET
MQMD_ReplyToQ and
MQMD_ReplyToQmgr the
MQPUT Uses them in
MQOD_ObjectName and
MQOD_ObjectQmgrName
END-IF
ReplyToQ at ReplyToQmgr
100
Replying pseudocode
DEFINE IN_MSG_DESC AS MQMD 1
DEFINE OUT_MSG_DESC AS MQMD 2
CALL MQGET(......, 4
......, 5
IN_MSG_DESC, 6
...) 7
8
IF IN_MSG_DESC.MsgType = MQMT_REQUEST 9
formulate reply 10
OUT_MSG_DESC.MsgType = MQMT_REPLY 11
OBJ_DESC.ObjectName = IN_MSG_DESC.ReplyToQ 12
OBJ_DESC.ObjectQMgrName = IN_MSG_DESC.ReplyToQMgr 13
14
CALL MQPUT1(......, 15
OBJ_DESC, 16
OUT_MSG_DESC, 17
...) 18
19
END-IF 20
101
MQPUT1
MQPUT1 (Hconn, ObjDesc, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)
PROGRAM QMGR
Hconn
ObjDesc
MsgDesc
PutMsgOpts
BufferLength
Buffer
CompCode
Reason
102
MQPUT1 security
CONNECTION
Application program
.
MQPUT1
MQPUT1 under
UserID
Access may be
denied
Local queue manager
QUEUE
103
MQPUT1 pseudocode (1 of 3)
DEFINE MESSAGE AS MQCHAR100 11
12
CONN_HANDLE, 15
COMP_CODE, 16
REASON_CODE) 17
18
OBJ_DESC.StrucId = MQOD_STRUC_ID 19
OBJ_DESC.Version = MQOD_VERSION_1 20
OBJ_DESC.ObjectType = MQOT_Q 21
OBJ_DESC.ObjectName = "MYQUEUE" 22
OBJ_DESC.ObjectQMgrName = DEFAULT_QMGR 23
104
MESSAGE_DESCRIPTOR.Strucid= MQMD_STRUC_ID 24
MESSAGE_DESCRIPTOR.Version= MQMD_VERSION_1 25
MESSAGE_DESCRIPTOR.Report= MQRO_NONE 26
MESSAGE_DESCRIPTOR.MsgType = MQMT_DATAGRAM 27
MESSAGE_DESCRIPTOR.Expiry = MQEI_UNLIMITED 28
MESSAGE_DESCRIPTOR.Feedback = MQFB_NONE 29
MESSAGE_DESCRIPTOR.Encoding = MQENC_NATIVE 30
MESSAGE_DESCRIPTOR.CodedCharSetId= MQCCSI_Q_MGR 31
MESSAGE_DESCRIPTOR.Format = "STKREQ" 32
MESSAGE_DESCRIPTOR.Priority = MQPRI_PRIORITY_AS_Q_DEF 33
MESSAGE_DESCRIPTOR.Persistence = MQPER_PERSISTENCE_AS_Q_DEF 34
MESSAGE_DESCRIPTOR.ReplyToQ = BLANKS 37
MESSAGE_DESCRIPTOR.ReplyToQMgr = BLANKS 38
39
105
PUT_OPTIONS.StrucId = MQPMO_STRUC_ID 40
PUT_OPTIONS.Version = MQPMO_VERSION_1 41
PUT_OPTIONS.Options = MQPMO_NO_SYNCPOINT 42
43
MESSAGE_LENGTH = 11 44
45
MESSAGE = "Hello World" 46
47
CALL MQPUT1(CONN_HANDLE, 48
OBJ_DESC, 49
PUT_OPTIONS, 51
MESSAGE_LENGTH, 52
MESSAGE, 53
COMP_CODE, 54
REASON_CODE) 55
56
STOP 60
END_IF 61
106
Controlling message retrieval
Unit objectives
Control message delivery with message ID and correlation ID
Write a program so that it includes enough time for responses
to arrive
Describe how to browse a queue using message tokens
Describe the browse and mark options in the MQGET function
Write application programs that can cooperatively browse a
queue
108
MsgId and correlId
MQPUT to local queue Q1
MQGET from shared reply queue
MQPUT to local queue Q1
MQGET from shared reply queue
Serving Application(s)
Requesting Application 1
Requesting Application 2
Q1
Q2
Common server
input queue
Common reply
queue
MQGET from Q1
MQPUT to Q2
109
MsgId, CorrelId, and application parallelism
PROGRAM 1
MQPUT
MQPUT
PROGRAM 4
PROGRAM 3
PROGRAM 2
MQGET
MQPUT
MQGET
MQPUT
MQGET ?
MQGET ?
110
MQPUT and MQPUT1 Msgid, Correlid
MSGID= MQMI_NONE
DO WHILE DATA TO
SEND
MQPUT
END-DO
DO WHILE DATA TO SEND
MSGID= MQMI_NONE
MQPUT
END-DO
MQPMO_NEW_*MSG_ID
111
Retrieval by MsgId and CorrelId
MSGID=3 CORRELID=1
MSGID=3 CORRELID=2
MSGID=3 CORRELID=3
MSGID=4 CORRELID=1
MSGID=4 CORRELID=2
MQGET MSGID=MQMI_NONE
CORRELID=3
MQGET MSGID=4
CORRELID=MQCI_NONE
MQGET MSGID=4
CORRELID=2
MQGET MSGID=MQMI_NONE
CORRELID=MQCI_NONE
MSGID=5 CORRELID=1
112
Retrieving every message
MSGID= MQMI_NONE
CORRELID=MQCI_NONE
DO WHILE NOT QEMTPY
MQGET
END-DO
DO WHILE NOT QEMPTY
MSGID= MQMI_NONE
CORRELID=MQCI_NONE
MQGET
END-DO
MQMO_NONE
113
MsgId and Correlld a worksheet example
PROGRAM 1
PROGRAM 5
PROGRAM 4 PROGRAM 3
PROGRAM 2
Q1
MsgId
CorrelId
Put by Program 4
...uses the MsgId to
retrieve corresponding
messages from Q5....
Program 5 retrieves the
original message from Q1,...
...and puts those two messages, together
with a confirm/reject message on Q6.
Q2
Q3
Q4
Q5
MsgId
CorrelId
Put by Program 5
114
MsgId and correlld - a solution example
PROGRAM 1
PROGRAM 5
PROGRAM 4 PROGRAM 3
PROGRAM 2
UM1 Q1
MsgId
CorrelId
Put by Program 3
...uses the MsgId to
retrieve corresponding
messages from Q5....
Program 5 retrieves the
original message from Q1,...
...and puts those two messages, together
with a confirm/reject message on Q6.
UM1 UM1
UM1
UM1
Q2
Q3
Q4
Q5
MsgId
CorrelId
Put by Program 4
UM1
UM1 = Unique MSGID One
115
Browse
PROGRAM
MQGMO_BROWSE...
MQGET
PROGRAM
MQGMO_BROWSE...
MQGET
PROGRAM
MQGET
PROGRAM
MQGET
1 1
2
1
2
116
Browsing the same message
PROGRAM 1
MQGMO_BROWSE . . .
PROGRAM 2
MQGET with
MQGET with
MQGMO_BROWSE . . .
MQGET with
MQGMO_MSG-UNDER-CURSOR
MQGMO_MSG-UNDER-CURSOR
MQGET with
MQRC_NONE
MQRC_NONE
MQRC_NONE
MQRC_NO_MSG_UNDER_CURSOR
1
3
2
4
117
Simple browsing pseudocode (1 of 2)
4
CALL MQCONN(......, 5
6
CALL MQOPEN(......, 7
8
GET_OPTIONS.Options = MQGMO_BROWSE_FIRST + MQGMO_LOCK 9
10
12
DO WHILE COMP_CODE = MQCC_OK 13
14
IF we need to process this message 15
16
GET_OPTIONS.Options = MQGMO_MSG_UNDER_CURSOR 17
18
20
22
118
Simple browsing pseudocode (2 of 2)
IF REASON_CODE NOT = MQRC_NO_MSG_UNDER_CURSOR 23
24
/* investigate what has gone wrong */ 25
26
END-IF 27
28
ELSE 29
30
/* process the message */ 31
32
END-IF 33
34
END-IF 35
36
GET_OPTIONS.Options = MQGMO_BROWSE_NEXT + MQGMO_LOCK 37
38
40
END-DO 41
42
/*find out why we terminated the loop and */ 43
/*take the appropriate action if required */ 44
119
WAIT
REPLYTOQ = 'B'
MQPUT
MQGET
MQRC_NO_MSG_AVAILABLE
will be returned if there is no
eligible message on the queue at
the time that the MQGET is
issued.
A
B
120
WAIT with WaitInterval
REPLYTOQ = 'B'
MQPUT
MQGET
MQGMO.WAITINTERVAL = A
number of milliseconds or forever
MQGMO.Options = MQGMO_WAIT
A
B
121
WAIT with WaitInterval pseudocode (1 of 2)
5
7
9
MESSAGE_DESCRIPTOR.MsgId = A-Value or MQMI_NONE 10
MESSAGE_DESCRIPTOR.CorrelId = A-Value or MQCI_NONE 11
12
GET_OPTIONS.Options = MQGMO_WAIT + MQGMO_FAIL_IF_QUIESCING 13
14
GET_OPTIONS.WaitInterval = 300000 15
16
122
WAIT with WaitInterval pseudocode (2 of 2)
18
IF COMP_CODE NOT = MQCC OK 19
20
IF REASON_CODE=MQRC_NO_MSG_AVAILABLE 21
/*we were woken up but there was no message */ 22
/*available - timeout expired */ 23
END-IF 24
25
IF REASON_CODE=MQRC_GET_INHIBITED 26
/*we were woken up but we are not now */ 27
/*allowed to get a message */ 28
END-IF 29
30
IF REASONE_CODE=MQRC_Q_MGR_QUIESCING 31
/*we were woken up queue manager quiescing*/ 32
END-IF 33
34
ELSE 35
/*we get the message OK, now process it*/ 36
END-IF 37
38
123
Server
SERVER PROGRAM
MQGET wait on input queue
MQPUT1 to appropriate
reply to queue
Process
Reply to queues
Server input queue
Requesting (client)
applications
MQGMO_FAIL_IF_QUIESCING
124
Expiry
Application A
MQPUT
Application B
MQGET
Time Lapsed
125
MQI security
Unit objectives
Explain the context fields of the message descriptor
Save the context fields in a program and then pass those
fields on to another message
Use alternate user authority to allow one user to send a
message on behalf of another
127
Message context
Queue 3
D
C
Queue 2
A
Queue 1
B
Information about source of message
Identity section - user-related
Origin section - program-related
Part of message descriptor
Can be passed in related message
128
Default context
Identity section
UserIdentifier
Accountingtoken
MVS CICS
Unit of work identifier
(UEPUOWDS)
IMS
PSB name + IMS
recovery token
OS/400
Job accounting code
UNIX
User number
ApplIdentityData
Blank
Origin section
PutApplType
CICS, UNIX, and so forth
PutApplName
PutDate
YYYYMMDD
PutTime
HHMMSSTH
ApplOriginData
Blank
129
No context
Option on MQPUT.
MQPMO_NO_CONTEXT.
The queue manager clears all the context fields.
Can be tested after MQGET.
Is PutApplType = MQAT_NO_CONTEXT?
Default and no context require no more authority than to put a
message on the target queue.
130
Passing context
D
A3
B
A2
A1
Various users put messages
on queue 1
Departmental DB
Corporate DB
D decides whether to
update corporate DB
B enriches
message
Put messages on queue 2 with same identity
context as message taken from queue 1
Open queue 1 as Save All Context
Put messages with Pass Identity Context
Queue 1
Queue 2
131
Context handling
Default
Pass
Identity
PASS ALL
SET
Identity
SET ALL
Queue manager
Program
Input queue
Output queue
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
ID
Origin
Queue manager
Program
Queue manager
Program
Queue manager
Program
Queue manager
Program
132
Programs that set context
Two options that require additional authority
MQPMO_SET_INDENTITY_CONTEXT
MQPMO_SET_ALL_CONTEXT
Used only by special programs
Message channel agents
System utilities
And so forth
133
Pass context pseudocode (1 of 2)
DEFINE MY_IN_HANDLE AS MQHOBJ 2
DEFINE MY_OUT_HANDLE AS MQHOBJ 3
DEFINE MY_INPUT_MQOD AS MQOD 4
DEFINE MY_OUTPUT_MQOD AS MQOD 5
8
CALL MQCONN(QMGR, 9
CONN_HANDLE, 10
COMP_CODE, 11
REASON_CODE) 12
13
OPEN OPTIONS=MQOO_SAVE_ALL_CONTEXT + 14
MQOO_INPUT_AS_Q_DEF 15
16
MY_INPUT_QUEUE.ObjectName='INP1' 17
18
134
Pass context pseudocode (2 of 2)
MY_INPUT_MQOD, 20
OPEN_OPTIONS, 21
MY_IN_HANDLE, 22
COMP_CODE, 23
REASON_CODE) 24
25
OPEN OPTIONS=MQOO_PASS_ALL_CONTEXT + 26
MQOO_OUTPUT 27
28
MY_OUTPUT_QUEUE.ObjectName='OUT1' 29
30
MY_OUTPUT_MQOD, 32
OPEN_OPTIONS, 33
MY_OUT_HANDLE, 34
COMP_CODE, 35
REASON CODE) 36
37
MQGET(......, 38
39
PUT_OPTIONS.Options=MQPMO_PASS_ALL_CONTEXT 40
PUT_OPTIONS.Context=MY_IN_HANDLE 41
42
CALL MQPUT(......, 43
135
MQINQ and MQSET
Unit objectives
Write a program that inquires about the attributes of an IBM
WebSphere MQ object
Write a program that changes the attributes of a IBM
WebSphere MQ queue
137
Why MQINQ and MQSET?
To query the maximum message length for a queue to set up
the input buffer size before the MQGET
To query the number of names in a namelist
To query the application name that implements a process, for
accounting purposes
To obtain backout and requeue, queue relevant information for
poison messages
To change a queue with TRIGTYPE=DEPTH from
NOTRIGGER to TRIGGER
138
MQINQ
PROGRAM
Hconn
Hobj
SelectorCount
Selectors
IntAttrCount
IntAttrs
CharAttrLength
CharAttrs
CompCode
Reason
QMGR
MQINQ(Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs, CharAttrLength, CharAttrs,
CompCode, Reason)
139
MQINQ pseudocode (1 of 2)
DEFINE OBJ_HANDLE AS MQHOBJ 2
DEFINE SELECTORS AS ARRAY 5 MQLONG 5
DEFINE SELECTOR_COUNT AS MQLONG 6
DEFINE INT_COUNT AS MQLONG 7
DEFINE INTS AS ARRAY 3 MQLONG 8
DEFINE CHAR_COUNT AS MQLONG 9
DEFINE CHARS AS CHAR2000 10
11
13
15
SELECTOR_COUNT = 4 16
17
SELECTORS(1) = MQCA_BACKOUT_REQ_Q_NAME 18
SELECTORS(2) = MQIA_BACKOUT_THRESHOLD 19
SELECTORS(3) = MQCA_CREATION_DATE 20
SELECTORS(4) = MQIA_INHIBIT_GET 21
140
MQINQ pseudocode (2 of 2)
INT_COUNT = 2 23
24
CHAR_COUNT = MQ_Q_NAME_LENGTH + 25
MQ_CREATION_DATE_LENGTH 26
27
MQINQ(CONN_HANDLE, 28
OBJ_HANDLE, 29
SELECTOR_COUNT, 30
SELECTORS, 31
INT_COUNT, 32
INTS, 33
CHARS_COUNT, 34
CHARS, 35
COMP_CODE, 36
REASON_CODE) 37
38
141
Format of MQSET
PROGRAM
Hconn
Hobj
SelectorCount
Selectors
IntAttrCount
IntAttrs
CharAttrLength
CharAttrs
CompCode
Reason
QMGR
MQSET(Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs, CharAttrLength, CharAttrs,
CompCode, Reason)
142
MQSET pseudocode (1 of 2)
DEFINE SELECTORS AS ARRAY 5 MQLONG 5
DEFINE SELECTOR_COUNT AS MQLONG 6
DEFINE INT_COUNT AS MQLONG 7
DEFINE INTS AS ARRAY 3 MQLONG 8
DEFINE CHAR_COUNT AS MQLONG 9
DEFINE CHARS AS CHAR2000 10
DEFINE TRIG DATA AS MQCHAR64 11
13
15
SELECTOR_COUNT = 3 16
17
SELECTORS(1) = MQIA_TRIGGER_TYPE 18
SELECTORS(2) = MQIA_TRIGGER_DEPTH 19
SELECTORS(3) = MQCA_TRIGGER_DATA 20
143
MQSET pseudocode (2 of 2)
INTS(1) = MQTT_DEPTH 21
INTS(2) = 10 22
23
INT_COUNT = 2 24
25
CHAR_COUNT = MQ_TRIGGER_DATA_LENGTH 26
TRIGDATA = "MY TRIGGER DATA" 27
MQSET(CONN_HANDLE, 28
OBJ_HANDLE, 29
SELECTOR_COUNT, 30
SELECTORS, 31
INT_COUNT, 32
INTS, 33
CHARS_COUNT, 34
CHARS, 35
COMP_CODE, 36
REASON_CODE) 37
38
144
Transaction support and triggering
Unit objectives
Describe the meaning of logical units of work
Explain how syncpointing is implemented in IBM WebSphere
MQ
Explain how IBM WebSphere MQ can start applications when
messages arrive on its queue
146
Transactions
UPDATE Q1 (MQGET)
UPDATE DB (SQL WRITE)
UPDATE Q2 (MQPUT)
COMMIT
Logical unit
of work
SYNCPOINT
Database
SYNCPOINT
147
Local units of work
Application
MQPUT # w/ syncpoint opt
MQGET # w/ syncpoint opt
If RC = 0 # no errors
MQCMIT #commit
Else # errors
MQBACK #rollback
Queue manager
148
Global units of work syncpoint coordination
Q
u
e
u
e

m
a
n
a
g
e
r

i
s

t
h
e
t
r
a
n
s
a
c
t
i
o
n

m
a
n
a
g
e
r
Application
MQBEGIN # unit of work begin
DB WRITE
MQCMIT #commit
Else # errors
MQBACK #rollback
Queue manager
A
n

e
x
t
e
r
n
a
l

t
r
a
n
s
a
c
t
i
o
n
M
a
n
a
g
e
r

c
o
n
t
r
o
l
s

t
h
e
u
n
i
t
s

o
f

w
o
r
k
Application
TransMgr begin # External TM begin
DB WRITE
TransMgr cmt() #commit
Else # errors
TransMgr back()#rollback
Queue manager
Database
Database
E
x
t
e
r
n
a
l
s
y
n
c
p
o
i
n
t

c
o
o
r
d
i
n
a
t
i
o
n
I
n
t
e
r
n
a
l
s
y
n
c
p
o
i
n
t

c
o
o
r
d
i
n
a
t
i
o
n
149
Syncpoint
MQGET #(customer order)
Write DB
MQPUT #(dispatch request)
MQPUT #(delivery confirmation)
Commit
Option on each MQGET, MQPUT or MQPUT1
NO_SYNCPOINT
Message is added or removed immediately
SYNCPOINT
MQGET, MQPUT or MQPUT1 becomes visible
or removed when transaction is committed
Default is platform-dependent
150
MQPUT within syncpoint control
MQPUT within
syncpoint
MQPUT within
syncpoint
MQPUT within
syncpoint
Commit
1
1 2
1 2 3
1 2 3
151
MQGET within syncpoint control
MQGET within
syncpoint
Commit
1 2 3
2 3
1 2 3
152
MQBEGIN
MQBEGIN (Hconn, CompCode, Reason)
CompCode
Reason
Queue manager
Hconn
Program
153
MQCMIT
MQCMIT (Hconn, CompCode, Reason)
CompCode
Reason
Queue manager
Hconn
Program
154
MQBACK
MQBACK (Hconn, CompCode, Reason)
CompCode
Reason
Queue manager
Hconn
Program
155
Syncpoint pseudocode
3
5
7
GET_OPTIONS.Options = MQGMO_NO_WAIT + MQGMO_SYNCPOINT + 8
MQGMO_FAIL_IF_QUIESCING 9
11
PUT_OPTIONS.Options = MQPMO_SYNCPOINT + 12
MQPMO_FAIL_IF_QUIESCING 13
15
CALL MQCMIT(......, 16
17
156
Poisoned messages
PROGRAM
MQGET
PROGRAM
Process
Message
PROGRAM
ERROR!
PROGRAM
BACKOUT
E
x
e
c
u
t
i
o
n
B
a
c
k
o
u
t

t
o

s
t
e
p

1
1
2
3
4
157
Mark skip backout (z/OS only)
MQGET using MQGMO_MARK_SKIP_BACKOUT
DB update 1
DB update 2
if error...
back out unit of work, including DB updates
Original message available in new transaction
MQPUT reply message
SYNCPOINT
158
Coordination choices
AIX, HP-UX, Sun Solaris
TXSeries
Tuxedo
WebSphere Application Server
Linux
Windows
TXSeries
Tuxedo
MTS/COM+
z/OS
CICS
IMS
RRS
iSeries
HP NSK
NonStop TM/MP (TMF)
AT&T GIS, SINIX, DC/OSx
Tuxedo
159
Rollback pseudocode
DEFINE GET_OPTIONS AS MQGM 1
DEFINE ERROR_OBJDESC AS MQOD 3
5
CALL MQINQ ( . . . . /* BACKOUT_THRESHOLD BACKOUT_REQ_Q_NAME */ 7
GET_OPTIONS.Options = MQGMO_NO_WAIT + 8
MQGMO_SYNCPOINT + MQGMO_FAIL_IF_QUIESCING 9
IF MQMD.BackoutCount > SAVED_BACKOUT_THRESHOLD 11
/* handle message as error and commit */ 12
PUT_OPTIONS.Options = MQPMO_SYNCPOINT+MQPMO_FAIL_IF_QUIESCING 13
ERROR_OBJDESC.OBJECTNAME = SAVED_BACKOUT_REQ_Q_NAME 14
CALL MQCMIT ( . . . ., 16
17
ELSE 18
CONTINUE . . . . 19
20
IF REASON NOT = MQRC_NONE 21
CALL MQBACK ( . . . ., 22
ELSE 23
CALL MQCMIT ( . . . . ., 24
160
Clients and transactions
Client Application
MQGET
MQPUT
MQCMIT/MQBACK
Extended Transactional Client
Client Application
TM API
MQGET
SQL WRITE
MQPUT
TM API
External Transaction
Manager
DB
MQ
client
Extended
XA
MQ
client
Network
Network
MQI Channel
MQI Channel
Queue manager
Queue manager
161
Triggering
Application
Queue
Initiation
Queue
MQPUT
application
queue
Program A
Trigger Monitor
Program B
Process
Definition
1
2
3
4
5
6 Applications
Queue Manager
and Trigger Monitor
Queue manager
MQGET
application
queue
MQGET
initiation
queue
162
Trigger types
First
TriggerMsgPriority
Every
TriggerMsgPriority
Depth
TriggerDepth
TriggerMsgPriority
163
Trigger type depth
TriggerControl = On
TriggerDepth = 3
Trigger
Monitor
TriggerControl = Off
TriggerDepth = 3
Trigger
Monitor
Start
TriggerControl = On
TriggerDepth = 3
PROGRAM
Put
message
PROGRAM
PROGRAM
PROGRAM
PROGRAM
PROGRAM
MQGET wait
Messages.
Turn
trigger on
Trigger
Monitor
1
2
3
164
MQTM (trigger message)
StrucId
Version
QName
ProcessName
TriggerData
ApplType (blank in TMC2)
ApplId
EnvData
UserData
QMgrName (TMC2)
165
Triggered application pseudocode
DEFINE TRIG AS MQTMC2 2
5
COPY INPUTPARAMETER TO TRIG 6
7
QMNAME = TRIG.QMgrName 8
QNAME = TRIG.QName 9
10
CALL MQCONN(QMNAME, CONN_HANDLE, ...) 11
12
OBJ_DESC.ObjectName = QNAME 13
14
CALL MQOPEN(CONN_HANDLE, OBJ_DESC, ..., OBJ_HANDLE, ...) 15
16
CALL MQGET(CONN_HANDLE, OBJ_HANDLE, ...) 17
18
166
Message groups and segmentation
3.0.3
Unit objectives
Write a program that logically groups messages together
Write a program that allows the queue manager to physically
segment large messages
Write a program that performs the physical segmentation
168
Physical and logical messages, segments and
groups
Message group
Logical message Logical message Logical message
Segment Segment
1 2
3
1 2
Physical message
Smallest unit of information
that can be placed on a
Queue
Logical message
Single unit of application
information
One or more physical
messages called segments
Segments are anywhere in the queue
Message group
A set of one or more logical
messages, composed of one
or more physical messages
169
Why?
Message groups
To ensure ordering on retrieval where not already guaranteed
Avoid the use of MsgID and CorrelID
To allow an application to group related messages together
When messages must be processed by the same or particular server
instance
Avoid the use of MsgID and CorrelID
Message segmentation
To handle large messages
Too large for the queue manager or the queue
Too large for the application buffer
170
Message groups
Message group XYZ
GroupXYZ SeqNum 1 GroupXYZ SeqNum GroupXYZ SeqNum
Logical messages in a group have:
The same UNIQUE GroupId in MQMD
A different MsgSeqNumber in MQMD, starting at 1
Logical messages are ordered in a group
Other fields in MQMD are independent
Physical messages not in a group have:
MQGI_NONE in GroupId
Value 1 in MsgSeqNumber
1 2 3
171
Grouping logical messages
MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)
MQMD_VERSION_2 MQPMO_VERSION_2
No mix for persistency
The queue manager returns the
GroupId and the MsgSeqNumber.
This is the recommended
procedure.
If not specified:
GroupId processing similar to
MsgId in previous version
The application assigns
MsgSeqNumber
GroupId
MsgSeqNumber
MsgFlags
MQMF_MSG_IN_GROUP
MQMF_LAST_MSG_IN_GROUP
MQPMO_LOGICAL_ORDER
172
Retrieving logical messages (1 of 2)
MQGMO_VERSION_2
MQGMO_ALL_MSGS_AVAILABLE
Messages available for retrieval only when all messages in a group
have arrived
MQGMO_LOGICAL_ORDER specified
Messages in a group are returned in MsgSeqNumber order
Only one message group at a time for a Hobj
MQGMO_LOGICAL_ORDER not specified
The application must select the correct GroupId, MsgSeqNumber
Can be used to restart in the middle of a group after a failure
Can then switch to MQGMO_LOGICAL_ORDER
To be used for applications forwarding messages
z/OS requires INDXTYPE of GROUPID
173
Retrieving logical messages (2 of 2)
MatchOptions field in MQGMO
For selective MQGETs
Only if MQGMO_LOGICAL_ORDER is not specified
GroupStatus field in MQGMO
Returned on the MQGET
MQMO_MATCH_MSG_ID
MQMO_MATCH_CORREL_ID
MQMO_MATCH_GROUP_ID
MQMO_MATCH_MSG_SEQ_NUMBER
MQGS_NOT_IN_GROUP
MQGS_MSG_IN_GROUP
MQGS_LAST_MSG_IN_GROUP
174
Message segmentation
Logical message
Group XYZ SeqNum 1
Offset 80
Group XYZ SeqNum 1
Offset 160
Group XYZ SeqNum 1
Offset 0
A segment is
A physical message
Identified by the GroupId, MsgSeqNumber, and Offset fields in the message
descriptor
So every segment starts with a MQMD
A message can be segmented and reassembled
By the queue manager
By an application
175
Segmentation by the queue manager
MQMF_SEGMENTATION_ALLOWED in MsgFlag of MQMD
version 2
The queue manager does the following:
User-defined formats are split on 16-byte boundaries
The split never occurs in the middle of an WebSphere MQ header
MQRO_..._WITH_DATA modified to MQRO_... in MQMD if the
segment does not contain any of the first 100 bytes of the user
message
No assumptions should be made on the way the queue manager
splits a message
Persistent message segmentation can be performed only
within a unit of work
The queue manager creates a unit of work if no user-defined unit of
work already exists
MQRC_UOW_NOT_AVAILABLE if a user-defined unit of work exists
and MQPMO_NO_SYNCPOINT is specified
176
Reassembly by the queue manager
MQGMO_VERSION_2
MQGMO_COMPLETE_MESSAGE
Only complete logical messages can be retrieved
If the segments have different MQMD values specified, values from
the first segment are returned
If different CodedCharSetId or encoding, MQCC_WARNING is returned
and a partial message is retrieved
Persistent message reassembly can be performed only within
a unit of work
The queue manager creates a unit of work if no user-defined unit of
work already exists
MQRC_UOW_NOT_AVAILABLE if a user-defined unit of work exists
and MQGMO_NO_SYNCPOINT is specified
177
Reassembly by the application (1 of 2)
MQGMO_VERSION_2
MQGMO_ALL_SEGMENTS_AVAILABLE
Messages available for retrieval only when all segments have arrived
It is forced by MQGMO_ALL_MSGS_AVAILABLE
MQGMO_LOGICAL_ORDER specified
Messages in a group are returned in Offset order
Only one logical message at a time for a Hobj
MQGMO_LOGICAL_ORDER not specified
The application must supply the GroupId, MsgSeqNumber and Offset
Can be used to restart in the middle of a group after a failure
Can then switch to MQGMO_LOGICAL_ORDER
To be used for applications forwarding messages
178
Reassembly by the application (2 of 2)
MatchOptions field in MQGMO
For selective MQGETs
MQMO_MATCH_MSG_ID
MQMO_MATCH_CORREL_ID
MQMO_MATCH_GROUP_ID
MQMO_MATCH_OFFSET and
MQGMO_MATCH_MSG_SEQ_NUMBER
Only if MQGMO_LOGICAL_ORDER is not specified
SegmentStatus field in MQGMO
Returned on the MQGET
MQSS_NOT_A_SEGMENT
MQSS_SEGMENT
MQSS_LAST_SEGMENT
179
Segmentation by the application
MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)
MQMD_VERSION_2 MQPMO_VERSION_2
No mix for persistency
The queue manager returns the GroupId,
the MsgSeqNumber and the Offset.
Only one logical message at a time
Segments are put in order of increasing
segment offset with no gaps
If not specified:
GroupId processing similar to
MsgId in previous version
The application assigns
MsgSeqNumber
GroupId
MsgSeqNumber
Offset
MsgFlags
MQMF_SEGMENT
MQMF_LAST_SEGMENT
MQPMO_LOGICAL_ORDER
180
Segmentation and message group - sample put
Message group
Logical message 1 Logical message 2 Logical message 3
Segment 1 Segment 1
Segment 2
Segment 3
Segment 2
PMO.Options = MQPMO_LOGICAL_ORDER
+ MQPMO_SYNCPOINT
MQPUT(MQMF_MSG_IN_GROUP + MQMF_SEGMENT)
MQPUT(MQMF_MSG_IN_GROUP + MQMF_SEGMENT)
MQPUT(MQMF_MSG_IN_GROUP + MQMF_LAST_SEGMENT)
MQPUT(MQMF_MSG_IN_GROUP)
MQPUT(MQMF_LAST_MSG_IN_GROUP + MQMF_SEGMENT)
MQPUT(MQMF_LAST_MSG_IN_GROUP + MQMF_LAST_SEGMENT)
MQCMIT
1 2 3
1
2
3
181
Segmentation and message group: sample get
GMO.Options = MQGMO_LOGICAL_ORDER
+ MQGMO_SYNCPOINT
+ MQGMO_ALL_MSGS_AVAILABLE
+ MQGMO_WAIT
Do while( Not MQGS_LAST_MSG_IN_GROUP
and not MQSS_LAST_SEGMENT)
MQGET
//Process a segment or completed
// logical message
End
MQCMIT
Message group
Logical message 1 Logical message 2 Logical message 3
Segment 1 Segment 1
Segment 2
Segment 3
Segment 2
182
Asynchronous message consume
Unit objectives
Manage message channels effectively
Enable messages to flow from one queue manager to another
by using intermediate queue managers
Implement separate message flows between any two queue
managers in an IBM WebSphere MQ network
184
What is asynchronous message consume?
Function call driven by arrival of a message instead of MQGET
waiting for arrival of a message
No application thread tied up with waiting for a message
Can provide asynchronous notification of events such as
connection termination or queue manager quiescing
185
What is an asynchronous consumer?
An asynchronous consumer is a message driven function or
routine, directly invoked by the queue manager to process
messages.
The message is delivered in a buffer so the application does
not need to allocate a buffer on its own for holding the data
passed in the message.
The advantages of this are:
Fewer critical resources spent doing nothing.
The application does not need to allocate a buffer and guess the
message size.
186
Traditional message retrieval using MQGET
MQCONN
MQOPEN(QUEUE1,&hObj1)
MQGET(&hObj1)
MQDISC
Waiting for message arrival
Application thread blocked
187
Threading modes use of application thread
MQCONN
MQOPEN(Q1, &hObj1)
MQOPEN(Q2, &hObj2)
MQCB(&hObj1,fun1)
MQCB(&hObj2,fun2)
MQCTL(MQOP_START_WAIT)
MQCTL(MQOP_STOP)
MQDISC
Pause till all call back functions
are deregistered and terminated
Message arrives at Q1
fun1()
Call back function fun()
is called and executed
in the same
application thread
MQCTL returns after the fun1
completes
188
Threading modes Allocating new threads
MQCONN
MQOPEN(Q1, &hObj2)
MQOPEN(Q2, &hObj2)
MQCB(&hObj1,fun1)
MQCB(&hObj2,fun2)
MQCTL(MQOP_START)
MQCTL(MQOP_STOP)
MQDISC
MQCTL returns and application
continues with its normal
processing
fun1()
fun2()
Q1
Q2
New threads are allocated
for executing fun1() and
fun2()
189
Life cycle of a message consumer
MQCB(&hObj1,fun1)
MQCTL(MQOP_START)
MQCTL()
MQCLOSE
Consumer function fun1() is registered using
MQCB with MQOP_REGISTER option
Consumer is started by MQCTL using
MQOP_START option
fun1()
Consumer receives and processes
messages
MQCTL(MQOP_STOP)
Consumer is suspended and
resumed by MQCTL using
different options
Consumer is stopped by
MQCTL using
MQOP_STOP option
Consumer is deregistered
using either MQCB or
MQCLOSE
190
MQCB manage call back
MQCB(Hconn, Operation, CallbackDesc, Hobj, MsgDesc, GetMsgOpts, CompCode,
Reason)
PROGRAM QMGR
Hconn
Operation
CallbackDesc
Hobj
MsgDesc
GetMsgOpts
CompCode
Reason
191
MQCBD call back descriptor
StrucID
Version
CallbackType
Options
MaxMsgLength
CallbackFunction
CallbackName
Reserved
CallbackArea
192
MQCTL control call backs
MQCB(Hconn, Operation, ControlOpts, CompCode, Reason)
PROGRAM QMGR
Hconn
Operation
ControlOpts
CompCode
Reason
193
Call back function
MyCBFunction(Hconn, MsgDesc, GetMsgOpts, Buffer, Context)
Call back
function ()
QMGR
Hconn
MsgDesc
GetMsgOpts
Buffer
Context
194

MQ Summay

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MQ Summay

Uploaded by

Copyright:

Available Formats

Overview

Summer, 2013,University Training Program

You might also like