### Linux Platform Setup

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Set up the MQI Node.js environment on Linux by sourcing setmqenv, updating LD_LIBRARY_PATH, and installing the npm package.

```bash
# Source setmqenv to set MQ environment variables
source /opt/mqm/bin/setmqenv -s
export LD_LIBRARY_PATH=/opt/mqm/lib64:$LD_LIBRARY_PATH

# Install package
npm install ibmmq
```

--------------------------------

### macOS Platform Setup

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Set up the MQI Node.js environment on macOS by installing via Homebrew or manually setting DYLD_LIBRARY_PATH and PATH, followed by installing the npm package.

```bash
# Install via Homebrew (recommended)
brew tap ibm-messaging/mq
brew install ibm-mq

# Or set manually
export DYLD_LIBRARY_PATH=/opt/mqm/lib64:$DYLD_LIBRARY_PATH
export PATH=/opt/mqm/bin:$PATH

npm install ibmmq
```

--------------------------------

### Windows Platform Setup

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Set up the MQI Node.js environment on Windows by running setmqenv.bat or setting the PATH environment variable manually, and then installing the npm package.

```cmd
REM Run setmqenv.bat or set manually
set PATH=C:\Program Files\IBM\MQ\bin64;%PATH%

REM Install package
npm install ibmmq
```

--------------------------------

### Basic Connection Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates establishing a basic connection to an IBM MQ queue manager.

```javascript
const MQ = require('ibmmq');

let qmgr = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  console.log('Connected to queue manager');
  // ... perform operations ...
} catch (e) {
  console.error('Connection failed:', e);
} finally {
  if (qmgr) {
    MQ.Disc(qmgr);
    console.log('Disconnected from queue manager');
  }
}
```

--------------------------------

### Synchronous Commit Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-transactions.md

Demonstrates how to perform a synchronous commit of a transaction. This includes beginning the transaction, performing get and put operations, and then committing the transaction. If an error occurs, the transaction is rolled back.

```javascript
const mq = require('ibmmq');

try {
  mq.Begin(qmr);
  
  // Get message from input queue
  const getBuffer = Buffer.alloc(1024);
  const getLen = mq.GetSync(inQueue, getmd, getgmo, getBuffer);
  
  // Process and put to output queue
  const processed = processMessage(getBuffer, getLen);
  mq.PutSync(outQueue, putmd, putpmo, processed);
  
  // Commit transaction
  mq.Cmit(qmr);
  console.log('Transaction committed successfully');
} catch (err) {
  console.error('Operation failed:', err.message);
  mq.Back(qmr); // Rollback
}
```

--------------------------------

### Example: With Security

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Shows how to connect to a queue manager with user ID and password authentication using MQCNO and MQCSP.

```APIDOC
## Example: With Security

### Description
Shows how to connect to a queue manager with user ID and password authentication using MQCNO and MQCSP.

### Code
```javascript
const cno = new mq.MQCNO();
const csp = new mq.MQCSP();
csp.UserId = 'appuser';
csp.Password = 'secret';
cno.SecurityParms = csp;

mq.Connx('QM1', cno, (err, qmr) => {
  if (!err) console.log('Connected with authentication');
});
```
```

--------------------------------

### Example: Open Queue

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Demonstrates how to use the MQOD structure to open a queue for input operations using the `mq.Open` function.

```APIDOC
## Example: Open Queue

### Description
Demonstrates how to use the MQOD structure to open a queue for input operations using the `mq.Open` function.

### Code
```javascript
const mq = require('ibmmq');

const od = new mq.MQOD();
od.ObjectType = mq.MQC.MQOT_Q;
od.ObjectName = 'MY.INPUT.QUEUE';

mq.Open(qmr, od, mq.MQC.MQOO_INPUT_SHARED, (err, obj) => {
  if (!err) console.log('Queue opened');
});
```
```

--------------------------------

### Install ibmmq Package

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/README.md

Installs the ibmmq package using npm. Ensure you are in the project directory.

```bash
mkdir <something>
cd <something>
npm install ibmmq
```

--------------------------------

### Example: Open Topic

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Illustrates how to configure the MQOD object to open a topic for publishing messages.

```APIDOC
## Example: Open Topic

### Description
Illustrates how to configure the MQOD object to open a topic for publishing messages.

### Code
```javascript
const od = new mq.MQOD();
od.ObjectType = mq.MQC.MQOT_TOPIC;
od.TopicString = 'news/finance/stocks';

mq.Open(qmr, od, mq.MQC.MQOO_OUTPUT, (err, obj) => {
  if (!err) console.log('Topic opened for publishing');
});
```
```

--------------------------------

### MQGMO Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQGMO structure for get message options.

```javascript
const MQ = require('ibmmq');

const gmo = {
  'Options': MQ.MQGMO_WAIT | MQ.MQGMO_ACCEPT_TRUNCATED_MSG | MQ.MQGMO_SYNCPOINT
};

// Use this gmo object when getting a message
// const msg = MQ.Get(qmgr, hObj, gmo);
```

--------------------------------

### MQCNO Constructor

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Initializes a new MQCNO object. No setup is required.

```javascript
const mq = require('ibmmq');

const cno = new mq.MQCNO();
```

