TIBCO FTL®

Public Member Functions | List of all members
TIBCO.FTL.IMessage Interface Reference

Message objects contain fields with values. More...

Inheritance diagram for TIBCO.FTL.IMessage:

## Public Member Functions
void | Acknowledge ()
| Explicitly acknowledge a message. More...
void | ClearAllFields ()
| Clear all fields in a mutable message. More...
void | ClearField (IMessageFieldRef messageRef)
| Clear a field in a mutable message. More...
void | ClearField (string name)
| Clear a field in a mutable message. More...
TibDateTime | GetDateTime (IMessageFieldRef messageRef)
| Get the value of a TibDateTime field from a message. More...
void | GetDateTime (IMessageFieldRef messageRef, ref TibDateTime dateTime)
| Get the value of a `TibDateTime` field from a message, and store it in an existing TibDateTime object. More...
TibDateTime | GetDateTime (string name)
| Get the value of a TibDateTime field from a message. More...
void | GetDateTime (string name, ref TibDateTime dateTime)
| Get the value of a `TibDateTime` field from a message, and store it in an existing TibDateTime object. More...
TibDateTime[] | GetDateTimeArray (IMessageFieldRef messageRef)
| Get the value of a TibDateTime array field from a message. More...
TibDateTime[] | GetDateTimeArray (string name)
| Get the value of a TibDateTime array field from a message. More...
int | GetDeliveryCount ()
| Get the delivery count of a message. More...
double | GetDouble (IMessageFieldRef messageRef)
| Get the value of a double floating-point field from a message. More...
double | GetDouble (string name)
| Get the value of a double floating-point field from a message. More...
double[] | GetDoubleArray (IMessageFieldRef messageRef)
| Get the value of a double array field from a message. More...
double[] | GetDoubleArray (string name)
| Get the value of a double array field from a message. More...
long | GetFieldCount ()
| Get the number of fields from the message's format. More...
byte[] | GetFieldsFingerPrint ()
| Return a fingerprint representing a message's set fields. More...
FieldType | GetFieldType (IMessageFieldRef messageRef)
| Get the type of a field within the message. More...
FieldType | GetFieldType (string name)
| Get the type of a field within the message. More...
string | GetFieldTypeString (FieldType type)
| Return a string that represents a field type. More...
IInbox | GetInbox (IMessageFieldRef messageRef)
| Get the value of an inbox field from a message. More...
IInbox | GetInbox (string name)
| Get the value of an inbox field from a message. More...
long | GetLong (IMessageFieldRef messageRef)
| Get the value of a long integer field from a message. More...
long | GetLong (string name)
| Get the value of a long integer field from a message. More...
long[] | GetLongArray (IMessageFieldRef messageRef)
| Get the value of a long array field from a message. More...
long[] | GetLongArray (string name)
| Get the value of a long array field from a message. More...
IMessage | GetMessage (IMessageFieldRef messageRef)
| Get the value of a message field from a message. More...
IMessage | GetMessage (string name)
| Get the value of a message field from a message. More...
IMessage[] | GetMessageArray (IMessageFieldRef messageRef)
| Get the value of a message array field from a message. More...
IMessage[] | GetMessageArray (string name)
| Get the value of a message array field from a message. More...
byte[] | GetOpaque (IMessageFieldRef messageRef)
| Get the value of an opaque field from a message. More...
IntPtr | GetOpaque (IMessageFieldRef messageRef, out int size)
| Get a pointer to the content of an opaque field from a message. More...
int | GetOpaque (IMessageFieldRef messageRef, ref byte[] bytes)
| Get the value of an opaque field from a message. More...
byte[] | GetOpaque (string name)
| Get the value of an opaque field from a message. More...
IntPtr | GetOpaque (string name, out int size)
| Get a pointer to the content of an opaque field from a message. More...
int | GetOpaque (string name, ref byte[] bytes)
| Get the value of an opaque field from a message. More...
long | GetStoreLocalMessageId ()
| Get the store local message id as assigned by the persistence service. More...
string | GetString (IMessageFieldRef messageRef)
| Get the value of a string field from a message. More...
string | GetString (string name)
| Get the value of a string field from a message. More...
string[] | GetStringArray (IMessageFieldRef messageRef)
| Get the value of a string array field from a message. More...
string[] | GetStringArray (string name)
| Get the value of a string array field from a message. More...
bool | IsFieldSet (IMessageFieldRef messageRef)
| Determine whether a field is set in a message. More...
bool | IsFieldSet (string name)
| Determine whether a field is set in a message. More...
IMessage | MutableCopy ()
| Create a mutable copy of a message. More...
void | SetArray (IMessageFieldRef messageRef, double[] value)
| Set a double array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, double[] value, int index, int count)
| Set a double array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, IMessage[] messages)
| Set a sub-message array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, IMessage[] messages, int index, int count)
| Set a sub-message array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, long[] value)
| Set a long array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, long[] value, int index, int count)
| Set a long array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, string[] value)
| Set a string array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, string[] value, int index, int count)
| Set a string array field in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, TibDateTime[] value)
| Set a TibDateTime array in a mutable message. More...
void | SetArray (IMessageFieldRef messageRef, TibDateTime[] value, int index, int count)
| Set a TibDateTime array in a mutable message. More...
void | SetArray (string name, double[] value)
| Set a double array field in a mutable message. More...
void | SetArray (string name, double[] value, int index, int count)
| Set a double array field in a mutable message. More...
void | SetArray (string name, IMessage[] messages)
| Set a sub-message array field in a mutable message. More...
void | SetArray (string name, IMessage[] messages, int index, int count)
| Set a sub-message array field in a mutable message. More...
void | SetArray (string name, long[] value)
| Set a long array field in a mutable message. More...
void | SetArray (string name, long[] value, int index, int count)
| Set a long array field in a mutable message. More...
void | SetArray (string name, string[] value)
| Set a string array field in a mutable message. More...
void | SetArray (string name, string[] value, int index, int count)
| Set a string array field in a mutable message. More...
void | SetArray (string name, TibDateTime[] value)
| Set a TibDateTime array field in a mutable message. More...
void | SetArray (string name, TibDateTime[] value, int index, int count)
| Set a TibDateTime array field in a mutable message. More...
void | SetDateTime (IMessageFieldRef messageRef, TibDateTime value)
| Set a TibDateTime field in a mutable message. More...
void | SetDateTime (string name, TibDateTime value)
| Set a TibDateTime field in a mutable message. More...
void | SetDouble (IMessageFieldRef messageRef, double value)
| Set a double floating-point field in a mutable message. More...
void | SetDouble (string name, double value)
| Set a double floating-point field in a mutable message. More...
void | SetInbox (IMessageFieldRef messageRef, IInbox inbox)
| Set an inbox field in a mutable message. More...
void | SetInbox (string name, IInbox inbox)
| Set an inbox field in a mutable message. More...
void | SetLong (IMessageFieldRef messageRef, long value)
| Set a long integer field in a mutable message. More...
void | SetLong (string name, long value)
| Set a long integer field in a mutable message. More...
void | SetMessage (IMessageFieldRef messageRef, IMessage msg)
| Set a sub-message field in a mutable message. More...
void | SetMessage (string name, IMessage msg)
| Set a sub-message field in a mutable message. More...
void | SetOpaque (IMessageFieldRef messageRef, byte[] value)
| Set an opaque (byte-array) field in a mutable message. More...
void | SetOpaque (IMessageFieldRef messageRef, byte[] value, int length)
| Set an opaque (byte-array) field in a mutable message. More...
void | SetOpaque (string name, byte[] value)
| Set an opaque (byte-array) field in a mutable message. More...
void | SetOpaque (string name, byte[] value, int length)
| Set an opaque (byte-array) field in a mutable message. More...
void | SetOpaqueDirect (IMessageFieldRef messageRef, IntPtr value, int length)
void | SetOpaqueDirect (string name, IntPtr value, int length)
| Set a field in a mutable message to contain a direct opaque value. More...
void | SetString (IMessageFieldRef messageRef, string value)
| Set a string field in a mutable message. More...
void | SetString (string name, string value)
| Set a string field in a mutable message. More...
int | WriteToByteArray (byte[] bytes)
| Write a serialized representation of a message to a byte-array. More...
int | WriteToPortableByteArray (byte[] bytes)
| Write a self-describing serialized representation of a message to a byte-array. More...

