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 (string name)
	Get the value of a TibDateTime field from a message. More...

TibDateTime	GetDateTime (IMessageFieldRef messageRef)
	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...

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[]	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 (string name)
	Get the value of a double floating-point field from a message. More...

double	GetDouble (IMessageFieldRef messageRef)
	Get the value of a double floating-point field from a message. More...

double[]	GetDoubleArray (string name)
	Get the value of a double array field from a message. More...

double[]	GetDoubleArray (IMessageFieldRef messageRef)
	Get the value of a double array field from a message. More...

FieldType	GetFieldType (string name)
	Get the type of a field within the message. More...

FieldType	GetFieldType (IMessageFieldRef messageRef)
	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 (string name)
	Get the value of an inbox field from a message. More...

IInbox	GetInbox (IMessageFieldRef messageRef)
	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 (string name)
	Get the value of a long array field from a message. More...

long[]	GetLongArray (IMessageFieldRef messageRef)
	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 (string name)
	Get the value 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...

IntPtr	GetOpaque (string name, out int size)
	Get a pointer to the content of an opaque field from a message. More...

byte[]	GetOpaque (IMessageFieldRef messageRef)
	Get the value 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...

IntPtr	GetOpaque (IMessageFieldRef messageRef, out int size)
	Get a pointer to the content of an opaque field from a message. More...

string	GetString (string name)
	Get the value of a string field from a message. More...

string	GetString (IMessageFieldRef messageRef)
	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 (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	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 (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, 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 (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 (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, 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 (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, 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	SetDateTime (string name, TibDateTime value)
	Set a TibDateTime field in a mutable message. More...

void	SetDateTime (IMessageFieldRef messageRef, TibDateTime value)
	Set a TibDateTime field in a mutable message. More...

void	SetDouble (string name, double value)
	Set a double floating-point field in a mutable message. More...

void	SetDouble (IMessageFieldRef messageRef, double value)
	Set a double floating-point field in a mutable message. More...

void	SetInbox (string name, IInbox inbox)
	Set an inbox field in a mutable message. More...

void	SetInbox (IMessageFieldRef messageRef, IInbox inbox)
	Set an inbox field in a mutable message. More...

void	SetLong (string name, long value)
	Set a long integer field in a mutable message. More...

void	SetLong (IMessageFieldRef messageRef, 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 (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	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	SetOpaqueDirect (string name, IntPtr value, int length)
	Set a field in a mutable message to contain a direct opaque value. More...

void	SetOpaqueDirect (IMessageFieldRef messageRef, IntPtr value, int length)

void	SetString (string name, string value)
	Set a string field in a mutable message. More...

void	SetString (IMessageFieldRef messageRef, 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().

A program that creates a mutable message must explicitly IDisposable.Dispose it to reclaim its resources. (However, it is often more efficient to reuse a mutable message. For further details, see the book TIBCO FTL Development.)

Programs must never Dispose immutable messages.

Customers do not implement this interface.

See Also: IMessageFieldRef

Member Function Documentation

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

int TIBCO.FTL.IMessage.GetDeliveryCount ( )

Get the delivery count of a message.

This value represents the number of times that a persistence server has delivered the message from a 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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

Create an array you think is big enough.
Call GetOpaque.
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.

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.

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.

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:

Create an array you think is big enough.
Call GetOpaque.
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

Create an array you think is big enough.
Call WriteToByteArray.
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).

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:

Create an array you think is big enough.
Call WriteToPortableByteArray.
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).

Public Member Functions

Detailed Description

Member Function Documentation