WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

MessageProducer

An application uses a message producer to send messages to a destination.

For a list of the XMS defined properties of a MessageProducer object, see Properties of MessageProducer.

Functions

Summary of functions:
Function Description
xmsMsgProducerClose Close the message producer.
xmsMsgProducerGetDeliveryMode Get the default delivery mode for messages sent by the message producer.
xmsMsgProducerGetDestination Get the destination for the message producer.
xmsMsgProducerGetDisableMsgID Get an indication of whether a receiving application requires message identifiers to be included in messages sent by the message producer.
xmsMsgProducerGetDisableMsgTS Get an indication of whether a receiving application requires time stamps to be included in messages sent by the message producer.
xmsMsgProducerGetPriority Get the default priority for messages sent by the message producer.
xmsMsgProducerGetTimeToLive Get the default length of time that a message exists before it expires.
xmsMsgProducerSend Send a message to the destination that was specified when the message producer was created. Send the message using the message producer's default delivery mode, priority, and time to live.
xmsMsgProducerSendDest Send a message to a specified destination if you are using a message producer for which no destination was specified when the message producer was created. Send the message using the message producer's default delivery mode, priority, and time to live.
xmsMsgProducerSendDestWithAttr Send a message to a specified destination if you are using a message producer for which no destination was specified when the message producer was created. Send the message using the specified delivery mode, priority, and time to live.
xmsMsgProducerSendWithAttr Send a message to the destination that was specified when the message producer was created. Send the message using the specified delivery mode, priority, and time to live.
xmsMsgProducerSetDeliveryMode Set the default delivery mode for messages sent by the message producer.
xmsMsgProducerSetDisableMsgID Indicate whether a receiving application requires message identifiers to be included in messages sent by the message producer.
xmsMsgProducerSetDisableMsgTS Indicate whether a receiving application requires time stamps to be included in messages sent by the message producer.
xmsMsgProducerSetPriority Set the default priority for messages sent by the message producer.
xmsMsgProducerSetTimeToLive Set the default length of time that a message exists before it expires.

xmsMsgProducerClose – Close Message Producer

Interface:
xmsRC xmsMsgProducerClose(xmsHMsgProducer *producer,
                          xmsHErrorBlock errorBlock);

Close the message producer.

If an application tries to close a message producer that is already closed, the call is ignored.

Parameters:
producer (input/output)
On input, the handle for the message producer. On output, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDeliveryMode – Get Default Delivery Mode

Interface:
xmsRC xmsMsgProducerGetDeliveryMode(xmsHMsgProducer producer,
                                    xmsINT *deliveryMode,
                                    xmsHErrorBlock errorBlock);

Get the default delivery mode for messages sent by the message producer.

Parameters:
producer (input)
The handle for the message producer.
deliveryMode (output)
The default delivery mode, which is one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT

For a real-time connection to a broker, the value is always XMSC_DELIVERY_NON_PERSISTENT.

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDestination – Get Destination

Interface:
xmsRC xmsMsgProducerGetDestination(xmsHMsgProducer producer,
                                   xmsHDest *destination,
                                   xmsHErrorBlock errorBlock);

Get the destination for the message producer.

Parameters:
producer (input)
The handle for the message producer.
destination (output)
The handle for the destination. If the message producer does not have a destination, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDisableMsgID – Get Disable Message ID Flag

Interface:
xmsRC xmsMsgProducerGetDisableMsgID(xmsHMsgProducer producer,
                                    xmsBOOL *msgIDDisabled,
                                    xmsHErrorBlock errorBlock);

Get an indication of whether a receiving application requires message identifiers to be included in messages sent by the message producer.

Parameters:
producer (input)
The handle for the message producer.
msgIDDisabled (output)
The value is xmsTRUE if a receiving application does not require message identifiers to be included in messages sent by the message producer. The value is xmsFALSE if a receiving application does require message identifiers.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDisableMsgTS – Get Disable Time Stamp Flag

