The first part of this document contains a discussion of general MQ-Series use as well as some notes from the IBM site. The last part contains information concerning the ME MQ class which provides a simplified interface to MQ-Series.

Most applications should choose to use MQ Series Client on their application workstations. A common scenario for use of MQ Series is two servers hosting MQ Series Queue Managers – one for production the other for development. The use of MQ client by applications simplifies installation and support.

To Begin Using MQ-Series

Using MQ Series Client requires

Install MQ Series Client on your workstation,
Map to a Queue Manager Server Node
Define MQSERVER Environment Variable
Have local MQ support person add the developer to the related Security Group.
“Recycle” the queue manager on the server
Include CMQB.BAS in your VB Project (if NOT using MQAX200)

Servers

Map to a server to see the test log files.

Go to Windows Explorer

Map Network Drive

Select a Drive letter

For Folder, enter Share Name

Click Finish

For this process to work, TTS must give you access to the share.

Granting rights and installing software are two different processes. Both must be done before using certain packages, including MQ Series.

Errors

\qmgrs\errors\ contains multiple versions of a log file. Here is an example of a log entry:

-------------------------------------------------------------------------------

11/05/02 11:56:51

AMQ9206: Error sending data to host ME-wd0055 (134.185.38.166).

EXPLANATION:

An error occurred sending data over TCP/IP to ME-wd0055 (134.185.38.166). This

may be due to a communications failure.

ACTION:

The return code from the TCP/IP(send) call was 10054 X('2746'). Record these

values and tell your systems administrator.

-------------------------------------------------------------------------------

\errors\ contains error log and trace files. Somehow logging and tracing to these files can be turned on and off.

It is possible to get an error that prevents a particular program from connecting to a Queue Manager. It appears to be related to improper termination of a class invoking the MQAX200 class. Objects using this class must be sure to terminate properly, releasing any active connections.

Required MQ Client Environment Variable

The Environment Variable MQSERVER must be defined before a client can use the server. If your program is running as a service, it may run under the LocalSystem account, define the Environment Variable as System instead of User.

Right click MY COMPUTER

PROPERTIES

ADVANCED

Click the ENVIRONMENT VARIABLES tab

Select NEW under System Variables

Variable Name = MQSERVER

Variable Value = CHANNEL1/TCP/servername(1414)

Press OK

Press Apply

Security Group Considerations

If a user is NOT defined as part of the related MQ Series Security Group, an authorization error results:

Error connecting via client to ‘QueueName’ RC(2035) Not authorized.

ReasonCode = 2059, ReasonName = MQRC_Q_MGR_NOT_AVAILABLE

Should one of these errors occur when you first begin using MQ-Series, have the local MQ support person verify that you are part of that group.

Recycle the Server’s Queue Manger

For some reason, it is sometimes necessary to “recycle” the queue manager on the server before a new client can connect to it. Until it is recycled, the “MQCONN failed with code 2058” error message is returned. “Queue manager name not valid or not known.”

To “recycle” the queue manager, contact TTS.

Gotcha’s

Beware of log file limits on Windows applications. Log file is used to recreate persistent messages.
Messages may have assigned priority. Queues must be defined to handle prioritized messages. See Implementation Notes.
Application security can be handled by parameters passed to the target.
A receiving program can be triggered to start based on a number of messages in its queue.
Report messages can be defined such as Confirmation of Delivery.
Message affinity or strings of dependent messages imply that cluster should not be used as a message can go to any queue manager with access to the target queue.
When using the Dead Letter Queue, the addition of the Dead Letter Header to a message may make the message too long for the dead-letter queue, so you should always make sure that your messages are shorter than the maximum size allowed for the dead-letter queue, by at least the value of the MQ_MSG_HEADER_LENGTH constant.

MQ Series VB Project Compilation Variable

Specify that you are creating an MQSeries client, before you compile or run the project, by setting the conditional compilation variable MqType to 2 as follows:

In a Visual Basic version 5 project:

1. Select the Project menu.

2. Select Name Properties (where Name is the name of the current project).

3. Select the Make tab in the dialog box.

4. In the Conditional Compilation Arguments field, enter this:

MqType=2

If you don’t set MqType=2 (or =1), you will see an error when compiling CMQB.BAS (“MQGETX – sub or function not defined”).

MQ Series Parameters

Change the environment variable based on server (Production or Development) MQ-Series definitions.

Environment Var	Environment Var Def	Qmgr Name
MQSERVER	CHANNEL1/TCP/ server name (1414)	CORPNAME. server name _1

When making calls and passing the queue manager name, a null will cause the default queue manager to be used. This can be explicitly passed or a “” can be passed for the name. Any queue manager other than the default must have the name specified.

Message Queue Naming

A queue name should be structured in a meaningful way: CORPNAME.nn.aaabbb.cccc.zz

	Definition	Usage notes
nn	QL or QR	local or remote
aaa	App	SAP S8, mfg process mainframe connectivity, etc
bbb	site	Prod, Office, Staff, etc
cccc	interface	transaction called
zz	DV, PD	development or production

Esample: CORPNAME.QR.040001.0001.DV where 040 is a numeric application representation. Queue naming should be done centrally, by one group.

Using MQ Series

OPEN Options

At least one of the following options must be specified:

MQOO_BROWSE

MQOO_INPUT_* (only one of these)

MQOO_INQUIRE

MQOO_OUTPUT

MQOO_SET

See below for details of these options; other options can be specified as required. If more than one option is required, the values can be:

Added together (do not add the same constant more than once), or
Combined using the bitwise OR operation (if the programming language supports bit operations).
Combinations that are not valid are noted; all other combinations are valid. Only options that are applicable to the type of object specified by ObjDesc are allowed (see table below).

Access options: The following options control the type of operations that can be performed on the object:

MQOO_INPUT_AS_Q_DEF - Open queue to get messages using queue-defined default. The queue is opened for use with subsequent GetMessage calls. The type of access is either shared or exclusive, depending on the value of the DefInputOpenOption queue attribute. This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues. This option is not supported on VSE/ESA.
MQOO_INPUT_SHARED - Open queue to get messages with shared access. The queue is opened for use with subsequent MQGET calls. The call can succeed if the queue is currently open by this or another application with MQOO_INPUT_SHARED, but fails with reason code MQRC_OBJECT_IN_USE if the queue is currently open with MQOO_INPUT_EXCLUSIVE. - This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues.
MQOO_INPUT_EXCLUSIVE - Open queue to get messages with exclusive access. The queue is opened for use with subsequent MQGET calls. The call fails with reason code MQRC_OBJECT_IN_USE if the queue is currently open by this or another application for input of any type (MQOO_INPUT_SHARED or MQOO_INPUT_EXCLUSIVE). This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues.

The following notes apply to these options:

Only one of these options can be specified.
An MQOPEN call with one of these options can succeed even if the InhibitGet queue attribute is set to MQQA_GET_INHIBITED (although subsequent MQGET calls will fail while the attribute is set to this value).
If the queue is defined as not being shareable (that is, the Shareability local-queue attribute has the value MQQA_NOT_SHAREABLE), attempts to open the queue for shared access are treated as attempts to open the queue with exclusive access.
If an alias queue is opened with one of these options, the test for exclusive use (or for whether another application has exclusive use) is against the base queue to which the alias resolves.
These options are not valid if ObjectQMgrName is the name of a queue manager alias; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

MQOO_BROWSE - Open queue to browse messages.

The queue is opened for use with subsequent MQGET calls with one of the following options:

MQGMO_BROWSE_FIRST

MQGMO_BROWSE_NEXT

MQGMO_BROWSE_MSG_UNDER_CURSOR

This is allowed even if the queue is currently open for MQOO_INPUT_EXCLUSIVE. An MQOPEN call with the MQOO_BROWSE option establishes a browse cursor, and positions it logically before the first message on the queue.

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects which are not queues. It is also not valid if ObjectQMgrName is the name of a queue manager alias; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

