1 unstable release
0.1.0 | Sep 10, 2024 |
---|
#256 in Asynchronous
1.5MB
34K
SLoC
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
-
As per
libmqm-sys
crate, download and install the redistributable client from IBM: https://ibm.biz/mq94redistclients -
Install the client in
/opt/mqm
or another location. -
Set the MQ_HOME environment variable to the installed location.
-
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
Feature | Description |
---|---|
link (default) | Support linking the MQ library at compile-time |
tracing | Add tracing to the MQI and MQAI calls using the tracing crate |
dlopen2 | Support loading the MQ library at run-time using dlopen2 |
mqai | Expose the MQAI functions |
pcf | Generate the PCF structures |
exits | Generate the exit structures |
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)
Dependencies
~2.5–4MB
~76K SLoC