--------------------------------

### Example: Local Connection

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Demonstrates how to establish a connection to a default local queue manager using MQCNO with default options.

```APIDOC
## Example: Local Connection

### Description
Demonstrates how to establish a connection to a default local queue manager using MQCNO with default options.

### Code
```javascript
const mq = require('ibmmq');

const cno = new mq.MQCNO();
cno.Options = mq.MQC.MQCNO_NONE;
// Connect to default local queue manager
mq.Connx('', cno, (err, qmr) => {
  if (!err) console.log('Connected to local queue manager');
});
```
```

--------------------------------

### Open Queue Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Demonstrates how to open a queue for shared input. Ensure the 'ibmmq' module is required and a queue manager is connected.

```javascript
const mq = require('ibmmq');

const od = new mq.MQOD();
od.ObjectType = mq.MQC.MQOT_Q;
od.ObjectName = 'MY.INPUT.QUEUE';

mq.Open(qmr, od, mq.MQC.MQOO_INPUT_SHARED, (err, obj) => {
  if (!err) console.log('Queue opened');
});
```

--------------------------------

### Example: Client Connection

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Illustrates how to configure and establish a client connection to a remote queue manager using MQCNO and MQCD.

```APIDOC
## Example: Client Connection

### Description
Illustrates how to configure and establish a client connection to a remote queue manager using MQCNO and MQCD.

### Code
```javascript
const cno = new mq.MQCNO();
cno.Options = mq.MQC.MQCNO_CLIENT_BINDING;

const cd = new mq.MQCD();
cd.ConnectionName = 'broker.example.com(1414)';
cd.ChannelName = 'DEV.APP.SVRCONN';
cno.ClientConn = cd;

mq.Connx('QM1', cno, (err, qmr) => {
  if (!err) console.log('Connected via client');
});
```
```

--------------------------------

### Initialize MQGMO Structure

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Creates a new instance of the MQGMO structure to define get message behavior.

```javascript
const gmo = new mq.MQGMO();
```

--------------------------------

### Open Topic Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Shows how to open a topic for output (publishing). The TopicString field is used to specify the topic path.

```javascript
const od = new mq.MQOD();
od.ObjectType = mq.MQC.MQOT_TOPIC;
od.TopicString = 'news/finance/stocks';

mq.Open(qmr, od, mq.MQC.MQOO_OUTPUT, (err, obj) => {
  if (!err) console.log('Topic opened for publishing');
});
```

--------------------------------

### Client Connection Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Establishes a client connection to a remote queue manager. Requires specifying connection details like host, port, and channel.

```javascript
const cno = new mq.MQCNO();
cno.Options = mq.MQC.MQCNO_CLIENT_BINDING;

const cd = new mq.MQCD();
cd.ConnectionName = 'broker.example.com(1414)';
cd.ChannelName = 'DEV.APP.SVRCONN';
cno.ClientConn = cd;

mq.Connx('QM1', cno, (err, qmr) => {
  if (!err) console.log('Connected via client');
});
```

--------------------------------

### Local Connection Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Connects to the default local queue manager using MQCNO_NONE. Requires the 'ibmmq' module.

```javascript
const mq = require('ibmmq');

const cno = new mq.MQCNO();
cno.Options = mq.MQC.MQCNO_NONE;
// Connect to default local queue manager
mq.Connx('', cno, (err, qmr) => {
  if (!err) console.log('Connected to local queue manager');
});
```

--------------------------------

### Using MQObject for Get Operation

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/types-and-constants.md

Shows how to use an MQObject instance, obtained from an Open callback, to perform a Get operation. This object is essential for interacting with opened MQ resources.

```javascript
mq.Open(qmr, od, mq.MQC.MQOO_INPUT_SHARED, (err, obj) => {
  if (!err) {
    // obj is MQObject instance
    const buffer = Buffer.alloc(1024);
    mq.GetSync(obj, md, gmo, buffer);
  }
});
```

--------------------------------

### MQAttr Usage Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-transactions.md

Demonstrates how to create MQAttr objects for inquiring about queue attributes and using the Inq function. The callback logs the retrieved values or an error.

```javascript
const attr1 = new mq.MQAttr(mq.MQC.MQIA_CURRENT_Q_DEPTH);
const attr2 = new mq.MQAttr(mq.MQC.MQIA_MAX_Q_DEPTH);
const selectors = [attr1, attr2];

mq.Inq(obj, selectors, (err) => {
  if (!err) {
    console.log('Current depth:', attr1.value);
    console.log('Max depth:', attr2.value);
  }
});
```

--------------------------------

### Example: Create Durable Subscription

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Demonstrates how to create a durable subscription using the MQSD structure and the `mq.Sub()` method in the ibmmq Node.js library.

```APIDOC
### Example: Create Durable Subscription

```javascript
const mq = require('ibmmq');

const sd = new mq.MQSD();
sd.TopicString = 'finance/stocks';
sd.SubName = 'MyStockWatcher';
sd.Options = [
  mq.MQC.MQSO_CREATE,
  mq.MQC.MQSO_PERSISTENT,
  mq.MQC.MQSO_MANAGED
];