## Detailed Description

Message objects contain fields with values.

This interface defines message objects and the methods that manipulate them.

To create a mutable message object, call IRealm.CreateMessage() or IMessage.MutableCopy().

If a subscriber has set the release to callback property, then the program must explicitly destroy all messages it receives through dispatch from that subscriber. Otherwise, the program must not destroy messages received through dispatch.

Programs must never Dispose immutable messages.

Customers do not implement this interface.

See also
  IMessageFieldRef

## Member Function Documentation

## ◆ Acknowledge()

void TIBCO.FTL.IMessage.Acknowledge | ( |  | ) |

Explicitly acknowledge a message.

When a durable subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable by calling this method.

When a durable subscriber object does not specify explicit acknowledgement, the FTL library automatically acknowledges the message when the application callback method returns.

For any message that arrives through a non-durable subscriber, this call returns without error (and without action).

See also
  FTL.SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

## ◆ ClearAllFields()

void TIBCO.FTL.IMessage.ClearAllFields | ( |  | ) |

Clear all fields in a mutable message.

After clearing all fields, you can re-use the message. The message format does not change.

This call is more efficient than creating a new empty message of the same format.

## ◆ ClearField() [1/2]

void TIBCO.FTL.IMessage.ClearField | ( | IMessageFieldRef | messageRef | ) |