MQOO_OUTPUT - Open queue to put messages. The queue is opened for use with subsequent MQPUT calls. An MQOPEN call with this option can succeed even if the InhibitPut queue attribute is set to MQQA_PUT_INHIBITED (although subsequent MQPUT calls will fail while the attribute is set to this value). This option is valid for all types of queue, including distribution lists.

MQOO_INQUIRE - Open object to inquire attributes. The queue, namelist, process definition, or queue manager is opened for use with subsequent MQINQ calls. This option is valid for all types of object other than distribution lists. It is not valid if ObjectQMgrName is the name of a queue manager alias; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

MQOO_SET - Open queue to set attributes. The queue is opened for use with subsequent MQSET calls. This option is valid for all types of queue other than distribution lists. It is not valid if ObjectQMgrName is the name of a local definition of a remote queue; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

Binding options: The following options apply when the object being opened is a cluster queue; these options control the binding of the queue handle to a particular instance of the cluster queue:

MQOO_BIND_ON_OPEN - Bind handle to destination when queue is opened. This causes the local queue manager to bind the queue handle to a particular instance of the destination queue when the queue is opened. As a result, all messages put using this handle are sent to the same instance of the destination queue, and by the same route. This option is valid only for queues, and affects only cluster queues. If specified for a queue that is not a cluster queue, the option is ignored. This option is supported in the following environments: AIX, DOS client, HP-UX, OS/390, OS/2, OS/400, Sun Solaris, Windows client, and Windows NT.

MQOO_BIND_NOT_FIXED - Do not bind to a specific destination. This stops the local queue manager binding the queue handle to a particular instance of the destination queue. As a result, successive MQPUT calls using this handle may result in the messages being sent to different instances of the destination queue, or being sent to the same instance but by different routes. It also allows the instance selected to be changed subsequently by the local queue manager, by a remote queue manager, or by a message channel agent (MCA), according to network conditions.

Note:

Client and server applications which need to exchange a series of messages in order to complete a transaction should not use MQOO_BIND_NOT_FIXED (or MQOO_BIND_AS_Q_DEF when DefBind has the value MQBND_BIND_NOT_FIXED), because successive messages in the series may be sent to different instances of the server application.

If MQOO_BROWSE or one of the MQOO_INPUT_* options is specified for a cluster queue, the queue manager is forced to select the local instance of the cluster queue. As a result, the binding of the queue handle is fixed, even if MQOO_BIND_NOT_FIXED is specified.

If MQOO_INQUIRE is specified with MQOO_BIND_NOT_FIXED, successive MQINQ calls using that handle may inquire different instances of the cluster queue, although usually all of the instances have the same attribute values.

MQOO_BIND_NOT_FIXED is valid only for queues, and affects only cluster queues. If specified for a queue that is not a cluster queue, the option is ignored. This option is supported in the following environments: AIX, DOS client, HP-UX, OS/390, OS/2, OS/400, Sun Solaris, Windows client, and Windows NT.

MQOO_BIND_AS_Q_DEF - Use default binding for queue. This causes the local queue manager to bind the queue handle in the way defined by the DefBind queue attribute. The value of this attribute is either MQBND_BIND_ON_OPEN or MQBND_BIND_NOT_FIXED.

MQOO_BIND_AS_Q_DEF is the default if neither MQOO_BIND_ON_OPEN nor MQOO_BIND_NOT_FIXED is specified.

MQOO_BIND_AS_Q_DEF is defined to aid program documentation. It is not intended that this option be used with either of the other two bind options, but because its value is zero such use cannot be detected.

This option is supported in the following environments: AIX, DOS client, HP-UX, OS/390, OS/2, OS/400, Sun Solaris, Windows client, and Windows NT.

Context options: The following options control the processing of message context:

MQOO_SAVE_ALL_CONTEXT - Save context when message retrieved. Context information is associated with this queue handle. This information is set from the context of any message retrieved using this handle. This context information can be passed to a message that is subsequently put on a queue using the MQPUT or MQPUT1 calls. See the MQPMO_PASS_IDENTITY_CONTEXT and MQPMO_PASS_ALL_CONTEXT options. Until a message has been successfully retrieved, context cannot be passed to a message being put on a queue. A message retrieved using one of the MQGMO_BROWSE_* browse options does not have its context information saved (although the context fields in the MsgDesc parameter are set after a browse). This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects which are not queues. One of the MQOO_INPUT_* options must be specified. This option is not supported in the following environments: VSE/ESA, 16-bit Windows, 32-bit Windows.

MQOO_PASS_IDENTITY_CONTEXT - Allow identity context to be passed. This allows the MQPMO_PASS_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity context information from an input queue that was opened with the MQOO_SAVE_ALL_CONTEXT option. The MQOO_OUTPUT option must be specified. This option is valid for all types of queue, including distribution lists. This option is not supported in the following environments: VSE/ESA, 16-bit Windows, 32-bit Windows.

MQOO_PASS_ALL_CONTEXT - Allow all context to be passed. This allows the MQPMO_PASS_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity and origin context information from an input queue that was opened with the MQOO_SAVE_ALL_CONTEXT option. This option implies MQOO_PASS_IDENTITY_CONTEXT, which need not therefore be specified. The MQOO_OUTPUT option must be specified. This option is valid for all types of queue, including distribution lists. This option is not supported in the following environments: VSE/ESA, 16-bit Windows, 32-bit Windows.

MQOO_SET_IDENTITY_CONTEXT - Allow identity context to be set. This allows the MQPMO_SET_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity context information contained in the MsgDesc parameter specified on the MQPUT or MQPUT1 call. This option implies MQOO_PASS_IDENTITY_CONTEXT, which need not therefore be specified. The MQOO_OUTPUT option must be specified. This option is valid for all types of queue, including distribution lists. This option is not supported on VSE/ESA.

MQOO_SET_ALL_CONTEXT - Allow all context to be set. This allows the MQPMO_SET_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity and origin context information contained in the MsgDesc parameter specified on the MQPUT or MQPUT1 call. This option implies the following options, which need not therefore be specified:

MQOO_PASS_IDENTITY_CONTEXT

MQOO_PASS_ALL_CONTEXT

MQOO_SET_IDENTITY_CONTEXT

The MQOO_OUTPUT option must be specified. This option is valid for all types of queue, including distribution lists. This option is not supported on VSE/ESA.

Other options: The following options control authorization checking, and what happens when the queue manager is quiescing:

MQOO_ALTERNATE_USER_AUTHORITY - Validate with specified user identifier. This indicates that the AlternateUserId field in the ObjDesc parameter contains a user identifier that is to be used to validate this MQOPEN call. The call can succeed only if this AlternateUserId is authorized to open the object with the specified options, regardless of whether the user identifier under which the application is running is authorized to do so. (This does not apply to any context options specified, however, which are always checked against the user identifier under which the application is running.) This option is valid for all types of object. This option is not supported on VSE/ESA. This option is accepted but ignored on 16-bit Windows and 32-bit Windows.

MQOO_FAIL_IF_QUIESCING - Fail if queue manager is quiescing. This option forces the MQOPEN call to fail if the queue manager is in quiescing state. On OS/390, for a CICS or IMS application, this option also forces the MQOPEN call to fail if the connection is in quiescing state. This option is valid for all types of object. This option is not supported on VSE/ESA. This option is accepted but ignored on 16-bit Windows on 32-bit Windows.

Option

Alias

Local and Model

Remote

Nonlocal Cluster

Distribution list

MQOO_INPUT_AS_Q_DEF

MQOO_INPUT_SHARED

MQOO_INPUT_EXCLUSIVE

MQOO_BROWSE

MQOO_OUTPUT

MQOO_INQUIRE

see note 2

MQOO_SET

see note 2

MQOO_BIND_ON_OPEN (see note 3)

MQOO_BIND_NOT_FIXED (see note 3)