mq.Sub(qmr, null, sd, (err, queueObj, subObj) => {
  if (!err) {
    console.log('Durable subscription created');
    // Messages will be queued for later retrieval
  }
});
```
```

--------------------------------

### MQCNO Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQCNO structure for connection options.

```javascript
const MQ = require('ibmmq');

const cno = {
  'Options': MQ.MQCNO_STANDARD_BINDING | MQ.MQCNO_CLIENT_BINDING,
  'SecurityParms': {
    'UserId': 'user',
    'Password': 'password'
  }
};

// Use this cno object in MQ.Connx or MQ.ConnxPromise
// const qmgr = MQ.Connx('QMGR_NAME', cno);
// const qmgrPromise = await MQ.ConnxPromise('QMGR_NAME', cno);
```

--------------------------------

### Connect and Put Message with Node.js MQI

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/INDEX.md

Demonstrates how to establish a connection to an MQ queue manager, open a queue for output, and send a message. Ensure you have the 'ibmmq' module installed.

```javascript
const mq = require('ibmmq');

const cno = new mq.MQCNO();
mq.Conn('QM1', (err, qmr) => {
  if (err) {
    console.error('Connection failed:', err.mqrcstr);
    return;
  }

  const od = new mq.MQOD();
  od.ObjectName = 'MY.QUEUE';
  
  mq.Open(qmr, od, mq.MQC.MQOO_OUTPUT, (err, obj) => {
    if (err) {
      console.error('Open failed:', err.message);
      mq.Disc(qmr);
      return;
    }

    const md = new mq.MQMD();
    const pmo = new mq.MQPMO();
    pmo.Options = mq.MQC.MQPMO_NONE;

    mq.Put(obj, md, pmo, 'Hello MQ', (err) => {
      if (err) {
        console.error('Put failed:', err.message);
      } else {
        console.log('Message sent');
      }
      
      mq.Close(obj, mq.MQC.MQCO_NONE, () => {
        mq.Disc(qmr);
      });
    });
  });
});
```

--------------------------------

### MQCD Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQCD structure for client descriptors.

```javascript
const MQ = require('ibmmq');

const cd = {
  'ChannelName': 'MY.SVRCONN.CHANNEL',
  'ConnectionName': 'localhost(1414)',
  'TransportType': MQ.MQXPT_TCP
};

// Use this cd object with MQ.Connx for client connections
// const qmgr = MQ.Connx('QMGR_NAME', { 'ClientConn': cd });
```

--------------------------------

### MQCSP Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQCSP structure for security parameters.

```javascript
const MQ = require('ibmmq');

const csp = {
  'UserId': 'appuser',
  'Password': 'apppassword',
  'SecurityExit': 'MYEXIT',
  'SecurityData': 'MYDATA'
};

// Use this csp object within MQCNO for authentication
// const cno = { 'SecurityParms': csp };
// const qmgr = MQ.Connx('QMGR_NAME', cno);
```

--------------------------------

### Set and Get Tuning Parameters

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Configure library-level behavior for message delivery, such as enabling MQCTL and setting callback strategies. You can also retrieve the current settings.

```javascript
const mq = require('ibmmq');

// Enable MQCTL (recommended, default)
mq.setTuningParameters({
  useCtl: true,
  callbackStrategy: 'DEFAULT'
});

// Get current settings
const params = mq.getTuningParameters();
console.log('useCtl:', params.useCtl);
console.log('callbackStrategy:', params.callbackStrategy);
```

--------------------------------

### MQSD Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQSD structure for subscription descriptors.

```javascript
const MQ = require('ibmmq');

const sd = {
  'Options': MQ.MQSO_CREATE | MQ.MQSO_RESUME,
  'ObjectString': 'TOPIC://MyTopic'
};

// Use this sd object when subscribing
// const hSub = MQ.Sub(qmgr, sd);
// const msg = MQ.Get(qmgr, hSub, {}); // Get messages from subscription
```

--------------------------------

### Configure Load Balancing Options (MQBNO)

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Configure connection load balancing across multiple queue managers using MQBNO. This example sets the application type and timeout for load balancing.

```javascript
const cno = new mq.MQCNO();
const bno = new mq.MQBNO();

bno.ApplType = mq.MQC.MQBBA_MQSC;
bno.Timeout = 60000;  // 60 seconds

cno.BalanceParms = bno;
mq.Connx('QM1', cno, callback);
```

--------------------------------

### MQPMO Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQPMO structure for put message options.

```javascript
const MQ = require('ibmmq');

const pmo = {
  'Options': MQ.MQPMO_NEW_MSG_ID | MQ.MQPMO_SYNCPOINT
};

// Use this pmo object when putting a message
// MQ.Put(qmgr, hObj, { 'Buffer': Buffer.from('Message'), 'MQPMO': pmo });
```

--------------------------------

### Begin

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-transactions.md

Starts a global transaction on the queue manager. All subsequent Put/Get operations will be part of this transaction until Cmit() or Back() is called. This function supports transactional operations on client connections.