Clear a field in a mutable message.

Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.

Parameters

  messageRef | The method clears this field.

Exceptions

  FTLException | The field is not defined in the format.

## ◆ ClearField() [2/2]

void TIBCO.FTL.IMessage.ClearField | ( | string | name | ) |

Clear a field in a mutable message.

Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.

Parameters

  name | The method clears the field with this name.

Exceptions

  FTLException | The field is not defined in the format.

## ◆ GetDateTime() [1/4]

TibDateTime TIBCO.FTL.IMessage.GetDateTime | ( | IMessageFieldRef | messageRef | ) |

Get the value of a TibDateTime field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The TibDateTime value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDateTime() [2/4]

void TIBCO.FTL.IMessage.GetDateTime | ( | IMessageFieldRef | messageRef,
|  | ref TibDateTime | dateTime
| ) |  |

Get the value of a `TibDateTime` field from a message, and store it in an existing TibDateTime object.

Parameters

  messageRef | The method gets the value of this field.
  dateTime | The method stores the value into this `TibDateTime` object.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDateTime() [3/4]

TibDateTime TIBCO.FTL.IMessage.GetDateTime | ( | string | name | ) |

Get the value of a TibDateTime field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The TibDateTime value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDateTime() [4/4]

void TIBCO.FTL.IMessage.GetDateTime | ( | string | name,
|  | ref TibDateTime | dateTime
| ) |  |

Get the value of a `TibDateTime` field from a message, and store it in an existing TibDateTime object.

Parameters

  name | The method gets the value of the field with this name.
  dateTime | The method stores the value into this `TibDateTime` object.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDateTimeArray() [1/2]

TibDateTime[] TIBCO.FTL.IMessage.GetDateTimeArray | ( | IMessageFieldRef | messageRef | ) |

Get the value of a TibDateTime array field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDateTimeArray() [2/2]

TibDateTime[] TIBCO.FTL.IMessage.GetDateTimeArray | ( | string | name | ) |

Get the value of a TibDateTime array field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The TibDateTime array value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDeliveryCount()

int TIBCO.FTL.IMessage.GetDeliveryCount | ( |  | ) |

Get the delivery count of a message.

This value represents the number of times that a persistence service has delivered the message from a standard or shared durable to any subscriber. The value 1 indicates the application is the first to receive the message.

The special value -1 indicates that delivery count does not apply. For example, the message is not in a shared durable or did not arrive from a persistence server that tracks delivery count.

Returns
  An integer: the delivery count

## ◆ GetDouble() [1/2]

double TIBCO.FTL.IMessage.GetDouble | ( | IMessageFieldRef | messageRef | ) |

Get the value of a double floating-point field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The double value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDouble() [2/2]

double TIBCO.FTL.IMessage.GetDouble | ( | string | name | ) |