MQOO_BIND_AS_Q_DEF (see note 3)

MQOO_SAVE_ALL_CONTEXT

MQOO_PASS_IDENTITY_CONTEXT

MQOO_PASS_ALL_CONTEXT

MQOO_SET_IDENTITY_CONTEXT

MQOO_SET_ALL_CONTEXT

MQOO_ALTERNATE_USER_AUTHORITY

MQOO_FAIL_IF_QUIESCING

Notes:

The validity of options for aliases depends on the validity of the option for the queue to which the alias resolves.
This option is valid only for the local definition of a remote queue.
This option can be specified for any queue type, but is ignored if the queue is not a cluster queue.

Grayed rows imply not applicable to 32 bit Windows platforms.

MQ Message Descriptor

Because there may be applications that require a special level of control leveraging the information in the Message Descriptor, the ME class includes a property that returns the Message Descriptor. However, a class cannot return string type of fixed length. All the fixed length string fields are changed to variable length strings. Blank fields under ActiveX Component are undefined. It is up to the user to be aware of this restriction when handling string data from the Message Descriptor.

ActiveX Component Field	API Field	Description	Most possibly used
	`StrucId`	Structure identifier
	`Version`	Structure version number	X
`Report`	`Report`	Options for report messages	X
`MessageType`	`MsgType`	Message type	X
`Expiry`	`Expiry`	Message lifetime	X
`Feedback`	`Feedback`	Feedback or reason code	X
`Encoding`	`Encoding`	Numeric encoding of message data	X
`CharacterSet`	`CodedCharSetId`	Character set identifier of message data
`Format`	`Format`	Format name of message data
`Priority`	`Priority`	Message priority	X
`Persistence`	`Persistence`	Message persistence	X
`MessageId`	`MsgId`	Message identifier
`CorrelationId`	`CorrelId`	Correlation identifier
`BackoutCount`	`BackoutCount`	Backout counter	X
`ReplyToQueueName`	`ReplyToQ`	Name of reply queue	X
`ReplyToQueueManagerName`	`ReplyToQMgr`	Name of reply queue manager	X
`UserId`	`UserIdentifier`	User identifier	X
`AccountingToken`	`AccountingToken`	Accounting token
`ApplicationIdData`	`ApplIdentityData`	Application data relating to identity
`PutApplicationType`	`PutApplType`	Type of application that put the message
`PutApplicationName`	`PutApplName`	Name of application that put the message
`PutDateTime`	`PutDate`	Date when message was put
	`PutTime`	Time when message was put
`ApplicationOriginData`	`ApplOriginData`	Application data relating to origin
`GroupId`	`GroupId`	Group identifier
`MessageSequenceNumber`	`MsgSeqNumber`	Sequence number of logical message within group
`Offset`	`Offset`	Offset of data in physical message from start of logical message
`MessageFlags`	`MsgFlags`	Message flags
`TotalMessageLength`	`OriginalLength`	Length of original message

The API

MQ Function Call Order

The normal call order as found in IBM documentation is as follows:

MQDEFAULTS

MQCONN or MQCONNX

MQSET

MQOPEN

MQPUT and MQPUT1

MQGET

MQINQ

MQBEGIN

MQPUT and MQPUT1

MQGET

MQINQ

MQCMIT or MQBACK

MQCLOSE

MQDISC

As implemented in this MQ Series ME class, the following calls are made:

MQCONN or MQCONNX

MQOPEN

MQPUT and MQPUT1 with persistence & delivery in MQMD. Delivery is passed in the Message Descriptor CorrelId (MQBYTE24)

MQGET with Syncpoint Control in MQGMO, Query MQMD for delivery options

MQCMIT or MQBACK

MQCLOSE

MQDISC

MQI Elementary Data Types

For the C language, the MQI provides the following elementary data types or unstructured fields:

MQBYTE	A single byte of data
MQBYTEn	A string of 16, 24, 32, 40, or 64 bytes
MQCHAR	One single-byte character
MQCHARn	A string of 4, 8, 12, 16, 20, 28, 32, 48, 64, 128, or 256 single-byte characters
MQHCONN	A connection handle (this data is 32 bits long)
MQHOBJ	An object handle (this data is 32 bits long)
MQLONG	A 32-bit signed binary integer
PMQLONG	A pointer to data of type MQLONG

shows the Visual Basic equivalents of the C elementary data types.

C data type	Visual Basic data type
MQBYTE	String * 1
MQBYTEn	String * n
MQCHAR	String * 1
MQCHARn	String * n
MQHCONN	Long
MQHOBJ	Long
MQLONG	Long
PMQLONG	No equivalent

CMQB

CMQB.BAS is a file that contains structure definitions and function definitions for use by an application with MQ-Series. This file can be found on the Development Server at /tools/vb/include/cmqb.bas.

Move it to your project folder and include it in your project.

Preparing Visual Basic programs

To prepare Visual Basic programs on Windows client:

1. Create a new project.

2. Add the supplied module file, CMQB.BAS, to the project.

3. Add other supplied module files if you need them:

CMQBB.BAS	MQAI support
CMQCFB.BAS	PCF support
CMQXB	Channel exits support

Call the procedure MQ_SETDEFAULTS before making any MQI calls in the project code. This procedure sets up default structures that the MQI calls require.

Include Modules

These include modules are located in folder /tools/vb/include/ which is found on the server.

Parameter Problem With CMQB.BAS

CMQB.BAS was changed by IBM, making the MQCONN and MQCONNX QMgrName parameter a fixed length string. It changed from

ByVal QMgrName As String

ByVal QMgrName As String * 48

The new code generates the following error:

This error can be avoided by changing the code back to its original form.

DLL Compilation Problem With CMQB.BAS

When using MQ-Series in an Active-X DLL project, compiling CMQB.BAS will result in the following error occurring in MQ_DEFAULTS:

“Functionality not supported in DLL”

This occurs because of the “end” statement. Change the MQ_DEFAULTS routine in the following way:

If MQVBDLL = "NONE" Then

MsgBox "MQType has not been set correctly" & Chr(10) & Chr(13) &

"Please see the comments at the start of CMQB.BAS", vbOKOnly +

vbExclamation, "Error"

gblnInitd = False

Else

...

gblnInitd = True

End If

Check gblnInitd (Project defined global variable) after calling MQ_DEFAULTS on class initialization.

The ActiveX Component (MQAX200)

To use the ActiveX component directly, outside of the simplified class described in this document, your VB Project must reference the following component: IBM MQSeries Automation Classes for ActiveX. This component should be registered as part of installing MQ Series on your workstation.

No files (like CMQB) need to be added to a project using the MQAX200 class.

MQ Method Call Order

The normal call order as found in IBM documentation is as follows:

Instantiate MQSession

mobjQMgr = mobjMQSess.AccessQueueManager(pstrQueMgrName)

mobjQMgr.AccessQueue(pstrQueName, llngOpenOpt)

lobjQueue = mobjQMgr.AccessQueue(pstrQueName, llngOpenOpt)

mobjQ.Get lobjMesgDesc, lobjGetMsgOptions

pstrMessage = lobjMesgDesc.MessageData

lobjMesgDesc.MessageData = pstrMessage

mobjQ.Put lobjMesgDesc, lobjPutOptions

lobjQueue.Close

mobjQMgr.Disconnect

What’s Missiing

The MQMD PutDateTime field is not defined in the .NET compile.

The GetMessageOptions Signal1 and Signal2 fields are not defined in the .NET compile.

Sending and Receiving Strings or Byte Arrays

MQ-Series has internal logic used to determine the nature of data – whether ASCII or Unicode. A test has shown that MQ-Series string handling does not handle Unicode correctly. Unicode characters were stored as HEX 7F’s.