```APIDOC
## Begin

### Description
Starts a global transaction on the queue manager. All subsequent Put/Get operations will be part of this transaction until Cmit() or Back() is called. This function supports transactional operations on client connections.

### Signature
```javascript
function Begin(
  qmr: MQQueueManager,
  callback?: (err: MQError | null) => void
): void
```

### Parameters
#### Parameters
- **qmr** (MQQueueManager) - Yes - Queue manager reference from Conn/Connx
- **callback** (function) - No - Callback invoked with error (null on success). If omitted, function is synchronous

### Return Type
void

### Throws
- **MQError**: When transaction start fails
- **TypeError**: When parameters have incorrect types

### Behavior
- Initiates a unit of work (transaction) on the connection
- All subsequent Put/Get operations are part of this transaction until Cmit() or Back() is called
- On client connections, transactional Put and Get operations are supported
- Multiple transactions cannot be active simultaneously on one connection

### Example: Transactional Message Processing
```javascript
const mq = require('ibmmq');

// Start transaction
mq.Begin(qmr, (err) => {
  if (err) {
    console.error('Begin failed:', err.mqrcstr);
    return;
  }

  // Get message
  mq.GetSync(getQueue, getmd, getgmo, buffer);
  console.log('Got message in transaction');

  // Put message
  mq.Put(putQueue, putmd, putpmo, processedData, (err) => {
    if (err) {
      console.error('Put failed:', err.message);
      // Backout transaction on error
      mq.Back(qmr, (err) => {
        console.log('Transaction backed out');
      });
    } else {
      // Commit transaction on success
      mq.Cmit(qmr, (err) => {
        if (!err) {
          console.log('Transaction committed');
        }
      });
    }
  });
});
```
```

--------------------------------

### Begin Transaction

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-transactions.md

Starts a global transaction on the queue manager. All subsequent Put/Get operations are part of this transaction until Cmit() or Back() is called. Multiple transactions cannot be active simultaneously on one connection.

```javascript
const mq = require('ibmmq');

// Start transaction
mq.Begin(qmr, (err) => {
  if (err) {
    console.error('Begin failed:', err.mqrcstr);
    return;
  }

  // Get message
  mq.GetSync(getQueue, getmd, getgmo, buffer);
  console.log('Got message in transaction');

  // Put message
  mq.Put(putQueue, putmd, putpmo, processedData, (err) => {
    if (err) {
      console.error('Put failed:', err.message);
      // Backout transaction on error
      mq.Back(qmr, (err) => {
        console.log('Transaction backed out');
      });
    } else {
      // Commit transaction on success
      mq.Cmit(qmr, (err) => {
        if (!err) {
          console.log('Transaction committed');
        }
      });
    }
  });
});
```

--------------------------------

### Resource Cleanup Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/errors-and-troubleshooting.md

Demonstrates proper resource cleanup by closing objects and disconnecting from the queue manager after processing messages. This is crucial for preventing resource exhaustion and handle unavailability.

```javascript
const mq = require('ibmmq');

function processMessages() {
  mq.Conn('QM1', (err, qmr) => {
    if (err) {
      console.error('Connection failed:', err.message);
      return;
    }

    const od = new mq.MQOD();
    od.ObjectName = 'MY.QUEUE';

    mq.Open(qmr, od, mq.MQC.MQOO_INPUT_SHARED, (openErr, obj) => {
      if (openErr) {
        if (openErr.mqrc === mq.MQC.MQRC_HANDLE_NOT_AVAILABLE) {
          console.error('System out of handles');
        }
        mq.Disc(qmr);
        return;
      }

      // Process messages...

      // Clean up properly
      mq.Close(obj, mq.MQC.MQCO_NONE, (closeErr) => {
        mq.Disc(qmr, (discErr) => {
          if (discErr) {
            console.error('Disconnect cleanup error:', discErr.message);
          }
        });
      });
    });
  });
}
```

--------------------------------

### Create Durable Subscription

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Example of creating a durable subscription with specific options. This snippet demonstrates setting the topic, subscription name, and combining multiple options for subscription management.

```javascript
const mq = require('ibmmq');

const sd = new mq.MQSD();
sd.TopicString = 'finance/stocks';
sd.SubName = 'MyStockWatcher';
sd.Options = [
  mq.MQC.MQSO_CREATE,
  mq.MQC.MQSO_PERSISTENT,
  mq.MQC.MQSO_MANAGED
];

mq.Sub(qmr, null, sd, (err, queueObj, subObj) => {
  if (!err) {
    console.log('Durable subscription created');
    // Messages will be queued for later retrieval
  }
});
```

--------------------------------

### Run Sample Programs

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/samples/README.md

Demonstrates how to navigate to the samples directory and execute sample programs using Node.js. It also shows how to set up the MQ environment.

```bash
cd <something>/node_modules/ibmmq/samples
. setmqenv -s  -k     # to make sure MQ libraries can be found

node amqsput.js
node amqsget.js
```

--------------------------------

### Handle No Message Available During Get

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/errors-and-troubleshooting.md

This example demonstrates how to handle the MQRC_NO_MSG_AVAILABLE error when attempting to get a message from a queue with a timeout. It also includes a check for MQRC_Q_FULL.