Get the value of a double floating-point field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The double value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDoubleArray() [1/2]

double[] TIBCO.FTL.IMessage.GetDoubleArray | ( | IMessageFieldRef | messageRef | ) |

Get the value of a double array field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetDoubleArray() [2/2]

double[] TIBCO.FTL.IMessage.GetDoubleArray | ( | string | name | ) |

Get the value of a double array field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetFieldCount()

long TIBCO.FTL.IMessage.GetFieldCount | ( |  | ) |

Get the number of fields from the message's format.

This call returns the number of field from the message's format.

Returns
  The number of fields from the message's format.

## ◆ GetFieldsFingerPrint()

byte[] TIBCO.FTL.IMessage.GetFieldsFingerPrint | ( |  | ) |

Return a fingerprint representing a message's set fields.

A message's fields fingerprint is calculated based on the message's set fields, taking into account each field's position, type, and name, but not value.

## ◆ GetFieldType() [1/2]

FieldType TIBCO.FTL.IMessage.GetFieldType | ( | IMessageFieldRef | messageRef | ) |

Get the type of a field within the message.

Parameters

  messageRef | The method gets the type of this field.

Returns
  The field's type as a FieldType.

## ◆ GetFieldType() [2/2]

FieldType TIBCO.FTL.IMessage.GetFieldType | ( | string | name | ) |

Get the type of a field within the message.

Parameters

  name | The method gets the type of the field with this name.

Returns
  The field's type as a FieldType.

## ◆ GetFieldTypeString()

string TIBCO.FTL.IMessage.GetFieldTypeString | ( | FieldType | type | ) |

Return a string that represents a field type.

Parameters

  type | The method converts this type to a string.

Returns
  A string corresponding to the type argument

Exceptions

  FTLInvalidArgumentException | The type is not defined as a FieldType.

## ◆ GetInbox() [1/2]

IInbox TIBCO.FTL.IMessage.GetInbox | ( | IMessageFieldRef | messageRef | ) |

Get the value of an inbox field from a message.

This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor `Dispose` the inbox object.

Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.

Programs can send messages to the inbox using IPublisher.SendToInbox.

Parameters

  messageRef | The method gets the value of this field.

Returns
  An Inbox object.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetInbox() [2/2]

IInbox TIBCO.FTL.IMessage.GetInbox | ( | string | name | ) |

Get the value of an inbox field from a message.

This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor `Dispose` the inbox object.

Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.

Programs can send messages to the inbox using IPublisher.SendToInbox.

Parameters

  name | The method gets the value of the field with this name.

Returns
  An Inbox object.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetLong() [1/2]

long TIBCO.FTL.IMessage.GetLong | ( | IMessageFieldRef | messageRef | ) |

Get the value of a long integer field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The long value of a field.

## ◆ GetLong() [2/2]

long TIBCO.FTL.IMessage.GetLong | ( | string | name | ) |

Get the value of a long integer field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The long value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetLongArray() [1/2]

long[] TIBCO.FTL.IMessage.GetLongArray | ( | IMessageFieldRef | messageRef | ) |

Get the value of a long array field from a message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetLongArray() [2/2]

long[] TIBCO.FTL.IMessage.GetLongArray | ( | string | name | ) |

Get the value of a long array field from a message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The array value of the field.

## ◆ GetMessage() [1/2]

IMessage TIBCO.FTL.IMessage.GetMessage | ( | IMessageFieldRef | messageRef | ) |

Get the value of a message field from a message.

This call deserializes the sub-message value, caches the result with the message object, and returns that cached sub-message. The sub-message is valid only for the lifetime of the parent message. Your program must not modify nor `Dispose` the sub-message.

Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.

Parameters

  messageRef | The method gets the value of this field.

Returns
  A message object; the sub-message.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetMessage() [2/2]

IMessage TIBCO.FTL.IMessage.GetMessage | ( | string | name | ) |

Get the value of a message field from a message.

This call deserializes the sub-message value, caches the result with the message object, and returns that cached sub-message. The sub-message is valid only for the lifetime of the parent message. Your program must not modify nor `Dispose` the sub-message.

Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.

Parameters

  name | The method gets the value of the field with this name.

Returns
  A message object; the sub-message.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetMessageArray() [1/2]

