View on
Paul Sturm > Tibco-Rv-1.15 > Tibco::Rv



Annotate this POD

View/Report Bugs
Module Version: 1.15   Source  


Tibco::Rv - Perl bindings and Object-Oriented library for TIBCO's TIB/Rendezvous


   use Tibco::Rv;

   my ( $rv ) = new Tibco::Rv;

   my ( $listener ) =
      $rv->createListener( subject => 'ABC', callback => sub
      my ( $msg ) = @_;
      print "Listener got a message: $msg\n";
   } );

   my ( $timer ) = $rv->createTimer( timeout => 2, callback => sub
      my ( $msg ) = $rv->createMsg;
      $msg->addString( field1 => 'myvalue' );
      $msg->addString( field2 => 'myothervalue' );
      $msg->sendSubject( 'ABC' );
      print "Timer kicking out a message: $msg\n";
      $rv->send( $msg );
   } );

   my ( $killTimer ) =
      $rv->createTimer( timeout => 7, callback => sub { $rv->stop } );

   print "finished\n"


Tibco::Rv provides bindings and Object-Oriented classes for TIBCO's TIB/Rendezvous message passing C API.

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


$rv = new Tibco::Rv( %args )
      service => $service,
      network => $network,
      daemon => $daemon

Creates a Tibco::Rv, which is the top-level object that manages all your TIB/Rendezvous needs. There should only ever be one of these created. Calling this method does the following: opens up the internal Rendezvous machinery; creates objects for the Intra-Process Transport and the Default Queue; creates a default QueueGroup and adds the Default Queue to it; and, creates the Default Transport using the supplied service/network/daemon arguments. Supply undef (or supply nothing) as the arguments to create a Default Transport connection to a Rendezvous daemon running under the default service/network/daemon settings.

See the Transport documentation section on the Intra-Process Transport for information on the Intra-Process Transport.

See the Queue documentation section on the Default Queue for information on the Default Queue.

See Tibco::Rv::QueueGroup for information on QueueGroups.

See your TIB/Rendezvous documentation for information on service/network/daemon arguments and connecting to Rendezvous daemons, and all other TIB/Rendezvous concepts.


Tibco::Rv::die( $status )

Dies (raises an exception) with the given $status. $status can either be a Status object, or one of the Status Constants (below). The exception is of the form:

   %d: %s

... where '%d' is the status number, and '%s' is a description of the error. The file and line number where the error occurred is appended.

All Tibco::Rv methods use this method to raise an exception when they encounter a TIB/Rendezvous error. Use an eval { .. }; if ( $@ ) block around all Tibco::Rv code if you care about that sort of thing.

To include a detailed stacktrace in the error message, include the string "MCarp=verbose" in the PERL5OPT environment variable (see Carp).

$ver = Tibco::Rv->version (or $ver = $rv->version)

Returns a string of the form:

   tibrv x.x.xx; tibrvcm y.y.yy; Tibco::Rv z.zz

where x.x.xx is the version of TIB/Rendezvous (the tibrv C library) that is being used, y.y.yy is the version of TIB/Rv Certified Messaging (the tibrvcm C library) that is being used, and z.zz is the version of Tibco::Rv (this Perl module) that is being used.

$transport = $rv->processTransport

Returns the Intra-Process Transport.

$transport = $rv->transport

Returns the Default Transport.

$queue = $rv->defaultQueue

Returns the Default Queue.

$queueGroup = $rv->defaultQueueGroup

Returns the Default QueueGroup. The Default QueueGroup originally contains only the Default Queue.


Begin processing events on the Default QueueGroup. This call remains in its own process loop until stop is called. Also, this call sets up a signal handler for TERM and KILL signals, which calls stop when either of those signals are received. It may also be useful to create a Listener which listens to a special subject, which, when triggered, calls stop.


Stops the process loop started by start. If the process loop is not happening, this call does nothing.

$msg = $rv->createMsg
      sendSubject => $sendSubject,
      replySubject => $replySubject,
      $fieldName1 => $stringValue1,
      $fieldName2 => $stringValue2, ...

Returns a new Msg object, 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.

$queueGroup = $rv->createQueueGroup

Returns a new QueueGroup object.

$transport = $rv->createTransport( %args )
      service => $service,
      network => $network,
      daemon => $daemon,
      description => $description,
      batchMode => $batchMode

Returns a new Transport object, using the given service/network/daemon arguments. These arguments can be undef or not specified to use the default arguments. Description defaults to undef, and batchMode defaults to Tibco::Rv::Transport::DEFAULT_BATCH. If Tibco::Rv was built against an Rv 6.x version, then this method will die with a Tibco::Rv::VERSION_MISMATCH Status message if you attempt to set batchMode to anything other than Tibco::Rv::Transport::DEFAULT_BATCH.

