mqi

Idiomatic Rust API's to the IBM® MQ Interface (MQI) and MQ Administration Interface (MQAI).

You can use mqi to:

• Connect to an IBM MQ server to send and receive MQ messages through the MQI functions
• Administer IBM MQ server through the MQAI functions

This crate depends and the libmqm-sys crate for connectivity to MQ queue managers. The underlying connection uses the IBM supplied MQ libraries, offering proven stability and performance.

Usage

1. As per libmqm-sys crate, download and install the redistributable client from IBM: https://ibm.biz/mq94redistclients

2. Install the client in /opt/mqm or another location.

3. Set the MQ_HOME environment variable to the installed location.

4. Add the following to your Cargo.toml

   [dependencies]
   mqi = "0.1.0"
   

Example

Connect to the default queue manager using the MQSERVER environment variable.

use std::error::Error;
use mqi::{
    prelude::*,
    connect_options::{ApplName, Credentials},
    mqstr,
    types::QueueName,
    QueueManager,
};

fn main() -> Result<(), Box<dyn Error>> {
    const TARGET: QueueName = QueueName(mqstr!("DEV.QUEUE.1"));

    // User credentials and application name.
    // MQI will use the C API defaults of using MQSERVER environment variable
    let connect_options = (ApplName(mqstr!("readme_example")), Credentials::user("user", "password"));

    // Connect to the queue manager. Make all MQ warnings as a rust Result::Err
    let queue_manager = QueueManager::connect(connect_options).warn_as_error()?;

    // Put a single string message on the target queue with no explicit put options. Discard any warnings.
    queue_manager.put_message(TARGET, (), "Hello").discard_warning()?;

    // Queue manager disconnect - this also happens automatically on Drop.
    queue_manager.disconnect().discard_warning()?;

    Ok(())
}

Refer to the examples folder for additional examples.

Goals

• Expose an ergonomic API over the IBM MQI libraries.
• Become the preferred API for developing MQ applications where performance and safety is the primary concern.
• Provide a simple layer over MQ to connect, send and receive MQ messages, whilst still allowing developers to tweak the advanced options that the MQI library provides.
• Use Rust features such as lifetimes, safety guarantees, strong type system and invariants for a robust API.

Feature flags

Status

This is under heavy development. The velocity of change to the API is high and is likely to evolve.

Support

There are no guarantees of compatibility with any future versions of the crate; the API is subject to change based on feedback and enhancements. Relentless refactoring may occur before a stable crate is released.

This crate is provided as-is with no guarantees of support or updates.

This crate is not approved, endorsed, acknowledged, or supported by IBM. You cannot use IBM formal support channels (Cases/PMRs) for assistance on the use of this crate.

Contributions

All feedback, suggestions, contributions and enhancements are welcome.

License

Licensed under

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)