About IBM MQ Automation Classes for ActiveX classes

Read this information alongside the reference topics under Developing applications reference.

See Features that can be used only with the primary installation on Windows for important information.

The MQSession class provides a root object that contains the status of the last action performed on any of the MQAX objects. See Error handling for more information.

The MQQueueManager and MQQueue classes provide access to the underlying IBM MQ objects. Methods or property accesses for these classes in general result in calls being made across the IBM MQ MQI.

The MQMessage, MQPutMessageOptions, and MQGetMessageOptions classes encapsulate the MQMD, MQPMO, and MQGMO data structures, and are used to help you send messages to queues and retrieve messages from them.

The MQDistributionList class encapsulates a collection of queues - local, remote, or alias for output. The MQDistributionListItem class encapsulates the MQOR, MQRR, and MQPMR structures and associates them with an owning distribution list.


Parameter passing

Parameters on method invocations are all passed by value, except where that parameter is an object, in which case it is a reference that is passed.

The class definitions provided list the Data Type for each parameter or property. For many ActiveX clients, such as Visual Basic, if the variable used is not of the required type, the value is automatically converted to or from the required type - providing such a conversion is possible. This follows standard rules of the client; MQAX provides no such conversion.

Many of the methods take fixed-length string parameters, or return a fixed-length character string. The conversion rules are as follows:

  • If the user supplies a fixed-length string of the wrong length, as an input parameter or as a return value, the value is truncated or padded with trailing spaces as required.
  • If the user supplies a variable-length string of the wrong length as an input parameter, the value is truncated or padded with trailing spaces.
  • If the user supplies a variable-length string of the wrong length as a return value, the string is adjusted to the required length (because returning a value destroys the previous value in the string anyway).
  • Strings provided as input parameters can contain embedded Nulls.

These classes can be found in the MQAX200 library.


Object access methods

These methods do not relate directly to any single IBM MQ call. Each of these methods creates an object in which reference information is then held, followed by connecting to or opening an IBM MQ object:

When a connection is made to a queue manager, it holds the 'connection handle' attribute generated by IBM MQ.

When a queue is opened, it holds the 'object handle' attribute generated by IBM MQ.

These IBM MQ attributes are not directly available to the MQAX program.


Errors

Syntactic errors on parameter passing can be detected at compile time and run time by the ActiveX client. Errors can be trapped using On Error in Visual Basic.

The IBM MQ ActiveX classes all contain two special read-only properties - ReasonCode and CompletionCode. These properties can be read at any time.

An attempt to access any other property, or to issue any method call might generate an error from IBM MQ.

If a property set or method invocation succeeds, the ReasonCode of the owning object is set to MQRC_NONE and CompletionCode is set to MQCC_OK.

If the property access or method invocation does not succeed, reason and completion codes are set in these fields.