With the Message Object it is possible to access the message area, either to set it for sending or to read it to access newly received data, via the MessageData property. This property is a string and is read and written as Unicode. A byte array can be read or written to the message area by using the Read or Write methods. This writes bytes exactly as in the array. However, if a string is sent by moving it to the MessageData property and read using the Read method, it is read as ASCII and NOT as Unicode. If an ASCII byte array (1 byte per character) is sent with the Write method. Both the Read and an access via MessageData yield the proper data – an ASCII byte array AND a Unicode string with the characters resolved as Unicode. A Unicode character byte array is sent and received properly using the Read and Write methods. However, if sent via Send and read from MessageData, the string is incorrectly encoded as if the 0 bytes are characters so that the string terminates incorrectly after the first character.

It is recommended that data sent using the Send method should be read with the Read method. And data sent by accessing the MessageData property should be read via the MessageData property. It is possible to mix the methods, but do so only after considering the ASCII/Unicode implications.

.NET

Develop From a Local Drive

When debugging a solution, the debugger generates the following error when defining a new instance of the MQAX200 ActiveX DLL.

This occurs because .NET has been designed with integrated security. Files on a local drive are completely trusted while files from a network share or from an Intranet location are not trusted. In fact, when loading a project with component references on a network share, warning messages will be displayed. To circumvent this problem, a security policy would need to be created for the development machine to specify which servers are to be trusted.

The easiest solution is to develop and test on a local drive.

The .NET Redistributable Framework

The .NET Redistributable Framework is required on workstations that will be running .NET applications. It is available locally or can be downloaded from:

http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/829/msdncompositedoc.xml

With Microsoft Windows NT® 4.0, SP 6a is required.

ME MQ Classes

Because a QM Connection has scope within the thread, multiple connections use the same handle # and disconnecting one, disconnects all connections to the same QM. Therefore, a MQ class defines a QM connection and all connections to its queues are maintained by an instance of that class.

ME MQ API Methods:

MEInitMQ (ByVal pstrClientOrServer As String,

ByRef pusrError As meQerr_t) As Boolean

MEConnectQM (ByVal queMgrName as string, 48 char max.

ByRef errorMesg as meQerr_t)

MEOpenQ (ByVal queMgrName as string, 48 char max both parms

ByVal queueName as String,

ByVal openForRorW as string, R or W

ByRef queHandle as Long,

ByRef errorMesg as meQerr_t)

MECloseQ (ByVal queHandle as Long,

ByVal queueName as String,

ByRef errorMesg as meQerr_t)

MEDisconnectQM (ByVal queHandle as Long,

ByRef errorMesg as meQerr_t)

MERead (ByVal queHandle as Long,

ByRef message as String,

ByVal messageLength as Double,

ByRef receivedLength as Double,

ByVal convert as Boolean, (i.e. EBCDIC/ASCII)

ByVal timeoutLength as Long, <0 forever,

ByVal signalHandle as Long,

ByVal signalId as Long, Not 0 if async notification desired

ByRef confirm as Boolean, True for confirm required

ByRef errorMesg as meQerr_t)

MEWrite (ByVal queHandle as Long,

ByRef message as String,

ByVal messageLength as Double,

ByVal persistence as boolean,

ByVal delivery as String, ("sync", "nosync")

ByVal priority as Long,

ByVal pstrReplyQue As String, _

ByVal pstrReplyQM As String, _

ByVal pstrMsgFormat As String, _

ByRef errorMesg as meQerr_t)

To facilitate communication with IMS, the Write Method includes parameters for Message Format, Reply Queue, and Reply Queue Manager. Messages using the IMS OTMA bridge require an MQMD format of "MQIMS". The IIH header, specified by using "MQIMS", allows the user to define a Reply Queue and a Reply Queue manager. These are required when an initiated transaction returns data to the caller. DFS messages are also sent to the Reply Queue and Reply Queue Manager. In the MQIIH header, the message format is specified as MQIMSVS since the message must have a LLZZ header as well. The LL is a 16 mit length (longest message segment is 32767) and ZZ is reserved as a 16 bit 0 value. For all other applications, an MQMD format of MQSTR is used.

MEConfirm (ByVal queHandle as Long,

ByVal messageID as String) See MERead.

meMQ.dll Methods

meConnectQM (ByVal queMgrName as string, 48 char max.

ByRef errorMesg as meQerr_t)

meOpenQ (ByVal queMgrName as string, 48 char max both parms

ByVal queueName as String,

ByVal openForRorW as string, R or W

ByRef queHandle as long, for later que identification

ByRef errorMesg as meQerr_t)

meCloseQ (ByVal disconnect as Boolean, True if do disconnect as well

ByVal queHandle as Long,

ByRef errorMesg as meQerr_t)

meDisconnectQM (ByRef errorMesg as meQerr_t)

meRead (ByVal queHandle as Long, 48 char max

ByRef message as String,

ByVal messageLength as Double,

ByRef receivedLength as Double,

ByVal convert as Boolean, (i.e. EBCDIC/ASCII)

ByVal timeoutLength as Long, <0 forever,

ByVal signalHandle as Long,

ByVal signalId as Long, Not 0 if async notification desired

ByRef confirm as Boolean, True for confirm required

ByRef errorMesg as meQerr_t)

