/ 
Tibco-Rv-1.15
River stage zero No dependents
/ Tibco::Rv

NAME

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

SYNOPSIS

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 } );

$rv->start;
print "finished\n"

DESCRIPTION

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.

CONSTRUCTOR

$rv = new Tibco::Rv( %args )
%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.

METHODS

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.

$rv->start

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.

$rv->stop

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

$msg = $rv->createMsg
%args:
   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 )
%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 )
%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 )
%args:
   interval => $interval,
   callback => sub { ... }

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

$io = $rv->createIO( %args )
%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 )
%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
%args:
   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 )
%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.

createCmListener
%args:
   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.

$rv->DESTROY

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.

STATUS CONSTANTS

Tibco::Rv::OK => 0
Tibco::Rv::INIT_FAILURE => 1
Tibco::Rv::INVALID_TRANSPORT => 2
Tibco::Rv::INVALID_ARG => 3
Tibco::Rv::NOT_INITIALIZED => 4
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::DAEMON_NOT_CONNECTED => 21
Tibco::Rv::VERSION_MISMATCH => 22
Tibco::Rv::SUBJECT_COLLISION => 23
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::CONVERSION_FAILED => 38
Tibco::Rv::RESERVED_HANDLER => 39
Tibco::Rv::ENCODER_FAILED => 40
Tibco::Rv::DECODER_FAILED => 41
Tibco::Rv::INVALID_MSG => 42
Tibco::Rv::INVALID_FIELD => 43
Tibco::Rv::INVALID_INSTANCE => 44
Tibco::Rv::CORRUPT_MSG => 45
Tibco::Rv::TIMEOUT => 50
Tibco::Rv::INTR => 51
Tibco::Rv::INVALID_DISPATCHABLE => 52
Tibco::Rv::INVALID_DISPATCHER => 53
Tibco::Rv::INVALID_EVENT => 60
Tibco::Rv::INVALID_CALLBACK => 61
Tibco::Rv::INVALID_QUEUE => 62
Tibco::Rv::INVALID_QUEUE_GROUP => 63
Tibco::Rv::INVALID_TIME_INTERVAL => 64
Tibco::Rv::INVALID_IO_SOURCE => 65
Tibco::Rv::INVALID_IO_CONDITION => 66
Tibco::Rv::SOCKET_LIMIT => 67
Tibco::Rv::OS_ERROR => 68
Tibco::Rv::INSUFFICIENT_BUFFER => 70
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::TOO_MANY_NEIGHBORS => 90
Tibco::Rv::ALREADY_EXISTS => 91
Tibco::Rv::PORT_BUSY => 100

OTHER CONSTANTS

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.

SEE ALSO

Tibco::Rv::Status
Tibco::Rv::Event
Tibco::Rv::QueueGroup
Tibco::Rv::Queue
Tibco::Rv::Dispatcher
Tibco::Rv::Transport
Tibco::Rv::Msg
Tibco::Rv::Cm::Listener
Tibco::Rv::Cm::Transport
Tibco::Rv::Cm::Msg

AUTHOR

Paul Sturm <sturm@branewave.com>

WEBSITE

http://branewave.com/perl

MAILING LIST

perl-tibco-discuss@branewave.com

COPYRIGHT

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. (http://www.tibco.com).

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 $ */