API Docs

Note

Sponsored by Zato - Open-Source ESB, SOA, REST, APIs and Cloud Integrations in Python

PyMQI - Python MQI Wrapper Classes

These classes wrap the pymqe low level MQI calls. They present an OO interface with a passing resemblance MQI C++.

Classes are also provided for easy use of the MQI structure parameters (MQMD, MQGMO etc.) from Python. These allow Python scripts to set/get structure members by attribute, dictionary etc.

The classes are:

  • MQOpts - Base class for defining MQI parameter structures.
  • CD - MQI MQCD structure class
  • CMHO - MQI MQCMHO structure class
  • MD - MQI MQMD structure class
  • GMO - MQI MQGMO structure class.
  • IMPO - MQI MQIMPO structure class
  • OD - MQI MQOD structure class.
  • PD - MQI MQPD structure class.
  • PMO - MQI MQPMO structure class.
  • RFH2 - MQI MQRFH2 structure class.
  • SCO - MQI MQSCO structure class
  • SMPO - MQI MQSMPO structure class
  • SRO - MQI MQSRO structure class
  • SD - MQI MQSD structure class
  • TM - MQI MQTM structure class
  • TMC2- MQI MQTMC2 structure class
  • Filter/StringFilter/IntegerFilter - PCF/MQAI filters
  • QueueManager - Queue Manager operations
  • Queue - Queue operations
  • Topic - Publish/subscribe topic operations
  • Subscription - Publish/subscribe subscription operations
  • PCFExecute - Programmable Command Format operations
  • Error - Base class for pymqi errors.
  • MQMIError - MQI specific error
  • PYIFError - Pymqi error

The following MQI operations are supported:

  • MQCONN, MQDISC (QueueManager.connect()/QueueManager.disconnect())
  • MQCONNX (QueueManager.connectWithOptions())
  • MQOPEN/MQCLOSE (Queue.open(), Queue.close(), Topic.open(), Topic.close())
  • MQPUT/MQPUT1/MQGET (Queue.put(), QueueManager.put1(), Queue.get())
  • MQCMIT/MQBACK (QueueManager.commit()/QueueManager.backout())
  • MQBEGIN (QueueuManager.begin())
  • MQINQ (QueueManager.inquire(), Queue.inquire())
  • MQSET (Queue.set())
  • MQSUB (Subscription.sub())
  • And various MQAI PCF commands.

The supported command levels (from 5.0 onwards) for the version of MQI linked with this module are available in the tuple pymqi.__mqlevels__. For a client build, pymqi.__mqbuild__ is set to the string ‘client’, otherwise it is set to ‘server’.

To use this package, connect to the Queue Manager (using QueueManager.connect()), then open a queue (using Queue.open()). You may then put or get messages on the queue (using Queue.put(), Queue.get()), as required.

Where possible, pymqi assumes the MQI defaults for all parameters.

Like MQI C++, pymqi can defer a queue connect until the put/get call.

Pymqi maps all MQI warning & error status to the MQMIError exception. Errors detected by pymqi itself raise the PYIFError exception. Both these exceptions are subclasses of the Error class.

MQI constants are defined in the CMQC module. PCF constants are defined in CMQCFC.

PCF commands and inquiries are executed by calling a MQCMD_* method on an instance of a PCFExecute object.

Pymqi is thread safe. Pymqi objects have the same thread scope as their MQI counterparts.

class pymqi.ByteString(value)

A simple wrapper around string values, suitable for passing into PyMQI calls wherever IBM’s docs state a ‘byte string’ object should be passed in.

pymqi.CD

alias of cd

class pymqi.CMHO(**kw)

CMHO(**kw)

Construct an MQCMHO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

exception pymqi.Error

Base class for all pymqi exceptions.

class pymqi.Filter(selector)

The user-facing MQAI filtering class which provides syntactic sugar on top of pymqi._Filter and its base classes.

class pymqi.FilterOperator(pub_filter)

Creates low-level filters basing on what’s been provided in the high-level pymqi.Filter object.