meSyncRead (ByVal plngQueHandle As Long,

ByRef pstrMessage As String,

ByVal plngMessageLength As Long,

ByRef plngReceivedLength As Long,

ByRef pblnStrConvert As Boolean,

ByVal plngTimeout As Long,

ByVal plngSignalHandle As Long,

ByVal plngSignalID As Long,

ByRef pblnConfirm As Boolean,

meWrite (ByVal queHandle as Long, 48 char max

ByRef message as String,

ByVal messageLength as Double,

ByVal persistence as boolean,

ByVal delivery as String, ("sync", "nosync")

ByVal priority as Long,

ByVal pstrReplyQue As String, _

ByVal pstrReplyQM As String, _

ByVal pstrMsgFormat As String, _

ByRef errorMesg as meQerr_t)

meConfirm (ByVal queHandle as Long,

ByRef errorMesg as meQerr_t) See meRead.

Properties

MessageDescriptorData - Read only. Returns the last received Message Descriptor. Provided so a user can access more detail as required. The fields differ based on whether the API or ActiveX version of the Class is used. See the Message Descriptor description above.

IsInitialized - Read only. Boolean. Returns True is correctly initialized. Otherwise, it returns False. Included since initialization of Client and Server may have different errors. The return from the meInitMQ method will yield the same result and is the more natural place to check for this status.

Error Return

Errors returned from the class will contain three fields: the Completion Code and the Reason Code from the actual MQ-Series function call and the error text as determined from the Reason Code. The following public type is the structure of the returned error.

public type meQerr_t

completionCode as long

reasonCode As String

msgText As String

end type

How to use

The methods are implemented as functions with a Boolean return value of True if the call succeeded and False if it failed. On failure the error return structure contains the error information. On success the error return structure may contain information if data or call related errors caused the error. The message or portion of it may have been processed correctly. The situation, where the call succeeded but error information is returned, occurs when a warning is returned from the MQ Series function call.

Code samples

Write a message:

Dim m As meMQClass

Dim e As meQerr_t

Dim msgDesc As meMQMD

Dim errTrue As Boolean

Dim sts As Boolean

Dim q As String

Dim qm As String

Dim message As String

Dim lblnPersist As Boolean

Dim lstrConfirm As String

Set m = New meMQClass

q = queNam

qm = queMgr

If (chkConf = 0) Then

lstrConfirm = "nosync"

Else

lstrConfirm = "sync"

End If

If (chkPers = 0) Then

lblnPersist = False

Else

lblnPersist = True

End If

message = snd

If (m.meInitMQ("client", e)) Then

If (m.meConnectQM(qm, e)) Then

If (m.meOpenQ("", q, "w", e)) Then

sts = m.meWrite(q, _

message, _

Len(message), _

lblnPersist, _

lstrConfirm, _

pty, _

“CORPNAME.QL.041000.DV”,

qm,

”MQSTR”, ‘ Default is MQSTR

End If

msgDesc = m.MessageDescriptorData

err = e.msgText

msgID = msgDesc.msgID

corelID = msgDesc.correlID

sts = m.meCloseQ("", q, e)

sts = m.meDisconnectQM(qm, e)

Set m = Nothing

Read a message:

Dim m As meMQClass

Dim e As meQerr_t

Dim msgDesc As meMQMD

Dim errTrue As Boolean

Dim sts As Boolean

Dim q As String

Dim qm As String

Dim message As String * 200

Dim llngRcvdLen As Long

Set m = New meMQClass

q = queNam

qm = queMgr

If (m.meInitMQ("client", e)) Then

If (m.meConnectQM(qm, e)) Then

If (m.meOpenQ("", q, "R", e)) Then

sts = m.meRead(q, _

message, _

Len(message), _

llngRcvdLen, _

timo, _

0, _

mstrMsgId, _

End If

msgDesc = m.MessageDescriptorData

mstrMsgId = msgDesc.msgID

msgID = mstrMsgId

corelID = msgDesc.correlID

err = e.msgText

rcv = Left(message, llngRcvdLen)

sts = m.meCloseQ("", q, e)

sts = m.meDisconnectQM(qm, e)

Set m = Nothing

Confirm a message:

Dim m As meMQClass

Dim e As meQerr_t

Dim msgDesc As meMQMD

Dim errTrue As Boolean

Dim sts As Boolean

Dim q As String

Dim qm As String

Dim message As String * 200

Dim lintRcvdLen As Integer

Set m = New meMQClass

q = queNam

qm = queMgr

If (m.meInitMQ("client", e)) Then

If (m.meConnectQM(qm, e)) Then

If (m.meOpenQ("", q, "R", e)) Then

sts = m.meConfirm(q, _

mstrMsgId, _

End If

msgDesc = m.MessageDescriptorData

msgID = mstrMsgId

corelID = msgDesc.correlID

err = e.msgText

sts = m.meCloseQ("", q, e)

sts = m.meDisconnectQM(qm, e)

Set m = Nothing

ME MQ Implementation Notes

General

1. Change CMQB MQ_DEFAULTS routine to conform to DLL creation as follows:

If MQVBDLL = "NONE" Then

gblnInitd = False

Else

...

gblnInitd = True

End If

Check gblnInitd after calling MQ_DEFAULTS on Initialize.

2. Giving users a wide variety of options and control over descriptors will require that the user map out CMQB and understand inner workings of MQ-Series. The purpose of this DLL is to isolate the user from such detail. Therefore, this DLL limits user choices to the following:

- Confirm or No confirm (GMO Syncpoint Ctl)

- Notification of delivery to ultimate consumer is not provided. Once the message queuing has completed, notification is returned to the caller. If end to end notification is required, use the Reply fields of the MQMD structure. This is not provided as part of this class at this time.

- Message Persistence (MQMD)

- Configuration Conversion (MQMD: Format)

- Timeout on input

- Priority (MQMD)

- Asynchronous notification of message availability

MQMD

- persistence - message survives QM restarts

3. SAP provides an MQ Series Link Header which is of mixed types. MQSeries provides the ability to define a configuration entity that defines the fields and controls the conversion within MQ Series.

4. It has been verified that if a Get program is running with syncpoint control as a client, data can be lost when the client crashes before being able to do a commit or rollback. This means, where guaranteed delivery is required, don't run as a client. OR, implement some process to avoid losing the data. This Class moves commitment responsibility to the user by returning a msgId.that can be used to delete a processed message from a queue (meCommit). See more detail below.

meOpenQ

1. MQOO_INPUT_EXCLUSIVE generates object already open with conflicting options. Use MQOO_INPUT_AS_Q_DEF instead.

meRead

1. To handle Commit and guaranteed delivery considering the client problem listed under General Notes above:

Use the MQMD CorrelId to pass "sync" or "nosync" from a Write (Put) call.
Set the put option MQPMO_NEW_MSG_ID to guarantee that the MQMD msgId field is unique
In the read call, immediately do an MQBACK if "sync" was specified on the write, otherwise do an MQCMIT.
In the read call, return the msgId to the caller so that a subsequent meConfirm call can be made to remove the message by the msgId.

This process results in a brief window (between the MQGET and MQBACK calls) where the message will be lost should the computer or process fail.

2. To determine the max message length allowed, use the MQIA_MAX_MSG_LENGTH selector with the MQINQ call. (Noted but not implemented in this class.)

3. MQMF_SEGMENTATION_INHIBITED - Require message handled as unit. Assume segmentation is not required.

4. MQGET MQGMO parameters for message arrival notification.

Options (set by class based on user specified notification)

MQGMO_WAIT

MQGMO_NO_WAIT

MQGMO_SET_SIGNAL

WaitInterval (MQWI_UNLIMITED or 0 or >0) milliseconds (passed to class from user)

signal1 - (if MQGMO_SET_SIGNAL) On 32-bit Windows, this field must contain the window handle of the window to which the signal is to be sent. If this is zero, the signal is sent to the thread requesting the signal. The signal is a Windows message with the identifier specified by the Signal2 field. The message contains a signal completion code in the WPARAM field.

signal2 - On 32-bit Windows, this field contains the identifier of a Windows message that is sent to the application window (as specified by the Signal1 field) to signal that a suitable message has arrived. The Windows call RegisterWindowMessage should be used to obtain a suitable identifier. This corresponds to the meRead plngSignalID argument. If plngSignalID is 0, signaling is not to be used.

5. In order to Q/DQ by priority: The MsgDeliverySequence attribute of the queue determines whether messages on the queue are stored in FIFO (first in, first out) sequence, or in FIFO within priority sequence. If this attribute is set to MQMDS_PRIORITY, messages are enqueued with the priority specified in the Priority field of their message descriptors; but if it is set to MQMDS_FIFO, messages are enqueued with the default priority of the queue. Messages of equal priority are stored on the queue in order of arrival.

meSyncRead

1. See meRead.

2. Some existing applications may exchanged queued data requiring guaranteed delivery but not be able to change the sender to specify confirm. This function forces all reads to be with guaranteed delivery requiring a Confirm call to delete from the queue.

meConfirm

1. Zero length can be specified for messages that have no data, or if the message is to be removed from the queue and the data discarded (MQGMO_ACCEPT_TRUNCATED_MSG must be specified in this case).

meWrite

1. When putting, use MQMD CorelId to pass a delivery of sync or nosync where sync gurantees delivery.

2. When putting, set the put option MQPMO_NEW_MSG_ID to guarantee that the MQMD msgId field is unique for all messages. If sync is specified in CorelId, then return the msgId to the user for a subsequent commit call.

Using A Dead Letter Queue

A queue can be assigned a dead letter queue into which the Queue Manager will place undeliverable messages. An application can also store messages into this queue. An application can define its own dead letter queue or use the system default dead letter queue. Application logic that will store messages into the dead letter queue should query the queue manager to find out what dead letter queue to use.

When the queue manager puts a message on this queue, it adds a header to the message, the format of which is described by the dead-letter header (MQDLH) structure, in the MQSeries Application Programming Reference manual. This header includes the name of the target queue and the reason the message was put on the dead-letter queue. It must be removed and the problem must be resolved before the message is put on the intended queue. Also, the queue manager changes the Format field of the message descriptor (MQMD) to indicate that the message contains an MQDLH structure.

The addition of the header to a message may make the message too long for the dead-letter queue, so you should always make sure that your messages are shorter than the maximum size allowed for the dead-letter queue, by at least the value of the MQ_MSG_HEADER_LENGTH constant. The maximum size of messages allowed on a queue is determined by the value of the MaxMsgLength attribute of the queue. For the dead-letter queue, you should make sure that this attribute is set to the maximum allowed by the queue manager. If your application cannot deliver a message, and the message is too long to be put on the dead-letter queue, follow the advice given in the description of the MQDLH structure.

You need to ensure that the dead-letter queue is monitored, and that any messages arriving on it get processed. A dead-letter queue handler is provided by MQSeries on all platforms except OS/390 and VSE/ESA. It runs as a batch utility and can be used to perform various actions on selected messages on the dead-letter queue. If you have a queue manager on one of the platforms that does not provide a dead-letter queue handler, you will need to provide your own. The program could be triggered, or run at regular intervals. For further details, see the MQSeries System Administration Guide for MQSeries for AIX, HP-UX, OS/2, Sun Solaris, and Windows NT; for other platforms, see the appropriate System Management Guide.

If data conversion is necessary, the queue manager converts the header information when you use the MQGMO_CONVERT option on the MQGET call. If the process putting the message is an MCA, the header is followed by all the text of the original message.

You should be aware that messages put on the dead-letter queue may be truncated if they are too long for this queue. A possible indication of this situation is the messages on the dead-letter queue being the same length as the value of the MaxMsgLength attribute of the queue.

The MQDLH structure describes the information that is prefixed to the application message data of messages on the dead-letter (undelivered-message) queue. A message can arrive on the dead-letter queue either because the queue manager or message channel agent has redirected it to the queue, or because an application has put the message directly on the queue.

Special processing is done when a message which is a segment is put with an MQDLH structure at the front; see the description of the MQMDE structure for further details.

This structure is not supported in the following environments: 16-bit Windows, 32-bit Windows.

Applications that put messages directly on the dead-letter queue should prefix the message data with an MQDLH structure, and initialize the fields with appropriate values. However, the queue manager does not check that an MQDLH structure is present, or that valid values have been specified for the fields.

If a message is too long to put on the dead-letter queue, the application should consider doing one of the following:

Truncate the message data to fit on the dead-letter queue.
Record the message on auxiliary storage and place an exception report message on the dead-letter queue indicating this.
Discard the message and return an error to its originator. If the message is (or might be) a critical message, this should be done only if it is known that the originator still has a copy of the message--for example, a message received by a message channel agent from a communication channel.

Which of the above is appropriate (if any) depends on the design of the application.

When a message is put on the dead-letter queue, all of the fields in the message descriptor MQMD should be copied from those in the original message descriptor (if there is one), with the exception of the following:

The CodedCharSetId and Encoding fields should be set to whatever character set and encoding are used for fields in the MQDLH structure.
The Format field should be set to MQFMT_DEAD_LETTER_HEADER to indicate that the data begins with a MQDLH structure.
The context fields:

UserIdentifier

AccountingToken

ApplIdentityData

PutApplType

PutApplName

PutDate

PutTime

ApplOriginData

should be set by using a context option appropriate to the nature of the program:

o A program putting on the dead-letter queue a message that is not related to any preceding message should use the MQPMO_DEFAULT_CONTEXT option; this causes the queue manager to set all of the context fields in the message descriptor to their default values.

o A program putting on the dead-letter queue a message it has just received should use the MQPMO_PASS_ALL_CONTEXT option, in order to preserve the original context information.

o A program putting on the dead-letter queue a reply to a message it has just received should use the MQPMO_PASS_IDENTITY_CONTEXT option; this preserves the identity information but sets the origin information to be that of the server.

o A message channel agent putting on the dead-letter queue a message it received from its communication channel should use the MQPMO_SET_ALL_CONTEXT option, to preserve the original context information.

In the MQDLH structure itself, the fields should be set as follows:

The CodedCharSetId, Encoding and Format fields should be set to the values that describe the application message data that follows the MQDLH structure--usually the values from the original message descriptor.
The context fields PutApplType, PutApplName, PutDate, and PutTime should be set to values appropriate to the application that is putting the message on the dead-letter queue; these values are not related to the original message.
Other fields should be set as appropriate.

Character data in the MQDLH structure should be in the character set defined by the CodedCharSetId field of the message descriptor. Numeric data in the MQDLH structure should be in the data encoding defined by the Encoding field of the message descriptor. The application should ensure that all fields have valid values, and that character fields are padded with blanks to the defined length of the field; the character data should not be terminated prematurely by using a null character, because the queue manager does not convert the null and subsequent characters to blanks in the MQDLH structure.

Applications that get messages from the dead-letter queue should verify that the messages begin with an MQDLH structure. The application can determine whether an MQDLH structure is present by examining the Format field in the message descriptor MQMD; if the field has the value MQFMT_DEAD_LETTER_HEADER, the message data begins with an MQDLH structure. Applications that get messages from the dead-letter queue should also be aware that such messages may have been truncated if they were originally too long for the queue.

Remote Queue Message Flow

When using the support tools described in the next chapter, keep in mind this flow for remote queue connections. A remote queue (QR) does not have Input Count, Output Count, and Queue Depth. A QR does have the name of the “remote” local queue (QL) to which it is sending, that queues Queue Manager, and the local Transmission Queue (QT). The QT for a QR has the Input Count, Output Count, and Queue Depth. The Trigger Data field in the QT definition specifies the Channel to be used by that QT.

MQ-Series Support Tools

Queue Browser

From a command prompt window, you can run utility amqbcg or amqsbcgc (queue browser), located in MQSeries folder \tools\c\samples\bin on the system running the queue manager. amqbcg is the server version, amqbcgc is the client version. It gives a hex and ASCII dump of all messages in the queue. Note that the queue names are case-sensitive. For access to this MQ Series folder, you must map to the MQ Server file share as described in the chapter To Begin Using MQ Series.

In order to execute from ME, you'd need to know the client connection channel name and queue manager name, and access to amqsbcgc.exe (which we have at ME). The client connection channel needs to be defined on the MQSeries server running the queue manager (this likely is not configured). This might be enough, but it's possible that other things could get in the way.

Remote Queue Administrator

The Remote Queue Administrator provides a great tool for administering the MQ environment. For example, it can be used to create and delete queues and to actually browse the contents of a queue. Creating and deleting queues should only be done by a support group responsible for maintaining the MQ Server. This section is NOT an exhaustive description of the tool’s use. It just tells you how to start and gives an overview of some key uses.

The WebSphere MQ for Windows Remote Queue Administrator SupportPac provides a simple, easy to configure GUI interface to administer WebSphere MQ (MQSeries) Queue Managers. It consists of a single program which sends PCF or MQSC messages to a local or remote Queue Manager and displays the output from the command server in dialogs. All Queue Managers that have a command server can be administered including MVS and OS/390. The program also has the ability to send monitor messages to the remote location at configurable intervals and display whether responses are received allowing simple monitoring of the availability of Queue Managers in your network.

WebSphere MQ for Windows Remote Queue Administrator is available as a free download from the IBM site:

http://www-3.ibm.com/software/ts/mqseries/txppacs/mo71.html

The download consists of a zip file which should be unzipped into a folder of your choosing. It unzips into three files:

MQMON.PDF – an excellent documentation file
readme.mo71 – a description of the release and its changes
mqmonntp.exe – the executable utility program

No Start menu is added. To execute the utility, run the exe by double clicking on it. Click File and then Add to define a queue manager.

Enter an identifying name in Location.

Enter the Queue Manager Name.

Enter a valid Reply queue Name. Must exist and not be used by another administrator.

Check Client.

Click Configure. A configuration page appears.

Enter or Select a valid Channel name.

Enter a valid Connection Name (MQ Server name).

Click OK (Notice that the configure button now shows configured.)

Press Add, and the main window now has the definition you just made.

For a shortcut to detailed information, expand the Server into Channels, Processes, and Queues. Double Click Queues. Double click on a specific queue to see detailed information on that queue. (See below.) Or get to the queue via the Commands menu bar item.

Click Commands on the menu bar and a list of operations is displayed. Click Queue List and press Refresh of the Queue List window. A list of queues is displayed. Double click one of the queues to see its statistics.

Following is a display of a queue. Note that 2 messages are queued and there is one user that has it opened for write and one for read.

To actually see what is in a queue, click the Browse button.

When Messages Don’t Show Up Where Expected

The Dead Letter Queue may contain clues as to what happened. The following steps are described above.

1) Use the main window of the Monitor Program to display the queues for the Queue Manager in question.

2) Select the Dead Letter Queue.

3) Click the Browse tab on the bottom of the queue list window.

4) If your message is in the queue, highlight it and press the Open tab.

