> tibemsMsgProducer
> Type
> Purpose
> Send message to destinations on the server.
> Remarks
> Clients use message producers to send messages. A message producer object can store several parameters that affect the messages it sends.
> Clients create message producers using functions of a tibemsSession object.

> Function | Description | Page
> tibemsMsgProducer_Close | Destroy the producer object; reclaim resources. | 176
> tibemsMsgProducer_GetDeliveryMode | Get the delivery mode property of a producer object. | 177
> tibemsMsgProducer_GetDestination | Get the destination of a message producer object. | 178
> tibemsMsgProducer_GetDisableMessageID | Get the disable message ID property of a producer object. | 179
> tibemsMsgProducer_GetDisableMessageTimestamp | Get the disable message timestamp property of a producer object. | 180
> tibemsMsgProducer_GetNPSendCheckMode | Get the mode that defines when a producer checks the result of sending a NON_PERSISTENT message. | 181
> tibemsMsgProducer_GetPriority | Get the priority property of a producer object. | 182
> tibemsMsgProducer_GetTimeToLive | Get the time-to-live property of a producer object. | 183
> tibemsMsgProducer_Send tibemsMsgProducer_SendEx tibemsMsgProducer_SendToDestination tibemsMsgProducer_SendToDestinationEx | Send a message. | 184
> tibemsMsgProducer_SetDeliveryMode | Set the delivery mode property of a producer object. | 187
> tibemsMsgProducer_SetDisableMessageID | Set the disable message ID property of a producer object. | 188
> tibemsMsgProducer_SetDisableMessageTimestamp | Set the disable message timestamp property of a producer object. | 189
> tibemsMsgProducer_SetNPSendCheckMode | Set when a producer should check the result of sending a NON_PERSISTENT message. | 190
> tibemsMsgProducer_SetPriority | Set the priority property of a producer object. | 192
> tibemsMsgProducer_SetTimeToLive | Set the time-to-live property of a producer object. | 193

> See Also
> tibemsSession_CreateProducer on page 300
> tibemsMsgProducer_Close
> Function
> Purpose
> Destroy the producer object; reclaim resources.
> C Declaration
> tibems_status tibemsMsgProducer_Close(
> tibemsMsgProducer msgProducer );
> COBOL Call
> CALL "tibemsMsgProducer_Close"
> USING BY VALUE msgProducer,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Close this producer.

> Remarks
> This call also notifies the server that the client program is closing the producer. In response, the server reclaims storage associated with the producer.
> Your program must explicitly close all producers that it creates.
> See Also
> tibemsSession_CreateProducer on page 300
> tibemsMsgProducer_GetDeliveryMode
> Function
> Purpose
> Get the delivery mode property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetDeliveryMode(
> tibemsMsgProducer msgProducer,
> tibems_int* deliveryMode );
> COBOL Call
> CALL "tibemsMsgProducer_GetDeliveryMode"
> USING BY VALUE msgProducer,
> BY REFERENCE deliveryMode,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> deliveryMode | The function stores the property in this location.

> Remarks
> Delivery mode instructs the server concerning persistent storage.
> Programs can use this property to define a default delivery mode for messages that this producer sends. Individual sending calls can override this default value.
> For values, see the type tibemsDeliveryMode on page 127.
> tibemsMsgProducer_GetDestination
> Function
> Purpose
> Get the destination of a message producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetDestination(
> tibemsMsgProducer msgProducer,
> tibemsDestination* destination );
> COBOL Call
> CALL "tibemsMsgProducer_GetDestination"
> USING BY VALUE msgProducer,
> BY REFERENCE destination,
> RETURNING tibems-status
> END-CALL.

> | msgProducer and destination have usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the destination from this producer.
> destination | The function stores the destination in this location.

> Remarks
> Each send call directs a message to a destination.
> Programs can use this property to define a default destination for messages that this producer sends. Individual sending calls can override this default value.
> Programs set this destination when creating the sender, and cannot subsequently change it.
> tibemsMsgProducer_GetDisableMessageID
> Function
> Purpose
> Get the disable message ID property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetDisableMessageID(
> tibemsMsgProducer msgProducer,
> tibems_bool* disable );
> COBOL Call
> CALL "tibemsMsgProducer_GetDisableMessageID"
> USING BY VALUE msgProducer,
> BY REFERENCE disable,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> disable | The function stores the property in this location.

> Remarks
> Applications that do not require message IDs can reduce overhead costs by disabling IDs (set this property to true).
> tibemsMsgProducer_GetDisableMessageTimestamp
> Function
> Purpose
> Get the disable message timestamp property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetDisableMessageTimestamp(
> tibemsMsgProducer msgProducer,
> tibems_bool* disable );
> COBOL Call
> CALL "tibemsMsgProducer_GetDisableMessageTimestamp"
> USING BY VALUE msgProducer,
> BY REFERENCE disable,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> disableMessageTimeStamp | The function stores the property in this location.