```javascript
const mq = require('ibmmq');

const buffer = Buffer.alloc(4096);
const md = new mq.MQMD();
const gmo = new mq.MQGMO();
gmo.Options = mq.MQC.MQGMO_WAIT;
gmo.WaitInterval = 5000; // 5 second timeout

try {
  const msgLen = mq.GetSync(obj, md, gmo, buffer);
  console.log('Message received, length:', msgLen);
} catch (err) {
  if (err.mqrc === mq.MQC.MQRC_NO_MSG_AVAILABLE) {
    console.log('Timeout: no messages available within 5 seconds');
  } else if (err.mqrc === mq.MQC.MQRC_Q_FULL) {
    console.error('Queue is full, cannot put message');
  } else {
    console.error('Get failed:', err.mqrcstr);
  }
}
```

--------------------------------

### GetDone

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-messaging.md

Stops asynchronous message retrieval that was previously started with the Get() function. It ensures that ongoing message fetching operations are cleanly terminated.

```APIDOC
## GetDone

### Description

Stop asynchronous message retrieval started with Get().

### Signature

```javascript
function GetDone(
  obj: MQObject,
  callback?: (err: MQError | null) => void
): void
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| obj | MQObject | Yes | — | Object from Open() where Get() is active |
| callback | function | No | — | Callback invoked when retrieval has stopped |

### Return Type

void

### Example

```javascript
const mq = require('ibmmq');

// Start asynchronous message retrieval
mq.Get(obj, md, gmo, (err, len, rxMd, buf) => {
  // Process messages...
});

// Later, stop retrieval
mq.GetDone(obj, (err) => {
  console.log('Asynchronous Get stopped');
});
```
```

--------------------------------

### Get stop

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/INDEX.md

Stops a get operation.

```APIDOC
## Get stop

### Description
Stops a get operation.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
Refer to the specific SDK documentation for parameter details.

### Request Example
N/A (SDK method)

### Response
Refer to the specific SDK documentation for response details.
```

--------------------------------

### Getting a Message

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Shows the process of getting a message from a queue.

```javascript
const MQ = require('ibmmq');

let qmgr = null;
let hObj = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  hObj = MQ.Open(qmgr, {
    'ObjectName': 'QUEUE.NAME',
    'Options': MQ.MQOO_INPUT_SHARED | MQ.MQOO_FAIL_IF_QUIESCING
  });

  const msg = MQ.Get(qmgr, hObj, {
    'Options': MQ.MQGMO_WAIT | MQ.MQGMO_ACCEPT_TRUNCATED_MSG
  });

  console.log('Message received:', msg.Buffer.toString());

} catch (e) {
  console.error('Get message failed:', e);
} finally {
  if (hObj) MQ.Close(qmgr, hObj);
  if (qmgr) MQ.Disc(qmgr);
}
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/README.md

Install developer tools on MacOS if an error message like 'gyp: No Xcode or CLT version detected' occurs during 'npm install'. This command typically resolves the issue.

```bash
xcode-select --install
```

--------------------------------

### Blocking Get with MQGMO and Timeout

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Performs a blocking get operation with a specified wait interval, retrieving a message from the queue.

```javascript
const mq = require('ibmmq');

const gmo = new mq.MQGMO();
gmo.Options = mq.MQC.MQGMO_WAIT;
gmo.WaitInterval = 30000; // Wait 30 seconds

const buffer = Buffer.alloc(4096);
const md = new mq.MQMD();

try {
  const msgLen = mq.GetSync(obj, md, gmo, buffer);
  const body = buffer.toString('utf8', 0, msgLen);
  console.log('Message:', body);
} catch (err) {
  if (err.mqrc === mq.MQC.MQRC_NO_MSG_AVAILABLE) {
    console.log('No message received within timeout');
  }
}
```

--------------------------------

### MQGMO - Get Message Options

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Controls the behavior of Get operations. It allows configuration of options such as waiting for messages, browsing, and message matching criteria.

```APIDOC
## MQGMO - Get Message Options

Controls behavior of Get operations.

### Constructor

```javascript
const gmo = new mq.MQGMO();
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| Options | number | MQGMO_NONE | Get options flags |
| WaitInterval | number | -1 | Wait time in milliseconds (-1 = use default queue timeout) |
| Signal | number | MQSIG_DEFAULT | Signal behavior for wait |
| MatchOptions | number | MQMO_NONE | Message matching criteria |
| GroupStatus | number | MQGS_NOT_IN_GROUP | Group status on return |
| SegmentStatus | number | MQSS_NOT_A_SEGMENT | Segment status on return |
| Segmentation | number | MQSEG_INHIBITED | Whether message segmentation is allowed |

### Common Options

| Constant | Description |
|----------|-------------|
| MQGMO_WAIT | Wait for message to arrive |
| MQGMO_BROWSE_FIRST | Browse message without removing |
| MQGMO_BROWSE_NEXT | Browse next message |
| MQGMO_BROWSE_MSG_UNDER_CURSOR | Browse message under cursor |
| MQGMO_ACCEPT_TRUNCATED_MSG | Accept truncated message if buffer too small |
| MQGMO_FAIL_IF_QUIESCING | Fail if queue manager is quiescing |
| MQGMO_CONVERT | Convert message encoding/character set |
| MQGMO_SYNCPOINT | Get message as part of transaction |