5) This will display a Reason Code, Destination Queue, Destination Queue Manager, Format, and part of the message.

Peruse the information for any clues to why the message is in the Dead Letter Queue.

IBM Mainframe Queue Access

There is usually no Queue Administrator available on the mainframe. This means mainframe tools must be used to access those queues.

The Mainframe Support Account

To access mainframe queues, you need a mainframe account. To do this go to your Lotus Notes desktop. You should have an ICON for Electronic Forms. Click on it and, when there, do a search for 'MVS'. You want the form 'MVS Userid Request Form for ME Systems Only'. Print the form and fill it out by entering your information at the top. Under Job Function, be sure to include MQ Support. Ask your TSO RACF Administrator for the group into which you should be placed (i.e. MQCORPNAME RACF) and include that under job function as well. Also ask that administrator for the Usage Accounting Number and enter that near the bottom of the form. Check A22TSO. Have your supervisor approve the request on the bottom of the form. Then Fax it to the number on the form. You will be notified when you are setup.

Using TN3270

When using TN3270 from a workstation, set up the connect screen as follows. The Terminal Type should be 3279.

Once you get connected to the mainframe, the following logon message will display.

TSO

Enter the TSO name followed by your User ID. If you don’t enter the User ID, you will be prompted to enter it. For example, ATSO MACY.