IMessage[] TIBCO.FTL.IMessage.GetMessageArray | ( | IMessageFieldRef | messageRef | ) |

Get the value of a message array field from a message.

This call deserializes the sub-message array value, caches the result with the message object, and returns that cached array object. The array is valid only for the lifetime of the message. Your program must not modify nor IDisposable.Dispose the sub-messages, nor modify the array.

Calling this method repeatedly returns the same cached array of cached messages; it does not repeat the deserialization.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetMessageArray() [2/2]

IMessage[] TIBCO.FTL.IMessage.GetMessageArray | ( | string | name | ) |

Get the value of a message array field from a message.

This call deserializes the sub-message array value, caches the result with the message object, and returns that cached array object. The array is valid only for the lifetime of the message. Your program must not modify nor IDisposable.Dispose the sub-messages, nor modify the array.

Calling this method repeatedly returns the same cached array of cached messages; it does not repeat the deserialization.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [1/6]

byte[] TIBCO.FTL.IMessage.GetOpaque | ( | IMessageFieldRef | messageRef | ) |

Get the value of an opaque field from a message.

This method copies the bytes from the message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The bytes value of a opaque field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [2/6]

IntPtr TIBCO.FTL.IMessage.GetOpaque | ( | IMessageFieldRef | messageRef,
|  | out int | size
| ) |  |

Get a pointer to the content of an opaque field from a message.

This method returns an unmanaged pointer to the underlying opaque data. It does not copy the data.

Parameters

  messageRef | The method gets a pointer to the content of this field.
  size | The method sets this out parameter to the size of the opaque value.

Returns
  An unmanaged pointer to the opaque data.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [3/6]

int TIBCO.FTL.IMessage.GetOpaque | ( | IMessageFieldRef | messageRef,
|  | ref byte[] | bytes
| ) |  |

Get the value of an opaque field from a message.

For efficiency, this method does not allocate a new byte-array object; instead it copies the bytes into the byte-array you supply.

Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method does not copy any bytes, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Programming Strategy:

1. Create an array you think is big enough.
2. Call GetOpaque.
3. If the returned size is bigger than your array, then call GetOpaque again with a larger array (at least the returned size).

For example:

int length = 2048;
byte[] bytes = new byte[length];
length = msg.GetOpaque(field, bytes);
if(length > bytes.Length)
{
bytes = new byte[length];
length = msg.GetOpaque(field, bytes);
}

Parameters

  messageRef | The method gets the value of this field.
  bytes | The method stores the value in this byte-array.

Returns
  The number of bytes in the opaque value.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [4/6]

byte[] TIBCO.FTL.IMessage.GetOpaque | ( | string | name | ) |

Get the value of an opaque field from a message.

This method copies the bytes from the message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The bytes value of a opaque field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [5/6]

IntPtr TIBCO.FTL.IMessage.GetOpaque | ( | string | name,
|  | out int | size
| ) |  |

Get a pointer to the content of an opaque field from a message.

This method returns an unmanaged pointer to the underlying opaque data. It does not copy the data.

Parameters

  name | The method gets a pointer to the content of the field with this name.
  size | The method sets this out parameter to the size of the opaque value.

Returns
  An unmanaged pointer to the opaque data.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetOpaque() [6/6]

int TIBCO.FTL.IMessage.GetOpaque | ( | string | name,
|  | ref byte[] | bytes
| ) |  |

Get the value of an opaque field from a message.

For efficiency, this method does not allocate a new byte-array object; instead it copies the bytes into the byte-array you supply.

Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method does not copy any bytes, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Programming Strategy:

1. Create an array you think is big enough.
2. Call GetOpaque.
3. If the returned size is bigger than your array, then call GetOpaque again with a larger array (at least the returned size).

For example:

int length = 2048;
byte[] bytes = new byte[length];
length = msg.GetOpaque(field, bytes);
if(length > bytes.Length)
{
bytes = new byte[length];
length = msg.GetOpaque(field, bytes);
}

Parameters

  name | The method gets the value of the field with this name.
  bytes | The method stores the value in this byte-array.

Returns
  The number of bytes in the opaque value.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetStoreLocalMessageId()