operator_mapping = {'greater': 4, 'less': 1, 'not_greater': 3, 'contains_gen': 26, 'excludes': 13, 'not_like': 21, 'like': 18, 'contains': 10, 'equal': 2, 'excludes_gen': 29, 'not_less': 6, 'not_equal': 5}
pymqi.GMO

alias of gmo

class pymqi.IMPO(**kw)

IMPO(**kw)

Construct an MQIMPO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.IntegerFilter(selector, value, operator)

A subclass of pymqi._Filter suitable for passing MQAI integer filters around.

pymqi.MD

alias of md

exception pymqi.MQMIError(comp, reason)

Exception class for MQI low level errors.

errStringDicts = (<pymqi._MQConst2String instance at 0x2b5cf8512a70>, <pymqi._MQConst2String instance at 0x2b5cf8512ab8>)
errorAsString()

Return the exception object MQI warning/failed reason as its mnemonic string.

class pymqi.MQOpts(list, **kw)

Base class for packing/unpacking MQI Option structures. It is constructed with a list defining the member/attribute name, default value (from the CMQC module) and the member pack format (see the struct module for the formats). The list format is:

[[‘Member0’, CMQC.DEFAULT_VAL0, ‘fmt1’]
[‘Member1’, CMQC.DEFAULT_VAL1, ‘fmt2’]
...

]

