/ 
Tibco-Rv-1.00
River stage zero No dependents
/ Tibco::Rv::Msg

NAME

Tibco::Rv::Msg - Tibco message object

SYNOPSIS

my ( $rv ) = new Tibco::Rv;
my ( $msg ) = $rv->createMsg;

$msg->addString( myField => 'a string' );
$msg->addBool( myField2 => Tibco::Rv::TRUE );
$msg->addI8Array( myNums => [ 1, 2, 3 ] );

$msg->sendSubject( 'MY.SEND.SUBJECT' );
$rv->send( $msg );

DESCRIPTION

Tibco Message-manipulating class. Add/update/delete data fields, set subject addressing information, and get the on-the-wire byte representation.

All methods die with a Tibco::Rv::Status message if there are any TIB/Rendezvous errors.

CONSTRUCTOR

$msg = new Tibco::Rv::Msg( %args )
%args:
   sendSubject => $sendSubject,
   replySubject => $replySubject,
   $fieldName1 => $stringValue1,
   $fieldName2 => $stringValue2, ...

Creates a Tibco::Rv::Msg, with sendSubject and replySubject as given in %args (sendSubject and replySubject default to undef if not specified). Any other name => value pairs are added as string fields.

METHODS

$field = $msg->createField

Returns a new Tibco::Rv::Msg::Field object.

$date = $msg->createDateTime

Returns a new Tibco::Rv::Msg::DateTime object.

$msgCopy = $msg->copy

Returns a newly created, independent copy of $msg. $msgCopy has all the same field data as $msg, but none of the subject addressing information.

$bytes = $msg->bytes

Returns the on-the-wire byte representation of $msg as a scalar value.

$bytes = $msg->bytesCopy

Same as bytes, but with an extraneous memory allocation. You probably just want to use bytes.

$msg = Tibco::Rv::Msg->createFromBytes( $bytes )

Returns a newly created Tibco::Rv::Msg from the on-the-wire byte representation $bytes.

$msg->expand( $additionalStorage )

Increase memory allocated for this message by $addtionalStorage bytes. You might want to do this before adding a lot of data to a message.

$msg->reset

Removes all fields and subject addressing information.

$numFields = $msg->numFields

Returns the number of fields in $msg (not including fields in sub-messages).

$byteSize = $msg->byteSize

Returns the number of bytes taken up by the on-the-wire byte representation.

$string = $msg->toString (or "$msg")

Returns a string representation of $msg for printing.

$subject = $msg->sendSubject

Returns the subject on which $msg will be published when sent via a Transport object.

$msg->sendSubject( $subject )

Sets the subject on which $msg will be published went sent via a Transport object. Returns the new subject.

$subject = $msg->replySubject

Returns the subject on which replies will be received when $msg is sent as a request/reply message via a Transport's sendRequest method.

$msg->replySubject( $subject )

Sets the subject on which replies will be recieved when $msg is sent as a request/reply message via a Transport's sendRequest method. Returns the new subject.

$msg->addField( $field )

Adds Field $field to $msg.

$msg->add<type>( $fieldName => $value, $fieldId )
<type> can be:
   Bool, String, Opaque, Xml,
   F32, F64, I8, I16, I32, I64, U8, U16, U32, U64,
   IPAddr32, IPPort16, DateTime, or Msg

Adds $value to $msg at field $fieldName, as type <type>. $fieldId is an optional field identifier. It must be unique with this message.

Bool values should be Tibco::Rv::TRUE or Tibco::Rv::FALSE.

Opaque values can contain embedded nulls ('\0'); String and Xml values cannot (and if you try, they'll be truncated to the first null).

IPAddr32 values should be specified in dotted-quad notation. For example, '66.35.250.150'.

DateTime values must be of type Tibco::Rv::Msg::DateTime.

$msg->add<type>Array( $fieldName => [ $val1, $val2, ... ], $fieldId )
<type> can be:
F32, F64, I8, I16, I32, I64, U8, U16, U32, or U64

Adds the given array reference of <type> values to $msg at field $fieldName. $fieldId is an optional field identifier. It must be unique within this message.

$value = $msg->get<type>( $fieldName, $fieldId )
<type> can be:
   Field, Bool, String, Opaque, Xml,
   F32, F64, I8, I16, I32, I64, U8, U16, U32, U64,
   IPAddr32, IPPort16, DateTime, or Msg

Returns the value of the specified field. If $fieldId is not specified (or undef), returns the first field found named $fieldName. If $fieldId is specified, returns the field with the given $fieldId.

If the specified field is not found, returns undef.

If the field is found but it is of a different type, returns the value converted to the given <type>. If conversion is not possible, dies with a Tibco::Rv::CONVERSION_FAILED Status message.

If $fieldId is specified but is not found, and a field named $fieldName is found but with a different $fieldId, then this method dies with a Tibco::Rv::ID_CONFLICT Status message.

$valueAryRef = $msg->get<type>Array( $fieldName, $fieldId )
<type> can be:
   F32, F64, I8, I16, I32, I64, U8, U16, U32, U64,

Behaves the same as get<type>, except that it returns an array reference of values instead of a single value.

$field = $msg->getFieldByIndex( $fieldIndex )

Returns field at index $fieldIndex. Iterate over all fields in $msg by using this method over range 0 .. numFields - 1.

$field = $msg->getFieldInstance( $fieldName, $instance )

When a message contains multiple fields with the same name, use this method to interate over all messages named $fieldName. Returns undef if not found, and when $instance exceeds the number of fields in this message named $fieldName. The first field of a given name is retrieved by using $instance = 1.

$status = $msg->removeField( $fieldName, $fieldId )

Searches for a field using the same algorithm as get<type>. If found, removes it. Returns Status Tibco::Rv::OK if found and deleted, or Status Tibco::Rv::NOT_FOUND if not found.

$status = $msg->removeFieldInstance( $fieldName, $instance )

Searches for a field using the same algorithm as getFieldInstance. If found, removes it. Returns Status Tibco::Rv::OK if found and deleted, or Status Tibco::Rv::NOT_FOUND if not found.

$msg->updateField( $field )

Updates the field specified by $field's name and identifier. If the field is not found, then $field is simply added.

If the field is found in $msg, and its type does not match the type of $field, this method dies with a Tibco::Rv::INVALID_TYPE Status message.

$msg->update<type>( $fieldName, $value, $fieldId )
<type> can be:
   Field, Bool, String, Opaque, Xml,
   F32, F64, I8, I16, I32, I64, U8, U16, U32, U64,
   IPAddr32, IPPort16, DateTime, or Msg

Updates the field specified by $fieldName and $fieldId ($fieldId is optional). If the field is not found, then $value is simply added.

If the field is found in $msg, and its type does not match the type of $field, this method dies with a Tibco::Rv::INVALID_TYPE Status message.

$msg->update<type>Array( $fieldName, [ $val1, $val2, ... ], $fieldId )
<type> can be:
   F32, F64, I8, I16, I32, I64, U8, U16, U32, U64,

Behaves the same as update<lt>type>, except that it takes an array reference of values instead of a single value.

$msg->markReferences

See TIB/Rendezvous documentation for discussion on what this method does.

$msg->clearReferences

See TIB/Rendezvous documentation for discussion on what this method does.

MESSAGE TYPE CONSTANTS

Tibco::Rv::Msg::MSG => 1
Tibco::Rv::Msg::DATETIME => 3
Tibco::Rv::Msg::OPAQUE => 7
Tibco::Rv::Msg::STRING => 8
Tibco::Rv::Msg::BOOL => 9
Tibco::Rv::Msg::I8 => 14
Tibco::Rv::Msg::U8 => 15
Tibco::Rv::Msg::I16 => 16
Tibco::Rv::Msg::U16 => 17
Tibco::Rv::Msg::I32 => 18
Tibco::Rv::Msg::U32 => 19
Tibco::Rv::Msg::I64 => 20
Tibco::Rv::Msg::U64 => 21
Tibco::Rv::Msg::F32 => 24
Tibco::Rv::Msg::F64 => 25
Tibco::Rv::Msg::IPPORT16 => 26
Tibco::Rv::Msg::IPADDR32 => 27
Tibco::Rv::Msg::ENCRYPTED => 32
Tibco::Rv::Msg::NONE => 22
Tibco::Rv::Msg::I8ARRAY => 34
Tibco::Rv::Msg::U8ARRAY => 35
Tibco::Rv::Msg::I16ARRAY => 36
Tibco::Rv::Msg::U16ARRAY => 37
Tibco::Rv::Msg::I32ARRAY => 38
Tibco::Rv::Msg::U32ARRAY => 39
Tibco::Rv::Msg::I64ARRAY => 40
Tibco::Rv::Msg::U64ARRAY => 41
Tibco::Rv::Msg::F32ARRAY => 44
Tibco::Rv::Msg::F64ARRAY => 45
Tibco::Rv::Msg::XML => 47

OTHER CONSTANTS

Tibco::Rv::Msg::FIELDNAME_MAX => 127

Maximum length of a field name

SEE ALSO

Tibco::Rv::Msg::Field
Tibco::Rv::Msg::DateTime

AUTHOR

Paul Sturm <sturm@branewave.com>