long TIBCO.FTL.IMessage.GetStoreLocalMessageId | ( |  | ) |

Get the store local message id as assigned by the persistence service.

This message id is local to a persistence service cluster and also different depending on the store being replicated or non replicated.

Returns
  The store local message id.

## ◆ GetString() [1/2]

string TIBCO.FTL.IMessage.GetString | ( | IMessageFieldRef | messageRef | ) |

Get the value of a string field from a message.

This method copies the string from the message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The string value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetString() [2/2]

string TIBCO.FTL.IMessage.GetString | ( | string | name | ) |

Get the value of a string field from a message.

This method copies the string from the message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The string value of a field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetStringArray() [1/2]

string[] TIBCO.FTL.IMessage.GetStringArray | ( | IMessageFieldRef | messageRef | ) |

Get the value of a string array field from a message.

This method copies the array and strings from the message.

Parameters

  messageRef | The method gets the value of this field.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ GetStringArray() [2/2]

string[] TIBCO.FTL.IMessage.GetStringArray | ( | string | name | ) |

Get the value of a string array field from a message.

This method copies the array and strings from the message.

Parameters

  name | The method gets the value of the field with this name.

Returns
  The array value of the field.

Exceptions

  FTLException | The field is not defined in the format, or is not set in the message.

## ◆ IsFieldSet() [1/2]

bool TIBCO.FTL.IMessage.IsFieldSet | ( | IMessageFieldRef | messageRef | ) |

Determine whether a field is set in a message.

Parameters

  messageRef | The method checks for this field.

Returns
  Boolean: `true` if the field is set; `false` otherwise.

## ◆ IsFieldSet() [2/2]

bool TIBCO.FTL.IMessage.IsFieldSet | ( | string | name | ) |

Determine whether a field is set in a message.

Parameters

  name | The method checks for a field with this name.

Returns
  Boolean: `true` if the field is set; `false` otherwise.

## ◆ MutableCopy()

IMessage TIBCO.FTL.IMessage.MutableCopy | ( |  | ) |

Create a mutable copy of a message.

Programs cannot modify inbound messages that subscribers receive. However, programs can use this method to create mutable copies (which they may modify).

Programs must IDisposable.Dispose mutable copies to reclaim resources.

Returns
  A mutable message object.

## ◆ SetArray() [1/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | double[] | value
| ) |  |