Next, enter your password. The first time you log on to TSO, you will be asked to enter a new password. You will asked to enter it a second time as a means of verification.

The next screen to appear requires that you press Enter again to get to the primary menu.

At the ISPF Primary Option Menu, select D.

On the Development Tools menu, select Q for the MQ utility.

Using the MQ Utility

In the following panels, selecting the End or Exit Function Keys will exit the utility. Pressing the Cancel Key (F12) will go back to the previous panel.

Four options are available.

B – will let you browse the contents of a Queue Manager’s Queues.

C – will let you issue MQM commands. This is seldom used.

D – will let you look into the Dead Letter Queue

OC – gives some general information of MQ objects

This utility package is described in IBM documentation at:

IBM TSO MQ Support Utility Documentation

Operations and Control Panel

OC gives the user access to queue status.

If you press Enter with an * in the Name input field right below the Object Type field, a list of the available objects of that type is presented. If you don’t know what Object types are available to look at, place the cursor on the Object Type input field and press F4 (Prompt). Select the object desired and press Enter. Usually that is Queue, but it could be Channel, or a number of other possibilities. This will take you back a panel and enter the selected object in the field.

If from the above 2 panels you select to view a queue, either by specifying the name or selecting from a list of the queues, (done by choosing to Display and pressing Enter) the following panel is presented:

In this display, the Output and Input use counts show the number of tasks that have the open for output or open for input respectively. The Current Queue Depth is the number of queued messages.

The Browse Panel

Choosing the B option from the list of MQ options will let you look at the data in the messages.

On this screen enter the Queue Manager and the Queue Name. Use the OC screen to get a list of queues if they are unknown. Press Enter.

By scrolling to the right, the data in the queue can be perused. To see the data in Hex, enter Hex at the command prompt and press Enter.

For data going to IMS, the MQIIH header is also shown. From left to right, assuming MQMD Display ==> is set to on, the data is shown as Message Descriptor, Dead Letter Header (if the DLQ is being displayed), the MQIIH (begins with “IIH “), and the message.

The DLQ Panel

Choosing the D (Dead Letter Queue) option from the list of MQ options will let you look at the Dead Letter Queue in a special way. By pressing Enter you can step through the messages with the following panel display: What you see is the Dead Letter Header information followed by the message text. There is not a way to display the text as Hex.

How to Setup an IBM MQ Environment

IMS OTMA Bridge Parameters

Description

These are the OTMA-related parameters that you must specify in IMS PROCLIB member DFSPBxxx:

GRNAME=

Specifies the XCF group IMS is to join. The group name is one to eight uppercase alphanumeric characters or other valid characters ($, @).

IMS joins the XCF group either during IMS initialization (if OTMA=Y is specified) or as a result of an IMS /START OTMA command. If GRNAME= is not specified and OTMA=N is specified, IMS cannot join the XCF group.

If you specify GRNAME= and OTMA is started, you can use the /DISPLAY OTMA

command to display the XCF status. You are not required to define any XCF information.

All OTMA clients must know the XCF group name. The group name for the OTMA clients and the IMS server must be the same.

If you use RACF for security, the IMSXCF.group.member (client member name) must be defined in the RACF FACILITY class.

OTMA=

Specifies whether OTMA is to be enabled. Values are Y|N. The default is N.

If you specify a valid group name for GRNAME=, you can use the /START OTMA command to enable OTMA later, even if you specify OTMA=N during system definition.

OTMAASY=

Specifies that a non-response transaction originating from a program-to-program switch be scheduled asynchronously. This parameter is for send-then-commit messages only. A DFS2082 message is not issued for a transaction scheduled asynchronously.

OTMAASY= can also be used in a multiple program-to-program switch environment to ensure that only the response transaction be scheduled synchronously.

The default is OTMAASY=N.

OTMANM=

Specifies the XCF member name that IMS uses for the group when IMS is not using XRF or RSR. The member name is 1 to 16 uppercase alphanumeric characters or other valid characters ($, @).

The OTMANM name can be specified in the IMS procedure or in the DFSPBxxx member. If OTMANM is not specified, IMS uses the IMS APPLID for the member name.

If IMS is using XRF or RSR, the XCF member name that IMS uses comes from the USERVAR name specified in the IMS procedure, in the DFSPBxxx member, or in the DFSHSBxx member. The OTMANM name is not used in this case.

Recommendation: Do not change the group name or the IMS member name during an IMS emergency or normal restart.

OTMAMD=

Specifies whether you want to have the member override function in the DFSYPRX0 user exit for a transaction invoked from an OTMA client. The parameter values are Y (Yes) or N (No). N means that for transactions that are invoked from a non-OTMA lterm, you can use the 16-byte member override field of the user exit parameter list to specify the OTMA client member name. You cannot, however, use the member override field for transactions that are invoked from an OTMA client. N is the default setting for the OTMAMD parameter. Y means that you can use the member override field of the user exit parameter list for both OTMA and non-OTMA invoked transactions.

OTMASP=

Using the OTMASP parameter provides the same function as setting the output flag of the OTMA destination resolution exit DFSYDRU0. Using an output flag in DFSYDRU0 indicates whether a synchronized tpipe needs to be created for OTMA output. If the only reason you code DFSYDRU0 is to set that output flag, you can use the OTMASP parameter instead. The OTMASP parameter values are Y (Yes) or N (No). N, which is the default, means that non-synchronized tpipes are to be created for the OTMA output. Y means that synchronized tpipes are to be created for OTMA output. If your organization uses both the DFSYDRU0 exit and the OTMASP parameter to control the kind of tpipe that gets created for OTMA output, the following table shows when synchronized tpipes will get created.

Table 8. Tpipes created when both OTMASP parameter and DFYDRU0 exit used

DFSYDRU0 is set to...	If OTMASP=Y, result is...	If OTMASP=N, result is...
Create synchronized tpipe	Synchronized tpipe	Synchronized tpipe
Create non-synchronized tpipe	Synchronized tpipe	Non-synchronized tpipe

OTMASE=

Specifies the type of OTMA RACF security that you want to use, if any. The

parameter values are as follows:

C OTMA RACF security is CHECK. IMS commands are checked against the CIMS class. IMS transactions are checked against the TIMS class.

