Module pymqi

 
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.
    gmo - MQI MQGMO structure class.
    pmo - MQI MQPMO structure class.
    od - MQI MQOD structure class.
    md - MQI MQMD structure class.
    cd - MQI MQCD structure class
    sco - MQI MQSCO structure class

    QueueManager - Queue Manager operations.    
    Queue - Queue 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())
    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())
    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 MQOpts

 
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.

Function __init__

 
MQOpts(memberList [,**kw])

    Initialise the option structure. 'list' is a list of structure
    member names, default values and pack/unpack formats. 'kw' is an
    optional keyword dictionary that may be used to override default
    values set by MQOpts sub-classes.

Function pack

 
 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.

Function unpack

 
unpack(buff)

        Unpack a 'C' structure 'buff' into self.

Function set

 
set(**kw)

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

Function get

 
get()

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

Function __getitem__

 
__getitem__(key)

    Return the member value associated with key, as in print
    obj['Flop'].

Function __str__

 
__str__()

    Pretty Print Structure.

Function __repr__

 
__repr__()

    Return the packed buffer as a printable string.

Class od

 
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 gmo

 
gmo(**kw)

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

Class pmo

 
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 md

 
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 cd

 
cd(**kw)

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

Class sco

 
sco(**kw)

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

Class Error

 
Base class for all pymqi exceptions.

Class MQMIError

 
Exception class for MQI low level errors.

Function __init__

 
MQMIError(comp, reason)

    Construct the error object with MQI completion code 'comp' and
    reason code 'reason'.

Function __str__

 
__str__()

    Pretty print the exception object, including its mnemonic string.

Function errorAsString

 
errorAsString()

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

Class PYIFError

 
Exception class for errors generated by pymqi.

Function __init__

 
PYIFError(e)

    Construct the error object with error string 'e'.

Function __str__

 
__str__()

    Pretty print the exception object.

Class QueueManager

 
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().

Function __init__

 
QueueManager(name = '')

    Connect to the Queue Manager 'name' (default value ''). If
    'name' is None, don't connect now, but defer the connection
    until connect() is called."""

Function __del__

 
__del__()

    Disconnect the Queue Manager, if connected.

Function connect

 
connect(name)

        Connect immediately to the Queue Manager 'name'.

Function connectWithOptions

 
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.

Function connectTCPClient

 
connectTCPClient(name, cd, channelName, connectString)

        Connect immediately to the remote Queue Manager 'name', using
        a TCP Client connection, with channnel 'channelName' and the
        TCP connection string 'connectString'. All other connection
        optons come from 'cd'.

Function disconnect

 
disconnect()

        Disconnect from queue manager, if connected.

Function getHandle

 
getHandle()

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

Function begin

 
begin()

        Begin a new global transaction. 
	

Function commit

 
commit()

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

Function backout

 
backout()

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

Function put1

 

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.

Function Inquire

 

inquire(attribute)

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

Class Queue

 
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.

Function __init__

 
    Queue(qMgr, [qDesc [,openOpts]])

    Associate a Queue instance with the QueueManager object 'qMgr'
    and optionally open the Queue.

    If qDesc is passed, it identifies the Queue either by name (if
    its a string), or by MQOD (if its a pymqi.od() instance). If
    qDesc is not defined, then the Queue is not opened
    immediately, but deferred to a subsequent call to open().

    If openOpts is passed, it specifies queue open options, and
    the queue is opened immediately. If openOpts is not passed,
    the queue open is deferred to a subsequent call to open(),
    put() or get().

    The following table clarifies when the Queue is opened:

       qDesc  openOpts   When opened
         N       N       open()
         Y       N       open() or get() or put()
         Y       Y       Immediately

Function __del__

 
    __del__()

    Close the Queue, if it has been opened.

Function open

 
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.

Function close

 
close([options])
        
        Close a queue, using options.

Function put

 
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.

Function get

 
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.

Function Inquire

 

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.

Function Set

 
set(attribute, arg)

        Sets the Queue attribute to arg.

Class PCFExecute

 
Send PCF commands or enquiries 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.  """

Function __init__

 
PCFExecute(name = '')

        Connect to the Queue Manager 'name' (default value '') ready
        for a PCF command. If name is a QueueManager instance, it is
        used for the connection, otherwise a new connection is made.

Function MQCMD_*

 
MQCMD_*(attrDict)

        Execute the PCF command or inquiry, passing an an optional
        dictionary of MQ attributes.  The command must begin with
        MQCMD_, and must be one of those defined in the CMQCFC
        module. If attrDict is passed, its keys must be an attribute
        as defined in the CMQC or CMQCFC modules (MQCA_*, MQIA_*,
        MQCACH_* or MQIACH_*). The key value must be an int or string,
        as appropriate.

        If an inquiry is executed, a list of dictionaries (one per
        matching query) is returned. Each dictionary encodes the
        attributes and values of the object queried. The keys are as
        defined in the CMQC module (MQIA_*, MQCA_*), The values are
        strings or ints, as appropriate.

        If a command was executed, or no inquiry results are
        available, an empty listis returned.

Function stringifyKeys

 
stringifyKeys(rawDict)

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