Set a double array field in a mutable message.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this double array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [2/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | double[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a double array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [3/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | IMessage[] | messages
| ) |  |

Set a sub-message array field in a mutable message.

This call copies the sub-message data into the enclosing message field, but does not create new .NET message objects. Programs may safely `Dispose` the messages argument after this call returns.

Parameters

  messageRef | The method sets the value of this field.
  messages | The method sets this message array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [4/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | IMessage[] | messages,
|  | int | index,
|  | int | count
| ) |  |

Set a sub-message array field in a mutable message.

This method copies count elements from the array, starting at index . Programs may safely `Dispose` the messages argument after this call returns.

Parameters

  messageRef | The method sets the value of this field.
  messages | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the messages array.

## ◆ SetArray() [5/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | long[] | value
| ) |  |

Set a long array field in a mutable message.

This method copies the array.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this long array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [6/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | long[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a long array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [7/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | string[] | value
| ) |  |

Set a string array field in a mutable message.

This method copies the array.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this array as the field value. (Null is not a legal value within this array.)

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [8/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | string[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a string array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [9/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | TibDateTime[] | value
| ) |  |

Set a TibDateTime array in a mutable message.

This method copies the array.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this TibDateTime array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [10/20]

void TIBCO.FTL.IMessage.SetArray | ( | IMessageFieldRef | messageRef,
|  | TibDateTime[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a TibDateTime array in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [11/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | double[] | value
| ) |  |

Set a double array field in a mutable message.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this double array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [12/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | double[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a double array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [13/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | IMessage[] | messages
| ) |  |

Set a sub-message array field in a mutable message.

Parameters

  name | The method sets the value of the field with this name.
  messages | The method sets this message array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [14/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | IMessage[] | messages,
|  | int | index,
|  | int | count
| ) |  |

Set a sub-message array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  name | The method sets the value of the field with this name.
  messages | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the messages array.

## ◆ SetArray() [15/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | long[] | value
| ) |  |

Set a long array field in a mutable message.

This method copies the array.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this long array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [16/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | long[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a long array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [17/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | string[] | value
| ) |  |

Set a string array field in a mutable message.

This method copies the array.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this string array as the field value. (Null is not a legal value within this array.)

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [18/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | string[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a string array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetArray() [19/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | TibDateTime[] | value
| ) |  |

Set a TibDateTime array field in a mutable message.

This method copies the array.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this TibDateTime array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetArray() [20/20]

void TIBCO.FTL.IMessage.SetArray | ( | string | name,
|  | TibDateTime[] | value,
|  | int | index,
|  | int | count
| ) |  |

Set a TibDateTime array field in a mutable message.

This method copies count elements from the array, starting at index .

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets the field value from this array. (Null is not a legal value for elements within this array.)
  index | The method copies value elements starting at this index.
  count | The method copies count elements.

Exceptions

  FTLException | The message uses a managed format that does not define the field. The index and count arguments specify a location beyond the end of the value array.

## ◆ SetDateTime() [1/2]

void TIBCO.FTL.IMessage.SetDateTime | ( | IMessageFieldRef | messageRef,
|  | TibDateTime | value
| ) |  |

Set a TibDateTime field in a mutable message.

The method copies the value from the message.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this TibDateTime as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetDateTime() [2/2]

void TIBCO.FTL.IMessage.SetDateTime | ( | string | name,
|  | TibDateTime | value
| ) |  |

Set a TibDateTime field in a mutable message.

The method copies the value from the message.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this TibDateTime as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetDouble() [1/2]

void TIBCO.FTL.IMessage.SetDouble | ( | IMessageFieldRef | messageRef,
|  | double | value
| ) |  |

Set a double floating-point field in a mutable message.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this double as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetDouble() [2/2]

void TIBCO.FTL.IMessage.SetDouble | ( | string | name,
|  | double | value
| ) |  |

Set a double floating-point field in a mutable message.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this double as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetInbox() [1/2]

void TIBCO.FTL.IMessage.SetInbox | ( | IMessageFieldRef | messageRef,
|  | IInbox | inbox
| ) |  |

Set an inbox field in a mutable message.

This method copies the inbox into the message.

Parameters

  messageRef | The method sets the value of this field.
  inbox | The method sets this inbox as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetInbox() [2/2]

void TIBCO.FTL.IMessage.SetInbox | ( | string | name,
|  | IInbox | inbox
| ) |  |

Set an inbox field in a mutable message.

This method copies the inbox into the message.

Parameters

  name | The method sets the value of the field with this name.
  inbox | The method sets this inbox as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetLong() [1/2]

void TIBCO.FTL.IMessage.SetLong | ( | IMessageFieldRef | messageRef,
|  | long | value
| ) |  |

Set a long integer field in a mutable message.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this long as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetLong() [2/2]

void TIBCO.FTL.IMessage.SetLong | ( | string | name,
|  | long | value
| ) |  |

Set a long integer field in a mutable message.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this long as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetMessage() [1/2]

void TIBCO.FTL.IMessage.SetMessage | ( | IMessageFieldRef | messageRef,
|  | IMessage | msg
| ) |  |

Set a sub-message field in a mutable message.

This call copies the sub-message data into the enclosing message field, but does not create a new .NET message object. Programs may safely `Dispose` the msg argument after this call returns.

Do not set a message as a sub-message of itself (at any level of nesting).

Parameters

  messageRef | The method sets the value of this field.
  msg | The method sets this sub-message as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetMessage() [2/2]

void TIBCO.FTL.IMessage.SetMessage | ( | string | name,
|  | IMessage | msg
| ) |  |

Set a sub-message field in a mutable message.

This call copies the sub-message data into the enclosing message field, but does not create a new .NET message object. Programs may safely `Dispose` the msg argument after this call returns.

Do not set a message as a sub-message of itself (at any level of nesting).

Parameters

  name | The method sets the value of the field with this name.
  msg | The method sets this sub-message as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaque() [1/4]

void TIBCO.FTL.IMessage.SetOpaque | ( | IMessageFieldRef | messageRef,
|  | byte[] | value
| ) |  |

Set an opaque (byte-array) field in a mutable message.

This method copies the entire byte-array into the field.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this byte array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaque() [2/4]

void TIBCO.FTL.IMessage.SetOpaque | ( | IMessageFieldRef | messageRef,
|  | byte[] | value,
|  | int | length
| ) |  |

Set an opaque (byte-array) field in a mutable message.

This method copies the specified portion of the byte-array value into the field.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this byte array as the field value.
  length | The method copies this many bytes into the message.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaque() [3/4]

void TIBCO.FTL.IMessage.SetOpaque | ( | string | name,
|  | byte[] | value
| ) |  |

Set an opaque (byte-array) field in a mutable message.

This method copies the entire byte-array into the field.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this byte array as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaque() [4/4]

void TIBCO.FTL.IMessage.SetOpaque | ( | string | name,
|  | byte[] | value,
|  | int | length
| ) |  |

Set an opaque (byte-array) field in a mutable message.

This method copies the specified portion of the byte-array value into the field.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this byte array as the field value.
  length | The method copies this many bytes into the message.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaqueDirect() [1/2]

void TIBCO.FTL.IMessage.SetOpaqueDirect | ( | IMessageFieldRef | messageRef,
|  | IntPtr | value,
|  | int | length
| ) |  |

Set a field in a mutable message to contain a direct opaque value.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets the field value to this pointer.
  length | The method sets the length of the field value to this length.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetOpaqueDirect() [2/2]

void TIBCO.FTL.IMessage.SetOpaqueDirect | ( | string | name,
|  | IntPtr | value,
|  | int | length
| ) |  |

Set a field in a mutable message to contain a direct opaque value.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets the field value to this pointer.
  length | The method sets the length of the field value to this length.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetString() [1/2]

void TIBCO.FTL.IMessage.SetString | ( | IMessageFieldRef | messageRef,
|  | string | value
| ) |  |

Set a string field in a mutable message.

This method copies the string value into the message.

Parameters

  messageRef | The method sets the value of this field.
  value | The method sets this string as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ SetString() [2/2]

void TIBCO.FTL.IMessage.SetString | ( | string | name,
|  | string | value
| ) |  |

Set a string field in a mutable message.

This method copies the string value into the message.

Parameters

  name | The method sets the value of the field with this name.
  value | The method sets this string as the field value.

Exceptions

  FTLException | The message uses a managed format that does not define the field.

## ◆ WriteToByteArray()

int TIBCO.FTL.IMessage.WriteToByteArray | ( | byte[] | bytes | ) |

Write a serialized representation of a message to a byte-array.

Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Programming Strategy:

1. Create an array you think is big enough.
2. Call WriteToByteArray.
3. If the returned size is bigger than your array, then call WriteToByteArray again with a larger array (at least the returned size).

For example:

IMessage msg;
// Obtain a message.
int length = 2048;
byte[] bytes = new byte[length];
length = msg.WriteToByteArray(bytes);
if(length > bytes.length)
{
bytes = new byte[length];
length = msg.WriteToByteArray(bytes);
}

Parameters

  bytes | The method writes the serialized representation into this byte-array.

Returns
  An integer; the actual size of the serialized representation (in bytes).

## ◆ WriteToPortableByteArray()

int TIBCO.FTL.IMessage.WriteToPortableByteArray | ( | byte[] | bytes | ) |

Write a self-describing serialized representation of a message to a byte-array.

This method writes a portable form of the message, which you can use outside the originating realm. The portable form is larger than optimized forms, because it includes all format metadata (as with a dynamic format).

Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Programming Strategy:

1. Create an array you think is big enough.
2. Call WriteToPortableByteArray.
3. If the returned size is bigger than your array, then call WriteToByteArray again with a larger array (at least the returned size).

For example:

IMessage msg;
// Obtain a message.
int length = 2048;
byte[] bytes = new byte[length];
length = msg.WriteToPortableByteArray(bytes);
if(length > bytes.length)
{
bytes = new byte[length];
length = msg.WriteToPortableByteArray(bytes);
}

Parameters

  bytes | The method writes the serialized representation into this byte-array.

Returns
  An integer; the actual size of the serialized representation (in bytes).