$dispatcher = $rv->createDispatcher( %args )
      idleTimeout => $idleTimeout

Returns a new Dispatcher object to dispatch on the Default QueueGroup, with the given idleTimeout argument (idleTimeout defaults to Tibco::Rv::WAIT_FOREVER if it is undef or not specified).

$queue = $rv->createQueue

Returns a new Queue object, added to the Default QueueGroup.

$rv->add( $queue )

Add $queue to the Default QueueGroup.

$rv->remove( $queue )

Remove $queue from the Default QueueGroup.

$hook = $rv->hook

Returns the Default Queue's event arrival hook.

$rv->hook( sub { ... } )

Set the Default Queue's event arrival hook to the given sub reference. This hook is called every time an event is added to the queue.

$timer = $rv->createTimer( %args )
      interval => $interval,
      callback => sub { ... }

Returns a new Timer object with the Default Queue and given interval, callback arguments.

$io = $rv->createIO( %args )
      socketId => $socketId,
      ioType => $ioType,
      callback => sub { ... }

Returns a new IO object with the Default Queue and given socketId, ioType, callback arguments.

$listener = $rv->createListener( %args )
      subject => $subject,
      callback => sub { ... }

Returns a new Listener object with the Default Queue, the Default Transport, and the given subject, callback arguments.

$rv->send( $msg )

Sends $msg via the Default Transport.

$reply = $rv->sendRequest( $request, $timeout )

Sends the given $request message via the Default Transport, using the given $timeout. $timeout defaults to Tibco::Rv::WAIT_FOREVER if given as undef or not specified. Returns the $reply message, or undef if the timeout is reached before receiving a reply.

$rv->sendReply( $reply, $request )

Sends the given $reply message in response to the given $request message via the Default Transport.

$inbox = $rv->createInbox

Returns a new $inbox subject. See Tibco::Rv::Msg for a more detailed discussion of sendRequest, sendReply, and createInbox.

$cmMsg = $rv->createCmMsg
      sendSubject => $sendSubject,
      replySubject => $replySubject,
      CMTimeLimit => $CMTimeLimit,
      $fieldName1 => $stringValue1,
      $fieldName2 => $stringValue2, ...

Returns a new cmMsg object, with sendSubject, replySubject, and CMTimeLimit as given in %args (these three values default to undef if not specified). Any other name => value pairs are added as string fields.

$cmTransport = $rv->createCmTransport( %args )
      service => $service,
      network => $network,
      daemon => $daemon,
      cmName => $cmName,
      requestOld => $requestOld,
      ledgerName => $ledgerName,
      syncLedger => $syncLedger,
      relayAgent => $relayAgent,
      defaultCMTimeLimit => $defaulCMTimeLimit,
      publisherInactivityDiscardInterval => $publisherInactivityDiscardInterval

Returns a new cmTransport object. If not specified, requestOld defaults to Tibco::Rv::FALSE, syncLedger defaults to Tibco::Rv::FALSE, defaultCMTimeLimit defaults to 0 (no time limit), and publisherInactivityDiscardInterval defaults to 0 (no time limit). If service/network/daemon parameters are not specified, the default transport is used, otherwise a new transport is created using the given service/network/daemon parameters.

cmName is the certified messaging correspondent name. If cmName is undef, then a unique, non-reusable name is generated for the duration of the object. If cmName is specified, it becomes a persistent correspondent identified by this name.

If requestOld is Tibco::Rv::TRUE, then unacknowledged messages sent to this persistent correspondent name will be re-requested from senders. If it is Tibco::Rv::TRUE, senders will not retain unacknowledged messages in their ledger files.

If ledgerName is specified, then this transport will use a file-based ledger by that name. Otherwise, a process-based ledger will be used.

If syncLedger is Tibco::Rv::TRUE, operations that update the ledger file will not return until changes are written out to the storage medium. If it is Tibco::Rv::TRUE, the operating system writes changes to the disk asynchronously.

If relayAgent is specified, the transport will connect to the given rvrad.

defaultCMTimeLimit is the number of seconds a certified sender is guaranteed to retain the message. It may be overridden for each message. It defaults to 0. A time limit of 0 represents no time limit.

See your TIB/Rendezvous documentation for more information about publisherInactivityDiscardInterval, which was introduced in tibrv 7.3. If Tibco::Rv was built against a version prior to 7.3, then this method will die with a Tibco::Rv::VERSION_MISMATCH Status message if you attempt to set publisherInactivityDiscardInterval to anything other than 0.

      queue => $queue,
      transport => $transport,
      subject => $subject,
      callback => sub { ... }