### Matching Options

| Constant | Description |
|----------|-------------|
| MQMO_MATCH_CORREL_ID | Match on correlation ID |
| MQMO_MATCH_MSG_ID | Match on message ID |
| MQMO_MATCH_GROUP_ID | Match on group ID |
| MQMO_MATCH_MSG_SEQ_NUMBER | Match on sequence number |

### Example: Blocking Get

```javascript
const mq = require('ibmmq');

const gmo = new mq.MQGMO();
gmo.Options = mq.MQC.MQGMO_WAIT;
gmo.WaitInterval = 30000; // Wait 30 seconds

const buffer = Buffer.alloc(4096);
const md = new mq.MQMD();

try {
  const msgLen = mq.GetSync(obj, md, gmo, buffer);
  const body = buffer.toString('utf8', 0, msgLen);
  console.log('Message:', body);
} catch (err) {
  if (err.mqrc === mq.MQC.MQRC_NO_MSG_AVAILABLE) {
    console.log('No message received within timeout');
  }
}
```
```

--------------------------------

### Opening a Queue

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates opening a specific queue for output operations.

```javascript
const MQ = require('ibmmq');

let qmgr = null;
let hObj = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  hObj = MQ.Open(qmgr, {
    'ObjectName': 'QUEUE.NAME',
    'ObjectQueueManagerName': 'QMGR_NAME',
    'Options': MQ.MQOO_OUTPUT | MQ.MQOO_FAIL_IF_QUIESCING
  });
  console.log('Queue opened successfully');
  // ... put messages ...
} catch (e) {
  console.error('Open queue failed:', e);
} finally {
  if (hObj) {
    MQ.Close(qmgr, hObj);
    console.log('Queue closed');
  }
  if (qmgr) {
    MQ.Disc(qmgr);
  }
}
```

--------------------------------

### Get prop

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/INDEX.md

Retrieves a property from a message.

```APIDOC
## Get prop

### Description
Retrieves a property from a message.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
Refer to the specific SDK documentation for parameter details.

### Request Example
N/A (SDK method)

### Response
Refer to the specific SDK documentation for response details.
```

--------------------------------

### Message Verbs

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Functions for putting and getting messages.

```APIDOC
## Put

### Description
Puts a message onto a queue.

### Method
Put

### Parameters
- **mqObject** (MQObject) - The MQObject instance representing the queue.
- **message** (string|Buffer) - The message content.
- **options** (object) - Put message options (MQPMO_*).

### Response
None.

## Put1

### Description
Puts a single message onto a queue with specified options.

### Method
Put1

### Parameters
- **mqObject** (MQObject) - The MQObject instance representing the queue.
- **message** (string|Buffer) - The message content.
- **options** (object) - Put message options (MQPMO_*).
- **messageDescriptor** (object) - Message descriptor (MQMD).

### Response
None.

## Get

### Description
Gets a message from a queue.

### Method
Get

### Parameters
- **mqObject** (MQObject) - The MQObject instance representing the queue.
- **options** (object) - Get message options (MQGMO_*).

### Response
Message object.

## GetDone

### Description
Indicates that a message has been processed.

### Method
GetDone

### Parameters
- **mqObject** (MQObject) - The MQObject instance representing the queue.
- **messageId** (string) - The ID of the message.

### Response
None.

## Ctl

### Description
Controls MQ operations.

### Method
Ctl

### Parameters
- **operation** (string) - The control operation to perform.

### Response
Depends on the operation.
```

--------------------------------

### Get

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/INDEX.md

Retrieves a message from a queue. Supports synchronous variants.

```APIDOC
## Get

### Description
Retrieves a message from a queue.

### Method
Supports synchronous variants.

### Endpoint
N/A (SDK method)

### Parameters
Refer to the specific SDK documentation for parameter details.

### Request Example
N/A (SDK method)

### Response
Refer to the specific SDK documentation for response details.
```

--------------------------------

### Initialize MQOD Object

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Creates a new MQOD object. This is the first step before setting its properties.

```javascript
const od = new mq.MQOD();
```

--------------------------------

### Getting Status Information

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Illustrates how to retrieve status information for a queue manager.

```javascript
const MQ = require('ibmmq');

let qmgr = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  const status = MQ.Stat(qmgr);
  console.log('Queue manager status:', status);
} catch (e) {
  console.error('Get status failed:', e);
} finally {
  if (qmgr) MQ.Disc(qmgr);
}
```

--------------------------------

### MQSCO Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQSCO structure for SSL/TLS configuration.

```javascript
const MQ = require('ibmmq');

const sco = {
  'KeyRepository': '/path/to/key.kdb',
  'CipherSuite': 'TLS_RSA_WITH_AES_128_CBC_SHA'
};

// Use this sco object within MQCNO for SSL/TLS
// const cno = { 'SSLConfig': sco };
// const qmgr = MQ.Connx('QMGR_NAME', cno);
```

--------------------------------

### Connecting to a Queue Manager

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/types-and-constants.md

Demonstrates how to establish a connection to a queue manager using mq.Conn and obtain an MQQueueManager instance. This instance is then used for subsequent operations.

```javascript
const mq = require('ibmmq');