MQOpts defines common methods to allow structure members to be set/get as attributes (foo.Member0 = 42), set/get as dictionary items (foo[‘Member0’] = 42) or set as keywords (foo.set(Member0 = 42, Member1 = ‘flipperhat’). The ctor can be passed an optional keyword list to initialize the structure members to non-default values. The get methods returns all attributes as a dictionary.

The pack() method packs all members into a ‘C’ structure according to the format specifiers passed to the ctor. The packing order is as specified in the list passed to the ctor. Pack returns a string buffer, which can be passed directly to the MQI ‘C’ calls.

The unpack() method does the opposite of pack. It unpacks a string buffer into an MQOpts instance.

Applications are not expected to use MQOpts directly. Instead, MQOpts is sub-classed as particular MQI structures.

get()

Return a dictionary of the current structure member values. The dictionary is keyed by a ‘C’ member name.

get_length()

Returns the length of the (would be) packed buffer.

get_vs(vs_name)

This method returns the string to which the VSPtr pointer points to.

pack()

Pack the attributes into a ‘C’ structure to be passed to MQI calls. The pack order is as defined to the MQOpts ctor. Returns the structure as a string buffer

set(**kw)

Set a structure member using the keyword dictionary ‘kw’. An AttributeError exception is raised for invalid member names.

set_vs(vs_name, vs_value, vs_offset, vs_buffer_size, vs_ccsid)

This method aids in the setting of the MQCHARV (variable length string) types in MQ structures. The type contains a pointer to a variable length string. A common example of a MQCHARV type is the ObjectString in the MQOD structure. In pymqi the ObjectString is defined as 5 separate elements (as per MQCHARV): ObjectStringVSPtr - Pointer ObjectStringVSOffset - Long ObjectStringVSBufSize - Long ObjectStringVSLength - Long ObjectStringVSCCSID - Long

unpack(buff)

Unpack a ‘C’ structure ‘buff’ into self.

class pymqi.MessageHandle(qmgr=None, cmho=None)

A higher-level wrapper around the MQI’s native MQCMHO structure.

default_value_length = 64
pymqi.OD

alias of od

class pymqi.PCFExecute(name='')

Send PCF commands or inquiries using the MQAI interface. PCFExecute must be connected to the Queue Manager (using one of the techniques inherited from QueueManager) before its used. PCF commands are executed by calling a CMQCFC defined MQCMD_* method on the object.

caStringDict = <pymqi._MQConst2String instance at 0x2b5cf8512ef0>
iaStringDict = <pymqi._MQConst2String instance at 0x2b5cf8512ea8>
stringifyKeys(rawDict)

Return a copy of rawDict with its keys converted to string mnemonics, as defined in CMQC.

stringify_keys(rawDict)

stringifyKeys(rawDict)

Return a copy of rawDict with its keys converted to string mnemonics, as defined in CMQC.

class pymqi.PD(**kw)

CMHO(**kw)

Construct an MQPD Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

pymqi.PMO

alias of pmo

exception pymqi.PYIFError(e)

Exception class for errors generated by pymqi.

class pymqi.Queue(qMgr, *opts)

Queue encapsulates all the Queue I/O operations, including open/close and get/put. A QueueManager object must be already connected. The Queue may be opened implicitly on construction, or the open may be deferred until a call to open(), put() or get(). The Queue to open is identified either by a queue name string (in which case a default MQOD structure is created using that name), or by passing a ready constructed MQOD class.

close([options])

Close a queue, using options.

get([maxLength[, mDesc, getOpts]])

Return a message from the queue. If the queue is not already open, it is opened now with the option ‘MQOO_INPUT_AS_Q_DEF’.

maxLength, if present, specifies the maximum length for the message. If the message received exceeds maxLength, then the behavior is as defined by MQI and the getOpts argument.

If maxLength is not specified, or is None, then the entire message is returned regardless of its size. This may require multiple calls to the underlying MQGET API.

mDesc is the pymqi.md() MQMD Message Descriptor for receiving the message. If it is not passed, or is None, then a default md() object is used.

getOpts is the pymqi.gmo() MQGMO Get Message Options structure for the get call. If it is not passed, or is None, then a default gmo() object is used.

If mDesc and/or getOpts arguments were supplied, they may be updated by the get operation.

get_handle()

Get the queue handle.

get_rfh2([maxLength[, mDesc, getOpts[, rfh2_header_1]]])

Get a message and attempt to unpack the rfh2 headers. opts[2] should be a empty list. Unpacking only attempted if Format in previous header is CMQC.MQFMT_RF_HEADER_2.

inquire(attribute)

Inquire on queue ‘attribute’. If the queue is not already open, it is opened for Inquire. Returns either the integer or string value for the attribute.

open(qDesc[, openOpts])

Open the Queue specified by qDesc. qDesc identifies the Queue either by name (if its a string), or by MQOD (if its a pymqi.od() instance). If openOpts is passed, it defines the Queue open options, and the Queue is opened immediately. If openOpts is not passed, the Queue open is deferred until a subsequent put() or get() call.

put(msg[, mDesc, putOpts])

Put the string buffer ‘msg’ on the queue. If the queue is not already open, it is opened now with the option ‘MQOO_OUTPUT’.

mDesc is the pymqi.md() MQMD Message Descriptor for the message. If it is not passed, or is None, then a default md() object is used.

putOpts is the pymqi.pmo() MQPMO Put Message Options structure for the put call. If it is not passed, or is None, then a default pmo() object is used.

If mDesc and/or putOpts arguments were supplied, they may be updated by the put operation.

put_rfh2(msg[, mDesc, putOpts[, rfh2_header]])

Put a RFH2 message. opts[2] is a list of RFH2 headers. MQMD and RFH2’s must be correct.

set(attribute, arg)

Sets the Queue attribute to arg.

set_handle(queue_handle)

Sets the queue handle in the case when a handl;e was returned from a previous MQ call.

class pymqi.QueueManager(name='')

QueueManager encapsulates the connection to the Queue Manager. By default, the Queue Manager is implicitly connected. If required, the connection may be deferred until a call to connect().

backout()

Backout any outstanding gets/puts in the current unit of work.

begin()

Begin a new global transaction.

commit()

Commits any outstanding gets/puts in the current unit of work.

connect(name)

Connect immediately to the Queue Manager ‘name’.

connectTCPClient(name, cd, channel, conn_name, user, password)

Connect immediately to the remote Queue Manager ‘name’, using a TCP Client connection, with channnel ‘channel’ and the TCP connection string ‘conn_name’. All other connection optons come from ‘cd’.

connectWithOptions(name [, opts=cnoopts][ ,cd=mqcd][ ,sco=mqsco])

connectWithOptions(name, cd, [sco])

Connect immediately to the Queue Manager ‘name’, using the optional MQCNO Options opts, the optional MQCD connection descriptor cd and the optional MQSCO SSL options sco.

The second form is defined for backward compatibility with older (broken) versions of pymqi. It connects immediately to the Queue Manager ‘name’, using the MQCD connection descriptor cd and the optional MQSCO SSL options sco.

connect_tcp_client(name, cd, channel, conn_name, user, password)

Connect immediately to the remote Queue Manager ‘name’, using a TCP Client connection, with channnel ‘channel’ and the TCP connection string ‘conn_name’. All other connection optons come from ‘cd’.

connect_with_options(name, *bwopts, **kw)
connectWithOptions(name [, opts=cnoopts][ ,cd=mqcd][ ,sco=mqsco])
connectWithOptions(name, cd, [sco])

Connect immediately to the Queue Manager ‘name’, using the optional MQCNO Options opts, the optional MQCD connection descriptor cd and the optional MQSCO SSL options sco.

The second form is defined for backward compatibility with older (broken) versions of pymqi. It connects immediately to the Queue Manager ‘name’, using the MQCD connection descriptor cd and the optional MQSCO SSL options sco.

disconnect()

Disconnect from queue manager, if connected.

getHandle()

Get the queue manager handle. The handle is used for other pymqi calls.

get_handle()

getHandle()

Get the queue manager handle. The handle is used for other pymqi calls.

inquire(attribute)

Inquire on queue manager ‘attribute’. Returns either the integer or string value for the attribute.

is_connected

Try pinging the queue manager in order to see whether the application is connected to it. Note that the method is merely a convienece wrapper around MQCMD_PING_Q_MGR, in particular, there’s still possibility that the app will disconnect between checking QueueManager.is_connected and the next MQ call.

put1(qDesc, msg[, mDesc, putOpts])

Put the single message in string buffer ‘msg’ on the queue using the MQI PUT1 call. This encapsulates calls to MQOPEN, MQPUT and MQCLOSE. put1 is the optimal way to put a single message on a queue.

qDesc identifies the Queue either by name (if its a string), or by MQOD (if its a pymqi.od() instance).

mDesc is the pymqi.md() MQMD Message Descriptor for the message. If it is not passed, or is None, then a default md() object is used.

putOpts is the pymqi.pmo() MQPMO Put Message Options structure for the put1 call. If it is not passed, or is None, then a default pmo() object is used.

If mDesc and/or putOpts arguments were supplied, they may be updated by the put1 operation.

class pymqi.RFH2(**kw)

RFH2(**kw)

Construct a RFH2 Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’. Attempt to parse the RFH2 when unpack is called.

add_folder(folder_data)

Adds a new XML folder to the RFH2 header. Checks if the XML is well formed and updates self.StrucLength.

big_endian_encodings = [1, 16, 256, 768, 17, 257, 272, 273]
initial_opts = [['StrucId', 'RFH ', '4s'], ['Version', 2, 'i'], ['StrucLength', 0, 'i'], ['Encoding', 546, 'i'], ['CodedCharSetId', 0, 'i'], ['Format', ' ', '8s'], ['Flags', 0, 'i'], ['NameValueCCSID', 0, 'i']]
pack(encoding)

Override pack in order to set correct numeric encoding in the format.

unpack(buff, encoding)

Override unpack in order to extract and parse RFH2 folders. Encoding meant to come from the MQMD.

pymqi.SCO

alias of sco

class pymqi.SD(**kw)

SD(**kw)

Construct a MQSD Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.SMPO(**kw)

SMPO(**kw)

Construct an MQSMPO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.SRO(**kw)

SRO(**kw)

Construct a MQSRO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.StringFilter(selector, value, operator)

A subclass of pymqi._Filter suitable for passing MQAI string filters around.

class pymqi.Subscription(queue_manager, sub_desc=None, sub_name=None, sub_queue=None, sub_opts=None, topic_name=None, topic_string=None)
Subscription(queue_manager, sub_descm sub_name, sub_queue, topic_name,
topic_string)

Subscription encapsulates a subscription to a topic.

close(sub_close_options=0, close_sub_queue=False, close_sub_queue_options=0)
get(max_length=None, *opts)

Get a publication from the Queue.

get_sub_queue()

Return the subscription queue.

sub(sub_desc, sub_queue)

Subscribe to a topic, alter or resume a subscription. Executes the MQSUB call with parameters. The subscription queue can be either passed as a Queue object or a Queue object handle.

class pymqi.TM(**kw)

TM(**kw)

Construct a MQTM Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.TMC2(**kw)

TMC2(**kw)

Construct a MQTMC2 Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.Topic(queue_manager, topic_name=None, topic_string=None, topic_desc=None, open_opts=None)

Topic(queue_manager, topic_name, topic_string, topic_desc, open_opts)

Topic encapsulates all the Topic I/O operations, including publish/subscribe. A QueueManager object must be already connected. The Topic may be opened implicitly on construction, or the open may be deferred until a call to open(), pub() or (The same as for Queue).

The Topic to open is identified either by a topic name and/or a topic string (in which case a default MQOD structure is created using those names), or by passing a ready constructed MQOD class. Refer to the “Using topic strings” section in the MQ7 Information Center for an explanation of how the topic name and topic string is combined to identify a particular topic.

close([options])

Close the topic, using options.

open(topic_name, topic_string, topic_desc, open_opts)

Open the Topic specified by topic_desc or create a object descriptor from topic_name and topic_string. If open_opts is passed, it defines the Topic open options, and the Topic is opened immediately. If open_opts is not passed, the Topic open is deferred until a subsequent pub() call.

pub(msg[, msg_desc, put_opts])

Publish the string buffer ‘msg’ to the Topic. If the Topic is not already open, it is opened now. with the option ‘MQOO_OUTPUT’.

msg_desc is the pymqi.md() MQMD Message Descriptor for the message. If it is not passed, or is None, then a default md() object is used.

put_opts is the pymqi.pmo() MQPMO Put Message Options structure for the put call. If it is not passed, or is None, then a default pmo() object is used.

If msg_desc and/or put_opts arguments were supplied, they may be updated by the put operation.

sub(sub_desc, sub_queue)

Subscribe to the topic and return a Subscription object. A subscription to a topic can be made using an existing queue, either by pasing a Queue object or a string at which case the queue will be opened with default options.

class pymqi.cd(**kw)

cd(**kw)

Construct a MQCD Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

pymqi.commonQArgs(*opts)

Process args common to put/get/put1. Module Private.

pymqi.common_q_args(*opts)

Process args common to put/get/put1. Module Private.

pymqi.connect(queue_manager, channel=None, conn_info=None, user=None, password=None)

A convenience wrapper for connecting to MQ queue managers. If given the ‘queue_manager’ parameter only, will try connecting to it in bindings mode. If given both ‘channel’ and ‘conn_info’ will connect in client mode. A pymqi.QueueManager is returned on successfully establishing a connection.

class pymqi.gmo(**kw)

gmo(**kw)

Construct a MQGMO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

pymqi.makeQDesc(qDescOrString)

Maybe make MQOD from string. Module Private

pymqi.make_q_desc(qDescOrString)

Maybe make MQOD from string. Module Private

class pymqi.md(**kw)

md(**kw)

Construct a MQMD Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.od(**kw)

od(**kw)

Construct a MQOD Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.pmo(**kw)

pmo(**kw)

Construct a MQPMO Structure with default values as per MQI. The default values may be overridden by the optional keyword arguments ‘kw’.

class pymqi.sco(**kw)

sco(**kw)

Construct a MQSCO Structure with default values as per MQI. The default values maybe overridden by the optional keyword arguments ‘kw’.


Previous topic

Mingw32

This Page