Interface:
xmsRC xmsMsgProducerGetDisableMsgTS(xmsHMsgProducer producer,
                                    xmsBOOL *timeStampDisabled,
                                    xmsHErrorBlock errorBlock);

Get an indication of whether a receiving application requires time stamps to be included in messages sent by the message producer.

Parameters:
producer (input)
The handle for the message producer.
timeStampDisabled (output)
The value is xmsTRUE if a receiving application does not require time stamps to be included in messages sent by the message producer. The value is xmsFALSE if a receiving application does require time stamps.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetPriority – Get Default Priority

Interface:
xmsRC xmsMsgProducerGetPriority(xmsHMsgProducer producer,
                                xmsINT *priority,
                                xmsHErrorBlock errorBlock);

Get the default priority for messages sent by the message producer.

Parameters:
producer (input)
The handle for the message producer.
priority (output)
The default message priority. The value is an integer in the range 0, the lowest priority, to 9, the highest priority.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetTimeToLive – Get Default Time to Live

Interface:
xmsRC xmsMsgProducerGetTimeToLive(xmsHMsgProducer producer,
                                  xmsLONG *timeToLive,
                                  xmsHErrorBlock errorBlock);

Get the default length of time that a message exists before it expires. The time is measured from when the message producer sends the message.

Parameters:
producer (input)
The handle for the message producer.
timeToLive (output)
The default time to live in milliseconds. A value of 0 means that a message never expires. For a real-time connection to a broker, the value is always 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSend – Send

Interface:
xmsRC xmsMsgProducerSend(xmsHMsgProducer producer,
                         xmsHMsg message,
                         xmsHErrorBlock errorBlock);

Send a message to the destination that was specified when the message producer was created. Send the message using the message producer's default delivery mode, priority, and time to live.

Parameters:
producer (input)
The handle for the message producer.
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_FORMAT_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsMsgProducerSendDest – Send (to a specified destination)

Interface:
xmsRC xmsMsgProducerSendDest(xmsHMsgProducer producer,
                             xmsHDest destination,
                             xmsHMsg message,
                             xmsHErrorBlock errorBlock);

Send a message to a specified destination if you are using a message producer for which no destination was specified when the message producer was created. Send the message using the message producer's default delivery mode, priority, and time to live.

Typically, you specify a destination when you create a message producer but, if you do not, you must specify a destination every time you send a message.

Parameters:
producer (input)
The handle for the message producer.
destination (input)
The handle for the destination.
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_FORMAT_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsMsgProducerSendDestWithAttr – Send (to a specified destination, specifying a delivery mode, priority, and time to live)

Interface:
xmsRC xmsMsgProducerSendDestWithAttr(xmsHMsgProducer producer,
                                     xmsHDest destination,
                                     xmsHMsg message,
                                     xmsINT deliveryMode,
                                     xmsINT priority,
                                     xmsLONG timeToLive,
                                     xmsHErrorBlock errorBlock);

Send a message to a specified destination if you are using a message producer for which no destination was specified when the message producer was created. Send the message using the specified delivery mode, priority, and time to live.

Typically, you specify a destination when you create a message producer but, if you do not, you must specify a destination every time you send a message.

Parameters:
producer (input)
The handle for the message producer.
destination (input)
The handle for the destination.
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode for the message, which must be one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT

For a real-time connection to a broker, the value must be XMSC_DELIVERY_NON_PERSISTENT.

priority (input)
The priority of the message. The value can be an integer in the range 0, for the lowest priority, to 9, for the highest priority. On a real-time connection to a broker, the value is ignored.
timeToLive (input)
The time to live for the message in milliseconds. A value of 0 means that the message never expires. For a real-time connection to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_FORMAT_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgProducerSendWithAttr – Send (specifying a delivery mode, priority, and time to live)