mq.Conn('QM1', (err, qmr) => {
  if (!err) {
    // qmr is MQQueueManager instance
    mq.Open(qmr, od, mq.MQC.MQOO_INPUT_SHARED, (err, obj) => {
      // Use qmr for subsequent operations
    });
  }
});
```

--------------------------------

### MQMD Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQMD structure for message descriptors.

```javascript
const MQ = require('ibmmq');

// When putting a message, you can provide an MQMD object
const msg = {
  'Buffer': Buffer.from('Message with MQMD'),
  'MQMD': {
    'Format': 'MQSTR',
    'MsgType': MQ.MQMT_DATAGRAM,
    'CorrelId': Buffer.from('some_correl_id')
  }
};

// ... use MQ.Put(qmgr, hObj, msg) ...

// When getting a message, the MQMD is returned
// const receivedMsg = MQ.Get(qmgr, hObj, {});
// console.log(receivedMsg.MQMD.Format); // Output: MQSTR
```

--------------------------------

### Querying Queue Manager Properties

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates how to query properties of a queue manager.

```javascript
const MQ = require('ibmmq');

let qmgr = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  const status = MQ.Inq(qmgr, {
    'Attribute': MQ.MQIA_MAX_CONNS
  });
  console.log('Queue manager property value:', status.Value);
} catch (e) {
  console.error('Inquiry failed:', e);
} finally {
  if (qmgr) MQ.Disc(qmgr);
}
```

--------------------------------

### MQSTS Structure Usage

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Example of using the MQSTS structure to hold status information.

```javascript
const MQ = require('ibmmq');

// The MQ.Stat function returns an MQSTS object
// const qmgr = MQ.Conn('QMGR_NAME');
// const status = MQ.Stat(qmgr);
// console.log(status.CompCode); // MQCC_OK
// console.log(status.ReasonCode); // MQRC_NONE
```

--------------------------------

### Connect (simple)

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/INDEX.md

Establishes a simple connection to the MQ queue manager. Supports both synchronous and promise-based variants.

```APIDOC
## Connect (simple)

### Description
Establishes a simple connection to the MQ queue manager.

### Method
Supports both synchronous and promise-based variants.

### Endpoint
N/A (SDK method)

### Parameters
Refer to the specific SDK documentation for parameter details.

### Request Example
N/A (SDK method)

### Response
Refer to the specific SDK documentation for response details.
```

--------------------------------

### Using Array Syntax for MQI Options

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/README.md

Demonstrates how to use array syntax for setting MQI options, which can be an alternative to bitwise operations. Ensure consistency in style throughout your application. Note that zero values are omitted from the array upon return.

```javascript
  pmo.Options = [MQC.MQPMO_NO_SYNCPOINT, MQC.MQPMO_NEW_MSG_ID, MQC.MQPMO_NEW_CORREL_ID];
  mq.PutSync( ... )

  var opts = pmo.Options as mq.MQC_MQPMO[]; // Be explicit
  if (opts.includes(MQC.MQPMO_SYNCPOINT)) {
    console.log("Array includes value SYNCPOINT");
  } else {
    console.log("Array does not include value SYNCPOINT");
  }
```

--------------------------------

### Putting a Message

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Illustrates how to put a message onto a queue.

```javascript
const MQ = require('ibmmq');

let qmgr = null;
let hObj = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  hObj = MQ.Open(qmgr, {
    'ObjectName': 'QUEUE.NAME',
    'Options': MQ.MQOO_OUTPUT | MQ.MQOO_FAIL_IF_QUIESCING
  });

  const msg = {
    'Buffer': Buffer.from('Hello, MQ!')
  };

  MQ.Put(qmgr, hObj, msg);
  console.log('Message put successfully');

} catch (e) {
  console.error('Put message failed:', e);
} finally {
  if (hObj) MQ.Close(qmgr, hObj);
  if (qmgr) MQ.Disc(qmgr);
}
```

--------------------------------

### Initialize MQCSP Structure

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Instantiate an MQCSP object to hold authentication credentials.

```javascript
const csp = new mq.MQCSP();
```

--------------------------------

### Setting Queue Manager Properties

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Shows how to set properties on a queue manager.

```javascript
const MQ = require('ibmmq');

let qmgr = null;

try {
  qmgr = MQ.Conn('QMGR_NAME');
  const status = MQ.Set(qmgr, {
    'Attribute': MQ.MQIA_MAX_CONNS,
    'Value': 100
  });
  console.log('Queue manager property set:', status);
} catch (e) {
  console.error('Set property failed:', e);
} finally {
  if (qmgr) MQ.Disc(qmgr);
}
```

--------------------------------

### Initialize MQMD Structure

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Initializes a new MQMD structure. This is used to specify message properties when putting and getting messages.

```javascript
const md = new mq.MQMD();
```

--------------------------------

### InqMp

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-properties.md

Inquire (retrieve) a property from a message handle. This function allows you to get the value of a specific property associated with a message.

```APIDOC
## InqMp

### Description
Inquire (retrieve) a property from a message handle. This function allows you to get the value of a specific property associated with a message.