F OTMA RACF security is FULL. The same type of security as CHECK, but additional checking is performed against dependent regions. F is the default value for the OTMASE parameter.

N OTMA RACF security is NONE. No calls to RACF are made.

P OTMA RACF security is PROFILE. Each OTMA message defines the level of security checking to be done.

Important: The /SECURE OTMA command overrides the value specified in the

OTMASE parameter.

Definitions

These parameters are specified in IMS PROCLIB member DFSPB00P:

Parameter	IMST	IMSP
GRNAME	MQSIMST	MQSIMSP
OTMA	Y	Y
OTMAASY	N	N
OTMANM	THEMIMSP	PIMS	IMST val will soon become TIMS
OTMAMD	N	N
OTMASP	Y	Y
OTMASE	N	N

· OTMASE options are C, F, N, P and specify security checking. For production we will leave this NO until we test this in TIMS.

· OTMANM on test is temporarily set to THEMIMSP but will be IMST.

MQ Parameters

MQ-Series Server Configuration

At ME, queues are managed by TTS. However, TTS does not support MQ-Series. Therefore, MQ-Series Servers are configured by scripts received from the MQ-Series support group in Rochester. The are sent to TTS. That group then executes the scripts to define the queues and channels. Here is a sample script to define a local and remote queue.

DEFINE QLOCAL ('Queue name’) +

DESCR('LU6.2 replacement - Receive from IMS for Appl, Application XYZ') +

PUT(ENABLED) +

DEFPRTY(0) +

DEFPSIST(YES) +

SCOPE(QMGR) +

GET(ENABLED) +

MAXDEPTH(150000) +

MAXMSGL(4194304) +

SHARE +

DEFSOPT(SHARED) +

MSGDLVSQ(FIFO) +

NOHARDENBO +

USAGE(XMITQ) +

TRIGGER +

TRIGTYPE(FIRST) +

TRIGDPTH(1) +

TRIGMPRI(0) +

TRIGDATA(' ') +

PROCESS(' ') +

INITQ(' ') +

RETINTVL(999999999) +

BOTHRESH(0) +

BOQNAME(' ') +

QDEPTHHI(80) +

QDEPTHLO(20) +

QDPMAXEV(ENABLED) +

QDPHIEV(DISABLED) +

QDPLOEV(DISABLED) +

QSVCINT(999999999) +

QSVCIEV(NONE) +

REPLACE

DEFINE QREMOTE('Queue Name') +

DESCR('LU6.2 replacement - Send to IMS from Appl, Application XYZ') +

PUT(ENABLED) +

DEFPRTY(0) +

DEFPSIST(YES) +

SCOPE(QMGR) +

XMITQ('Transmit Qname') +

RNAME('Receive Queue Name’) +

RQMNAME('MQn') +

REPLACE

Here is a sample channel definition script.

DEFINE CHANNEL ('MQn.MEMQSRVR_1') CHLTYPE(RCVR) +

TRPTYPE(TCP) +

DESCR('Receiver Channel from MQn IMSApplName QMgr') +

MAXMSGL(4194304) +

MSGDATA(' ') +

MSGEXIT(' ') +

RCVDATA(' ') +

RCVEXIT(' ') +

SCYDATA(' ') +

SCYEXIT(' ') +

SENDDATA(' ') +

SENDEXIT(' ') +

BATCHSZ(50) +

SEQWRAP(999999999) +

MCAUSER(' ') +

NPMSPEED(NORMAL) +

PUTAUT(DEF) +

REPLACE

DEFINE CHANNEL (‘Channel Name’) CHLTYPE(SDR) +

TRPTYPE(TCP) +

DESCR('Sender Channel to MQn IMS Prod QMgr') +

MAXMSGL(4194304) +

MSGDATA(' ') +

MSGEXIT(' ') +

RCVDATA(' ') +

RCVEXIT(' ') +

SCYDATA(' ') +

SCYEXIT(' ') +

SENDDATA(' ') +

SENDEXIT(' ') +

XMITQ('Transmit Queue for this Channel') +

CONVERT(YES) +

DISCINT(1200) +

LONGRTY(999999999) +

LONGTMR(1200) +

SHORTRTY(10) +

SHORTTMR(60) +

CONNAME('192.232.77.145(1416)') +

NPMSPEED(NORMAL) +

USERID(' ') +

BATCHSZ(50) +

SEQWRAP(999999999) +

MCATYPE(PROCESS) +

MCAUSER(' ') +

REPLACE

Conversion

When ASCII / EBCDIC conversion is required, the queue definition CONVERT parameter (see above) must be set to YES on the MQ channel.

Storage Class

In MVS, when MQ is configured, page sets (or VSAM files) are allocated for storing messages. The storage class points to the page set. On the queue definition, the storage class to be used is specified. The IMS Bridge is "aware" of this storage class.

Parameter	IMST / MQm	IMSP / MQn
storage class	IMSTOTMA	IMSPOTMA

For Test, the following definition can be found using the IBM MQ Utility.

Storage class name . . . . . IMSTOTMA

Disposition . . . . . . . . : QMGR MQM7

Description . . . . . . . . : Storage class for IMST OTMA

interface

Page set identifier . . . . : 2

XCF group name . . . . . . : MQSIMST

XCF member name . . . . . . : TMEMIMSP

Last alteration time . . . : 2003-06-20 14.06.47

Storage class IMSPOTMA on MQM8 is defined with XCF group name of MQSIMSP and XCF Member name of PIMS which correspond to the production IMS region OTMA configuration.

If MQ is to start a CICS transaction when a message is queued, use the following utility input (See ME MQ Documentation CICS Utility file.) to define the queue as such:

An example of trigger definitions:

Trigger Definition

Trigger type . . . . . . . : F F=First, E=Every,D=Depth, N=None

Trigger set . . . . . . :Y Y=Yes, N=No

Trigger message priority :0 0 - 9

Trigger depth . . . . . :1 1 - 999999999

Trigger data . . . . . . :

Process name . . . . . . :APPL.nnnnnn.LBP0

Initiation queue . . . . :CICS01.INITQ

There is an MQ Process definition

Process name . . . . . . . . APPL.nnnnnn.LBP0

Disposition . . . . . . . . : QMGR MQn

Description . . . . . . . . :

Application type . . . . . : CICS

Application

ID . . . : LBP0

XCF Parameters

XCF is the MVS Xross systems Coupling Facility. It allows for one subsystem to communicate to other subsystems in a sysplex environment. A sysplex environment can be one MVS image or multiple MVS's joined as a single Sysplex.

TMEMIMSP PIMS

For XCF, we define in SYS1.PARMLIB(COUPLE00) the following way:

CLASSDEF CLASS(MQSOTMA0) CLASSLEN(2048) MAXMSG(750)

GROUP(MQSIMSP,MQSIMST)

This sets up the capability for OTMA and IMS to talk to MQ.

The start up parms in IMS's DFSPB00x, specify the same group name MQSIMSP and MQSIMST.

How MQ is set up to use XCF, I do not know.

CICS Connectivity

To make the CICS regions 'MQ aware', JCL and parameter changes are required.

Region parameters:

CICST

INITPARM=(CSQCPARM='SN=MQn,TN=001,IQ=CICSnn.INITQ')

CICS1ME

INITPARM=(CSQCPARM='SN=MQn,TN=001,IQ=CICS1ME.INITQ')

To the started task, add to the //STEPLIB concatenation

DD DSN=SYS1.MQM.SCSQANLE,DISP=SHR

DD DSN=SYS1.MQM.SCSQCICS,DISP=SHR

DD DSN=SYS1.MQM.MQn.SCSQAUTH,DISP=SHR

DD DSN=SYS1.MQM.SCSQAUTH,DISP=SHR

Using MEMQ to replace LU62

The ME MQ Class (meMQ.dll) was developed to be used as an integral part of an LU6.2 replacement package. However, the class also provides a simplified interface to MQ Series for users on Microsoft platforms.