Interface:
xmsRC xmsMsgProducerSendWithAttr(xmsHMsgProducer producer,
                                 xmsHMsg message,
                                 xmsINT deliveryMode,
                                 xmsINT priority,
                                 xmsLONG timeToLive,
                                 xmsHErrorBlock errorBlock);

Send a message to the destination that was specified when the message producer was created. Send the message using the specified delivery mode, priority, and time to live.

Parameters:
producer (input)
The handle for the message producer.
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode for the message, which must be one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT

For a real-time connection to a broker, the value must be XMSC_DELIVERY_NON_PERSISTENT.

priority (input)
The priority of the message. The value can be an integer in the range 0, for the lowest priority, to 9, for the highest priority. On a real-time connection to a broker, the value is ignored.
timeToLive (input)
The time to live for the message in milliseconds. A value of 0 means that the message never expires. For a real-time connection to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_FORMAT_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgProducerSetDeliveryMode – Set Default Delivery Mode

Interface:
xmsRC xmsMsgProducerSetDeliveryMode(xmsHMsgProducer producer,
                                    xmsINT deliveryMode,
                                    xmsHErrorBlock errorBlock);

Set the default delivery mode for messages sent by the message producer.

Parameters:
producer (input)
The handle for the message producer.
deliveryMode (input)
The default delivery mode, which must be one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT

For a real-time connection to a broker, the value must be XMSC_DELIVERY_NON_PERSISTENT.

The default value is XMSC_DELIVERY_PERSISTENT, except for a real-time connection to a broker for which the default value is XMSC_DELIVERY_NON_PERSISTENT.

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetDisableMsgID – Set Disable Message ID Flag

Interface:
xmsRC xmsMsgProducerSetDisableMsgID(xmsHMsgProducer producer,
                                    xmsBOOL msgIDDisabled,
                                    xmsHErrorBlock errorBlock);

Indicate whether a receiving application requires message identifiers to be included in messages sent by the message producer.

On a connection to a queue manager, or on a real-time connection to a broker, this flag is ignored. On a connection to a service integration bus, the flag is honoured.

Parameters:
producer (input)
The handle for the message producer.
msgIDDisabled (input)
The value xmsTRUE means that a receiving application does not require message identifiers to be included in messages sent by the message producer. The value xmsFALSE means that a receiving application does require message identifiers. The default value is xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetDisableMsgTS – Set Disable Time Stamp Flag

Interface:
xmsRC xmsMsgProducerSetDisableMsgTS(xmsHMsgProducer producer,
                                    xmsBOOL timeStampDisabled,
                                    xmsHErrorBlock errorBlock);

Indicate whether a receiving application requires time stamps to be included in messages sent by the message producer.

On a real-time connection to a broker, this flag is ignored. On a connection to a queue manager, or on a connection to a service integration bus, the flag is honoured.

Parameters:
producer (input)
The handle for the message producer.
timeStampDisabled (input)
The value xmsTRUE means that a receiving application does not require time stamps to be included in messages sent by the message producer. The value xmsFALSE means that a receiving application does require time stamps. The default value is xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetPriority – Set Default Priority

Interface:
xmsRC xmsMsgProducerSetPriority(xmsHMsgProducer producer,
                                xmsINT priority,
                                xmsHErrorBlock errorBlock);

Set the default priority for messages sent by the message producer.

On a real-time connection to a broker, the priority of a message is ignored.

Parameters:
producer (input)
The handle for the message producer.
priority (input)
The default message priority. The value can be an integer in the range 0, for the lowest priority, to 9, for the highest priority. The default value is 4.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetTimeToLive – Set Default Time to Live

Interface:
xmsRC xmsMsgProducerSetTimeToLive(xmsHMsgProducer producer,
                                  xmsLONG timeToLive,
                                  xmsHErrorBlock errorBlock);

Set the default length of time that a message exists before it expires. The time is measured from when the message producer sends the message.

Parameters:
producer (input)
The handle for the message producer.
timeToLive (input)
The default time to live in milliseconds. The default value is 0, which means that a message never expires. For a real-time connection to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.