vania-janet/multiturn-rag-retrieval-data huggingface dataset:
To this end, path parameters MUST be enumerated in the [Path Item](https://spec.openapis.org/oas/v3.0.3path-item-object) object and not the [Operation](https://spec.openapis.org/oas/v3.0.3operation-object) object. Further, path parameters SHOULD be defined as [Components](https://spec.openapis.org/oas/v3.0.3components-object) and referenced in Path Item objects. Finally, schemas used by parameters SHOULD also be defined as separate [Components](https://spec.openapis.org/oas/v3.0.3components-object) and referenced in [Parameter](https://cloud.ibm.com/docs/parameter) objects.



 Example 

The following example demonstrates how parameters can be defined in an OpenAPI definition to maximize reuse.

paths:
'/farms/{id}':
parameters:
- $ref: '/components/parameters/FarmId'
get:
operationId: get_farm
...
patch:
operationId: update_farm
...
'/farms/{farm_id}/barns':
parameters:
- $ref: '/components/parameters/FarmIdQualified'
get:
operationId: list_farm_barns
...
post:
operationId: create_farm_barn
...
'/farms/{farm_id}/barns/{id}':
parameters:
- $ref: '/components/parameters/FarmIdQualified'
- $ref: '/components/parameters/FarmBarnId'
get:
operationId: get_farm_barn
...
patch:
operationId: update_farm_barn
...
components:
parameters:
FarmId:
name: id
in: path
required: true
description: The identifier for a farm
schema:
Segment By Service instance, The queue manager name 







 Non-persistent message browse - byte count 

Total non-persistent message browse byte count for a queue manager



Table 42: Non-persistent message browse - byte count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_persistent_message_browse_bytes_total 
 Metric Type counter 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Non-persistent message browse count 

Total non-persistent message browse count for a queue manager



Table 43: Non-persistent message browse count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_persistent_message_browse_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Non-persistent message get - byte count 

Total non-persistent message get byte count for a queue manager



Table 44: Non-persistent message get - byte count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_persistent_message_get_bytes_total 
 Metric Type counter 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Persistent - topic MQPUT/MQPUT1 count 

Total persistent topic MQPUT/MQPUT1 count for a queue manager



Table 45: Persistent - topic MQPUT/MQPUT1 count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_persistent_topic_mqput_mqput1_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Persistent message MQPUT count 

Total persistent message MQPUT count for a queue manager



Table 46: Persistent message MQPUT count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_persistent_message_mqput_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Persistent message MQPUT1 count 

Total persistent message MQPUT1 count for a queue manager



Table 47: Persistent message MQPUT1 count metric metadata

 Metadata Description
Total published to subscribers byte count for a queue manager



Table 51: Published to subscribers - byte count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_published_to_subscribers_bytes_total 
 Metric Type counter 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Published to subscribers - message count 

Total published to subscribers message count for a queue manager



Table 52: Published to subscribers - message count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_published_to_subscribers_message_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Purged queue count 

Total purged queue count for a queue manager



Table 53: Purged queue count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_purged_queue_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Put non-persistent messages - byte count 

Total non-persistent messages put byte count for a queue manager



Table 54: Put non-persistent messages - byte count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_persistent_message_put_bytes_total 
 Metric Type counter 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Put persistent messages - byte count 

Total persistent messages put byte count for a queue manager



Table 55: Put persistent messages - byte count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_persistent_message_put_bytes_total 
 Metric Type counter 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Queue Manager file system - bytes in use 

File system bytes in use for a queue manager



Table 56: Queue Manager file system - bytes in use metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_queue_manager_file_system_in_use_bytes 
 Metric Type gauge 
 Value Type byte 
 Segment By Service instance, The queue manager name 







 Queue Manager file system - free space 

File system free space for a queue manager



Table 57: Queue Manager file system - free space metric metadata
Because many tools in the Kafka ecosystem (such as connectors to other systems) use only the value and ignore the key, it is best to put all of the message data in the value and use the key for partitioning or log compaction. Do not rely on everything that reads from Kafka to use the key.

Many other messaging systems also have a way of carrying other information along with the messages. Kafka version 0.11 introduces record headers for this purpose.

You might find it useful to read this information along with [consuming messages](https://cloud.ibm.com/docs/EventStreams?topic=EventStreams-consuming_messages) in Event Streams.



 Configuration settings 

Many configuration settings exist for the producer. You can control aspects of the producer, including batching, retries, and message acknowledgment. Here are the most important ones:



Table 1. Producer configuration settings

 Name Description Valid values Default 

 key.serializer The class used to serialize keys. Java class that implements Serializer interface, such as org.apache.kafka.common.serialization.StringSerializer. No default - you must specify a value. 
 value.serializer The class used to serialize values. Java class that implements Serializer interface, such as org.apache.kafka.common.serialization.StringSerializer. No default - you must specify a value. 
 acks The number of servers required to acknowledge each message published. This controls the durability guarantees that the producer requires. 0, 1, all (or -1) 1 
 retries The number of times that the client resends a message when the send encounters an error. 0,... 0 
 max.block.ms The number of milliseconds that a send or metadata request can block waiting. 0,... 60000 (1 minute) 
 max.in.flight.requests.per.connection The maximum number of unacknowledged requests that the client sends on a connection before it blocks further requests. 1,... 5
Producing messages 

A producer is an application that publishes streams of messages to Kafka topics. This information focuses on the Java programming interface that is part of the Apache Kafka project. The concepts apply to other languages too, but the names are sometimes a little different.

In the programming interfaces, a message is called a record. For example, the Java class org.apache.kafka.clients.producer.ProducerRecord is used to represent a message from the point of view of the producer API. The terms record and message can be used interchangeably, but essentially a record is used to represent a message.

When a producer connects to Kafka, it makes an initial bootstrap connection. This connection can be to any of the servers in the cluster. The producer requests the partition and leadership information about the topic that it wants to publish to. Then, the producer establishes another connection to the partition leader and can publish messages. These actions happen automatically internally when your producer connects to the Kafka cluster.

When a message is sent to the partition leader, that message is not immediately available to consumers. The leader appends the record for the message to the partition, assigning it the next offset number for that partition. After all the followers for the in-sync replicas replicated the record and acknowledged that they wrote the record to their replicas, the record is now committed and becomes available for consumers.

Each message is represented as a record that comprises two parts: key and value. The key is commonly used for data about the message and the value is the body of the message. Because many tools in the Kafka ecosystem (such as connectors to other systems) use only the value and ignore the key, it is best to put all of the message data in the value and use the key for partitioning or log compaction. Do not rely on everything that reads from Kafka to use the key.

Many other messaging systems also have a way of carrying other information along with the messages. Kafka version 0.11 introduces record headers for this purpose.
[Commit count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_commit_total) 
 [Create durable subscription count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_durable_subscription_create_total) 
 [Create non-durable subscription count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_non_durable_subscription_create_total) 
 [Delete durable subscription count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_durable_subscription_delete_total) 
 [Delete non-durable subscription count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_non_durable_subscription_delete_total) 
 [Expired message count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_expired_message_total) 
 [Failed MQCB count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_failed_mqcb_total) 
 [Failed MQCLOSE count](https://cloud.ibm.com/docs/mqcloud?topic=mqcloud-monitor_sysdigibm_mq_qmgr_failed_mqclose_total)
Request bodies 



* Any JSON number value which evaluates to an integer within the service providing an API MUST be considered a valid integer, but MAY be rejected by other validation rules.
* The null JSON keyword MAY be accepted in a JSON merge patch request body if the field is optional in the resource state and MUST NOT be accepted otherwise.
* Any other value MUST be rejected with a 400 status code and appropriate error response model.







 Query parameters 



* Any string containing a [valid JSON number](https://datatracker.ietf.org/doc/html/rfc7159section-6) value without a fractional or exponential value MUST be considered a valid integer.
* Any other string containing a valid JSON number (that is, a string with a fractional or exponential value) MAY be used for comparative filtering but MUST NOT be considered an exact match.
* The lowercase string null MUST be considered a match for a value absent from the observable resource state.
* Any other string MUST be considered invalid and SHOULD be rejected with a 400 status code and appropriate error response model.





Schema guidance for integers in requests

 Constraint Recommended value Description 

 type integer type MUST be string. 
 format int32 or int64 format MUST be int32 or int64. 
 minimum ≥-2147483648 for int32 or ≥-9007199254740991 for int64 minimum value MUST be present. 
 maximum ≤2147483647 for int32 or ≤9007199254740991 for int64 maximum value MUST be present. 











 Float 

The float type provides for numeric values which cannot be represented as integers and for which guaranteed precision is not required. A float field MUST NOT purport to support values or precision beyond a 64-bit double

[6]



 Response format 

For responses, a float field SHOULD be documented as either a 32-bit float or a 64-bit double and MAY further constrain the range of valid values. For the sake of backward-compatible future expansions, documented constraints MAY be more permissive (allowing for a larger range of values) for responses than for requests.

A float value MUST be returned as a JSON number and MAY have a decimal point or use scientific notation.
Metric Name ibm_mq_qmgr_durable_subscription_alter_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Commit count 

The total number of commits for a queue manager



Table 3: Commit count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_commit_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Create durable subscription count 

Count of create durable subscriptions for a queue manager



Table 4: Create durable subscription count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_durable_subscription_create_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Create non-durable subscription count 

Total non-durable subscription create count for a queue manager



Table 5: Create non-durable subscription count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_durable_subscription_create_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Delete durable subscription count 

Count of delete durable subscriptions for a queue manager



Table 6: Delete durable subscription count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_durable_subscription_delete_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Delete non-durable subscription count 

Total non-durable subscription delete count for a queue manager



Table 7: Delete non-durable subscription count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_non_durable_subscription_delete_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Expired message count 

Total number of expired messages for a queue manager



Table 8: Expired message count metric metadata

 Metadata Description 

 Metric Name ibm_mq_qmgr_expired_message_total 
 Metric Type counter 
 Value Type none 
 Segment By Service instance, The queue manager name 







 Failed MQCB count
Consuming messages 

A consumer is an application that consumes streams of messages from Kafka topics. A consumer can subscribe to one or more topics or partitions. This information focuses on the Java™ programming interface that is part of the Apache Kafka project. The concepts apply to other languages too, but the names are sometimes a little different.

When a consumer connects to Kafka, it makes an initial bootstrap connection. This connection can be to any of the servers in the cluster. The consumer requests the partition and leadership information about the topic that it wants to consume from. Then, the consumer establishes another connection to the partition leader and can consume messages. These actions happen automatically internally when your consumer connects to the Kafka cluster.

A consumer is normally a long-running application. A consumer requests messages from Kafka by calling Consumer.poll(...) regularly. The consumer calls poll(), receives a batch of messages, processes them promptly, and then calls poll() again.

When a consumer processes a message, the message is not removed from its topic. Instead, consumers can choose from several ways of notifying Kafka which messages were processed. This process is known as committing the offset.

In the programming interfaces, a message is called a record. For example, the Java class org.apache.kafka.clients.consumer.ConsumerRecord is used to represent a message for the consumer API. The terms record and message can be used interchangeably, but essentially a record is used to represent a message.

You might find it useful to read this information along with [producing messages](https://cloud.ibm.com/docs/EventStreams?topic=EventStreams-producing_messages) in Event Streams.



 Configuring consumer properties 

Many configuration settings exist for the consumer that control aspects of its behavior. The following settings are some of the most important ones.



Table 1. Configuring consumer properties

 Name Description Valid values Default 

 key.deserializer The class used to deserialize keys. Java class that implements Deserializer interface, such as org.apache.kafka.common.serialization.StringDeserializer.
<EncodingType>string</EncodingType>
</ListVersionsResult>
Show more

delimiter: A delimiter is a character that you specify to group keys. All keys that contain the same string between the prefix and the first occurrence of the delimiter are grouped under a single result element in CommonPrefixes. These groups are counted as one result against the max-keys limitation. These keys are not returned elsewhere in the response.

encoding-type: Requests COS to url-encode the object keys in the response. Object keys may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that COS encodes the keys in the response. Valid value: url.

key-marker: Specifies the key to start with when listing objects in a bucket.

max-keys: Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.

prefix: Use this parameter to select only those keys that begin with the specified prefix.

version-id-marker: Specifies the object version you want to start listing from.





 Operations on specific versions of objects 

Several APIs make use of a new query parameter (?versionId=<VersionId>) that indicates which version of the object you are requesting. This parameter is used in the same manner for reading, deleting, checking metadata and tags, and restoring archived objects. For example, to read a version of an object foo with a version ID of L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo, the request might look like the following:

=======

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/foo?versionId=L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" -H 'Authorization: bearer $TOKEN'
retries The number of times that the client resends a message when the send encounters an error. 0,... 0 
 max.block.ms The number of milliseconds that a send or metadata request can block waiting. 0,... 60000 (1 minute) 
 max.in.flight.requests.per.connection The maximum number of unacknowledged requests that the client sends on a connection before it blocks further requests. 1,... 5 
 request.timeout.ms The maximum amount of time the producer waits for a response to a request. If the response is not received before the timeout elapses, the request is retried, or fails if the number of retries was exhausted. 0,... 30000 (30 seconds) 



Many more configuration settings are available, but ensure that you read the [Apache Kafka documentation](http://kafka.apache.org/documentation/) thoroughly before you experiment with them.





 Partitioning 

With Kafka, partitions are the unit of scalability. Therefore, partitioning is an effective way to increase your throughput because it allows topic data to flow in multiple parallel streams.

When the producer publishes a message on a topic, the producer can choose which partition to use. If ordering is important, note that a partition is an ordered sequence of records, but a topic comprises one or more partitions. If you want a set of messages to be delivered in order, ensure that they all go on the same partition. The most straightforward way to achieve this is to give all of those messages the same key.

The producer can explicitly specify a partition number when it publishes a message. This gives direct control, but it makes the producer code more complex because it takes on the responsibility for managing the partition selection. For more information, see the method call Producer.partitionsFor. For example, the call is described for [Kafka version 2.2.0](https://kafka.apache.org/22/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html).
Right click on queue 'DEV.TEST.1'.
2. Click 'Put Test Message...'.
3. Type in a test message in the 'Message data' text box.
4. Click Put message.
5. Click Close.
6. Click Refresh in the 'Queues' panel.



You can see that the 'Current queue depth' for 'DEV.TEST.1' is now 1.





 Using runmqsc: 

We will make use of the sample program amqsputc to assist in putting messages on the test queue. In the same shell used in the previous steps:



1. Export the 'MQSAMP_USER_ID' variable:



* Linux: export MQSAMP_USER_ID="<your MQ username>"
* Windows (Command prompt): set MQSAMP_USER_ID=<your MQ username>
* Windows (PowerShell): $env:MQSAMP_USER_ID="<your MQ username>"



2. Run <PATH_TO_SAMPLE_BIN_DIR>/amqsputc DEV.TEST.1 <your QMGR name>
3. Enter your platform API key when prompted for a password.
4. Type in a test message.
5. Hit Enter twice to exit the amqsputc sample.









 Browse a message on the test queue 

This step is unique to MQ Explorer and cannot be achieved using the command line.



1. Right click on queue 'DEV.TEST.1'.
2. Click 'Browse Messages...'.
3. Confirm you can see your test message and then click Close.







 Get a message using the amqsgetc sample program 

This step is unique to runmqsc and cannot be achieved on MQ Explorer.

In the same shell used in the previous steps:



1. Run <PATH_TO_SAMPLE_BIN_DIR>/amqsgetc DEV.TEST.1 <your QMGR name>
2.
export MQSERVER="CLOUD.ADMIN.SVRCONN/TCP/<HOSTNAME>(<PORT>)"
export MQS_KEYSTORE_CONF=/bob/.mqs/keystore.conf

On Linux:
export MQSAMP_USER_ID=bob
export MQSERVER="CLOUD.ADMIN.SVRCONN/TCP/<HOSTNAME>(<PORT>)"
export MQS_KEYSTORE_CONF=/home/bob/.mqs/keystore.conf

On Windows:
set MQSAMP_USER_ID=bob
set MQSERVER=CLOUD.ADMIN.SVRCONN/TCP/<HOSTNAME>(<PORT>)
set MQS_KEYSTORE_CONF=C:Usersbob.mqskeystore.conf



* <HOSTNAME> - this is 'hostname' in the file connection_info.txt
* <PORT> - this is 'listenerPort' in the file connection_info.txt



3. From alice's command shell, run the sample program to send messages to the protected queue.

amqsputc DEV.QUEUE.1 <your Queue manager name>

3.1 Enter the application API key for alice when prompted for a password(This is your '"apiKey' value in the file "applicationApiKeyalice.json).
3.2 Type the text of the message, then press Enter key twice to send only a single message.
Note: Pressing the Enter key twice will exit the sample application.
![Image showing alice sending message to protectec queue](https://cloud.ibm.com/docs-content/v1/content/3a120b16db5fdc3e70d071af8a63ce5515c1b096/mqcloud/images/mqoc_app_ams_st_putpq.png)
4. From bob's command shell, run the sample program to receive the messages.

amqsgetc DEV.QUEUE.1.ALIAS <your Queue manager name>