Chapter 5 Producer : tibemsMsgProducer

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.
 
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
 
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
 
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
 
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
 
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
 
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
 
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
 
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
 
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
 
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.
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.
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.
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
 
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
 
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
 
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
 
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
 
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
 
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.