> Remarks
> Applications that do not require timestamps can reduce overhead costs by disabling timestamps (set this property to true).
> tibemsMsgProducer_GetNPSendCheckMode
> Function
> Purpose
> Get the mode that defines when a producer checks the result of sending a NON_PERSISTENT message.
> C Declaration
> extern tibems_status tibemsMsgProducer_GetNPSendCheckMode(
> tibemsMsgProducer msgProducer,
> tibemsNpCheckMode* mode);
> COBOL Call
> CALL "tibemsMsgProducer_GetNPSendCheckMode"
> USING BY VALUE msgProducer,
> BY REFERENCE mode,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> mode | The function stores the mode in this location. Must not be null. See tibemsNpCheckMode on page 128 for details.

> Remarks
> This function returns the send check mode set by the tibemsMsgProducer_SetNPSendCheckMode function. If the returned value is NPSEND_CHECK_DEFAULT, then the effective mode can be set by the server parameter applied to all producers.
> See Also
> tibemsMsgProducer_SetNPSendCheckMode on page 190
> tibemsMsgProducer_GetPriority
> Function
> Purpose
> Get the priority property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetPriority(
> tibemsMsgProducer msgProducer,
> tibems_int* priority );
> COBOL Call
> CALL "tibemsMsgProducer_GetPriority"
> USING BY VALUE msgProducer,
> BY REFERENCE priority,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> priority | The function stores the property in this location.

> Remarks
> Priority affects the order in which the server delivers messages to consumers (higher values first).
> The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
> Programs can use this property to define a default priority for messages that this producer sends. Individual sending calls can override this default value.
> tibemsMsgProducer_GetTimeToLive
> Function
> Purpose
> Get the time-to-live property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_GetTimeToLive(
> tibemsMsgProducer msgProducer,
> tibems_long* timeToLive );
> COBOL Call
> CALL "tibemsMsgProducer_GetTimeToLive"
> USING BY VALUE msgProducer,
> BY REFERENCE timeToLive,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Get the property from this producer.
> timeToLive | The function stores the property in this location.

> Remarks
> Time-to-live (in milliseconds) determines the expiration time of a message.

> ● | If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.

> ● | If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.

> Programs can use this property to define a default time-to-live for messages that this producer sends. Individual sending calls can override this default value.
> Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.
> tibemsMsgProducer_Send
> Function
> Purpose
> Send a message.
> C Declaration
> tibems_status tibemsMsgProducer_Send(
> tibemsMsgProducer msgProducer,
> tibemsMsg message );
> tibems_status tibemsMsgProducer_SendEx(
> tibemsMsgProducer msgProducer,
> tibemsMsg message,
> tibems_int deliveryMode,
> tibems_int priority,
> tibems_long timeToLive );
> tibems_status tibemsMsgProducer_SendToDestination(
> tibemsMsgProducer msgProducer,
> tibemsDestination destination,
> tibemsMsg message );
> tibems_status tibemsMsgProducer_SendToDestinationEx(
> tibemsMsgProducer msgProducer,
> tibemsDestination destination,
> tibemsMsg message,
> tibemsDeliveryMode deliveryMode,
> tibems_int priority,
> tibems_long timeToLive );
> COBOL Call
> CALL "tibemsMsgProducer_Send"
> USING BY VALUE msgProducer,
> BY VALUE message,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsgProducer_SendEx"
> USING BY VALUE msgProducer,
> BY VALUE message,
> BY VALUE deliveryMode,
> BY VALUE priority,
> BY VALUE timeToLive,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsgProducer_SendToDestination"
> USING BY VALUE msgProducer,
> BY VALUE destination,
> BY VALUE message,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsgProducer_SendToDestinationEx"
> USING BY VALUE msgProducer,
> BY VALUE destination,
> BY VALUE message,
> BY VALUE deliveryMode,
> BY VALUE priority,
> BY VALUE timeToLive,
> RETURNING tibems-status
> END-CALL.

> | msgProducer, message and destination have usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Send a message through this producer object.
> destination | When present, the call sends the message to this destination (queue or topic). Other send calls send the message to the producer’s default destination. When the producer does not specify a default, the send call must supply this parameter.
> message | Send this message object.
> deliveryMode | When present, the call sends the message with this delivery mode. This argument is an enumerated value (see tibemsDeliveryMode on page 127). Other send calls send the message with the producer’s default delivery mode.
> priority | When present, the call sends the message with this priority. Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority. Other send calls send the message with the producer’s default priority.
> timeToLive | When present, the call uses this value (in milliseconds) to compute the message expiration.
> ● | If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.
> ● | If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
> Other send calls use the producer’s default value to compute expiration. Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.