Returns a new cmListener object. transport must be a Tibco::Rv::Cm::Transport. If not specified, queue defaults to the Default Queue, subject defaults to the empty string, and callback defaults to:

   sub { print "cmListener received: @_\n" }

A program registers interest in $subject by creating a Listener. Messages coming in on $subject via $transport are placed on the $queue. When $queue dispatches such an event, it triggers the given callback.


Closes the TIB/Rendezvous machinery. DESTROY is called automatically when $rv goes out of scope, but you may also call it explicitly. All Tibco objects that you have created are invalidated (except for Tibco::Rv::Msg objects). Nothing will happen if DESTROY is called on an already-destroyed $rv.


Tibco::Rv::OK => 0
Tibco::Rv::INIT_FAILURE => 1
Tibco::Rv::INVALID_ARG => 3
Tibco::Rv::ARG_CONFLICT => 5
Tibco::Rv::SERVICE_NOT_FOUND => 16
Tibco::Rv::NETWORK_NOT_FOUND => 17
Tibco::Rv::DAEMON_NOT_FOUND => 18
Tibco::Rv::NO_MEMORY => 19
Tibco::Rv::INVALID_SUBJECT => 20
Tibco::Rv::VC_NOT_CONNECTED => 24
Tibco::Rv::NOT_PERMITTED => 27
Tibco::Rv::INVALID_NAME => 30
Tibco::Rv::INVALID_TYPE => 31
Tibco::Rv::INVALID_SIZE => 32
Tibco::Rv::INVALID_COUNT => 33
Tibco::Rv::NOT_FOUND => 35
Tibco::Rv::ID_IN_USE => 36
Tibco::Rv::ID_CONFLICT => 37
Tibco::Rv::ENCODER_FAILED => 40
Tibco::Rv::DECODER_FAILED => 41
Tibco::Rv::INVALID_MSG => 42
Tibco::Rv::INVALID_FIELD => 43
Tibco::Rv::CORRUPT_MSG => 45
Tibco::Rv::TIMEOUT => 50
Tibco::Rv::INTR => 51
Tibco::Rv::INVALID_EVENT => 60
Tibco::Rv::INVALID_QUEUE => 62
Tibco::Rv::INVALID_IO_SOURCE => 65
Tibco::Rv::SOCKET_LIMIT => 67
Tibco::Rv::OS_ERROR => 68
Tibco::Rv::EOF => 71
Tibco::Rv::INVALID_FILE => 72
Tibco::Rv::FILE_NOT_FOUND => 73
Tibco::Rv::IO_FAILED => 74
Tibco::Rv::NOT_FILE_OWNER => 80
Tibco::Rv::ALREADY_EXISTS => 91
Tibco::Rv::PORT_BUSY => 100


Tibco::Rv::SUBJECT_MAX => 255

Maximum length of a subject

Tibco::Rv::SUBJECT_TOKEN_MAX => 127

Maximum number of tokens a subject can contain

Tibco::Rv::FALSE => 0

Boolean false

Tibco::Rv::TRUE => 1

Boolean true

Tibco::Rv::WAIT_FOREVER => -1.0

Blocking wait on event dispatch calls (waits until an event occurs)

Tibco::Rv::NO_WAIT => 0.0

Non-blocking wait on event dispatch calls (returns immediately)

Tibco::Rv::VERSION => <this version>

Programmatically access the installed version of Tibco::Rv, in the form 'x.xx'

Tibco::Rv::TIBRV_VERSION_RELEASE => <build option>

Programmatically access the major version of TIB/Rendezvous. For instance, TIBRV_VERSION_RELEASE = 7 for all releases in the Rv 7.x series, or 6 for all releases in the Rv 6.x series. This allows for backwards compatibility when building Tibco::Rv against any version of tibrv, 6.x or later.

If Tibco::Rv is built against an Rv 6.x release, then using any function available only in Rv 7.x will die with a Tibco::Rv::VERSION_MISMATCH Status message.




Paul Sturm <>




Copyright (c) 2005 Paul Sturm. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

I would love to hear about my software being used; send me an email!

Tibco::Rv will not operate without TIB/Rendezvous, which is not included in this distribution. You must obtain TIB/Rendezvous (and a license to use it) from TIBCO, Inc. (

TIBCO and TIB/Rendezvous are trademarks of TIBCO, Inc.

TIB/Rendezvous copyright notice:

/* * Copyright (c) 1998-2003 TIBCO Software Inc. * All rights reserved. * TIB/Rendezvous is protected under US Patent No. 5,187,787. * For more information, please contact: * TIBCO Software Inc., Palo Alto, California, USA * * $Id: tibrv.h,v 2.10 2003/01/13 12:08:40 randy Exp $ */

syntax highlighting: