/ 
Tibco-Rv-1.15
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.

$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 within this message.

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

Opaque values can contain embedded nulls "\0", while 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.33.193.143'.

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.

$valAryRef = $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<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>