TipcMtGetDeliveryMode

Name

TipcMtGetDeliveryMode — get the delivery mode of a message type

Synopsis

T_BOOL TipcMtGetDeliveryMode(mt, delivery_mode_return) 
T_IPC_MT mt; 
T_IPC_DELIVERY_MODE *delivery_mode_return; 

Arguments

mt — message type to get delivery mode from

delivery_mode_return — storage for message type delivery mode

Return Values

TRUE if the delivery mode was successfully retrieved from the message type, FALSE otherwise.

Diagnostics

If TipcMtGetDeliveryMode fails, it returns FALSE and sets the global SmartSockets error number to:

Description

TipcMtGetDeliveryMode gets the delivery mode of a message type. The delivery mode of a message type is used as the default delivery mode for messages of this type. When a message is created, its delivery mode is initialized to the message type delivery mode.

The default message delivery mode is T_IPC_DELIVERY_BEST_EFFORT. In this mode, no special actions are taken to ensure delivery of sent messages. The message is delivered unless network failures or process failures occur. If the message is not delivered, there is no way for the sender to know that delivery failed. When there is a failure, it is possible for some messages to be lost or be delivered in a different order than the order in which they were published.

In the case of a network or process failure, a more useful delivery mode is T_IPC_DELIVERY_ORDERED. Messages can still be lost in the event of a failure, but all delivered messages are received in the order in which they were published. Because Java Message Service (JMS) cannot handle messages that come out of order, you must use the T_IPC_DELIVERY_ORDERED delivery mode or one of the GMD delivery modes if you are sending messages to a JMS client.

The difference between the other delivery modes and the GMD delivery modes is that in GMD, a copy of the message is kept when the message is sent and acknowledgements are sent when the message is received. No acknowledgements (ACKs) are used in the ordered or best effort delivery modes, and no copy of the message is kept.

One of the GMD delivery modes is T_IPC_DELIVERY_SOME. In this mode, the sending process saves a copy of the message in the connection GMD area until the message is successfully delivered, and the sender can also resend the message if necessary. Delivery is considered successful if the sent message is acknowledged by at least one receiving process.

The other and most robust GMD delivery mode is T_IPC_DELIVERY_ALL. In this mode, the sending process saves a copy of the message in the connection GMD area until the message is successfully delivered, and the sender can also resend the message if necessary. Delivery is not considered successful until all receiving processes acknowledge the sent message. For two processes communicating through a non-RTclient and non-RTserver T_IPC_CONN connection, T_IPC_DELIVERY_SOME and T_IPC_DELIVERY_ALL are identical because there is only one process receiving the message. For RTclients, the two modes do differ if more than one RTclient is subscribing to the subject in the destination of the message.

The delivery mode of an outgoing message can always be set on a per-message basis, but using message type delivery modes makes it easier to change the default delivery mode for all outgoing messages of a specific type. The standard SmartSockets message types by default usually have a delivery mode of T_IPC_DELIVERY_BEST_EFFORT, but these can be changed. The exception is the SmartSockets JMS message types, which have a delivery mode of T_IPC_DELIVERY_ORDERED, but that can also be changed. User-defined message types can also use whatever delivery mode is appropriate.

Caution

If TipcMtGetDeliveryMode returns FALSE, it does not store a value in delivery_mode_return.

See Also

TipcMsgGetDeliveryMode, TipcMtSetDeliveryMode

Examples

This example prints the delivery mode of the NUMERIC_DATA message type:

T_IPC_MT mt; 
T_IPC_DELIVERY_MODE delivery_mode; 
T_STR delivery_mode_str; 
 
mt = TipcMtLookup("numeric_data"); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (!TipcMtGetDeliveryMode(mt, &delivery_mode)) { 
  return;  /* error */ 
} 
 
/* convert the delivery mode to a string to make it easier to read */ 
if (!TipcDeliveryModeToStr(delivery_mode, &delivery_mode_str)) { 
  return;  /* error */ 
} 
 
TutOut("NUMERIC_DATA msg type has delivery mode %s\n",  
       delivery_mode_str);