### Signature
```javascript
function InqMp(
  qmr: MQQueueManager,
  hMsg: number,
  impo: MQIMPO,
  propDesc: MQPD,
  propName: string,
  valueBuffer: Buffer,
  callback?: (err: MQError | null, value: any) => void
): any
```

### Parameters
#### Path Parameters
(No path parameters for this method)

#### Query Parameters
(No query parameters for this method)

#### Request Body
(No request body for this method)

#### Method Parameters
- **qmr** (MQQueueManager) - Required - Queue manager reference
- **hMsg** (number) - Required - Message handle from CrtMh()
- **impo** (MQIMPO) - Required - Inquire message property options
- **propDesc** (MQPD) - Required - Property descriptor with type
- **propName** (string) - Required - Name of property to retrieve
- **valueBuffer** (Buffer) - Required - Buffer to receive property value
- **callback** (function) - Optional - Callback invoked with (error, value). If omitted, returns synchronously

### Return Type
- any: Property value (when no callback)
- undefined: When callback provided (result via callback)

### Example: Retrieve String Property
```javascript
const mq = require('ibmmq');

const impo = new mq.MQIMPO();
const pd = new mq.MQPD();
pd.Type = mq.MQC.MQPDT_STRING;

const buffer = Buffer.alloc(256);

mq.InqMp(qmr, hMsg, impo, pd, 'AppVersion', buffer, (err, value) => {
  if (!err) {
    console.log('AppVersion property:', value);
  }
});
```
```

--------------------------------

### Configure Topic-Based Subscriptions

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/configuration.md

Set TopicString and SelectionString to define the topic and filtering criteria for subscriptions. MQSL_ALL subscribes to all levels.

```javascript
const sd = new mq.MQSD();
sd.TopicString = 'finance/stocks/apple';  // Topic path
sd.SelectionString = 'Price > 100';        // Optional filtering
sd.SubLevel = mq.MQC.MQSL_ALL;            // Subscribe to all levels

mq.Sub(qmr, null, sd, (err, queueObj, subObj) => {
  // Use queueObj to get published messages
});
```

--------------------------------

### Basic MQ Error Handling Example

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/errors-and-troubleshooting.md

Demonstrates how to catch and log MQ errors using a callback function after attempting a connection. It logs specific error details like the verb, completion code, and reason code.

```javascript
const mq = require('ibmmq');

mq.Conn('BADQMGR', (err, qmr) => {
  if (err) {
    console.error('Error in:', err.verb);
    console.error('Completion Code:', err.mqccstr, `(${err.mqcc})`);
    console.error('Reason Code:', err.mqrcstr, `(${err.mqrc})`);
    console.error('Full message:', err.message);
  } else {
    console.log('Connected');
  }
});
```

--------------------------------

### Initialize MQPMO Structure

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Creates a new instance of the MQPMO structure to define put message behavior.

```javascript
const pmo = new mq.MQPMO();
```

--------------------------------

### Initialize MQCD Structure

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Instantiate an MQCD object to define client connection parameters.

```javascript
const cd = new mq.MQCD();
```

--------------------------------

### Get (Asynchronous)

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/api-reference-messaging.md

Asynchronously retrieves messages from a queue, invoking a callback for each message received. This method is designed for non-blocking message consumption.

```APIDOC
## Get (Asynchronous)

### Description
Asynchronously get messages from a queue with callback invocation for each message.

### Signature
```javascript
function Get(
  obj: MQObject,
  md: MQMD,
  gmo: MQGMO,
  callback: (err: MQError | null, len: number, md: MQMD, buf: Buffer) => void
): void
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| obj | MQObject | Yes | — | Opened queue object |
| md | MQMD | Yes | — | Message descriptor template |
| gmo | MQGMO | Yes | — | Get message options |
| callback | function | Yes | — | Callback invoked for each message with (error, length, updatedMd, buffer) |

### Return Type

void

### Behavior

- Callback is invoked multiple times as messages arrive
- Call GetDone() to stop receiving messages
- When gmo.Options includes MQGMO_WAIT, callback blocks until message arrives or timeout
- Used with MQCB internal message callbacks for true asynchronous processing

### Example

```javascript
const mq = require('ibmmq');

const md = new mq.MQMD();
const gmo = new mq.MQGMO();
gmo.Options = mq.MQC.MQGMO_WAIT;
gmo.WaitInterval = 5000; // 5 second timeout

let msgCount = 0;

mq.Get(obj, md, gmo, (err, msgLen, rxMd, buffer) => {
  if (err) {
    console.error('Get failed:', err.mqrcstr);
    mq.GetDone(obj); // Stop getting messages
  } else {
    msgCount++;
    const body = buffer.toString('utf8', 0, msgLen);
    console.log(`Message ${msgCount}:`, body);
    if (msgCount >= 10) {
      mq.GetDone(obj); // Stop after 10 messages
    }
  }
});
```
```

--------------------------------

### Initialize MQSD

Source: https://github.com/ibm-messaging/mq-mqi-nodejs/blob/master/_autodocs/structures.md

Instantiate a new MQSD object to define subscription parameters.

```javascript
const sd = new mq.MQSD();
```