> tibemsMsgProducer_SetDeliveryMode
> Function
> Purpose
> Set the delivery mode property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_SetDeliveryMode(
> tibemsMsgProducer msgProducer,
> tibems_int deliveryMode );
> COBOL Call
> CALL "tibemsMsgProducer_SetDeliveryMode"
> USING BY VALUE msgProducer,
> BY VALUE deliveryMode,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> deliveryMode | Set the property to this value.

> Remarks
> Delivery mode instructs the server concerning persistent storage.
> Programs can use this property to define a default delivery mode for messages that this producer sends. Individual sending calls can override this default value.
> For values, see the type tibemsDeliveryMode on page 127.
> tibemsMsgProducer_SetDisableMessageID
> Function
> Purpose
> Set the disable message ID property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_SetDisableMessageID(
> tibemsMsgProducer msgProducer,
> tibems_bool disable );
> COBOL Call
> CALL "tibemsMsgProducer_SetDisableMessageID"
> USING BY VALUE msgProducer,
> BY VALUE disable,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> disable | Set the property to this value.

> Remarks
> Applications that do not require message IDs can reduce overhead costs by disabling IDs (set this property to true).
> tibemsMsgProducer_SetDisableMessageTimestamp
> Function
> Purpose
> Set the disable message timestamp property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_SetDisableMessageTimestamp(
> tibemsMsgProducer msgProducer,
> tibems_bool disable );
> COBOL Call
> CALL "tibemsMsgProducer_SetDisableMessageTimestamp"
> USING BY VALUE msgProducer,
> BY VALUE disable,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> disable | Set the property to this value.

> Remarks
> Applications that do not require timestamps can reduce overhead costs by disabling timestamps (set this property to true).
> tibemsMsgProducer_SetNPSendCheckMode
> Function
> Purpose
> Set when a producer should check the result of sending a NON_PERSISTENT message.
> C Declaration
> extern tibems_status tibemsMsgProducer_SetNPSendCheckMode(
> tibemsMsgProducer msgProducer,
> tibemsNpCheckMode mode);
> COBOL Call
> CALL "tibemsMsgProducer_SetNPSendCheckMode"
> USING BY VALUE msgProducer,
> BY VALUE mode,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> mode | The send check mode. See tibemsNpCheckMode on page 128 for details.

> Remarks
> tibemsNpCheckMode only applies to messages sent using the NON_PERSISTENT delivery mode, using non-transactional Session. It does not apply to cases when message was sent using PERSISTENT or RELIABLE_DELIVERY delivery modes, or if the corresponding Session is transactional.
> If the producer's send check mode is not set, it may execute the mode applied globally to all producers via EMS server parameter. Setting any mode other than NPSEND_CHECK_DEFAULT unconditionally overrides global setting defined by the server.
> Normally applications use the server's setting or configure producers with a specific send mode only once. However, if required, applications may choose to change this mode before sending every message.
> If a producer does not check the result of sending a message, it will not know if a problem has occurred and the message was not processed by the server. If the producer checks the result of the send, the send method will receive the server's response to the send and throw the appropriate exception if any problem has occurred. However, checking the result of sending a message will reduce the performance of the producer.
> See Also
> tibemsMsgProducer_GetNPSendCheckMode on page 181
> tibemsMsgProducer_SetPriority
> Function
> Purpose
> Set the priority property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_SetPriority(
> tibemsMsgProducer msgProducer,
> tibems_int priority );
> COBOL Call
> CALL "tibemsMsgProducer_SetPriority"
> USING BY VALUE msgProducer,
> BY VALUE priority,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> priority | Set the property to this value.

> Remarks
> Priority affects the order in which the server delivers messages to consumers (higher values first).
> The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
> Programs can use this property to define a default priority for messages that this producer sends. Individual sending calls can override this default value.
> tibemsMsgProducer_SetTimeToLive
> Function
> Purpose
> Set the time-to-live property of a producer object.
> C Declaration
> tibems_status tibemsMsgProducer_SetTimeToLive(
> tibemsMsgProducer msgProducer,
> tibems_long timeToLive );
> COBOL Call
> CALL "tibemsMsgProducer_SetTimeToLive"
> USING BY VALUE msgProducer,
> BY VALUE timeToLive,
> RETURNING tibems-status
> END-CALL.

> | msgProducer has usage pointer.

> Parameters

> Parameter | Description
> msgProducer | Set the property of this producer.
> timeToLive | Set the property to this value.

> Remarks
> Time-to-live (in milliseconds) determines the expiration time of a message.

> ● | If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.

> ● | If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.

> Programs can use this property to define a default time-to-live for messages that this producer sends. Individual sending calls can override this default value.
> Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.

Copyright © TIBCO Software Inc. All Rights Reserved.