TIBCO Rendezvous® C++ Reference
Software Release 8.5 December 2019 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES. DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWN DISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS. This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, the TIBCO logo, and the TIBCO O logo, TIB, Information Bus, FTL, eFTL, Rendezvous, and LogLogic are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. Java and all Java based trademarks and logos are trademarks or registered trademarks of Oracle Corporation and/or its affiliates. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. See the readme file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer to TIBCO's Virtual Patent Marking document (https://www.tibco.com/patents) for details. Copyright © 1997 - 2019. TIBCO Software Inc. All Rights Reserved. Contents | iii Contents
Figures ...... xiii
Tables ...... xv
Preface ...... xvii Manual Organization ...... xviii TIBCO Documentation and Support Services ...... xix How to Access TIBCO Documentation...... xix TIBCO Rendezvous Documentation...... xix How to Contact TIBCO Support ...... xx How to Join TIBCO Community ...... xxi
Chapter 1 Concepts ...... 1 Implementation ...... 2 Wrapper Architecture ...... 2 Uncaught C++ Exceptions ...... 2 Strings and Character Encodings ...... 3 Custom Datatypes ...... 4
Chapter 2 Programmer’s Checklist ...... 5 Checklist ...... 6 Code ...... 6 Compile ...... 6 Link ...... 6 Run ...... 6 Programming Restrictions ...... 7 Include These Header Files...... 8 Link These Library Files...... 9 UNIX ...... 9 Microsoft Windows ...... 10 VMS ...... 13 Source Code Distribution...... 16
TIBCO Rendezvous C++ Reference iv | Contents
Chapter 3 Rendezvous Environment ...... 17 Tibrv ...... 18 Tibrv::close() ...... 19 Tibrv::defaultQueue()...... 20 Tibrv::open() ...... 21 Tibrv::processTransport()...... 22 Tibrv::version()...... 23 TibrvSdContext ...... 24 TibrvSdContext:setDaemonCert() ...... 25 TibrvSdContext:setUserCertWithKey() ...... 27 TibrvSdContext:setUserCertWithKeyBin() ...... 28 TibrvSdContext:setUserNameWithPassword() ...... 29
Chapter 4 Data ...... 31 Validity of Data Extracted From Message Fields...... 32 Scalar Snapshot ...... 32 Pointer Snapshot ...... 33 Deleting Snapshot References ...... 36 Multiple Subscription Snapshots ...... 36 Field Names and Field Identifiers ...... 37 Finding a Field Instance...... 38 TibrvMsg ...... 39 TibrvMsg() ...... 42 ~TibrvMsg() ...... 44 TibrvMsg::addField() ...... 45 Add Scalar ...... 47 Add Array ...... 49 Add Nested Message ...... 51 Add String ...... 52 Add Opaque Byte Sequence ...... 53 Add XML Byte Sequence...... 54 Add DateTime ...... 55 TibrvMsg::clearReferences() ...... 56 TibrvMsg::convertToString()...... 57 TibrvMsg::createCopy() ...... 58 TibrvMsg::detach()...... 59 TibrvMsg::expand() ...... 60 TibrvMsg::getAsBytes() ...... 61 TibrvMsg::getAsBytesCopy() ...... 62 TibrvMsg::getByteSize() ...... 63 TibrvMsg::getCurrentTime()...... 64 TibrvMsg::getField()...... 65 Get Scalar ...... 68
TIBCO Rendezvous C++ Reference Contents | v
Get Array ...... 70 Get Nested Message ...... 72 Get String ...... 73 Get Opaque Byte Sequence...... 74 Get XML Byte Sequence ...... 75 Get DateTime ...... 76 TibrvMsg::getFieldByIndex()...... 78 TibrvMsg::getFieldInstance() ...... 79 TibrvMsg::getEvent() ...... 80 TibrvMsg::getHandle() ...... 81 TibrvMsg::getNumFields() ...... 82 TibrvMsg::getReplySubject() ...... 83 TibrvMsg::getSendSubject() ...... 84 TibrvMsg::getStatus() ...... 85 TibrvMsg::isDetached() ...... 86 TibrvMsg::markReferences() ...... 87 TibrvMsg::removeField()...... 89 TibrvMsg::removeFieldInstance() ...... 91 TibrvMsg::reset() ...... 92 TibrvMsg::setReplySubject() ...... 93 TibrvMsg::setSendSubject() ...... 94 TibrvMsg::updateField() ...... 95 Update Scalar...... 98 Update Array...... 100 Update Nested Message ...... 102 Update String ...... 103 Update Opaque Byte Sequence...... 104 Update XML Byte Sequence ...... 105 Update DateTime ...... 106 TibrvMsgField ...... 107 TibrvMsgField()...... 109 TibrvMsgField::getCount() ...... 110 TibrvMsgField::getData() ...... 111 TibrvMsgField::getId()...... 112 TibrvMsgField::getName() ...... 113 TibrvMsgField::getSize()...... 114 TibrvMsgField::getType() ...... 115 TibrvMsgDateTime ...... 116 TibrvMsgDateTime()...... 119
Chapter 5 Events and Queues ...... 121 Event Overview ...... 122 TibrvEvent ...... 123
TIBCO Rendezvous C++ Reference vi | Contents
TibrvEvent::destroy() ...... 125 TibrvEvent::getClosure() ...... 126 TibrvEvent::getHandle()...... 127 TibrvEvent::getType()...... 128 TibrvEvent::getQueue() ...... 129 TibrvEvent::isIOEvent() ...... 130 TibrvEvent::isListener() ...... 131 TibrvEvent::isTimer() ...... 132 TibrvEvent::isValid()...... 133 TibrvEvent::isVectorListener() ...... 134 TibrvCallback ...... 135 TibrvCallback::onEvent() ...... 136 TibrvEventOnComplete ...... 137 TibrvEventOnComplete::onComplete() ...... 138 TibrvListener ...... 141 TibrvListener::create() ...... 144 TibrvListener::getSubject() ...... 145 TibrvListener::getTransport() ...... 146 TibrvMsgCallback ...... 147 TibrvMsgCallback::onMsg() ...... 148 TibrvVectorListener ...... 149 TibrvVectorListener::create() ...... 150 TibrvVectorListener::getSubject() ...... 155 TibrvVectorListener::getTransport() ...... 156 TibrvVectorCallback ...... 157 TibrvVectorCallback::onMsgs() ...... 158 TibrvTimer ...... 159 TibrvTimer::create() ...... 162 TibrvTimer::getInterval() ...... 163 TibrvTimer::resetInterval() ...... 164 TibrvTimerCallback ...... 165 TibrvTimerCallback::onTimer() ...... 166 TibrvIOEvent ...... 167 TibrvIOEvent::create() ...... 170 TibrvIOEvent::getIOSource() ...... 171 TibrvIOEvent::getIOType() ...... 172 TibrvIOCallback ...... 173 TibrvIOCallback::onIOEvent() ...... 174 TibrvDispatchable ...... 175 TibrvDispatchable::destroy() ...... 176 TibrvDispatchable::dispatch() ...... 177 TibrvDispatchable::getDispatchable() ...... 178
TIBCO Rendezvous C++ Reference Contents | vii
TibrvDispatchable::isValid() ...... 179 TibrvDispatchable::poll()...... 180 TibrvDispatchable::timedDispatch() ...... 181 TibrvQueue ...... 182 TibrvQueue::create() ...... 185 TibrvQueue::destroy()...... 186 TibrvQueue::dispatch() ...... 187 TibrvQueue::getCount() ...... 188 TibrvQueue::getHandle() ...... 189 TibrvQueue::getLimitPolicy() ...... 190 TibrvQueue::getName() ...... 191 TibrvQueue::getPriority() ...... 192 TibrvQueue::isValid() ...... 193 TibrvQueue::poll()...... 194 TibrvQueue::setLimitPolicy()...... 195 TibrvQueue::setName() ...... 196 TibrvQueue::setPriority() ...... 197 TibrvQueue::timedDispatch() ...... 198 TibrvQueueOnComplete ...... 199 TibrvQueueOnComplete::onComplete()...... 200 TibrvQueueGroup ...... 201 TibrvQueueGroup::add() ...... 203 TibrvQueueGroup::create() ...... 204 TibrvQueueGroup::destroy()...... 205 TibrvQueueGroup::dispatch() ...... 206 TibrvQueueGroup::getHandle() ...... 207 TibrvQueueGroup::isValid() ...... 208 TibrvQueueGroup::poll()...... 209 TibrvQueueGroup::remove()...... 210 TibrvQueueGroup::timedDispatch() ...... 211 TibrvDispatcher ...... 212 TibrvDispatcher::create() ...... 213 TibrvDispatcher::destroy() ...... 214 TibrvDispatcher::getDispatchable() ...... 215 TibrvDispatcher::getHandle() ...... 216 TibrvDispatcher::getName() ...... 217 TibrvDispatcher::isValid() ...... 218 TibrvDispatcher::setName() ...... 219
Chapter 6 Transports...... 221 TibrvTransport ...... 222 TibrvTransport::createInbox() ...... 224 TibrvTransport::destroy() ...... 226
TIBCO Rendezvous C++ Reference viii | Contents
TibrvTransport::getDescription() ...... 227 TibrvTransport::getHandle()...... 228 TibrvTransport::isValid() ...... 229 TibrvTransport::requestReliability() ...... 230 TibrvTransport::send() ...... 232 TibrvTransport::sendReply() ...... 233 TibrvTransport::sendRequest() ...... 234 TibrvTransport::setDescription() ...... 236 tibrvTransportBatchMode ...... 237 TibrvProcessTransport ...... 238 TibrvNetTransport ...... 239 TibrvNetTransport::create() ...... 241 TibrvNetTransport::getDaemon() ...... 244 TibrvNetTransport::getNetwork() ...... 245 TibrvNetTransport::getService()...... 246 TibrvNetTransport::setBatchMode()...... 247
Chapter 7 Virtual Circuits ...... 249 TibrvVcTransport ...... 250 TibrvVcTransport::createAcceptVc() ...... 252 TibrvVcTransport::createConnectVc() ...... 254 TibrvVcTransport::waitForVcConnection() ...... 255
Chapter 8 Fault Tolerance ...... 257 Fault Tolerance Road Map ...... 258 tibrvftAction ...... 259 TibrvFtMember ...... 260 TibrvFtMember::create() ...... 262 TibrvFtMember::destroy() ...... 265 TibrvFtMember::getClosure()...... 266 TibrvFtMember::getGroupName() ...... 267 TibrvFtMember::getHandle() ...... 268 TibrvFtMember::getQueue() ...... 269 TibrvFtMember::getTransport() ...... 270 TibrvFtMember::getWeight() ...... 271 TibrvFtMember::isValid() ...... 272 TibrvFtMember::setWeight() ...... 273 TibrvFtMemberCallback ...... 274 TibrvFtMemberCallback::onFtAction() ...... 275 TibrvFtMemberOnComplete ...... 277 TibrvFtMemberOnComplete::onComplete...... 278 TibrvFtMonitor ...... 279
TIBCO Rendezvous C++ Reference Contents | ix
TibrvFtMonitor::create() ...... 281 TibrvFtMonitor::destroy() ...... 283 TibrvFtMonitor::getClosure() ...... 284 TibrvFtMonitor::getGroupName() ...... 285 TibrvFtMonitor::getHandle() ...... 286 TibrvFtMonitor::getQueue() ...... 287 TibrvFtMonitor::getTransport() ...... 288 TibrvFtMonitor::isValid() ...... 289 TibrvFtMonitorCallback ...... 290 TibrvFtMonitorCallback::onFtMonitor() ...... 291 TibrvFtMonitorOnComplete ...... 292 TibrvFtMonitorOnComplete::onComplete...... 293
Chapter 9 Certified Message Delivery ...... 295 TibrvCmListener ...... 296 TibrvCmListener::confirmMsg() ...... 298 TibrvCmListener::create()...... 299 TibrvCmListener::destroy() ...... 300 TibrvCmListener::getSubject() ...... 301 TibrvCmListener::getTransport()...... 302 TibrvCmListener::isValid() ...... 303 TibrvCmListener::setExplicitConfirm() ...... 304 TibrvCmTransport ...... 305 TibrvCmTransport::addListener() ...... 308 TibrvCmTransport::allowListener() ...... 309 TibrvCmTransport::connectToRelayAgent() ...... 310 TibrvCmTransport::create()...... 312 TibrvCmTransport::createInbox() ...... 316 TibrvCmTransport::destroy()...... 317 TibrvCmTransport::disallowListener() ...... 318 TibrvCmTransport::disconnectFromRelayAgent()...... 319 TibrvCmTransport::expireMessages() ...... 320 TibrvCmTransport::getDefaultTimeLimit()...... 321 TibrvCmTransport::getLedgerName()...... 322 TibrvCmTransport::getName() ...... 323 TibrvCmTransport::getRelayAgent() ...... 324 TibrvCmTransport::getRequestOld()...... 325 TibrvCmTransport::getSyncLedger() ...... 326 TibrvCmTransport::getTransport() ...... 327 TibrvCmTransport::removeListener() ...... 328 TibrvCmTransport::removeSendState() ...... 330 TibrvCmTransport::reviewLedger() ...... 331 TibrvCmTransport::send()...... 332
TIBCO Rendezvous C++ Reference x | Contents
TibrvCmTransport::sendReply()...... 333 TibrvCmTransport::sendRequest()...... 334 TibrvCmTransport::setDefaultTimeLimit() ...... 336 TibrvCmTransport::setPublisherInactivityDiscardInterval() ...... 337 TibrvCmTransport::syncLedger() ...... 338 TibrvCmTransportOnComplete ...... 339 TibrvCmTransportOnComplete::onComplete...... 340 TibrvCmReviewCallback ...... 341 TibrvCmReviewCallback::onLedgerMsg() ...... 342 TibrvCmMsg ...... 344 TibrvCmMsg::getSender() ...... 345 TibrvCmMsg::getSequence()...... 346 TibrvCmMsg::getTimeLimit() ...... 348 TibrvCmMsg::setTimeLimit() ...... 349 TibrvCmMsgCallback ...... 350 TibrvCmMsgCallback::onCmMsg() ...... 351
Chapter 10 Distributed Queue...... 353 TibrvCmQueueTransport ...... 354 TibrvCmQueueTransport::create()...... 357 TibrvCmQueueTransport::destroy() ...... 361 TibrvCmQueueTransport::getCompleteTime()...... 362 TibrvCmQueueTransport::getUnassignedMessageCount()...... 363 TibrvCmQueueTransport::getWorkerWeight() ...... 364 TibrvCmQueueTransport::getWorkerTasks() ...... 365 TibrvCmQueueTransport::setCompleteTime()...... 366 TibrvCmQueueTransport::setTaskBacklogLimit...() ...... 367 TibrvCmQueueTransport::setWorkerWeight() ...... 368 TibrvCmQueueTransport::setWorkerTasks() ...... 369
Chapter 11 Datatypes...... 371 Wire Format Datatypes ...... 372 C Datatypes ...... 374 Datatype Conversion...... 376 General Rules ...... 376 Converting to Boolean ...... 377
Chapter 12 Status and Errors ...... 379 TibrvStatus ...... 380 TibrvStatus::getCode()...... 385 TibrvStatus::getText()...... 386
TIBCO Rendezvous C++ Reference Contents | xi
Index ...... 387
TIBCO Rendezvous C++ Reference xii | Contents
TIBCO Rendezvous C++ Reference Figures | xiii Figures
Figure 1 Extracting a Scalar Field ...... 32 Figure 2 Extracting a Pointer Field ...... 33 Figure 3 Updating a Pointer Field...... 34 Figure 4 Updating a Submessage Field ...... 35 Figure 5 Mark and Clear References ...... 88 Figure 6 Completion when Callback Methods are in Progress...... 140 Figure 7 Completion when Callback Methods are Not in Progress ...... 140 Figure 8 Listener Activation and Dispatch ...... 142 Figure 9 Grouping Messages into Vectors ...... 152 Figure 10 Vector Listener Callbacks in a Single Dispatch Thread ...... 153 Figure 11 Vector Listener Callbacks in Multiple Dispatch Threads ...... 153 Figure 12 Timer Activation and Dispatch ...... 160 Figure 13 I/O Event Activation and Dispatch ...... 168 Figure 14 Wire Format to C Datatype Conversion Matrix...... 378
TIBCO Rendezvous C++ Reference xiv | Figures
TIBCO Rendezvous C++ Reference Tables | xv Tables
Table 1 Header Files...... 8 Table 2 Linker Flags for UNIX...... 9 Table 3 Library Files for Microsoft Windows ...... 10 Table 4 Library Files for VMS ...... 14 Table 5 Date and Time Representations ...... 117
TIBCO Rendezvous C++ Reference xvi | Tables
TIBCO Rendezvous C++ Reference Preface | xvii Preface
TIBCO Rendezvous® is a messaging infrastructure product. TIBCO is proud to announce the latest release of TIBCO Rendezvous software. This release is the latest in a long history of TIBCO products that leverage the power of the Information Bus® technology to enable truly event-driven IT environments. To find out more about how TIBCO Rendezvous software and other TIBCO products are powered by TIB® technology, please visit us at www.tibco.com. This manual describes the TIBCO Rendezvous API for C++ programmers. It is part of the documentation set for TIBCO Rendezvous Software Release 8.5.0.
Topics
• Manual Organization, page xviii • TIBCO Documentation and Support Services, page xix
TIBCO Rendezvous C++ Reference xviii | Manual Organization
Manual Organization
The organization of this book mirrors the underlying object structure of the TIBCO Rendezvous C++ API. Each chapter describes a group of closely related objects and the methods that pertain to them.
TIBCO Rendezvous C++ Reference Preface | xix
TIBCO Documentation and Support Services
How to Access TIBCO Documentation Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainly in HTML and PDF formats. The TIBCO Product Documentation website is updated frequently and is more current than any other documentation included with the product. To access the latest documentation, visit https://docs.tibco.com.
TIBCO Rendezvous Documentation TIBCO_HOME is the top-level directory in which TIBCO products are installed. • On Windows platforms, the default TIBCO_HOME is C:\tibco. • On UNIX platforms, the default TIBCO_HOME is /opt/tibco. The following documents form the Rendezvous documentation set: • TIBCO Rendezvous Concepts Read this book first. It contains basic information about Rendezvous components, principles of operation, programming constructs and techniques, advisory messages, and a glossary. All other books in the documentation set refer to concepts explained in this book. • TIBCO Rendezvous Administration Begins with a checklist of action items for system and network administrators. This book describes the mechanics of Rendezvous licensing, network details, plus a chapter for each component of the Rendezvous software suite. Readers should have TIBCO Rendezvous Concepts at hand for reference. • TIBCO Rendezvous Installation Includes step-by-step instructions for installing Rendezvous software on various operating system platforms. • TIBCO Rendezvous C Reference Detailed descriptions of each datatype and function in the Rendezvous C API. Readers should already be familiar with the C programming language, as well as the material in TIBCO Rendezvous Concepts. • TIBCO Rendezvous C++ Reference Detailed descriptions of each class and method in the Rendezvous C++ API. The C++ API uses some datatypes and functions from the C API, so we
TIBCO Rendezvous C++ Reference xx | TIBCO Documentation and Support Services
recommend the TIBCO Rendezvous C Reference as an additional resource. Readers should already be familiar with the C++ programming language, as well as the material in TIBCO Rendezvous Concepts. • TIBCO Rendezvous .NET Reference Detailed descriptions of each class and method in the Rendezvous .NET interface. Readers should already be familiar with either C# or Visual Basic .NET, as well as the material in TIBCO Rendezvous Concepts. • TIBCO Rendezvous Java Reference Detailed descriptions of each class and method in the Rendezvous Java language interface. Readers should already be familiar with the Java programming language, as well as the material in TIBCO Rendezvous Concepts. • TIBCO Rendezvous Configuration Tools Detailed descriptions of each Java class and method in the Rendezvous configuration API, plus a command line tool that can generate and apply XML documents representing component configurations. Readers should already be familiar with the Java programming language, as well as the material in TIBCO Rendezvous Administration. • TIBCO Rendezvous z/OS Installation and Configuration Information about Rendezvous for IBM z/OS systems regarding installation and maintenance. Some information may be also useful for application programmers. • TIBCO Rendezvous for z/OS COBOL Reference Detailed descriptions of each datatype and function in the Rendezvous COBOL API. Readers should already be familiar with the COBOL programming language, z/OS, as well as the material in TIBCO Rendezvous Concepts. • TIBCO Rendezvous Release Notes Lists new features, changes in functionality, deprecated features, migration and compatibility information, closed issues and known issues.
How to Contact TIBCO Support You can contact TIBCO Support in the following ways: • For an overview of TIBCO Support, visit http://www.tibco.com/services/support .
TIBCO Rendezvous C++ Reference Preface | xxi
• For accessing the Support Knowledge Base and getting personalized content about products you are interested in, visit the TIBCO Support portal at https://support.tibco.com. • If you already have a valid maintenance or support contract, visit this site: • For creating a Support case, you must have a valid maintenance or support contract with TIBCO. You also need a user name and password to log in to https://support.tibco.com. If you do not have a user name, you can request one by clicking Register on the website.
How to Join TIBCO Community TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter experts to share and access their collective experience. TIBCO Community offers access to Q&A forums, product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and tools that extend and enable customers to gain full value from TIBCO products. In addition, users can submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.
TIBCO Rendezvous C++ Reference xxii | TIBCO Documentation and Support Services
TIBCO Rendezvous C++ Reference Concepts | 1
Chapter 1 Concepts
This chapter presents concepts specific to the TIBCO Rendezvous® C++ language interface. For concepts that pertain to Rendezvous software in general, see the book TIBCO Rendezvous Concepts.
Topics
• Implementation, page 2 • Strings and Character Encodings, page 3 • Custom Datatypes, page 4
TIBCO Rendezvous C++ Reference 2 | Chapter 1 Concepts
Implementation
The Rendezvous C++ API consists of a thin wrapper around the C API.
Wrapper Architecture It features a lightweight object model, in which C++ objects refer to C objects using a pointer or handle.
General Case In general, C++ constructors declare typed variables and create hollow objects. In contrast, create methods make hollow objects operational, by creating a corresponding C object, and storing its handle in the C++ object. Similarly, C++ destroy methods destroy the corresponding C object—however, although they invalidate the C++ object, they do not free its storage. In contrast, C++ destructors first call the corresponding destroy method, and then destroy the C++ object, reclaiming its storage.
Data Objects Data objects (messages, message fields, and datetime objects) present exceptions to these rules. C++ data objects have constructors and destructors, but not create and destroy methods. Message constructors declare typed variables, but do not allocate storage; the first operation on a message variable creates a C++ object. Datetime and field objects are identical to the corresponding C structs. Their constructors declare typed variables and allocate struct storage.
Uncaught C++ Exceptions The Rendezvous C library (within the C++ wrapper) does not support uncaught C++ exceptions. Throwing uncaught exceptions through Rendezvous C library code can leave Rendezvous code in undefined states. Application callback methods in your C++ programs must ensure that they catch all exceptions thrown within their code (and exceptions thrown within application program code that they call). Such callback methods include TibrvMsgCallback::onMsg(), TibrvEventOnComplete::onComplete(), and others.
TIBCO Rendezvous C++ Reference Strings and Character Encodings | 3
Strings and Character Encodings
Rendezvous software uses strings in several roles: • String data inside message fields •Field names • Subject names (and other associated strings that are not strictly inside the message) • Certified delivery correspondent names • Group names (fault tolerance)
All these strings (both in C++ and in wire format) use the character encoding appropriate to the ISO locale of the sender. For example, the United States is locale en_US, and uses the Latin-1 character encoding (also called ISO 8859-1); Japan is locale ja_JP, and uses the Shift-JIS character encoding. When two programs exchange messages within the same locale, strings are always correct. However, when a message sender and receiver use different character encodings, the receiving program must convert between encodings as needed. Rendezvous software does not convert automatically.
TIBCO Rendezvous C++ Reference 4 | Chapter 1 Concepts
Custom Datatypes
The Rendezvous C++ API does not include classes to support custom datatypes. However, the C API machinery is available in C++ programs. The Rendezvous distribution includes a C++ source code example.
See Also Custom Datatypes on page 363 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference | 5
Chapter 2 Programmer’s Checklist
Developers of Rendezvous programs can use this checklist during the four phases of the development cycle: installing Rendezvous software, coding your C++ program, compiling your C++ program, and running your program.
Topics
• Checklist, page 6 • Programming Restrictions, page 7 • Include These Header Files, page 8 • Link These Library Files, page 9 • Source Code Distribution, page 16
TIBCO Rendezvous C++ Reference 6 | Chapter 2 Programmer’s Checklist
Checklist
Code • Include the appropriate Rendezvous C++ header files; see Include These Header Files on page 8.
Compile • Compile your programs. • VMS requires programmers to define the compile command; see VMS on page 13.
Link • Link with the appropriate Rendezvous C++ and C library files; see Link These Library Files on page 9. • If name-mangling incompatibilities prevent your program from linking with the Rendezvous C++ library, you might need to recompile the C++ library. For more information, see Source Code Distribution on page 16. • To create a shared library that uses the Rendezvous C++ API, you must recompile the Rendezvous C++ library. (This step is not necessary on Windows, AIX and TruUNIX64 platforms.) For more information, see Source Code Distribution on page 16. • VMS requires programmers to define the link command; see VMS on page 13.
Run • Be sure that the Rendezvous daemon can run on each application host computer. The user’s path must contain a version appropriate for the application host. For more information, see Rendezvous Daemon (rvd) on page 35 in TIBCO Rendezvous Administration.
TIBCO Rendezvous C++ Reference Programming Restrictions | 7
Programming Restrictions
In general, it is illegal to call Rendezvous methods from inside signal handlers.
TIBCO Rendezvous C++ Reference 8 | Chapter 2 Programmer’s Checklist
Include These Header Files
Rendezvous C++ programs must include the appropriate header files from this list.
Table 1 Header Files Header File Description Communications, Events and Data All programs must include this API header file.
tibrv/tibrvcpp.h Include this header file for the Rendezvous C++ API. This header automatically includes tibrv.h.
Certified Message Delivery and Distributed Queue
tibrv/cmcpp.h Include this header file for the Rendezvous certified message delivery and distributed queue C++ API. This header automatically includes cm.h.
Fault Tolerance
tibrv/ftcpp.h Include this header file for the Rendezvous fault tolerance C++ API. This header automatically includes ft.h.
Secure Daemons and OpenSSL
Programs that connect to secure daemons (rvsd, rvsrd) must include this header file.
tibrv/sdcpp.h Include this header file for the Rendezvous secure daemon C++ API. This header automatically includes sd.h.
TIBCO Rendezvous C++ Reference Link These Library Files | 9
Link These Library Files
Rendezvous C++ programs must link the appropriate library files. Choose from the appropriate table based on operating system platform.
UNIX In UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.
Table 2 Linker Flags for UNIX Linker Flag Description Rendezvous C++ Library All programs must link this library.
-ltibrvcpp All programs must link using this library flag.
Communications, Data and Event Manager All programs must link only one of these two libraries.
-ltibrv All programs must link this library.
Secure Daemon
-ltibrvsd Programs that connect to secure daemons (rvsd, rvsrd) must link using this library flag.
Certified Message Delivery, Fault Tolerance, and Distributed Queues Programs may also link one or more of these libraries as needed.
-ltibrvcm Programs that use certified message delivery must link using this library flag. Programs that use distributed queues must link using this library flag.
-ltibrvft Programs that use fault tolerance features must link using this library flag. Programs that use distributed queues must link using this library flag.
-ltibrvcmq Programs that use distributed queues must link using this library flag. In addition, distributed queue programs also use communications, certified message delivery, and fault tolerance libraries; they must link with appropriate flags from those groups.
TIBCO Rendezvous C++ Reference 10 | Chapter 2 Programmer’s Checklist
Microsoft Windows
The C++ library is only available as a static library; the C library is available as a DLL and as a static library. To create a C++ DLL, you must recompile the Rendezvous C++ library; see Source Code Distribution on page 16.
Table 3 Library Files for Microsoft Windows (Sheet 1 of 3) Library File Description Rendezvous C++ Library All programs must link only one of these C++ libraries.
libtibrvcpp.lib Rendezvous C++ libraries. Static libraries, for use with the /MT compiler option.
libtibrvcppmd.lib Rendezvous C++ libraries. Static libraries, for use with the /MD compiler option.
Communications, Data and Event Manager All programs must link only one of these C libraries.
tibrv.lib Rendezvous C library. DLL (import library).
libtibrv.lib Rendezvous C library. Static library, for use with the /MT compiler option.
libtibrvmd.lib Rendezvous C library. Static library, for use with the /MD compiler option.
Secure Daemon
Programs that connect to secure daemons (rvsd, rvsrd) must link only one of these sets of libraries.
tibrvsd.lib Secure daemon additions. libeay32.lib ssleay32.lib DLL (import library).
TIBCO Rendezvous C++ Reference Link These Library Files | 11
Table 3 Library Files for Microsoft Windows (Sheet 2 of 3) Library File Description libtibrvsd.lib Secure daemon additions. libeay32.lib ssleay32.lib Static library, for use with the /MT compiler option.
libtibrvsdmd.lib Secure daemon additions. libeay32.lib ssleay32.lib Static library, for use with the /MD compiler option.
Certified Message Delivery Programs that use certified message delivery must link only one of these C libraries. Programs that use distributed queues must link only one of these libraries.
tibrvcm.lib Rendezvous certified message delivery software. DLL (import library).
libtibrvcm.lib Rendezvous certified message delivery software. Static library, for use with the /MT compiler option.
libtibrvcmmd.lib Rendezvous certified message delivery software. Static library, for use with the /MD compiler option.
Fault Tolerance Programs that use fault tolerance must link only one of these C libraries. Programs that use distributed queues must link only one of these libraries.
tibrvft.lib Rendezvous fault tolerance software. DLL (import library).
libtibrvft.lib Rendezvous fault tolerance software. Static library, for use with the /MT compiler option.
libtibrvftmd.lib Rendezvous fault tolerance software. Static library, for use with the /MD compiler option.
TIBCO Rendezvous C++ Reference 12 | Chapter 2 Programmer’s Checklist
Table 3 Library Files for Microsoft Windows (Sheet 3 of 3) Library File Description Distributed Queue Programs that use distributed queues must link only one of these C libraries. In addition, distributed queue programs also use certified message delivery, and fault tolerance libraries; they must link appropriate libraries from those groups.
tibrvcmq.lib Rendezvous distributed queue software. DLL (import library).
libtibrvcmq.lib Rendezvous distributed queue software. Static library, for use with the /MT compiler option.
libtibrvcmqmd.lib Rendezvous distributed queue software. Static library, for use with the /MD compiler option.
TIBCO Rendezvous C++ Reference Link These Library Files | 13
VMS In VMS environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.
Migrating to Release 8.x
Forward Migration In general, applications linked with shareable images migrate forward to new versions of TIBCO Rendezvous without any need to relink; they usually operate smoothly with newer shareable images. Exception: In Rendezvous release 8.0, we reorganized the Rendezvous shareable image libraries on OpenVMS platforms, in order to resolve issues with third-party libraries. As a result, you must relink applications linked with shareable image libraries when you upgrade across this division (from 7.5.4 or earlier, to 8.0 or later, on OpenVMS).
Older Shareable Libraries Applications that link with sharable images usually cannot run with older shareable libraries (from earlier Rendezvous releases). The reason is that new releases can introduce new entry points, which are absent from older shareable libraries. This incompatibility can cause problems if you link an application against a current shareable library, and then distribute it to other host computers where it runs with older shareable libraries.
Compile On VMS platforms, Rendezvous programmers using C++ (CXX) must define the CXX-compile command appropriately. For the HP C++ compiler: $ CPP :== CXX/FLOAT=IEEE/IEEE_MODE=UNDERFLOW_TO_ZERO - /PREFIX=ALL/WARNINGS=DISABLE=EXTRASEMI - /INCLUDE_DIRECTORY=("/tibrv/include",[])
Link Rendezvous API libraries are multi-threaded, so VMS scheduler upcalls can yield significant performance improvements:
TIBCO Rendezvous C++ Reference 14 | Chapter 2 Programmer’s Checklist
$ LINK/THREADS_ENABLE=UPCALLS
Library Files In VMS environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.
Table 4 Library Files for VMS (Sheet 1 of 2) Library File Description C++ Library All programs must link this C++ library.
libtibrvcpp.olb Rendezvous C++ library. Static library.
Communications, Data and Event Manager All programs must link only one of these libraries.
libtibrv.olb Rendezvous C library. Static library.
libtibrvshr.exe Rendezvous C library. VMS sharable image.
Secure Daemon
Programs that connect to secure daemons (rvsd, rvsrd) must link only one of these sets of libraries.
libtibrvsd.olb Secure daemon additions. libcrypto.olb libssl.olb Static library.
libtibrvsdshr.exe Secure daemon additions. libcryptoshr.exe libsslshr.exe VMS sharable image.
TIBCO Rendezvous C++ Reference Link These Library Files | 15
Table 4 Library Files for VMS (Sheet 2 of 2) Library File Description Certified Message Delivery Programs that use certified message delivery must link only one of these libraries. Programs that use distributed queues must link only one of these libraries.
libtibrvcm.olb Rendezvous certified message delivery software. Static library.
libtibrvcmshr.exe Rendezvous certified message delivery software. VMS sharable image.
Fault Tolerance Programs that use fault tolerance must link only one of these libraries. Programs that use distributed queues must link only one of these libraries.
libtibrvft.olb Rendezvous fault tolerance software. Static library.
libtibrvftshr.exe Rendezvous fault tolerance software. VMS sharable image.
Distributed Queue Programs that use distributed queues must link only one of these libraries. In addition, distributed queue programs also use certified message delivery, and fault tolerance libraries; they must link appropriate libraries from those groups.
libtibrvcmq.olb Rendezvous distributed queue software. Static library.
libtibrvcmqshr.exe Rendezvous distributed queue software. VMS sharable image.
TIBCO Rendezvous C++ Reference 16 | Chapter 2 Programmer’s Checklist
Source Code Distribution
We compile the C++ API libraries on each platform using the vendor’s primary compiler. This default case works well in most environments. For maximum flexibility we also distribute the C++ API as source code. Some environments are incompatible with the default compilation settings. In these situations, you can recompile the Rendezvous C++ API libraries to match your environment. For example: • The compiler in your environment differs from our primary compiler in its name-mangling technique. By recompiling the Rendezvous C++ libraries, you can ensure compatibility with other software compiled in your environment. • Our static compilation is not position independent (on most platforms). To use Rendezvous software to produce shared libraries or executables, you must recompile with appropriate flags.
TIBCO Rendezvous C++ Reference | 17
Chapter 3 Rendezvous Environment
This brief chapter describes the methods that open and close the internal machinery upon which Rendezvous software depends.
Topics
• Tibrv, page 18 • TibrvSdContext, page 24
TIBCO Rendezvous C++ Reference 18 | Chapter 3 Rendezvous Environment
Tibrv Class
Declaration class Tibrv
Purpose The Rendezvous environment.
Remarks Programs do not create instances of Tibrv. Instead, programs use its static methods to open and close the Rendezvous environment, and extract utility objects.
Method Description Page Environment Life Cycle and Properties
Tibrv::open() Start Rendezvous internal machinery. 21
Tibrv::close() Stop and destroy Rendezvous internal machinery. 19
Tibrv::version() Identify the Rendezvous API release number. 23
Utility Objects
Tibrv::defaultQueue() Extract the default queue object. 20
Tibrv::processTransport() Extract the intra-process transport object. 22
TIBCO Rendezvous C++ Reference Tibrv::close() | 19
Tibrv::close() Method
Declaration static TibrvStatus close();
Purpose Stop and destroy Rendezvous internal machinery.
Remarks After Tibrv::close() destroys the internal machinery, Rendezvous software becomes inoperative: • Events no longer arrive in queues. • All events, queues and queue groups are unusable, so programs can no longer dispatch events. • All transports are unusable, so programs can no longer send outbound messages.
After closing a Tibrv object, all events, transports, queues and queue groups associated with that environment are invalid; it is illegal to call any methods of these objects.
Reference Count A reference count protects against interactions between programs and third-party packages that call Tibrv::open() and Tibrv::close(). Each call to Tibrv::open() increments an internal counter; each call to Tibrv::close() decrements that counter. A call to Tibrv::open() actually creates internal machinery only when the reference counter is zero; subsequent calls merely increment the counter, but do not duplicate the machinery. A call to Tibrv::close() actually destroys the internal machinery only when the call decrements the counter to zero; other calls merely decrement the counter. In each program, the number of calls to Tibrv::open() and Tibrv::close() must match.
See Also Tibrv::open() on page 21
TIBCO Rendezvous C++ Reference 20 | Chapter 3 Rendezvous Environment
Tibrv::defaultQueue() Method
Declaration static TibrvQueue* defaultQueue();
Purpose Extract the default queue object.
Remarks If Rendezvous is not open, the default queue is invalid; nevertheless, this method returns a pointer to it. Each process has exactly one default queue; the call Tibrv::open() automatically creates it. Programs must not destroy the default queue.
See Also TibrvQueue on page 182.
TIBCO Rendezvous C++ Reference Tibrv::open() | 21
Tibrv::open() Method
Declaration static TibrvStatus open();
Purpose Start Rendezvous internal machinery.
Remarks This call creates the internal machinery that Rendezvous software requires for its operation: • Internal data structures. • Default event queue. • Intra-process transport. •Event driver.
Until the first call to Tibrv::open() creates the internal machinery, all events, transports, queues and queue groups are unusable. Messages and their methods do not depend on the internal machinery.
Reference Count A reference count protects against interactions between programs and third-party packages that call Tibrv::open() and Tibrv::close(). Each call to Tibrv::open() increments an internal counter; each call to Tibrv::close() decrements that counter. A call to Tibrv::open() actually creates internal machinery only when the reference counter is zero; subsequent calls merely increment the counter, but do not duplicate the machinery. A call to Tibrv::close() actually destroys the internal machinery only when the call decrements the counter to zero; other calls merely decrement the counter. In each program, the number of calls to Tibrv::open() and Tibrv::close() must match.
See Also Tibrv::close() on page 19
TIBCO Rendezvous C++ Reference 22 | Chapter 3 Rendezvous Environment
Tibrv::processTransport() Method
Declaration static TibrvProcessTransport* processTransport();
Purpose Extract the intra-process transport object.
Remarks If Rendezvous is not open, the intra-process transport is invalid; nevertheless, this method returns a pointer to it. Each process has exactly one intra-process transport; the call Tibrv::open() automatically creates it. Programs must not destroy the intra-process transport.
See Also TibrvProcessTransport on page 238
TIBCO Rendezvous C++ Reference Tibrv::version() | 23
Tibrv::version() Method
Declaration static const char* version();
Purpose Identify the Rendezvous API release number.
TIBCO Rendezvous C++ Reference 24 | Chapter 3 Rendezvous Environment
TibrvSdContext Class
Declaration class TibrvSdContext
Purpose This class defines static methods for interacting with secure Rendezvous daemons.
Remarks Programs do not create instances of TibrvSdContext. Instead, programs use its static methods to configure user names, passwords and certificates, and to register trust in daemon certificates.
Method Description Page
TibrvSdContext:setDaemonCert() Register trust in a secure daemon. 25
TibrvSdContext:setUserCertWithKey() Register a (PEM) certificate with 27 private key for identification to secure daemons.
TibrvSdContext:setUserCertWithKeyBin() Register a (PKCS #12) certificate with 28 private key for identification to secure daemons.
TibrvSdContext:setUserNameWithPassword() Register a user name with password 29 for identification to secure daemons.
TIBCO Rendezvous C++ Reference TibrvSdContext:setDaemonCert() | 25
TibrvSdContext:setDaemonCert() Method
Declaration static TibrvStatus setDaemonCert( const char* daemonName, const char* daemonCert);
#define TIBRV_SECURE_DAEMON_ANY_NAME (NULL) #define TIBRV_SECURE_DAEMON_ANY_CERT (NULL)
Purpose Register trust in a secure daemon.
Remarks When any program transport connects to a secure daemon, it verifies the daemon’s identity using TLS protocols. Certificates registered using this method identify trustworthy daemons. Programs divulge user names and passwords to daemons that present registered certificates.
Parameter Description daemonName Register a certificate for a secure daemon with this name. For the syntax and semantics of this parameter, see Daemon Name, below.
daemonCert Register this public certificate. The text of this certificate must be in PEM encoding. See also Certificate on page 26.
Daemon Name The daemon name is a three-part string of the form: ssl:host:port_number
This string must be identical to the string you supply as the daemon argument to the transport creation call; see TibrvNetTransport::create() on page 241. Colon characters (:) separate the three parts. ssl indicates the protocol to use when attempting to connect to the daemon. host indicates the host computer of the secure daemon. You can specify this host either as a network IP address, or a hostname. Omitting this part specifies the local host. port_number specifies the port number where the secure daemon listens for TLS connections. (This syntax is similar to the syntax connecting to remote daemons, with the addition of the prefix ssl.)
TIBCO Rendezvous C++ Reference 26 | Chapter 3 Rendezvous Environment
In place of this three-part string, you can also supply the constant TIBRV_SECURE_DAEMON_ANY_NAME. This form lets you register a catch-all certificate that applies to any secure daemon for which you have not explicitly registered another certificate. For example, you might use this form when several secure daemons share the same certificate.
Certificate For important details, see CA-Signed Certificates on page 171 in TIBCO Rendezvous Administration. In place of an actual certificate, you can also supply the constant TIBRV_SECURE_DAEMON_ANY_CERT. The program accepts any certificate from the named secure daemon. For example, you might use this form when testing a secure daemon configuration, before generating any actual certificates.
Any Name and Notice that the constants TIBRV_SECURE_DAEMON_ANY_NAME and Any Certificate TIBRV_SECURE_DAEMON_ANY_CERT each eliminate one of the two security checks before transmitting sensitive identification data to a secure daemon. We strongly discourage using both of these constants simultaneously, because that would eliminate all security checks, leaving the program vulnerable to unauthorized daemons.
TIBCO Rendezvous C++ Reference TibrvSdContext:setUserCertWithKey() | 27
TibrvSdContext:setUserCertWithKey() Method
Declaration static TibrvStatus setUserCertWithKey( const char* userCertWithKey, const char* password);
Purpose Register a (PEM) certificate with private key for identification to secure daemons.
Remarks When any program transport connects to a secure daemon, the daemon verifies the program’s identity using TLS protocols. The Rendezvous API includes two methods that achieve similar effects: • This call accepts a certificate in PEM text format. • TibrvSdContext:setUserCertWithKeyBin() accepts a certificate in PKCS #12 binary format.
Parameter Description userCertWithKey Register this user certificate with private key. The text of this certificate must be in PEM encoding.
password Use this password to decrypt the private key.
For important information about password security, see Security Factors on page 171 in TIBCO Rendezvous Administration.
CA-Signed You can also supply a certificate signed by a certificate authority (CA). To use a Certificate CA-signed certificate, you must supply not only the certificate and private key, but also the CA’s public certificate (or a chain of such certificates). Concatenate these items in one string. For important details, see CA-Signed Certificates on page 171 in TIBCO Rendezvous Administration.
Errors Error status code TIBRV_INVALID_FILE can indicate either disk I/O failure, or invalid certificate data, or an incorrect password.
See Also TibrvSdContext:setUserCertWithKeyBin() on page 28
TIBCO Rendezvous C++ Reference 28 | Chapter 3 Rendezvous Environment
TibrvSdContext:setUserCertWithKeyBin() Method
Declaration static TibrvStatus setUserCertWithKeyBin( const void* userCertWithKey, tibrv_u32 userCertWithKey_size, const char* password);
Purpose Register a (PKCS #12) certificate with private key for identification to secure daemons.
Remarks When any program transport connects to a secure daemon, the daemon verifies the program’s identity using TLS protocols. The Rendezvous API includes two methods that achieve similar effects: • This call accepts a certificate in PKCS #12 binary format. • TibrvSdContext:setUserCertWithKey() accepts a certificate in PEM text format.
Parameter Description userCertWithKey Register this user certificate with private key. The binary data of this certificate must be in PKCS #12 format.
userCertWithKey_size The length (in bytes) of the certificate data.
password Use this password to decrypt the private key.
For important information about password security, see Security Factors on page 171 in TIBCO Rendezvous Administration.
CA-Signed You can also supply a certificate signed by a certificate authority (CA). To use a Certificate CA-signed certificate, you must supply not only the certificate and private key, but also the CA’s public certificate (or a chain of such certificates). For important details, see CA-Signed Certificates on page 171 in TIBCO Rendezvous Administration.
Errors Error status code TIBRV_INVALID_FILE can indicate either disk I/O failure, or invalid certificate data, or an incorrect password.
See Also TibrvSdContext:setUserCertWithKey() on page 27 www.rsasecurity.com/rsalabs/pkcs
TIBCO Rendezvous C++ Reference TibrvSdContext:setUserNameWithPassword() | 29
TibrvSdContext:setUserNameWithPassword() Method
Declaration static TibrvStatus setUserNameWithPassword( const char* userName, const char* password);
Purpose Register a user name with password for identification to secure daemons.
Remarks When any program transport connects to a secure daemon, them daemon verifies the program’s identity using TLS protocols.
Parameter Description userName Register this user name for communicating with secure daemons.
password Register this password for communicating with secure daemons.
For important information about password security, see Security Factors on page 171 in TIBCO Rendezvous Administration.
TIBCO Rendezvous C++ Reference 30 | Chapter 3 Rendezvous Environment
TIBCO Rendezvous C++ Reference | 31
Chapter 4 Data
This chapter describes messages and the data they contain.
Topics
• Validity of Data Extracted From Message Fields, page 32 • Field Names and Field Identifiers, page 37 • TibrvMsg, page 39 • TibrvMsgField, page 107 • TibrvMsgDateTime, page 116
See Also Strings and Character Encodings, page 3 Datatypes, page 371 Custom Datatypes on page 363 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference 32 | Chapter 4 Data
Validity of Data Extracted From Message Fields
To extract data values from the fields of a message, programs use a set of get convenience methods. All of these methods extract a snapshot of the message data—that is, the data value as it exists at a particular time. If the program later modifies the message by removing or updating the field, the snapshot remains unchanged. Rendezvous messages implement snapshot semantics using two separate strategies for scalar data and pointer data.
Scalar Snapshot To extract the value of a scalar field, a program declares a scalar in program-owned storage, and passes its address to the get method; the get method copies a snapshot of the scalar field value from the message into program storage. The program can modify its snapshot at any time without affecting the original message. The program can update or delete the message field at any time without affecting the snapshot copy.
Figure 1 Extracting a Scalar Field
Message
1 Snapshot Copy of Scalar Field Get Field Scalar Value
2 Update FieldUpdate
After deleting or updating the field, Message 3 the snapshot copy of the scalar value remains in program storage. Updated Scalar Snapshot Copy of Field Scalar Value
TIBCO Rendezvous C++ Reference Validity of Data Extracted From Message Fields | 33
Pointer Snapshot Pointer data is a broad category, which includes arrays, strings, opaque byte sequences, XML data, and submessages. To extract the value of an array, string, XML, or opaque field, a program declares a typed pointer variable in program-owned storage, and passes its reference to the get method; the get method copies a pointer to the field value into the program’s variable. The method does not copy data into program-owned storage; the data still resides in storage associated with the message. Nonetheless, Rendezvous software protects the integrity of snapshot pointer data from subsequent changes to the message field.
Figure 2 Extracting a Pointer Field
This pointer remains valid until the message is Message destroyed. Moreover, the array to which it points is a snapshot, which remains unchanged even if the program subsequently updates or removes the field.
Pointer to ArrayArray Value Snapshot Array
(Schematic diagrams in this section illustrate the general principles of snapshot semantics as they apply to pointer data of message fields. However, these diagrams do not accurately reflect the storage allocation and geometry of messages, nor do they reflect the underlying implementation of snapshots.)
Rendezvous Protects Pointer Snapshots from Changes to the Message If the program removes the field from the message, then Rendezvous software protects the integrity of the snapshot data by retaining it in storage associated with the message; the program’s pointer to the snapshot data remains valid until the message is destroyed, even though the data is no longer accessible through the message. If the program updates the message field (see Figure 3 on page 34), then Rendezvous software protects the integrity of the snapshot data by retaining it in storage associated with the message; the program’s pointer to the snapshot data remains valid until the message is destroyed, and the program’s view of the snapshot data remains unchanged—even though the get method would extract updated data from the message. These semantics apply to all pointer data—arrays, strings, opaque byte sequences, XML data, and submessages.
TIBCO Rendezvous C++ Reference 34 | Chapter 4 Data
Figure 3 Updating a Pointer Field
This pointer remains valid until the message is Message destroyed. Moreover, the snapshot of Array 1 remains unchanged by updating the field. After updating the field, subsequent Get calls bypass this snapshot.
Pointer to SnapshotArray Valueof Array 1 Snapshot Array 1
Copy of Array 2 Update Field Array 2
Updating the field copies Array 2 from the program into the message, without disturbing Array 1 snapshot. Subsequent Get calls extract this copy of Array 2.
Do Not Modify Pointer Snapshots Programs must treat array, string, XML data and opaque pointer data as read-only snapshots, and must not modify the data to which those pointers refer. For example, it is illegal for programs to change any element in a snapshot array; it is illegal for programs to change any byte in snapshot strings, XML data or opaque byte sequences. Although Rendezvous software does not enforce this restriction, violating this rule is dangerous, and can result in erroneous program behavior. Do not attempt to modify the elements of an array snapshot, nor the bytes of a string, XML data or opaque snapshot. Figure 3 illustrates the correct way to modify the value of pointer data within a message field. Instead of directly modifying storage associated with the message, supply the new value through an update call, which replaces the whole value of the field. (Even after updating or removing the field, it is still illegal to modify the snapshot.) Although superseded snapshot data remains in storage associated with the message, it is not included when sending the message, nor when accessing message fields.
TIBCO Rendezvous C++ Reference Validity of Data Extracted From Message Fields | 35
Rendezvous Protects the Message from Changes to Submessage Snapshots In contrast to other pointer data, programs may legally modify snapshot submessages (since a submessage is also a message in its own right). Field modification methods apply equally to ordinary messages and to submessage snapshots extracted using get calls. Moreover, modifying a snapshot submessage does not affect the original field in the parent message. Field modification methods protect the integrity of the parent message when updating or removing a field in a submessage snapshot, or when adding a new field to the submessage snapshot. Figure 4 illustrates this protection for parent messages. After updating a field in a snapshot submessage, subsequent get calls extract a pristine copy of the submessage from the field of the parent message, creating a second snapshot. Meanwhile, the modified snapshot submessage remains in storage owned by the parent message; it remains valid until the parent message is destroyed. (However, if the program detaches the snapshot submessage, it remains valid until the program explicitly destroys the submessage.)
Figure 4 Updating a Submessage Field
Updating a field in a snapshot submessage does not affect Message the field value of the parent message. Subsequent calls to get the submessage from the parent message bypass the updated snapshot, and instead extract a new snapshot of the unchanged submessage.
Pointer to Snapshot of Submsg 1 Snapshot Submsg 1 This pointer remains valid until the Updated Field in message is destroyed. Snapshot of Submsg 1 Subsequent calls to get the field from the Pristine Copy of snapshot submessage extract this new value. Submsg 1
Unchanged Field in Copy of Submsg 1
TIBCO Rendezvous C++ Reference 36 | Chapter 4 Data
Deleting Snapshot References Ordinarily, snapshot references remain part of the message until the program destroys the message. However, in rare situations snapshots can accumulate within a program, causing unbounded memory growth. For example, consider the result of a program that calls a method repeatedly on the same message, where each call creates a new snapshot within the storage associated with that message. Message storage grows, and destroying the message is the only way to free that storage. A pair of methods give programs explicit control over snapshot references, so you can avoid such situations: • TibrvMsg::markReferences() • TibrvMsg::clearReferences() When a program repeatedly extracts snapshot references data and does not destroy the parent messages, consider using these methods to control the proliferation of references.
See Also TibrvMsg::markReferences() on page 87
Multiple Subscription Snapshots Rendezvous software also protects the integrity of messages distributed to multiple subscriptions. When a callback method modifies an inbound message (whether detached or not), Rendezvous software still presents the original message content to subsequent callback methods.
TIBCO Rendezvous C++ Reference Field Names and Field Identifiers | 37
Field Names and Field Identifiers
Rendezvous programs can specify fields in two ways: •A field name is a character string. Each field can have at most one name. Several fields can have the same name. •A field identifier is a 16-bit unsigned integer, which must be unique within the message. That is, two fields in the same message cannot have the same identifier. However, a nested submessage is considered a separate identifier space from its enclosing parent message and any sibling submessages.
Message methods specify fields using a combination of a field name and a unique field identifier. When absent, the default field identifier is zero. To compare the speed and space characteristics of these two options, see Search Characteristics on page 38.
Rules and Restrictions
NULL is a legal field name only when the identifier is zero. It is illegal for a field to have both a non-zero identifier and a NULL field name. However, NULL is not the same as "" (the empty string). It is legal for a field to have a non-zero identifier and the empty string as its field name.
Field Search Algorithm The methods that get message fields (including methods that update or remove fields, since these methods call get internally) all use this algorithm to find a field within a message, as specified by a field identifier and a field name. 1. If the program supplied a non-zero field identifier, then search for the field with that identifier. On failure, continue to step 2. (If the identifier is zero, skip to step 3.) 2. If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name. On failure, or if the program supplied NULL as the field name, return the status code TIBRV_NOT_FOUND. If the name search succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT. 3. Begin here when the program supplied zero as the identifier (or omitted a field identifier).
TIBCO Rendezvous C++ Reference 38 | Chapter 4 Data
Search for a field with the specified name—even if that name is NULL. On failure, return the status code TIBRV_NOT_FOUND.
If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.
Adding a New Field When a program adds a new field to a message, it can attach a field name, a field identifier, or both. If the program supplies an identifier, Rendezvous software checks that it is unique within the message; if the identifier is already in use, the operation fails with the status code TIBRV_ID_IN_USE.
Search Characteristics In general, an identifier search completes in constant time. In contrast, a name search completes in linear time proportional to the number of fields in the message. Name search is quite fast for messages with 16 fields or fewer; for messages with more than 16 fields, identifier search is faster.
Space Characteristics The smallest field name is a one-character string, which occupies three bytes in Rendezvous wire format. That one ASCII character yields a name space of 127 possible field names; a larger range requires additional characters. Field identifiers are 16 bits, which also occupy three bytes in Rendezvous wire format. However, those 16 bits yield a space of 65535 possible field identifiers; that range is fixed, and cannot be extended.
Finding a Field Instance When a message contains several field instances with the same field name, these methods find a specific instance by name and number (they do not use field identifiers): • TibrvMsg::getFieldInstance() on page 79. • TibrvMsg::removeFieldInstance() on page 91.
TIBCO Rendezvous C++ Reference TibrvMsg | 39
TibrvMsg Class
Declaration class TibrvMsg
Purpose Represent Rendezvous messages.
Remarks This class lacks create() and destroy() methods; use the constructor and destructor instead.
(Sheet 1 of 3) Method Description Page Message Life Cycle and Properties
TibrvMsg() Create a message object. 42
~TibrvMsg() Destroy a message object. 44
TibrvMsg::convertToString() Format a message as a string. 57
TibrvMsg::createCopy() Store a copy of this message in another 58 message object.
TibrvMsg::detach() Detach an inbound message from 59 Rendezvous storage; the program assumes responsibility for destroying the message.
TibrvMsg::expand() Enlarge a message by allocating 60 additional storage.
TibrvMsg::getAsBytes() Extract the data from a message as a byte 61 sequence.
TibrvMsg::getAsBytesCopy() Extract a copy of the data from a message 62 as a byte sequence.
TibrvMsg::getByteSize() Return the size of a message (in bytes). 63
TibrvMsg::getHandle() Extract the C message handle from a C++ 81 message object.
TibrvMsg::getNumFields() Extract the number of fields in a message. 82
TIBCO Rendezvous C++ Reference 40 | Chapter 4 Data
(Sheet 2 of 3) Method Description Page
TibrvMsg::getStatus() Extract the status code stored by the 85 message constructor.
TibrvMsg::isDetached() Determine the ownership of the message. 86
TibrvMsg::reset() Clear a message, preparing it for re-use. 92
Fields
TibrvMsg::addField() Add a field object to a message. 45
TibrvMsg::getField() Get a specified field from a message. 65
TibrvMsg::getFieldByIndex() Get a field from a message by an index. 78
TibrvMsg::getFieldInstance() Get a specified instance of a field from a 79 message.
TibrvMsg::removeField() Remove a field from a message. 89
TibrvMsg::removeFieldInstance() Remove a specified instance of a field 91 from a message.
TibrvMsg::updateField() Update a field within a message. 95
Address Information
TibrvMsg::getReplySubject() Extract the reply subject from a message. 83
TibrvMsg::getSendSubject() Extract the subject from a message. 84
TibrvMsg::setReplySubject() Set the reply subject for a message. 93
TibrvMsg::setSendSubject() Set the subject for a message. 94
Field References
TibrvMsg::clearReferences() Clear references in this message. 56
TibrvMsg::markReferences() Mark references in this message. 87
TIBCO Rendezvous C++ Reference TibrvMsg | 41
(Sheet 3 of 3) Method Description Page Event Dispatched
TibrvMsg::getEvent() Extract the event associated with a 80 (dispatched) message object.
Time String
TibrvMsg::getCurrentTime() Get the current date and time. 64
See Also Strings and Character Encodings, page 3 TibrvMsgField on page 107 Datatypes, page 371
TIBCO Rendezvous C++ Reference 42 | Chapter 4 Data
TibrvMsg() Constructor
Declaration TibrvMsg(tibrv_u32 initialSize=512); // Declare empty msg obj.
TibrvMsg(const TibrvMsg& msg); // Copy constructor.
TibrvMsg(const void* bytes); // Create from bytes.
TibrvMsg(tibrvMsg Cmsg, // Create from C handle. tibrv_bool detached);
Purpose Create a message object.
Remarks The first form of this constructor merely declares a C++ variable. It does not allocate storage; it does not create a C message object. (Subsequent operations on the variable automatically allocates storage and create the inner structure.) This form works efficiently with methods such as TibrvTransport::sendRequest(), which requires a variable to receive its reply message and overwrites the contents of that variable. The other forms of this constructor simultaneously declare a variable, allocate storage, create an object with inner structure, and store the status code in the object. The status code indicates any conditions that might make the message object unusable; if the object is unusable, any subsequent operation on the message will return the same status code. None of the constructors place address information (for example, the subject) on the new message object. This class has no destroy() method; use the destructor instead (see ~TibrvMsg() on page 44).
(Sheet 1 of 2) Parameter Description initialSize Optional. This form of the constructor declares an empty message variable. When a subsequent operation triggers storage allocation, allocate a storage block of this size (in bytes).
msg Create an independent copy of this message.
TIBCO Rendezvous C++ Reference TibrvMsg() | 43
(Sheet 2 of 2) Parameter Description bytes Create a message with fields populated from this byte array. The new message is completely independent of the byte array. For example, programs can create such byte arrays from messages using the method TibrvMsg::getAsBytes(), and store them in files; after reading them from such files, programs can reconstruct a message from its byte array.
Cmsg Create a C++ message object that embeds this C message handle. This form of the constructor does not copy the C message.
detached Specify whether the Cmsg is detached—that is, whether the program owns the message. TIBRV_TRUE indicates a detached inbound message, or a message created in the program. The destructor also destroys the embedded C message. TIBRV_FALSE indicates an attached inbound message. The destructor does not destroy the embedded C message.
See Also TibrvMsg::createCopy() on page 58 TibrvMsg::detach() on page 59 TibrvMsg::getAsBytes() on page 61 TibrvMsg::getStatus() on page 85 TibrvMsg::getHandle() on page 81 tibrvMsg on page 52 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference 44 | Chapter 4 Data
~TibrvMsg() Destructor
Declaration ~TibrvMsg();
Purpose Destroy a message object.
See Also TibrvMsg::detach() on page 59
TIBCO Rendezvous C++ Reference TibrvMsg::addField() | 45
TibrvMsg::addField() Method
Declaration TibrvStatus addField(const TibrvMsgField& field)
Purpose Add a field object to a message.
Remarks This method copies the data into the new message field. All related convenience methods behave similarly.
Parameter Description field Add this field to the message.
Adding Fields to Rendezvous programs must use this three-step process: a Nested 1. Extract the nested submessage (see Get Nested Message on page 72). Message 2. Add the new fields to the extracted submessage, using type-specific convenience methods or this method. The field is added to a snapshot copy of the submessage, and modifies the copy rather than the original parent message. 3. Store the modified submessage back into the field of the parent message (see Update Nested Message on page 102).
Avoiding Whenever possible, we recommend storing arrays in message fields using one of Common the Rendezvous array types. This strategy makes the most efficient use of storage Mistakes space, processor time, and network bandwidth. If you must store array elements as individual fields, be careful mapping array indices to field identifiers. Zero-based arrays are common in C++ programs, but zero has a special meaning as a field identifier—it represents the absence of an identifier. Do not map the zeroth element of an array (myArray[0]) to a field with identifier zero; it is impossible to retrieve such a field by its identifier (because it does not have one). It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
Reserved Field Name
The field name _data_ is reserved. Programs may not add fields with this name. More generally, all fields that begin with the underbar character are reserved.
TIBCO Rendezvous C++ Reference 46 | Chapter 4 Data
Field Name The constant TIBRVMSG_FIELDNAME_MAX (127) determines the longest possible Length field name.
Convenience When the datatype of a field is determined during execution, use this general Methods method. When you can determine the datatype of a field before compile-time, we recommend using type-specific convenience methods instead of this general method. Type-specific methods yield these advantages when adding fields: • Code readability. •Type checking. • Accept constants and literals directly.
(Type-specific methods yield even further advantages when extracting or updating fields.) These categories of type-specific convenience methods add a new field: • Add Scalar, page 47. • Add Array, page 49. • Add Nested Message, page 51. • Add String, page 52. • Add Opaque Byte Sequence, page 53. • Add XML Byte Sequence, page 54. • Add DateTime, page 55.
See Also Add Scalar, page 47
TIBCO Rendezvous C++ Reference Add Scalar | 47
Add Scalar Convenience Methods
Declaration TibrvStatus addtype( const char* fieldName, tibrv_type value, tibrv_u16 fieldId=0);
Purpose Add a field containing a scalar value.
Method Name Field Value Type Type Description addBool tibrv_bool boolean
addF32 tibrv_f32 32-bit floating point
addF64 tibrv_f64 64-bit floating point
addI8 tibrv_i8 8-bit integer
addI16 tibrv_i16 16-bit integer
addI32 tibrv_i32 32-bit integer
addI64 tibrv_i64 64-bit integer
addU8 tibrv_u8 8-bit unsigned integer
addU16 tibrv_u16 16-bit unsigned integer
addU32 tibrv_u32 32-bit unsigned integer
addU64 tibrv_u64 64-bit unsigned integer
addIPAddr32 tibrv_ipaddr32 4-byte IP address
addIPPort16 tibrv_ipport16 2-byte IP port
(Sheet 1 of 2) Parameter Description fieldName Create the field with this name. NULL is a legal name. However, if fieldId is non-zero, then fieldName must be non-NULL.
TIBCO Rendezvous C++ Reference 48 | Chapter 4 Data
(Sheet 2 of 2) Parameter Description value Add a new field with this value (which may be a literal or stored in a variable). The convenience method must correspond to the datatype of this value. We recommend casting the data to match the convenience method. The method copies the value into the new message field.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference Add Array | 49
Add Array Convenience Methods
Declaration TibrvStatus addelement_typeArray( const char* fieldName, const element_type* value, tibrv_u32 numElements, tibrv_u16 fieldId=0);
Purpose Add a field containing an array value.
Method Name Element Type Type Description addF32Array tibrv_f32 32-bit floating point array
addF64Array tibrv_f64 64-bit floating point array
addI8Array tibrv_i8 8-bit integer array
addI16Array tibrv_i16 16-bit integer array
addI32Array tibrv_i32 32-bit integer array
addI64Array tibrv_i64 64-bit integer array
addU8Array tibrv_u8 8-bit unsigned integer array
addU16Array tibrv_u16 16-bit unsigned integer array
addU32Array tibrv_u32 32-bit unsigned integer array
addU64Array tibrv_u64 64-bit unsigned integer array
(Sheet 1 of 2) Parameter Description fieldName Create the new field with this name. NULL is a legal name. However, if fieldId is non-zero, then fieldName must be non-NULL.
TIBCO Rendezvous C++ Reference 50 | Chapter 4 Data
(Sheet 2 of 2) Parameter Description value Add a new field that contains this array. The method signature must correspond to the datatype of this value. The method copies the array into the new message field.
numElements When adding an array type, the program supplies the count of array elements in this parameter.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference Add Nested Message | 51
Add Nested Message Convenience Method
Declaration TibrvStatus addMsg( const char* fieldName, const TibrvMsg&msg, tibrv_u16 fieldId=0);
Purpose Add a field containing a nested submessage.
Remarks This method adds only the data portion of the nested message (value); it does not include any address information or certified delivery information.
Parameter Description fieldName Create the new field with this name.
msg Add a new field that contains this submessage. The method copies the data into the new field.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference 52 | Chapter 4 Data
Add String Convenience Method
Declaration TibrvStatus addString( const char* fieldName, const char* value, tibrv_u16 fieldId=0);
Purpose Add a field containing a string.
Remarks The string cannot contain interior NULL bytes, because this method expects a NULL-terminated string. To add a string with interior NULL bytes, use the generic method TibrvMsg::addField().
Parameter Description fieldName Create the new field with this name.
value Add a new field that contains this string (which may be a literal or stored in a variable). The method copies the data into the new field.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference Add Opaque Byte Sequence | 53
Add Opaque Byte Sequence Convenience Method
Declaration TibrvStatus addOpaque( const char* fieldName, const void* value, tibrv_u32 size tibrv_u16 fieldId=0);
Purpose Add a field containing an opaque byte sequence.
Parameter Description fieldName Create the new field with this name.
value Add a new field that contains this opaque buffer. The method copies the data into the new message field.
size When adding an opaque buffer, the program supplies the size (in bytes) of the data in this parameter.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference 54 | Chapter 4 Data
Add XML Byte Sequence Convenience Method
Declaration TibrvStatus addXml( const char* fieldName, const void* value, tibrv_u32 size tibrv_u16 fieldId=0);
Purpose Add a field containing an XML byte sequence.
Remarks XML data is a byte sequence. Adding a field of type TIBRVMSG_XML compresses the bytes. Extracting data from the field uncompresses it to obtain the original byte sequence.
Parameter Description fieldName Create the new field with this name.
value Add a new field that contains the XML data in this buffer. The method copies the data into the new message field.
size When adding XML data, the program supplies the size (in bytes) of the data in this parameter.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
TIBCO Rendezvous C++ Reference Add DateTime | 55
Add DateTime Convenience Method
Declaration TibrvStatus addDateTime( const char* fieldName, const TibrvMsgDateTime& value, tibrv_u16 fieldId=0);
Purpose Add a field containing a Rendezvous datetime value.
Parameter Description fieldName Create the new field with this name.
value Add a new field that contains this datetime value. The method copies the data into the new message field.
fieldId Create the new field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
Example This example code converts a time_t value to a datetime value, and adds the datetime to a message field. Programs can adapt this example as appropriate. (For corresponding code to extract a datetime value from a message field, and convert it to a time_t value, see the example at Get DateTime, page 76.) #include
See Also TibrvMsgDateTime on page 116
TIBCO Rendezvous C++ Reference 56 | Chapter 4 Data
TibrvMsg::clearReferences() Method
Declaration TibrvStatus clearReferences();
Purpose Clear references in this message.
Remarks This method clears references back to the most recent mark. For a description and example, see TibrvMsg::markReferences() on page 87.
See Also Validity of Data Extracted From Message Fields, page 32 Deleting Snapshot References, page 36 TibrvMsg::markReferences() on page 87
TIBCO Rendezvous C++ Reference TibrvMsg::convertToString() | 57
TibrvMsg::convertToString() Method
Declaration TibrvStatus convertToString(const char*& string)
Purpose Format a message as a string.
Remarks Programs can use this method to obtain a string representation of the message for printing. For most datatypes, this method formats the full value of the field to the string; these types are an exceptions: TIBRVMSG_OPAQUE This method abbreviates the value of an opaque field; for example, [472 opaque bytes]. TIBRVMSG_XML This method abbreviates the value of an XML field; for example, [XML document: 472 bytes]. The size measures uncompressed data.
This method formats TIBRVMSG_IPADDR32 fields as four dot-separated decimal integers. This method formats TIBRVMSG_IPPORT16 fields as one decimal integer.
Parameter Description string The program supplies a variable in this parameter; the method stores the string representation in that variable.
See Also Converting DateTime to Strings, page 118
TIBCO Rendezvous C++ Reference 58 | Chapter 4 Data
TibrvMsg::createCopy() Method
Declaration TibrvStatus createCopy(TibrvMsg& copy)
Purpose Store a copy of this message in another message object.
Remarks Despite its name, this method does not create a new object. Instead, it stores an independent copy in the variable it receives as a parameter.
Parameter Description copy The program supplies a variable in this parameter; the method stores an independent copy of the message in that variable.
See Also TibrvMsg() on page 42
TIBCO Rendezvous C++ Reference TibrvMsg::detach() | 59
TibrvMsg::detach() Method
Declaration TibrvMsg* detach();
Purpose Detach an inbound message from Rendezvous storage; the program assumes responsibility for destroying the message.
Remarks When Rendezvous software creates a message, it owns that message. This situation occurs only in the case of inbound messages presented to a data callback method; Rendezvous software destroys such messages when the callback method returns, unless the program explicitly detaches the message. After a detach operation, the program owns the message, and must explicitly destroy it to reclaim the storage. Programs may detach inbound messages. A program cannot detach a message that it already owns; attempts to do so return NULL. Programs can use this method to detach either an entire message, or a submessage. After detaching a submessage, the program owns that submessage, even after the destruction of the surrounding parent message. Callback methods receive inbound messages in stack parameters, which evaporate when the callback methods return. Programs detach messages to allow the messages to persist beyond the local context. Consequently, the detach operation returns a new C++ object, which the program can store in a variable with wider scope. The original inbound message becomes invalid, transferring its embedded C message to the new C++ message object.
Programs may modify messages only with methods that add, remove or update fields. It is illegal to directly modify data storage in a message field. Detaching a message does not change this restriction. For further information, see Do Not Modify Pointer Snapshots on page 34, or more generally, Validity of Data Extracted From Message Fields on page 32.
See Also ~TibrvMsg() on page 44 TibrvCallback::onEvent() on page 136 TibrvMsgCallback::onMsg() on page 148 TibrvCmMsgCallback::onCmMsg() on page 351
TIBCO Rendezvous C++ Reference 60 | Chapter 4 Data
TibrvMsg::expand() Method
Declaration TibrvStatus expand(tibrv_u32 additionalStorage);
Purpose Enlarge a message by allocating additional storage.
Remarks When adding data to a message would overflow the allocated space, the message automatically expands by allocating additional storage. However, reallocation (whether explicit or automatic) is a slow operation; to optimize program performance, we recommend allocating sufficient storage initially, so that reallocation is not required. In most cases, the message expands in place (without copying). In some cases, this method copies the message to a new location. In all cases, existing pointers to the message, its fields, and its field values remain valid (even after copying). If no space is available, this method returns the error code TIBRV_NO_MEMORY.
Parameter Description additionalStorage Enlarge the message by this amount (in bytes) to allocate for the message. If the message was oldSize bytes before this call, it is oldSize + additionalStorage when the method returns.
TIBCO Rendezvous C++ Reference TibrvMsg::getAsBytes() | 61
TibrvMsg::getAsBytes() Method
Declaration TibrvStatus getAsBytes(const void*& bytePtr);
Purpose Extract the data from a message as a byte sequence.
Remarks Return a copy of the message data as a byte sequence, suitable for archiving in a file. To reconstruct the message from bytes, see TibrvMsg() on page 42. The byte data includes the message header and all message fields in Rendezvous wire format. It does not include address information, such as the subject and reply subject, nor certified delivery information. The byte sequence can contain interior NULL bytes.
Parameter Description bytePtr The program supplies a variable. The method stores a pointer to the byte sequence in that variable.
See Also TibrvMsg() on page 42 TibrvMsg::getAsBytesCopy() on page 62
TIBCO Rendezvous C++ Reference 62 | Chapter 4 Data
TibrvMsg::getAsBytesCopy() Method
Declaration TibrvStatus getAsBytesCopy( void* bytePtr, tibrv_u32 byteSize);
Purpose Extract a copy of the data from a message as a byte sequence.
Remarks Return the data as a byte sequence, suitable for archiving in a file. This method copies the message data into a buffer, which the program owns and may modify. The byte data includes the message header and all message fields in Rendezvous wire format. It does not include address information, such as the subject and reply subject. To allocate appropriate storage, programs determine the length of the byte sequence using TibrvMsg::getByteSize() on page 63. The byte sequence can contain interior NULL bytes.
Parameter Description bytePtr The program supplies a byte buffer. The method copies the byte sequence into that buffer.
byteSize The size of the buffer.
See Also TibrvMsg::getAsBytes() on page 61 TibrvMsg::getByteSize() on page 63 TibrvMsg() on page 42
TIBCO Rendezvous C++ Reference TibrvMsg::getByteSize() | 63
TibrvMsg::getByteSize() Method
Declaration TibrvStatus getByteSize(tibrv_u32& byteSize) const;
Purpose Return the size of a message (in bytes).
Remarks This measurement accounts for the actual space that the message occupies (in wire format), including its header and its fields. It does not include storage that is allocated but unused. It does not include address information, such as the subject or reply subject. Programs can use this method as part of these tasks: • Measure the size of message before allocating space to store a copy—as with TibrvMsg::getAsBytesCopy(). • Assess throughput rates. • Limit output rates (also called throttling).
Parameter Description byteSize The program supplies a variable. The method stores the message size (in bytes) in that variable.
See Also TibrvMsg::getAsBytes() on page 61 TibrvMsg::getAsBytesCopy() on page 62
TIBCO Rendezvous C++ Reference 64 | Chapter 4 Data
TibrvMsg::getCurrentTime() Method
Declaration static TibrvStatus getCurrentTime( TibrvMsgDateTime& dateTime);
Purpose Get the current date and time.
Remarks This static method uses an operating system call to get the current time. Programs can call this method without reference to any message object.
Parameter Description dateTime The program supplies a variable; the method stores the current time in that variable.
Example TibrvMsgDateTime myTime; ... if (TibrvMsg::getCurrentTime(myTime) == TIBRV_OK) ...
TIBCO Rendezvous C++ Reference TibrvMsg::getField() | 65
TibrvMsg::getField() Method
Declaration TibrvStatus getField( const char* fieldName, TibrvMsgField& field, tibrv_u16 fieldId=0);
Purpose Get a specified field from a message.
Remarks Programs specify the field to retrieve using the fieldName and fieldId parameters. For details, see Field Names and Field Identifiers, page 37. The method takes a snapshot of the field, and stores that information in the field argument, overwriting the field object supplied as an argument. The method copies scalar data into the program’s field object. Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. Programs can use a related method to loop through all the fields of a message. To retrieve each field by its integer index number, see TibrvMsg::getFieldByIndex() on page 78.
Parameter Description fieldName Get a field with this name.
field The program supplies a TibrvMsgField object; the method overwrites the contents of the object with a snapshot of the information from the message field.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
Field Search Algorithm This method, and related methods that get message fields, all use this algorithm to find a field within a message, as specified by a field identifier and a field name. 1. If the identifier is zero, skip to step 3. If the program supplied a non-zero field identifier, then search for the field with that identifier. If the search succeeds, return the field.
TIBCO Rendezvous C++ Reference 66 | Chapter 4 Data
On failure, continue to step 2. 2. If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name. If the name search succeeds, and the identifier in the field is NULL, return the field. If the name search succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT. If the name search fails, or if the program supplied NULL as the field name, return the status code TIBRV_NOT_FOUND. 3. When the program supplied zero as the identifier, search for a field with the specified name—even if that name is NULL. If the search succeeds, return the field. On failure, return the status code TIBRV_NOT_FOUND.
If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.
Extracting Rendezvous programs must separately extract the nested submessage using Fields from a TibrvMsg::getMsg(), and then get the desired fields from the submessage. Nested Message
Convenience Methods In most situations, we recommend using type-specific convenience methods instead of this general method. Type-specific methods yield these advantages when extracting fields: • Code readability. •Type checking. • Automatic type conversion.
However, we do recommend the general method in two specific situations: • No convenience method exists. • The program must extract the data exactly as it appears in the message, without automatic type conversion. (Convenience methods always convert extracted data to a specific type.)
These categories of type-specific convenience methods find a field and get its data:
TIBCO Rendezvous C++ Reference TibrvMsg::getField() | 67
• Get Scalar, page 68. • Get Array, page 70. • Get Nested Message, page 72. • Get String, page 73. • Get Opaque Byte Sequence, page 74. • Get XML Byte Sequence, page 75. • Get DateTime, page 76.
See Also Field Names and Field Identifiers, page 37 Get Scalar, page 68 TibrvMsgField on page 107
TIBCO Rendezvous C++ Reference 68 | Chapter 4 Data
Get Scalar Convenience Methods
Declaration TibrvStatus getscalar_type( const char* fieldName, tibrv_scalar_type& value, tibrv_u16 fieldId=0);
Purpose Get the value of a field as a scalar value.
Remarks Each convenience method in this family retrieves a field and extracts its data. If the field’s type (as it exists) does not match the type of the convenience method, then the method attempts to convert the data (see Datatype Conversion on page 376). If conversion is not possible, the method returns TIBRV_CONVERSION_FAILED.
Method Name Type Type Description getBool tibrv_bool boolean
getF32 tibrv_f32 32-bit floating point
getF64 tibrv_f64 64-bit floating point
getI8 tibrv_i8 8-bit integer
getI16 tibrv_i16 16-bit integer
getI32 tibrv_i32 32-bit integer
getI64 tibrv_i64 64-bit integer
getU8 tibrv_u8 8-bit unsigned integer
getU16 tibrv_u16 16-bit unsigned integer
getU32 tibrv_u32 32-bit unsigned integer
getU64 tibrv_u64 64-bit unsigned integer
getIPAddr32 tibrv_ipaddr32 4-byte IP address
getIPPort16 tibrv_ipport16 2-byte IP port
TIBCO Rendezvous C++ Reference Get Scalar | 69
Parameter Description fieldName Get a field with this name.
value When extracting a scalar type, the program supplies a variable in this parameter, and the method copies the scalar value of the field to that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 70 | Chapter 4 Data
Get Array Convenience Methods
Declaration TibrvStatus getelement_typeArray( const char* fieldName, tibrv_element_type*& value, tibrv_u32& numElementsAddr, tibrv_u16 fieldId=0);
Purpose Get the value of a field as an array.
Remarks Each convenience method in this family retrieves a field and extracts its data. If the field’s type (as it exists) is does not match the type of the convenience method, then the method attempts to convert the data (see Datatype Conversion on page 376). If conversion is not possible, the method returns TIBRV_CONVERSION_FAILED. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. These methods produce values that are read-only snapshots of the field data (see Pointer Snapshot on page 33). Programs must not modify elements of the value array.
Method Name Element Type Type Description getF32Array tibrv_f32 32-bit floating point array
getF64Array tibrv_f64 64-bit floating point array
getI8Array tibrv_i8 8-bit integer array
getI16Array tibrv_i16 16-bit integer array
getI32Array tibrv_i32 32-bit integer array
getI64Array tibrv_i64 64-bit integer array
getU8Array tibrv_u8 8-bit unsigned integer array
getU16Array tibrv_u16 16-bit unsigned integer array
getU32Array tibrv_u32 32-bit unsigned integer array
getU64Array tibrv_u64 64-bit unsigned integer array
TIBCO Rendezvous C++ Reference Get Array | 71
Parameter Description fieldName Get a field with this name.
value When extracting an array type, the program supplies a variable in this parameter, and the method stores a pointer to the array in that variable.
numElementsAddr When extracting an array type, the program supplies a variable in this parameter, and the method stores the number of array elements in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 72 | Chapter 4 Data
Get Nested Message Convenience Method
Declaration TibrvStatus getMsg( const char* fieldName, TibrvMsg& subMessage, tibrv_u16 fieldId=0);
Purpose Get the value of a field as a Rendezvous message.
Remarks Since it is not possible to convert any other datatype to a message, the field must already contain a message. Otherwise, the method returns TIBRV_CONVERSION_FAILED. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. After extracting a submessage, a program can detach it. A detached submessage remains valid and unchanged even after the parent message is destroyed. The program must explicitly destroy the detached submessage. This method produces values that are modifiable snapshots of the field data. Programs may modify the resulting submessage by adding, removing or updating fields. However, these modifications do not change the field in the original parent message; instead, they force Rendezvous software to make a copy of the field (see Rendezvous Protects the Message from Changes to Submessage Snapshots on page 35).
Parameter Description fieldName Get a field with this name.
subMessage The program supplies a variable in this parameter, and the method stores the submessage in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference Get String | 73
Get String Convenience Method
Declaration TibrvStatus getString( const char* fieldName, char*& value, tibrv_u16 fieldId=0);
Purpose Get the value of a field as a character string.
Remarks This convenience method retrieves a field and extracts its data, automatically converting it to a string. Programs can use this method to obtain a printable representation of field data. For most datatypes, this method formats the full value of the field to the output string; these types are exceptions: TIBRVMSG_OPAQUE This method abbreviates the value of an opaque field; for example, [472 opaque bytes]. TIBRVMSG_XML This method abbreviates the value of an XML field; for example, [XML document: 472 bytes]. The size measures uncompressed data.
Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. This method produces values that are read-only snapshots of the field data (see Pointer Snapshot on page 33). Programs must not modify the value string.
Parameter Description fieldName Get a field with this name.
value The program supplies a variable in this parameter, and the method stores a pointer to the field value in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37 Datatype Conversion, page 376
TIBCO Rendezvous C++ Reference 74 | Chapter 4 Data
Get Opaque Byte Sequence Convenience Method
Declaration TibrvStatus getOpaque( const char* fieldName, void*& value, tibrv_u32& length, tibrv_u16 fieldId=0);
Purpose Get the value of a field as an opaque byte sequence.
Remarks This convenience method retrieves a field and extracts its data. Since it is not possible to convert any other datatype to an opaque byte sequence, the field must already contain an opaque byte sequence. Otherwise, the method returns TIBRV_CONVERSION_FAILED. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. This method produces values that are read-only snapshots of the field data (see Pointer Snapshot on page 33). Programs must not modify the value sequence.
Parameter Description fieldName Get a field with this name.
length The program supplies a variable in this parameter, and the method stores the length of the opaque byte sequence in that variable.
value The program supplies a variable in this parameter, and the method stores a pointer to the field value in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference Get XML Byte Sequence | 75
Get XML Byte Sequence Convenience Method
Declaration TibrvStatus getXml( const char* fieldName, void*& value, tibrv_u32& length, tibrv_u16 fieldId=0);
Purpose Get the value of a field as an XML byte sequence.
Remarks This convenience method retrieves a field and extracts its data. XML data is a byte sequence. Adding a field of type TIBRVMSG_XML compresses the bytes. Extracting data from the field uncompresses it to obtain the original byte sequence. Since it is not possible to convert any other datatype to an XML byte sequence, the field must already contain an XML byte sequence. Otherwise, the method returns TIBRV_CONVERSION_FAILED. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. This method produces values that are read-only snapshots of the field data (see Pointer Snapshot on page 33). Programs must not modify the value sequence.
Parameter Description fieldName Get a field with this name.
length The program supplies a variable in this parameter, and the method stores the length of the XML byte sequence in that variable.
value The program supplies a variable in this parameter, and the method stores a pointer to the field value in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 76 | Chapter 4 Data
Get DateTime Convenience Method
Declaration TibrvStatus getDateTime( const char* fieldName, TibrvMsgDateTime& value, tibrv_u16 fieldId=0);
Purpose Get the value of a field as an datetime value.
Remarks This convenience method retrieves a field and extracts its data. Since it is not possible to convert any other datatype to a datetime value, the field must already contain a datetime. Otherwise, the method returns TIBRV_CONVERSION_FAILED. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. This method produces values that are read-only snapshots of the field data (see Pointer Snapshot on page 33). Programs must not modify the datetime value.
Parameter Description fieldName Get a field with this name.
value The program supplies a variable in this parameter, and the method stores the field value in that variable.
fieldId Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.
Example This example code extracts a datetime value from a message field, and converts it to a time_t value. Programs can adapt this code as appropriate. (For corresponding code to convert a time_t value to a datetime value, and add the datetime to a message field, see the example at Add DateTime, page 55.) #include
TibrvStatus getAsTimeT( TibrvMsg& msg, const char* field, time_t& value) { TibrvMsgDateTime d; TibrvStatus error;
error = msg.getDateTime(field,d);
TIBCO Rendezvous C++ Reference Get DateTime | 77
if (error != TIBRV_OK) return error;
if (d.sec > INT_MAX || d.sec < INT_MIN) return TIBRV_CONVERSION_FAILED;
value = (time_t)d.sec; }
See Also Validity of Data Extracted From Message Fields, page 32 Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 78 | Chapter 4 Data
TibrvMsg::getFieldByIndex() Method
Declaration TibrvStatus getFieldByIndex( TibrvMsgField& field, tibrv_u32 fieldIndex);
Purpose Get a field from a message by an index.
Remarks Programs can loop through all the fields of a message, to retrieve each field in turn using an integer index. The method copies scalar data into the program’s field object. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. Add, remove and update calls can perturb the order of fields (which, in turn, affects the results when a program gets a field by index).
Parameter Description
field The program supplies a TibrvMsgField object; the method overwrites the contents of the object, using information from the message field.
fieldIndex Get the field with this index. Zero specifies the first field.
See Also TibrvMsg::getField() on page 65
TIBCO Rendezvous C++ Reference TibrvMsg::getFieldInstance() | 79
TibrvMsg::getFieldInstance() Method
Declaration TibrvStatus getFieldInstance( const char* fieldName, TibrvMsgField& fieldAddr, tibrv_u32 instance);
Purpose Get a specified instance of a field from a message.
Remarks When a message contains several field instances with the same field name, retrieve a specific instance by number (for example, get the ith field named foo). Programs can use this method in a loop that examines every field with a specified name. The argument 1 denotes the first instance of the named field. The method copies scalar data into the program’s field object. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data. When the instance argument is greater than the actual number of instances of the field in the message, this method returns the status code TIBRV_NOT_FOUND.
Release 5 Rendezvous 5 (and earlier) did not support array datatypes. Some older Interaction programs circumvented this limitation by using several fields with the same name to simulate arrays. This work-around is no longer necessary, since release 6 (and later) supports array datatypes within message fields. The method TibrvMsg::getFieldInstance() ensures backward compatibility, so new programs can still receive and manipulate messages sent from older programs. Nonetheless, we encourage programmers to use array types as appropriate, and we discourage storing several fields with the same name in a message.
Parameter Description fieldName Get an instance of the field with this name. NULL specifies the empty string as the field name.
fieldAddr The program supplies a TibrvMsgField object; the method overwrites the contents of the object, using information from the message field.
instance Get this instance of the specified field name. The argument 1 denotes the first instance of the named field.
See Also TibrvMsg::getField() on page 65
TIBCO Rendezvous C++ Reference 80 | Chapter 4 Data
TibrvMsg::getEvent() Method
Declaration TibrvEvent* getEvent();
Purpose Extract the event associated with a (dispatched) message object.
Remarks Dispatch associates the message with a listener event. This call is valid only for an inbound message that has already been dispatched to a listener event. If the message is not associated with a listener event, then this method returns NULL.
See Also TibrvEvent::getClosure() on page 126 TibrvVectorCallback::onMsgs() on page 158
TIBCO Rendezvous C++ Reference TibrvMsg::getHandle() | 81
TibrvMsg::getHandle() Method
Declaration tibrvMsg getHandle() const;
Purpose Extract the C message handle from a C++ message object.
See Also TibrvMsg() on page 42
TIBCO Rendezvous C++ Reference 82 | Chapter 4 Data
TibrvMsg::getNumFields() Method
Declaration TibrvStatus getNumFields(tibrv_u32& numFields) const;
Purpose Extract the number of fields in a message.
Remarks This method counts the immediate fields of the message; it does not descend into submessages to count their fields recursively.
Parameter Description numFields The program supplies a variable in this parameter; the method stores the number of fields in that variable.
TIBCO Rendezvous C++ Reference TibrvMsg::getReplySubject() | 83
TibrvMsg::getReplySubject() Method
Declaration TibrvStatus getReplySubject(const char*& replySubject);
Purpose Extract the reply subject from a message.
Remarks The reply subject string is part of a message’s address information—it is not part of the message itself. If the destination subject is not set, this method passes NULL in the return parameter.
Parameter Description replySubject The program supplies a variable in this parameter; the method stores the reply subject in that variable. The method makes a snapshot copy of the reply subject string, and supplies a pointer to that snapshot within message storage. The pointer remains valid as long as the message itself remains valid in the same location. The reply subject pointer becomes invalid if the program destroys the message, or returns from the data callback method that determines the scope of an inbound message. For more information, see Pointer Snapshot on page 33, and Deleting Snapshot References on page 36.
See Also TibrvMsg::setReplySubject() on page 93 Supplementary Information for Messages on page 19 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 84 | Chapter 4 Data
TibrvMsg::getSendSubject() Method
Declaration TibrvStatus getSendSubject(const char*& sendSubject);
Purpose Extract the subject from a message.
Remarks The subject string is part of a message’s address information—it is not part of the message itself. If the destination subject is not set, this method passes NULL in the return parameter.
Parameter Description sendSubject The program supplies a variable in this parameter; the method stores the send subject in that variable. The method makes a snapshot copy of the subject string, and supplies a pointer to that snapshot within message storage. The pointer remains valid as long as the message itself remains valid in the same location. The subject pointer becomes invalid if the program destroys the message, or returns from the data callback method that determines the scope of an inbound message. For more information, see Pointer Snapshot on page 33, and Deleting Snapshot References on page 36.
See Also TibrvMsg::setSendSubject() on page 94 Supplementary Information for Messages on page 19 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvMsg::getStatus() | 85
TibrvMsg::getStatus() Method
Declaration TibrvStatus getStatus() const;
Purpose Extract the status code stored by the message constructor.
Remarks We recommend that programs test the status after calls to TibrvMsg() that copy a TibrvMsg, or construct a message from a byte array.
See Also TibrvMsg on page 39 TibrvMsg() on page 42 TibrvStatus on page 380
TIBCO Rendezvous C++ Reference 86 | Chapter 4 Data
TibrvMsg::isDetached() Method
Declaration tibrv_bool isDetached();
Purpose Determine the ownership of the message.
Remarks Ownership of a message belongs either to Rendezvous software, or to your program. When Rendezvous software owns a message, the message is considered attached. Rendezvous software automatically destroys the message and reclaims its storage. For example, Rendezvous software creates an object representing an inbound message, and presents it as a parameter to a listener callback method; when the callback method returns, Rendezvous software destroys the message. A program can explicitly detach an inbound message. Thereafter, the program owns the message, and assumes the responsibility to destroy it and reclaim its storage. When a program creates a message object, the program owns that message, along with the responsibility to destroy it. This method determines the ownership of a message. It returns TIBRV_TRUE when the program owns the message; it returns TIBRV_FALSE when Rendezvous software owns the message.
See Also TibrvMsg::detach() on page 59
TIBCO Rendezvous C++ Reference TibrvMsg::markReferences() | 87
TibrvMsg::markReferences() Method
Declaration TibrvStatus markReferences();
Purpose Mark references in this message.
Remarks Extracting pointer data from a message field creates a snapshot of that data. The snapshot remains associated with the message until the program destroys the message. However, in rare situations snapshots can accumulate within a program, causing unbounded memory growth. This method gives programs explicit control over snapshot references; by clearing references, the program declares that it no longer needs the references that arise as side effects of calls that get a message field. For example, consider a program fragment that repeatedly sends a message, modifying fields within a nested submessage before each send call. Each call to extract the nested message produces a snapshot reference. By surrounding the get operation with a mark and clear pair (with the clear call occurring at any time after the get call), the program releases the reference, which helps control memory usage. void TimerCallback::onTimer(TibrvTimer* timer) { TibrvMsg* msg = (TibrvMsg*)timer->getClosure();
msg->markReferences();
TibrvMsg submsg; msg->getMsg("foo",submsg); ... msg->clearReferences();
msg->setSendSubject(some_subject);
/* send a message */ transport.send(*msg); }
Every call to TibrvMsg::markReferences() must be paired with a call to TibrvMsg::clearReferences(). It is legal to mark references several times, as long as the program eventually clears all the marks. To understand this idea, it is helpful to think of get and mark as pushdown operations, and clear as a pop operation. Figure 5 illustrates that each clear call deletes snapshots back to the most recent mark.
TIBCO Rendezvous C++ Reference 88 | Chapter 4 Data
Figure 5 Mark and Clear References
This pointer remains valid until the call that clears references back to mark 1 (that is, the second clear call).
Mark 1 Pointer to ArraySnapshot Value 1 Snapshot 1 Mark 2 Pointer to ArraySnapshot Value 2 Snapshot 2
This pointer remains valid until the call that clears references back to mark 2 (that is, the first clear call).
Unless a program explicitly marks and clears references, references persist until the message is destroyed or reset.
See Also Validity of Data Extracted From Message Fields, page 32 Deleting Snapshot References, page 36 TibrvMsg::clearReferences() on page 56
TIBCO Rendezvous C++ Reference TibrvMsg::removeField() | 89
TibrvMsg::removeField() Method
Declaration TibrvStatus removeField( const char* fieldName, tibrv_u16 fieldId=0);
Purpose Remove a field from a message.
Remarks Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) previously extracted from the field remains valid even after removing the field from the message.
Parameter Description fieldName Remove the field with this name.
fieldId Remove the field with this identifier. Zero is a special value that signifies no field identifier.
Field Search This method uses this algorithm to find and remove a field within a message, as Algorithm specified by a field identifier and a field name. 1. If the identifier is zero, skip to step 3. If the program supplied a non-zero field identifier, then search for the field with that identifier. If the search succeeds, remove the field. On failure, continue to step 2. 2. If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name. If the program supplied NULL as the field name, return the status code TIBRV_NOT_FOUND. If the name search fails, return the status code TIBRV_NOT_FOUND. If the name search succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT. If the search succeeds, remove the field. 3. When the program supplied zero as the identifier, search for a field with the specified name—even if that name is NULL. If the search succeeds, remove the field. If the search fails, return the status code TIBRV_NOT_FOUND.
TIBCO Rendezvous C++ Reference 90 | Chapter 4 Data
If a message contains several fields with the same name, searching by name removes the first instance of the field with that name.
See Also TibrvMsg::removeFieldInstance() on page 91
TIBCO Rendezvous C++ Reference TibrvMsg::removeFieldInstance() | 91
TibrvMsg::removeFieldInstance() Method
Declaration TibrvStatus removeFieldInstance( const char* fieldName, tibrv_u32 instance);
Purpose Remove a specified instance of a field from a message.
Remarks When a message contains several field instances with the same field name, remove a specific instance by number (for example, remove the ith field named foo). Programs can use this method in a loop that examines every field with a specified name. The argument 1 denotes the first instance of the named field. If the specified instance does not exist, the method returns TIBRV_NOT_FOUND. Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) previously extracted from the field remains valid even after removing the field from the message.
Parameter Description fieldName Remove the field with this name.
instance Remove this instance of the field. The argument 1 specifies the first instance of the named field.
See Also TibrvMsg::removeField() on page 89
TIBCO Rendezvous C++ Reference 92 | Chapter 4 Data
TibrvMsg::reset() Method
Declaration TibrvStatus reset();
Purpose Clear a message, preparing it for re-use.
Remarks When this method returns, the message has no fields; it is like a newly created message. The message’s address information is also reset. Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) previously extracted from fields of the old message are invalid.
See Also TibrvMsg() on page 42 ~TibrvMsg() on page 44
TIBCO Rendezvous C++ Reference TibrvMsg::setReplySubject() | 93
TibrvMsg::setReplySubject() Method
Declaration TibrvStatus setReplySubject(const char* replySubject);
Purpose Set the reply subject for a message.
Remarks A receiver can reply to an inbound message using its reply subject. Rendezvous routing daemons modify subjects and reply subjects to enable transparent point-to-point communication across network boundaries. This modification does not apply to subject names stored in message data fields; we discourage storing point-to-point subject names in data fields.
Parameter Description replySubject Use this string as the new reply subject, replacing any existing reply subject. The method copies this string to the message. The reply subject NULL removes the previous reply subject. The empty string is not a legal subject name.
See Also TibrvMsg::getReplySubject() on page 83 Supplementary Information for Messages on page 19 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 94 | Chapter 4 Data
TibrvMsg::setSendSubject() Method
Declaration TibrvStatus setSendSubject(const char* sendSubject);
Purpose Set the subject for a message.
Remarks The subject of a message can describe its content, as well as its destination set. Rendezvous routing daemons modify subjects and reply subjects to enable transparent point-to-point communication across network boundaries. This modification does not apply to subject names stored in message data fields; we discourage storing point-to-point subject names in data fields.
Parameter Description sendSubject Use this string as the new subject, replacing any existing subject. The method copies this string to the message. The subject NULL removes the previous subject, leaving the message unsendable. The empty string is not a legal subject name.
See Also TibrvMsg::getSendSubject() on page 84 Supplementary Information for Messages on page 19 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvMsg::updateField() | 95
TibrvMsg::updateField() Method
Declaration TibrvStatus updateField( const TibrvMsgField& field);
Purpose Update a field within a message. For most programs, we recommend type-specific convenience methods instead of this generic method. However, translation engine programs can require generic TibrvMsg::updateField(), and would use it in conjunction with generic TibrvMsg::getField(). In this paradigm, modify the field returned from TibrvMsg::getField() by replacing its field.value, and supply it as the field argument to TibrvMsg::updateField().
Remarks This method locates a field within the message by matching the name and identifier of field. Then it updates the message field using the field argument. (Notice that the program may not supply a field object with a different field name, field identifier, or datatype.) If no existing field matches the specifications in the field argument, then this method adds the field to the message. Update convenience methods also add the field if it is not present. The type of the existing field (within the message) and the type of the updating field argument must be identical; otherwise, the method returns the error status code TIBRV_INVALID_TYPE. However, when updating array or vector fields, the count (number of elements) can change. Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data.
Parameter Description field Update the existing message field using this field.
Field Search This method, and related methods that update message fields, all use this Algorithm algorithm to find and update a field within a message, as specified by a field identifier and a field name. 1. If the identifier is zero, skip to step 3. If the program supplied a non-zero field identifier, then search for the field with that identifier. If the search succeeds, then update that field.
TIBCO Rendezvous C++ Reference 96 | Chapter 4 Data
On failure, continue to step 2. 2. If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name. If the program supplied NULL as the field name, return the status code TIBRV_NOT_FOUND. If the name search succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT. If the search fails, add the field as specified (with name and identifier). 3. When the program supplied zero as the identifier, search for a field with the specified name—even if that name is NULL. If the search fails, add the field as specified (with name and identifier).
If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.
Reserved Field Name
The field name _data_ is reserved. Programs may not add fields with this name. More generally, all fields that begin with the underbar character are reserved.
Field Name The constant TIBRVMSG_FIELDNAME_MAX determines the longest possible field Length name.
Convenience When the datatype of a field is determined during execution, use this general Methods method. When you can determine the datatype of a field before compile-time, we recommend using type-specific convenience methods instead of this general method. Type-specific methods yield these advantages when updating fields: • Code readability. •Type checking. • Automatic type conversion.
These categories of type-specific convenience methods find a field and update its data: • Update Scalar, page 98. • Update Array, page 100. • Update Nested Message, page 102.
TIBCO Rendezvous C++ Reference TibrvMsg::updateField() | 97
• Update String, page 103. • Update Opaque Byte Sequence, page 104 • Update DateTime, page 106
Nested Message When the new value is a message object, this method uses only the data portion of the nested message (data); it does not include any address information or certified delivery information.
TIBCO Rendezvous C++ Reference 98 | Chapter 4 Data
Update Scalar Convenience Methods
Declaration TibrvStatus updatescalar_type ( const char* fieldName, tibrv_scalar_type value, tibrv_u16 fieldId=0);
Purpose Update a field containing a scalar value.
Remarks Each convenience method in this family locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match.
Method Name Value Type Type Description updateBool tibrv_bool boolean scalar
updateI8 tibrv_i8 8-bit integer
updateU8 tibrv_u8 8-bit unsigned integer
updateI16 tibrv_i16 16-bit integer
updateU16 tibrv_u16 16-bit unsigned integer
updateI32 tibrv_i32 32-bit integer
updateU32 tibrv_u32 32-bit unsigned integer
updateI64 tibrv_i64 64-bit integer
updateU64 tibrv_u64 64-bit unsigned integer
updateF32 tibrv_f32 32-bit floating point
updateF64 tibrv_f64 64-bit floating point
updateIPAddr32 tibrv_ipaddr32 4-byte IP address
updateIPPort16 tibrv_ipport16 2-byte IP port
TIBCO Rendezvous C++ Reference Update Scalar | 99
Parameter Description fieldName Update a field with this name.
value Update the message field to this value (which may be a literal or stored in a variable). The method copies the value into the new message field.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 100 | Chapter 4 Data
Update Array Convenience Methods
Declaration TibrvStatus updateelement_typeArray( const char* fieldName, const tibrv_scalar_type value, tibrv_u32 numElements, tibrv_u16 fieldId=0);
Purpose Update a field containing an array value.
Remarks Each convenience method in this family locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match. The number of elements can change. Pointer data previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data. (See Pointer Snapshot on page 33.)
Method Name Element Type Type Description updateI8Array tibrv_i8 8-bit integer array
updateU8Array tibrv_u8 8-bit unsigned integer array
updateI16Array tibrv_i16 16-bit integer array
updateU16Array tibrv_u16 16-bit unsigned integer array
updateI32Array tibrv_i32 32-bit integer array
updateU32Array tibrv_u32 32-bit unsigned integer array
updateI64Array tibrv_i64 64-bit integer array
updateU64Array tibrv_u64 64-bit unsigned integer array
updateF32Array tibrv_f32 32-bit floating point array
updateF64Array tibrv_f64 64-bit floating point array
TIBCO Rendezvous C++ Reference Update Array | 101
Parameter Description fieldName Update a field with this name.
value Update the message field to this array value. The method copies the new array into the existing field.
numElements When updating an array type, the program supplies the count of array elements in this parameter.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 102 | Chapter 4 Data
Update Nested Message Convenience Method
Declaration TibrvStatus updateMsg( const char* fieldName, const TibrvMsg& value, tibrv_u16 fieldId=0);
Purpose Update a field containing a nested submessage.
Remarks This convenience method locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match. The message size (that is, its length in bytes) can change. Pointer data previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data. (See Rendezvous Protects the Message from Changes to Submessage Snapshots on page 35.) This method uses only the data portion of the nested message (value); it does not include any address information or certified delivery information.
Parameter Description fieldName Update a field with this name.
value Update the message field to this value. The method copies the new value into the field.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference Update String | 103
Update String Convenience Method
Declaration TibrvStatus updateString( const char* fieldName, const char* value, tibrv_u16 fieldId=0);
Purpose Update a field containing a character string.
Remarks This convenience method locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match. The length of the string can change. Pointer data previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data. (See Pointer Snapshot on page 33.)
Parameter Description fieldName Update a field with this name.
value Update the message field to this value (which may be a literal or stored in a variable). The method copies the new value into the existing field.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 104 | Chapter 4 Data
Update Opaque Byte Sequence Convenience Method
Declaration TibrvStatus updateOpaque( const char* fieldName, const void* value, tibrv_u32 size, tibrv_u16 fieldId=0);
Purpose Update a field containing an opaque byte sequence.
Remarks This convenience method locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match. The size can change. Pointer data previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data. (See Pointer Snapshot on page 33.)
Parameter Description fieldName Update a field with this name.
value Update the message field to this value. The method copies the new value into the existing field.
size The program supplies the size of the new data in this parameter.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference Update XML Byte Sequence | 105
Update XML Byte Sequence Convenience Method
Declaration TibrvStatus updateXml( const char* fieldName, const void* value, tibrv_u32 size, tibrv_u16 fieldId=0);
Purpose Update a field containing an XML byte sequence.
Remarks This convenience method locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match. The size can change. Pointer data previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data. (See Pointer Snapshot on page 33.) XML data is a byte sequence. Adding (or updating) a field of type TIBRVMSG_XML compresses the bytes. Extracting data from the field uncompresses it to obtain the original byte sequence.
Parameter Description fieldName Update a field with this name.
value Update the message field to this value. The method copies the new value into the existing field.
size The program supplies the size of the new data in this parameter.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference 106 | Chapter 4 Data
Update DateTime Convenience Method
Declaration TibrvStatus updateDateTime( const char* fieldName, const TibrvMsgDateTime& value, tibrv_u16 fieldId=0);
Purpose Update a field containing a datetime value.
Remarks This convenience method locates a field (by name or identifier) and updates its data. The type of the existing field (within the message) and the type of the updating value must match.
Parameter Description fieldName Update a field with this name.
value Update the message field to this value. The method copies the new value into the existing field.
fieldId Update the field with this identifier. Zero is a special value that signifies no field identifier. It is illegal to add a field that has both a NULL field name, and a non-zero field identifier.
See Also Field Names and Field Identifiers, page 37
TIBCO Rendezvous C++ Reference TibrvMsgField | 107
TibrvMsgField Class
Declaration class TibrvMsgField : public tibrvMsgField
Purpose Represent a message field.
Remarks Because the field object is identical to the C field struct, programs can use the struct’s accessors to get and set the field’s name, data, and other members. Although a formal destructor is not needed, C++ declares a default destructor, which has no effect.
Method Description Page TibrvMsgField() Create a message field object. 109
TibrvMsgField::getCount() Get the number of elements in a 110 field.
TibrvMsgField::getData() Get the data value of a field. 111
TibrvMsgField::getId() Get the identifier of a field. 112
TibrvMsgField::getName() Get the name of a field. 113
TibrvMsgField::getSize() Get the size of a field. 114
TibrvMsgField::getType() Get the datatype of a field. 115
(Sheet 1 of 2) Member Type Description
name char* The field’s name. NULL signifies the empty string as the field name. Field name strings use the ISO 8859-1 character encoding.
size tibrv_u32 The size of the field’s data (in bytes). For array types, size reflects the size (in bytes) of one array element. For TIBRVMSG_STRING, size reflects the number of bytes in the string (including the NULL terminator, if present). For TIBRVMSG_OPAQUE and TIBRVMSG_XML, size reflects the number of bytes of opaque data.
TIBCO Rendezvous C++ Reference 108 | Chapter 4 Data
(Sheet 2 of 2) Member Type Description
count tibrv_u32 The number of values in an array field. For array types, count is the number of array elements. For example, when a field contains a array of ten 32-bit integers, its size is 4, and its count is 10. (For scalar types, strings, XML data, and opaque byte sequences, count is 1. That is, the field contains one string—not an array of characters; one opaque value—not an array of bytes.)
data tibrvLocalData The field’s data value.
id tibrv_u16 The field’s identifier. Identifiers are optional, but must be unique within each message.
type tibrv_u8 A Rendezvous datatype token denoting the type of the field’s data.
See Also TibrvMsg::addField() on page 45 TibrvMsg::getField() on page 65 TibrvMsg::updateField() on page 95 tibrvMsgField on page 55 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvMsgField() | 109
TibrvMsgField() Constructor
Declaration TibrvMsgField()
TibrvMsgField(const TibrvMsgField& field)
TibrvMsgField(const tibrvMsgField& cField)
Purpose Create a message field object.
Remarks Because the field object is identical to the C field struct, programs can use the struct’s accessors to get and set the field’s name, data, and other members.
Parameter Description
field Create an independent copy of this TibrvMsgField object.
cField Create an independent copy of this C field struct in a new TibrvMsgField object.
See Also TibrvMsg::addField() on page 45 TibrvMsg::getField() on page 65 TibrvMsg::updateField() on page 95
TIBCO Rendezvous C++ Reference 110 | Chapter 4 Data
TibrvMsgField::getCount() Method
Declaration tibrv_u32 getCount() const;
Purpose Get the number of elements in a field.
Remarks For array types, count is the number of array elements. For example, when a field contains a array of ten 32-bit integers, its size is 4, and its count is 10. (For scalar types, strings, opaque byte sequences and XML data, the count is 1. That is, the field contains one string—not an array of characters; one opaque value—not an array of bytes.) This method returns the value of the member field.count.
TIBCO Rendezvous C++ Reference TibrvMsgField::getData() | 111
TibrvMsgField::getData() Method
Declaration tibrvLocalData getData() const;
Purpose Get the data value of a field.
Remarks This method returns the value of the member field.data.
Do not use this method to access opaque data that requires memory alignment; the C struct tibrvLocalData does not necessarily preserve alignment. Instead, see Add Opaque Byte Sequence on page 53, Get Opaque Byte Sequence on page 74, or Update Opaque Byte Sequence on page 104.
TIBCO Rendezvous C++ Reference 112 | Chapter 4 Data
TibrvMsgField::getId() Method
Declaration tibrv_u16 getId() const;
Purpose Get the identifier of a field.
Remarks Identifiers are optional, but must be unique within each message. This method returns the value of the member field.id.
TIBCO Rendezvous C++ Reference TibrvMsgField::getName() | 113
TibrvMsgField::getName() Method
Declaration const char* getName() const;
Purpose Get the name of a field.
Remarks NULL signifies the empty string as the field name. Field name strings use the ISO 8859-1 character encoding. This method returns the value of the member field.name.
TIBCO Rendezvous C++ Reference 114 | Chapter 4 Data
TibrvMsgField::getSize() Method
Declaration tibrv_u32 getSize() const;
Purpose Get the size of a field.
Remarks Return the size of the field’s data (in bytes). For array types, size reflects the size (in bytes) of one array element. For TIBRVMSG_STRING, size reflects the number of bytes in the string (including the NULL terminator, if present). For TIBRVMSG_OPAQUE and TIBRVMSG_XML, size reflects the number of data bytes. This method returns the value of the member field.size.
TIBCO Rendezvous C++ Reference TibrvMsgField::getType() | 115
TibrvMsgField::getType() Method
Declaration tibrv_u8 getType() const;
Purpose Get the datatype of a field.
Remarks Return the Rendezvous datatype token denoting the type of the field’s data. This method returns the value of the member field.type.
TIBCO Rendezvous C++ Reference 116 | Chapter 4 Data
TibrvMsgDateTime Class
Declaration class TibrvDateTime : public tibrvMsgDateTime
Purpose Represent date and time.
Remarks Because the datetime object is identical to the C field struct, programs can use the struct’s accessors to get and set the field’s sec and nsec members.
Although a formal destructor is not needed, C++ declares a default destructor, which has no effect.
Method Description Page TibrvMsgDateTime() Create a Rendezvous datetime object. 119
Member Type Description sec tibrv_i64 Signed 64-bit integer representing seconds.
nsec tibrv_u32 Unsigned 32-bit integer representing nanoseconds after the seconds value. This value is always non-negative, between zero and 999999999. It modifies the date in whole seconds by specifying the number of nanoseconds after that date. For example, the time 1/2 second before midnight of December 31, 1969 is -1 seconds plus 500,000,000 nanoseconds.
(Sheet 1 of 2) Operator Description == Test equality. Operands can be any combination of C++ TibrvMsgDateTime objects and C tibrvMsgDateTime objects. Return TIBRV_TRUE if the two objects represent the same time; TIBRV_FALSE otherwise.
TIBCO Rendezvous C++ Reference TibrvMsgDateTime | 117
(Sheet 2 of 2) Operator Description != Test inequality. Operands can be any combination of C++ TibrvMsgDateTime objects and C tibrvMsgDateTime objects. Return TIBRV_FALSE if the two objects do not represent the same time; TIBRV_TRUE otherwise.
Representations Rendezvous software represents time values in two ways—one within C and C++ programs, and a more compact wire format within messages. Table 5 on page 117 compares these two representations. In both representations, zero denotes the epoch, 12:00 midnight, January 1st, 1970. Range limits denote the extreme value on either side of that center. Bold type indicates the primary unit of measurement for each representation.
Table 5 Date and Time Representations Representation Details Within C and Seconds as a 64-bit signed integer, plus nanoseconds as a 32-bit unsigned C++ programs integer. However, values are restricted to the range and granularity supported by Rendezvous wire format. Forcing larger or finer values into this representation produces an error. Two constants bracket the available (restricted) range of values within programs— TIBRVMSG_DATETIME_SEC_MAX and TIBRVMSG_DATETIME_SEC_MIN.
range in years 292,471,208,677
range in seconds 9,223,372,036,854,775,807
restricted range in seconds 549,755,813,887
restricted range in millisecs 549,755,813,887,000
Rendezvous Seconds as a 40-bit signed integer, plus microseconds as a 24-bit unsigned wire format integer.
range in years 17,432
range in seconds 549,755,813,887
range in milliseconds 549,755,813,887,000
TIBCO Rendezvous C++ Reference 118 | Chapter 4 Data
Converting TibrvMsg::convertToString() prints times in UTC format (also known as Zulu DateTime to time or GMT). The ISO-8601 standard requires appending a Z character in this Strings notation. TibrvMsg::convertToString() uses Common Era numbering for years. This system does not include a year zero. So for example, the time 1 second before 0001-01-01 00:00:00Z would print as -0001-12-31 23:59:59Z. TibrvMsg::convertToString() uses a proleptic Gregorian calendar. That is, when formatting dates earlier than the adoption of the Gregorian calendar, it projects the Gregorian calendar backward beyond its actual invention and adoption.
See Also Add DateTime, page 55 TibrvMsg::convertToString() Get DateTime, page 76 Update DateTime, page 106 tibrvMsgDateTime on page 53 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvMsgDateTime() | 119
TibrvMsgDateTime() Constructor
Declaration TibrvMsgDateTime()
TibrvMsgDateTime(const TibrvMsgDateTime& dateTime)
TibrvMsgDateTime(const tibrvMsgDateTime& cDateTime)
Purpose Create a Rendezvous datetime object.
Remarks With no arguments, this method creates an object representing the epoch (0 seconds, 0 nanoseconds). Because the datetime object is identical to the C field struct, programs can use the struct’s accessors to get and set the field’s sec and nsec members.
Parameter Description
dateTime Create an independent copy of this TibrvMsgDateTime object.
cDateTime Create an independent copy of this C datetime struct in a new TibrvMsgDateTime object.
See Also TibrvMsgDateTime on page 116 Representations, page 117
TIBCO Rendezvous C++ Reference 120 | Chapter 4 Data
TIBCO Rendezvous C++ Reference | 121
Chapter 5 Events and Queues
This chapter presents classes and methods associated with event interest and event processing.
Topics
• Event Overview, page 122 • TibrvEvent, page 123 • TibrvCallback, page 135 • TibrvEventOnComplete, page 137 • TibrvListener, page 141 • TibrvMsgCallback, page 147 • TibrvVectorListener, page 149 • TibrvVectorCallback, page 157 • TibrvTimer, page 159 • TibrvTimerCallback, page 165 • TibrvIOEvent, page 167 • TibrvIOCallback, page 173 • TibrvDispatchable, page 175 • TibrvQueue, page 182 • TibrvQueueGroup, page 201 • TibrvDispatcher, page 212
TIBCO Rendezvous C++ Reference 122 | Chapter 5 Events and Queues
Event Overview
Programs can express interest in events. When an event occurs, it triggers a program callback method to process the event. Events wait in queues until programs dispatch them. Dispatching an event runs its callback method to process the event. Event queues organize events awaiting dispatch. Programs dispatch events to run callback methods. Queue groups add flexibility and fine-grained control to the event queue dispatch mechanism. Programs can create groups of queues and dispatch them according to their queue priorities.
TIBCO Rendezvous C++ Reference TibrvEvent | 123
TibrvEvent Class
Declaration class TibrvEvent
Purpose Event objects represent program interest in events, and event occurrences.
Remarks Programs create instances of event subclasses of TibrvEvent, but not of this superclass. Each call to a Rendezvous event create method results in a new event object, which represents your program’s interest in a set of events. Rendezvous software uses the same event object to signal each occurrence of such an event. Destroying an event object cancels the program’s interest in that event. Destroying the queue or transport of an event automatically destroys the event as well. Although the fault tolerance classes are technically events, they are sufficiently different from listeners and timers that they require separate description. See Chapter 8, Fault Tolerance, on page 257.
Method Description Page
TibrvEvent::destroy() Destroy an event, canceling interest. 125
TibrvEvent::getClosure() Extract the closure data of an event object. 126
TibrvEvent::getHandle() Return the C event handle of this C++ event object. 127
TibrvEvent::getType() Return the C event type token of an event object. 128
TibrvEvent::getQueue() Extract the queue of an event object. 129
TibrvEvent::isIOEvent() Test whether this event object is an I/O event. 130
TibrvEvent::isListener() Test whether this event object is a listener. 131
TibrvEvent::isTimer() Test whether this event object is a timer. 132
TibrvEvent::isValid() Test whether an event has been destroyed. 133
TibrvEvent::isVectorListener() Test whether this event object is a vector listener. 134
Descendants TibrvListener on page 141 TibrvVectorListener on page 149 TibrvTimer on page 159
TIBCO Rendezvous C++ Reference 124 | Chapter 5 Events and Queues
TibrvIOEvent on page 167 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference TibrvEvent::destroy() | 125
TibrvEvent::destroy() Method
Declaration virtual TibrvStatus destroy( TibrvEventOnComplete* completeCB = NULL);
Purpose Destroy an event, canceling interest.
Remarks Destroying an event object cancels interest in it. Upon return from TibrvEvent::destroy(), the destroyed event is no longer dispatched. However, all active callback methods of this event continue to run and return normally, even though the event is invalid. It is legal for an event callback method to destroy its own event argument. Destroying event interest invalidates the event object; subsequent API calls involving the invalid event return error status, unless explicitly documented to the contrary. This method also destroys the C event handle embedded in the C++ event object. Although TibrvEvent::destroy() prevents future dispatch calls from running the destroyed event’s callback method, that callback method might be already running in one or more threads that dispatch events from the same queue. In each thread where the callback method is already in progress, that callback method does continue to run until complete. Rendezvous software ensures that the completion method runs when the last callback-in-progress has completed; for important details, see TibrvEventOnComplete::onComplete() on page 138.
Parameter Description completeCB Rendezvous software runs the completion callback method immediately after all instances of the event’s callback method have completed. If the event’s callback method is not running when the event is destroyed, the destroy call runs it before returning. If this parameter is NULL, TibrvEvent::destroy() does not trigger a completion method.
See Also TibrvEvent::isValid() on page 133 TibrvEventOnComplete on page 137 tibrvEvent_Destroy() on page 151 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference 126 | Chapter 5 Events and Queues
TibrvEvent::getClosure() Method
Declaration void* getClosure() const;
Purpose Extract the closure data of an event object.
Remarks If no closure data is set for the event object, this method returns NULL. This method can extract the closure data even from invalid events.
TIBCO Rendezvous C++ Reference TibrvEvent::getHandle() | 127
TibrvEvent::getHandle() Method
Declaration tibrvEvent getHandle() const;
Purpose Return the C event handle of this C++ event object.
Remarks If the event is invalid, this method returns the constant TIBRV_INVALID_ID.
See Also tibrvEvent on page 132 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference 128 | Chapter 5 Events and Queues
TibrvEvent::getType() Method
Declaration TibrvStatus getType( tibrvEventType &type) const;
Purpose Return the C event type token of an event object.
Parameter Description type The program supplies a variable. This method stores the event type in that variable.
See Also tibrvEventType on page 161 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvEvent::getQueue() | 129
TibrvEvent::getQueue() Method
Declaration TibrvQueue* getQueue() const;
Purpose Extract the queue of an event object.
Remarks If the event is invalid, this method returns NULL.
TIBCO Rendezvous C++ Reference 130 | Chapter 5 Events and Queues
TibrvEvent::isIOEvent() Method
Declaration tibrv_bool isIOEvent() const;
Purpose Test whether this event object is an I/O event.
Remarks This method returns TIBRV_TRUE when the event is an I/O event. Otherwise, it returns TIBRV_FALSE.
See Also TibrvListener on page 141 TibrvTimer on page 159 TibrvIOEvent on page 167 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference TibrvEvent::isListener() | 131
TibrvEvent::isListener() Method
Declaration tibrv_bool isListener() const;
Purpose Test whether this event object is a listener.
Remarks This method returns TIBRV_TRUE when the event is a listener (including a certified delivery listener). Otherwise, it returns TIBRV_FALSE.
See Also TibrvListener on page 141 TibrvTimer on page 159 TibrvIOEvent on page 167 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference 132 | Chapter 5 Events and Queues
TibrvEvent::isTimer() Method
Declaration tibrv_bool isTimer() const;
Purpose Test whether this event object is a timer.
Remarks This method returns TIBRV_TRUE when the event is a timer. Otherwise, it returns TIBRV_FALSE.
See Also TibrvListener on page 141 TibrvTimer on page 159 TibrvIOEvent on page 167 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference TibrvEvent::isValid() | 133
TibrvEvent::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test whether an event has been destroyed.
Remarks This method returns TIBRV_FALSE if it has been destroyed (using the destroy method); TIBRV_TRUE otherwise. Notice that TibrvEvent::destroy() invalidates the event immediately, even though active callback methods may continue to run.
See Also TibrvEvent::destroy() on page 125
TIBCO Rendezvous C++ Reference 134 | Chapter 5 Events and Queues
TibrvEvent::isVectorListener() Method
Declaration tibrv_bool isVectorListener() const;
Purpose Test whether this event object is a vector listener.
Remarks This method returns TIBRV_TRUE when the event is a vector listener. Otherwise, it returns TIBRV_FALSE.
See Also TibrvVectorListener on page 149
TIBCO Rendezvous C++ Reference TibrvCallback | 135
TibrvCallback Class
Declaration class TibrvCallback
Purpose Superclass of event callback interface classes.
Remarks Programs can implement this interface to process events. Subclass interfaces process specific types of events.
Method Description Page
TibrvCallback::onEvent() Process events. 136
Descendants TibrvMsgCallback on page 147 TibrvVectorListener on page 149 TibrvCmMsgCallback on page 350 TibrvTimerCallback on page 165 TibrvIOCallback on page 173
TIBCO Rendezvous C++ Reference 136 | Chapter 5 Events and Queues
TibrvCallback::onEvent() Method
Declaration virtual void onEvent( TibrvEvent* event, TibrvMsg& msg) = 0;
Purpose Process events.
Remarks Implement this method to process events.
Parameter Description event This parameter receives the event.
msg When the event is an inbound message, this parameter receives the message object. For all other event types, this parameter receives a message object with no fields. The program must not use this empty message in any way.
TIBCO Rendezvous C++ Reference TibrvEventOnComplete | 137
TibrvEventOnComplete Class
Declaration class TibrvEventOnComplete
Purpose Run program code after all callback methods of a destroyed event have completed.
Remarks Implement this interface to post-process destroyed events.
Method Description Page
TibrvEventOnComplete::onComplete() A program can destroy an event object even 138 when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
TIBCO Rendezvous C++ Reference 138 | Chapter 5 Events and Queues
TibrvEventOnComplete::onComplete() Method
Declaration virtual void onComplete( TibrvEvent* destroyedEvent) = 0;
Purpose A program can destroy an event object even when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
Parameter Description destroyedEvent This parameter receives the event object. This object is identical to the object that the program created to express event interest. However, by the time this method runs, the event is already destroyed; this method cannot use the event object in Rendezvous calls.
Remarks This type of method is important in two situations: • An event callback method calls TibrvEvent::destroy() to destroy its event, and the program must do additional processing after the rest of the callback method has completed. • Several threads dispatch an event (so the event callback method can be running in several threads) and the program must do additional processing after the callback method has completed in all threads.
Upon return from TibrvEvent::destroy(), the destroyed event’s callback method can no longer begin to run. However, in each thread where the callback method is already in progress, that callback method does continue to run until complete. The completion callback can still extract closure data from the event, even though the event is already destroyed. TibrvEvent::destroy() accepts an argument of type TibrvEventOnComplete. Rendezvous software ensures that the completion method runs when the last callback-in-progress has completed.
Timing and This completion method can run in two situations: Context • Figure 6 on page 140 illustrates a situation in which the program calls TibrvEvent::destroy() while callback methods of the destroyed event are in progress. When the last of those callback methods completes, Rendezvous
TIBCO Rendezvous C++ Reference TibrvEventOnComplete::onComplete() | 139
software runs the completion method immediately, in the same thread as the callback method that completes last. • Figure 7 on page 140 illustrates a situation in which the program calls TibrvEvent::destroy() when the destroyed event’s callback method is not running in any thread. In this case, TibrvEvent::destroy() calls the completion method before returning. Notice that in this situation, the completion method runs in the program context, instead of the usual context of a callback method. In rare instances, deadlock can occur, resulting from unintended interactions between mutex operations in the program context before the destroy call, and mutex operations in the program’s completion method code. To protect against this type of deadlock, programmers can use a straightforward thought-experiment as a preventive test. Expand the completion method code immediately after the call to TibrvEvent::destroy()—as it would run when the destroyed event’s callback method is not running in any thread. Trace mutex locking activity within this context to determine whether the resulting code could violate established rules for proper use of mutex locks. ... mutex lock operations ... myEvent::destoy() expand completion method code here, and check for violations of mutex rules ...
Potential violations and conflicts usually become apparent during this exercise. Remember, it is the programmer’s responsibility to prevent deadlock.
TIBCO Rendezvous C++ Reference 140 | Chapter 5 Events and Queues
Figure 6 Completion when Callback Methods are in Progress
2. Destroy event. Event becomes invalid. No more callback functions can begin running.
Event Valid
Callback Function Running in Thread 1
Callback Function Running Completion Function Running in Thread 2 in Thread 2
Callback Function Running 3. All callback functions are complete. in Thread 3 The completion function runs immediately after the last callback function returns, in the dispatch 1. Several threads dispatch the event, thread of that callback function. running its callback function.
Figure 7 Completion when Callback Methods are Not in Progress
1. Destroy event. Event becomes invalid. Event Valid No more callback functions can begin running.
Program Code Completion Function Running Context in Destroy Thread
2. Notice that no callback functions are in progress when the program destroys the event. So the completion function runs in the destroy thread, immediately after the destroy function returns.
See Also TibrvIOEvent::create() on page 170 TibrvListener::create() on page 144 TibrvTimer::create() on page 162 TibrvEvent::destroy() on page 125
TIBCO Rendezvous C++ Reference TibrvListener | 141
TibrvListener Class
Declaration class TibrvListener : public TibrvEvent TibrvListener(); // Construct empty. virtual ~TibrvListener(); // Destroy and reclaim storage.
Purpose Listen for inbound messages.
Remarks A listener object continues listening for messages until the program destroys it. The constructor creates a hollow object; the create method makes it operational. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue or transport of a listener event automatically invalidates the listener as well.
Method Description Page
TibrvListener::create() Listen for inbound messages. 144
TibrvListener::getSubject() Extract the subject from a 145 listener event object.
TibrvListener::getTransport() Extract the transport from a 146 listener event object.
Inherited Methods
TibrvEvent::destroy() TibrvEvent::getClosure() TibrvEvent::getHandle() TibrvEvent::getType() TibrvEvent::getQueue() TibrvEvent::isValid() TibrvEvent::isListener() TibrvEvent::isTimer() TibrvEvent::isIOEvent()
Activation and Dispatch When an inbound message on the transport has a destination subject that matches the listener subject, then the message triggers the event.
TIBCO Rendezvous C++ Reference 142 | Chapter 5 Events and Queues
The method TibrvListener::create() creates a C listener event object, and activates the event—that is, it begins listening for all inbound messages with matching subjects. When a message arrives, Rendezvous software places the event object and message on its event queue. Dispatch removes the event object from the queue, and runs the callback method to process the message. (To stop receiving inbound messages on the subject, destroy the event object; this action cancels all messages already queued for the listener event; see TibrvEvent::destroy() on page 125.) Figure 8 illustrates that Rendezvous software does not deactivate the listener when it places new message events on the queue (in contrast to I/O events, which are temporarily deactivated). Consequently, several messages can accumulate in the queue while the callback method is processing.
Figure 8 Listener Activation and Dispatch
5. Destroy listener event. 1. Create and activate listener event. Messages stop arriving.
Listener Event Active
2. Message arrives. Event enters queue.
3. Dispatch event.
4. Callback function returns. Event Callback Waiting in Function Dispatch next event. Queue Running
Callback Event Waiting in Function Queue Running
Callback Event Waiting in Queue Function Running
Callback Event Waiting in Queue Function Running 6. Destroying listener Event Waiting in More messages arrive. cancels messages in Queue the queue.
TIBCO Rendezvous C++ Reference TibrvListener | 143
When the callback method is I/O-bound, messages can arrive faster than the callback method can process them, and the queue can grow unacceptably long. In programs where a delay in processing messages is unacceptable, consider dispatching from several threads to process messages concurrently.
Related Classes TibrvEvent on page 123 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference 144 | Chapter 5 Events and Queues
TibrvListener::create() Method
Declaration TibrvStatus create ( TibrvQueue* queue, TibrvCallback* callback, TibrvTransport* transport, const char* subject, const void* closure = NULL);
Purpose Listen for inbound messages.
Remarks This method creates a C listener and stores its handle in the C++ object.
Parameter Description queue For each inbound message, place the event on this event queue.
callback On dispatch, process the event with this callback object. This object can be an instance of class TibrvMsgCallback, or its superclass TibrvCallback.
transport Listen for inbound messages on this transport.
subject Listen for inbound messages with subjects that match this specification. Wildcard subjects are permitted. The empty string is not a legal subject name.
closure Store this closure data in the event object.
Listening for Use this method to listen for advisory subjects. We recommend sending advisory Advisory message events to the default queue. Messages
Inbox Listener To receive unicast (point-to-point) messages, listen to an inbox subject name. First call TibrvTransport::createInbox() to create the unique inbox name; then call TibrvListener::create() to begin listening. Remember that other programs have no information about an inbox until the listening program uses it as a reply subject in an outbound message. See also, Inbox Names on page 94 in TIBCO Rendezvous Concepts.
See Also TibrvListener::getSubject() on page 145 TibrvTransport::createInbox() on page 224
TIBCO Rendezvous C++ Reference TibrvListener::getSubject() | 145
TibrvListener::getSubject() Method
Declaration TibrvStatus getSubject(const char*& subject) const;
Purpose Extract the subject from a listener event object.
Parameter Description subject The program supplies a variable. The method stores the subject of the listener event object in that variable.
Remarks Programs must not free nor modify the resulting subject string.
TIBCO Rendezvous C++ Reference 146 | Chapter 5 Events and Queues
TibrvListener::getTransport() Method
Declaration TibrvTransport* getTransport() const;
Purpose Extract the transport from a listener event object.
TIBCO Rendezvous C++ Reference TibrvMsgCallback | 147
TibrvMsgCallback Class
Declaration class TibrvMsgCallback : public TibrvCallback
Purpose Process inbound messages (listener events).
Remarks Implement this interface to process inbound messages.
Method Description Page
TibrvMsgCallback::onMsg() Process inbound messages (listener 148 events).
Related Classes TibrvCallback on page 135 TibrvCmMsgCallback on page 350
See Also TibrvListener::create() on page 144
TIBCO Rendezvous C++ Reference 148 | Chapter 5 Events and Queues
TibrvMsgCallback::onMsg() Method
Declaration virtual void onMsg(TibrvListener* listener, TibrvMsg& msg) = 0;
Purpose Process inbound messages (listener events).
Remarks Implement this method to process inbound messages.
Parameter Description listener This parameter receives the listener event.
msg This parameter receives the inbound message.
CM Label The callback method for certified delivery messages can use certified delivery Information (CM) label information to discriminate among these situations: •If TibrvCmMsg::getSender() returns status code TIBRV_NOT_FOUND, then the message uses the reliable protocol (that is, it was sent from an ordinary transport). •If TibrvCmMsg::getSender() returns a valid sender name, then the message uses the certified delivery protocol (that is, it is a labeled message, sent from a CM transport).
See Also TibrvCmListener::create() on page 299 TibrvCmMsg::getSender() on page 345 TibrvCmMsg::getSequence() on page 346 TibrvCmMsg::getTimeLimit() on page 348
TIBCO Rendezvous C++ Reference TibrvVectorListener | 149
TibrvVectorListener Class
Declaration class TibrvVectorListener : public TibrvEvent TibrvVectorListener(); // Construct empty. virtual ~TibrvVectorListener(); // Destroy and reclaim storage.
Purpose Listen for inbound messages, and receive them in a vector.
Remarks A vector listener object continues listening for messages until the program destroys it. The constructor creates a hollow object; the create method makes it operational. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue or transport of a vector listener event automatically invalidates the vector listener as well.
Method Description Page
TibrvVectorListener::create() Listen for inbound messages, and receive 150 them in a vector.
TibrvVectorListener::getSubject() Extract the subject from a vector listener 155 event object.
TibrvVectorListener::getTransport() Extract the transport from a vector listener 156 event object.
Inherited Methods
TibrvEvent::destroy() TibrvEvent::getClosure() TibrvEvent::getHandle() TibrvEvent::getType() TibrvEvent::getQueue() TibrvEvent::isValid() TibrvEvent::isListener() TibrvEvent::isTimer() TibrvEvent::isIOEvent()
Related Classes TibrvEvent on page 123 TibrvVectorCallback on page 157
TIBCO Rendezvous C++ Reference 150 | Chapter 5 Events and Queues
TibrvVectorListener::create() Method
Declaration TibrvStatus create ( TibrvQueue* queue, TibrvVectorCallback* callback, TibrvTransport* transport, const char* subject, const void* closure = NULL);
Purpose Listen for inbound messages, and receive them in a vector.
Remarks This method creates a C vector listener and stores its handle in the C++ object.
Parameter Description queue Place each inbound message on this event queue.
callback On dispatch, process the message vector with this callback object. This object must be an instance of class TibrvVectorCallback.
transport Listen for inbound messages on this transport.
subject Listen for inbound messages with subjects that match this specification. Wildcard subjects are permitted. The empty string is not a legal subject name.
closure Store this closure data in the event object.
Motivation The standard way of receiving messages—one at a time—has the advantage of simplicity. However, if your application requires high throughput and low latency, consider receiving data messages in a vector instead. Vector listeners can boost performance for programs that receive a large number of messages by reducing the overhead associated with message dispatch. Applications that require high throughput (that is, many messages arriving rapidly) could benefit from vector listeners.
We do not recommend vector listeners for command messages, administrative messages, advisory messages, nor any other out-of-band purpose.
TIBCO Rendezvous C++ Reference TibrvVectorListener::create() | 151
Activation and This method creates a vector listener event object, and activates the event—that is, Dispatch it begins listening for all inbound messages with matching subjects. Dispatch removes a group of matching messages from the queue, and runs the callback method to process the message vector. To stop receiving inbound messages on the subject, destroy the event object; this action cancels all messages already queued for the vector listener event.
Interoperability Vector listeners and ordinary listeners can listen on the same queue.
Grouping When several vector listeners use the same queue, the dispatcher groups Messages into messages into vectors with the following properties: Vectors • The sequence of messages in a vector reflect consecutive arrival in the queue. • All messages in a vector share the same callback object (though they need not match the same listener).
From these properties we can derive further inferences: • If two vector listeners use the same callback object, then the dispatcher can group messages on their subjects into the same vector. • If two messages are adjacent in the queue, but require different callback objects, then the dispatcher cannot group them into the same vector.
Example 1 Vector Listeners: Same Callback Two vector listeners, F and P, listen on subjects FOO and PHU, respectively. Both F and P designate the same queue, Q1, and the same callback object, C1, to process their messages. In this situation, the dispatcher for Q1 can group messages on subjects FOO and PHU into the same vector (as long as the messages constitute a contiguous sequence within Q1).
Example 2 Vector Listeners: Different Callbacks Extend the previous example by adding a third vector listener, B, which listens on subject BAR. B designates the same queue, Q1, but uses a new callback object, C2 to process its messages. In this situation, the dispatcher for Q1 must group messages on subject BAR separately from messages on subjects FOO and PHU. Suppose the Q1 contains 49 messages with subjects FOO or PHU, then 1 message with subject BAR, then 30 more messages with subjects FOO and PHU. Figure 9 shows this message queue. The dispatcher produces at least three separate events.
TIBCO Rendezvous C++ Reference 152 | Chapter 5 Events and Queues
Because messages 49 and 50 require different callbacks, the dispatcher must close the vector of FOO and PHU messages at message 49, and start a new vector for message 50 with subject BAR. When the dispatcher encounters message 51 with subject FOO again, it closes the BAR vector after only one message, and starts a third vector for FOO.
Figure 9 Grouping Messages into Vectors
Message Queue
FOO PHU FOO FOO BAR FOO PHU FOO ...... 1 2 48 49 50 51 52 80
Event A Event B Event C
Example 3 Vector Listeners: Mixing Vector and Ordinary Listeners Altering the previous example, suppose that B is an ordinary listener, instead of a vector listener. B necessarily specifies a different callback object than F and P (because ordinary listeners and vector listeners require different callback types with different signatures). The behavior of the dispatcher remains the same as in Example 2.
Dispatch Order Messages dispatch in the order that they arrive in the queue. However, the order vs. in which callbacks process messages can differ from dispatch order. The following Processing examples illustrate this possibility by contrasting three scenarios. Order Example 4 Vector Listeners: Deliberately Processing Out of Order The simplest callback (from the programmer’s perspective) processes the messages within a vector in order (that is, the order that dispatcher moves them from the queue into the vector, which mirrors the order in which the messages arrive in the queue). Nonetheless you could program a callback that processes messages in reverse order, or any other order (though one would need a convincing reason to do so).
TIBCO Rendezvous C++ Reference TibrvVectorListener::create() | 153
Example 5 Vector Listeners: Processing Message Vectors in a Single Dispatcher Thread Figure 10 shows a closer look at the situation of Example 2, in which several vector listeners all designate Q1 for their events. If a single thread dispatches Q1, then the callbacks are guaranteed to run in sequence. If the callbacks process messages in the order that they appear within the vectors, then message processing order is identical to dispatch order, which is also identical to arrival order. Figure 10 shows this effect.
Figure 10 Vector Listener Callbacks in a Single Dispatch Thread
Single Message Dispatch Thread
Msgs 1 - 49 Msgs 51 - 80
51 49 50
Example 6 Vector Listeners: Processing Message Vectors in Separate Threads However, if several threads dispatch Q1 in parallel, then the callbacks can run concurrently. In this situation, message processing order could differ dramatically from arrival order. Figure 11 shows this possibility.
Figure 11 Vector Listener Callbacks in Multiple Dispatch Threads
Thread A
Msgs 1 - 49
Thread B 49
50 Thread C
Msgs 51 - 80
51
TIBCO Rendezvous C++ Reference 154 | Chapter 5 Events and Queues
Although message number 49 dispatches (in event A) before message 50 (in event B), it is possible for the BAR callback (in thread B) to process message 50 before the FOO callback (in thread A) processes message 49. Furthermore, it is even possible for the FOO callback (in thread C) to process message 51 before the FOO callback (in thread A) processes message 49.
Before developing a program that processes inbound message vectors in several threads, consider carefully whether it is important (in the context of your application’s semantics) to process messages in order of arrival.
See Also TibrvVectorListener::getSubject() on page 155
TIBCO Rendezvous C++ Reference TibrvVectorListener::getSubject() | 155
TibrvVectorListener::getSubject() Method
Declaration TibrvStatus getSubject(const char*& subject) const;
Purpose Extract the subject from a vector listener event object.
Parameter Description subject The program supplies a variable. The method stores the subject of the vector listener event object in that variable.
Remarks Programs must not free nor modify the resulting subject string.
TIBCO Rendezvous C++ Reference 156 | Chapter 5 Events and Queues
TibrvVectorListener::getTransport() Method
Declaration TibrvTransport* getTransport() const;
Purpose Extract the transport from a vector listener event object.
TIBCO Rendezvous C++ Reference TibrvVectorCallback | 157
TibrvVectorCallback Class
Declaration class TibrvVectorCallback
Purpose Process inbound message vectors (vector listener events).
Remarks Implement this interface to process inbound message vectors.
Method Description Page
TibrvVectorCallback::onMsgs() Process inbound message vectors (vector listener 158 events).
Related Classes TibrvVectorListener on page 149
See Also TibrvVectorListener::create() on page 150
TIBCO Rendezvous C++ Reference 158 | Chapter 5 Events and Queues
TibrvVectorCallback::onMsgs() Method
Declaration virtual void onMsgs( TibrvMsg* mesages[], tibrv_u32 numMessages) = 0;
Purpose Process inbound message vectors (vector listener events).
Parameter Description messages This parameter receives an array of pointers to inbound messages.
numMessages This parameter receives the number of messages in the array.
Remarks Implement this method to process inbound message vectors. In the simplest arrangement, your callback method processes the messages in the array. When the callback method returns, the Rendezvous library deallocates the array. If your application requires a more complex processing arrangement, it can detach individual messages, and pass them to other threads for processing. (If your program detaches a message, then it must also explicitly destroy it.) It is illegal to pass the message array to a different thread for processing, or to use it as dynamically-allocated storage. Notice that in contrast to TibrvMsgCallback::onMsg(), this vector callback does not receive the listener event as an argument. You can use TibrvMsg::getEvent() to get it from the individual message objects.
See Also TibrvMsg::getEvent() on page 80 TibrvVectorListener::create() on page 150
TIBCO Rendezvous C++ Reference TibrvTimer | 159
TibrvTimer Class
Declaration class TibrvTimer : public TibrvEvent TibrvTimer(); // Construct empty. virtual ~TibrvTimer(); // Destroy and reclaim storage
Purpose Timer event.
Remarks All timers are repeating timers. To simulate a once-only timer, code the callback method to destroy the timer. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue of a timer automatically destroys the timer as well.
Activation and The method TibrvTimer::create() creates a C timer event object, and activates Dispatch the timer event—that is, it requests notification from the operating system when the timer’s interval elapses. When the interval elapses, Rendezvous software places the event object on its event queue. Dispatch removes the event object from the queue, and runs the callback method to process the timer event. When the callback method begins, Rendezvous software automatically reactivates the event, using the same interval. On dispatch Rendezvous software also determines whether the next interval has already elapsed, and requeues the timer event if appropriate. (To stop the cycle, destroy the event object; see TibrvEvent::destroy() on page 125.) Notice that time waiting in the event queue until dispatch can increase the effective interval of the timer. It is the programmer’s responsibility to ensure timely dispatch of events. Figure 12 illustrates a sequence of timer intervals. The number of elapsed timer intervals directly determines the number of event callbacks. At any moment the timer object appears on the event queue at most once—not several times as multiple copies. Nonetheless, Rendezvous software arranges for the appropriate number of timer event callbacks based the number of intervals that have elapsed since the timer became active or reset its interval. Destroying or invalidating the timer object immediately halts the sequence of timer events. The timer object ceases to queue new events, and an event already in the queue does not result in a callback. (However, callback methods that are already running in other threads continue to completion.) Resetting the timer interval immediately interrupts the sequence of timer events and begins a new sequence, counting the new interval from that moment. The reset operation is equivalent to destroying the timer and creating a new object in its place.
TIBCO Rendezvous C++ Reference 160 | Chapter 5 Events and Queues
Figure 12 Timer Activation and Dispatch
1. Activate timer.
Timer Timer Timer Interval Interval Interval
2. Interval elapses. Event Callback Function Waiting in Enter queue. Running Queue Event 3. Dispatch the event Callback Function Waiting in Running to its callback function. Queue
4. Interval elapses. Event Enter queue. Waiting in Queue 5. Dispatch the event to its callback function.
Timer Express the timer interval (in seconds) as a 64-bit floating point number. This Granularity representation allows microsecond granularity for intervals for over 100 years. The actual granularity of intervals depends on hardware and operating system constraints.
TIBCO Rendezvous C++ Reference TibrvTimer | 161
Zero as Interval Many programmers traditionally implement user events as timers with interval zero. Instead, we recommend implementing user events as messages on the intra-process transport. For more information, see Intra-Process Transport and User Events on page 93 in TIBCO Rendezvous Concepts.
Method Description Page
TibrvTimer::create() Start a timer. 162
TibrvTimer::getInterval() Extract the interval from a timer 163 event object.
TibrvTimer::resetInterval() Reset the interval of a timer event 164 object.
Inherited Methods
TibrvEvent::destroy() TibrvEvent::getClosure() TibrvEvent::getHandle() TibrvEvent::getType() TibrvEvent::getQueue() TibrvEvent::isValid() TibrvEvent::isListener() TibrvEvent::isTimer() TibrvEvent::isIOEvent()
Related Classes TibrvEvent on page 123
TIBCO Rendezvous C++ Reference 162 | Chapter 5 Events and Queues
TibrvTimer::create() Method
Declaration TibrvStatus create ( TibrvQueue* queue, TibrvCallback* callback, tibrv_f64 interval, const void* closure = NULL);
Purpose Start a timer.
Parameter Description queue At each time interval, place the event on this event queue.
callback On dispatch, process the event with this callback object. This object can be an instance of class TibrvTimerCallback, or its superclass TibrvCallback.
interval The timer triggers its callback method at this repeating interval (in seconds).
closure Store this closure data in the event object.
Remarks This method creates a C timer, activates it, and stores its handle in the C++ object.
Timer Express the timer interval (in seconds) as a 64-bit floating point number. This Granularity representation allows microsecond granularity for intervals for over 100 years. The actual granularity of intervals depends on hardware and operating system constraints.
Zero as Interval Many programmers traditionally implement user events as timers with interval zero. Instead, we recommend implementing user events as messages on the intra-process transport. For more information, see Intra-Process Transport and User Events on page 93 in TIBCO Rendezvous Concepts.
See Also Timer Event Semantics, page 76 in TIBCO Rendezvous Concepts TibrvEvent::destroy() on page 125 TibrvTimerCallback on page 165 TibrvTimerCallback::onTimer() on page 166
TIBCO Rendezvous C++ Reference TibrvTimer::getInterval() | 163
TibrvTimer::getInterval() Method
Declaration TibrvStatus getInterval (tibrv_f64& interval) const;
Purpose Extract the interval from a timer event object.
Parameter Description interval The program supplies a variable. The method stores the interval of the timer event object in that variable.
See Also TibrvTimer::resetInterval() on page 164
TIBCO Rendezvous C++ Reference 164 | Chapter 5 Events and Queues
TibrvTimer::resetInterval() Method
Declaration TibrvStatus resetInterval(tibrv_f64 newInterval);
Purpose Reset the interval of a timer event object.
Remarks The timer begins counting the new interval immediately.
Parameter Description newInterval The timer triggers its callback method at this new repeating interval (in seconds).
Timer Express the timer interval (in seconds) as a 64-bit floating point number. This Granularity representation allows microsecond granularity for intervals up to approximately 146 years. The actual granularity of intervals depends on hardware and operating system constraints.
Limit of This method can affect a timer only before or during its interval—but not after its Effectiveness interval has elapsed. This method neither examines, changes nor removes an event that is already waiting in a queue for dispatch. If the next event for the timer object is already in the queue, then that event remains in the queue, representing the old interval. The change takes effect with the subsequent interval. (To circumvent this limitation, a program can destroy the old timer object and replace it with a new one.)
TIBCO Rendezvous C++ Reference TibrvTimerCallback | 165
TibrvTimerCallback Class
Declaration class TibrvTimerCallback : public TibrvCallback
Purpose Process timer events.
Remarks Implement this interface to process timer events.
Method Description Page
TibrvTimerCallback::onTimer() Process timer events. 166
Related Classes TibrvCallback on page 135
See Also TibrvTimer::create() on page 162
TIBCO Rendezvous C++ Reference 166 | Chapter 5 Events and Queues
TibrvTimerCallback::onTimer() Method
Declaration virtual void onTimer(TibrvTimer* timer) = 0;
Purpose Process timer events.
Remarks Implement this method to process timer events.
Parameter Description timer This parameter receives the timer event.
TIBCO Rendezvous C++ Reference TibrvIOEvent | 167
TibrvIOEvent Class
Declaration class TibrvIOEvent : public TibrvEvent TibrvI0Event(); // Create empty. virtual ~TibrvI0Event(); // Destroy and reclaim storage.
Purpose I/O event.
Remarks The constructor creates a hollow object; TibrvIOEvent::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue of an I/O event automatically destroys the I/O event as well.
Activation and The method TibrvIOEvent::create() creates an event object that describes an Dispatch I/O situation, and activates the event—that is, it requests notification from the operating system when that I/O situation occurs. When the situation occurs, Rendezvous software deactivates the event, and places the event object on its event queue. Dispatch removes the event object from the queue, and runs the callback method to process the event. When the callback method returns, Rendezvous software automatically reactivates the event. (To stop the cycle, destroy the event object; see TibrvEvent::destroy() on page 125.) Figure 13 illustrates that Rendezvous software temporarily deactivates the I/O event from the time it enters the queue until its callback method returns. Consequently, an I/O object can cause at most one event at a time.
TIBCO Rendezvous C++ Reference 168 | Chapter 5 Events and Queues
Figure 13 I/O Event Activation and Dispatch
1. Activate I/O event. 3. Dispatch event to its callback function.
Event Callback I/O Event Waiting in Function Active Queue Running
2. I/O event occurs. 4. When the callback function returns, Deactivate event reactivate I/O event for the next cycle. and enter queue.
Event I/O Event Waiting in Active Queue
I/O event deactivated
Semantics of I/O The semantics of all I/O conditions depend on the underlying operating system Events and event manager. Rendezvous software does not change those semantics.
TIBCO Rendezvous C++ Reference TibrvIOEvent | 169
I/O events trigger when the operating system reports that an I/O condition on a monitored socket would succeed (that is, transfer at least one byte without blocking). Nonetheless, Rendezvous software cannot guarantee that a subsequent I/O call will not block.
Method Description Page
TibrvIOEvent::create() Wait for specified I/O situations 170 to occur.
TibrvIOEvent::getIOSource() Extract the source (socket ID) 171 from an I/O event object.
TibrvIOEvent::getIOType() Extract the I/O type from an I/O 172 event object.
Inherited Methods
TibrvEvent::destroy() TibrvEvent::getClosure() TibrvEvent::getHandle() TibrvEvent::getType() TibrvEvent::getQueue() TibrvEvent::isValid() TibrvEvent::isListener() TibrvEvent::isTimer() TibrvEvent::isIOEvent()
Related Classes TibrvEvent on page 123
See Also TibrvIOCallback on page 173
TIBCO Rendezvous C++ Reference 170 | Chapter 5 Events and Queues
TibrvIOEvent::create() Method
Declaration TibrvStatus create ( TibrvQueue* queue, TibrvCallback* callback, tibrv_i32 socketId, tibrvIOType ioType, const void* closure = NULL);
Purpose Wait for specified I/O situations to occur.
Parameter Description queue At each time interval, place the event on this event queue.
callback On dispatch, process the event with this callback object. This object can be an instance of class TibrvIOCallback, or its superclass TibrvCallback.
socketID Wait for I/O occurrences on this socket.
ioType Wait for I/O occurrences of this type.
See tibrvIOType on page 162 in TIBCO Rendezvous C Reference.
closure Store this closure data in the event object.
Remarks This method creates a C I/O event and stores its handle in the C++ object. All timers are repeating timers. To simulate a once-only timer, code the callback method to destroy the timer.
See Also TibrvEvent::destroy() on page 125 TibrvTimerCallback on page 165 TibrvTimerCallback::onTimer() on page 166 I/O Event Semantics, page 74 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvIOEvent::getIOSource() | 171
TibrvIOEvent::getIOSource() Method
Declaration TibrvStatus getIOSource (tibrv_i32& ioSource) const;
Purpose Extract the source (socket ID) from an I/O event object.
Parameter Description source The program supplies a variable. The method stores the source of the I/O event object in that variable.
See Also TibrvIOEvent::create() on page 170
TIBCO Rendezvous C++ Reference 172 | Chapter 5 Events and Queues
TibrvIOEvent::getIOType() Method
Declaration TibrvStatus getIOType (tibrvIOType& ioType)) const;
Purpose Extract the I/O type from an I/O event object.
Parameter Description ioType The program supplies a variable. The method stores the source of the I/O event object in that variable.
See tibrvIOType on page 162 in TIBCO Rendezvous C Reference.
See Also TibrvIOEvent::create() on page 170
TIBCO Rendezvous C++ Reference TibrvIOCallback | 173
TibrvIOCallback Class
Declaration class TibrvIOCallback : public TibrvCallback
Purpose Process I/O events.
Remarks Implement this interface to process I/O events.
Method Description Page
TibrvIOCallback::onIOEvent() Process I/O events. 174
Related Classes TibrvCallback on page 135
See Also TibrvIOEvent on page 167
TIBCO Rendezvous C++ Reference 174 | Chapter 5 Events and Queues
TibrvIOCallback::onIOEvent() Method
Declaration virtual void onIOEvent(TibrvIOEvent* ioEvent) = 0;
Purpose Process I/O events.
Remarks Implement this method to process I/O events.
Parameter Description ioEvent This parameter receives the I/O event.
TIBCO Rendezvous C++ Reference TibrvDispatchable | 175
TibrvDispatchable Class
Declaration class TibrvDispatchable
Purpose Common interface for queues and queue groups.
Remarks Programs never instantiate this class. Both TibrvQueue and TibrvQueueGroup implement this interface, so programs can call the common methods on objects of either class. For example, consider a dispatcher routine that receives an object of type TibrvDispatchable; it can call the dispatch() method, without needing to determine whether the object is queue or a queue group.
Method Description Page Life Cycle
TibrvDispatchable::destroy() Destroy a queue or queue group. 176
TibrvDispatchable::getDispatchable() Extract the C handle of a queue or queue 178 group.
TibrvDispatchable::isValid() Test validity of a queue or queue group. 179
Dispatch
TibrvDispatchable::dispatch() Dispatch an event; if no event is ready, 177 block.
TibrvDispatchable::poll() Dispatch an event, if possible. 180
TibrvDispatchable::timedDispatch() Dispatch an event, but if no event is ready 181 to dispatch, limit the time that this call blocks while waiting for an event.
Descendants TibrvQueue on page 182 TibrvQueueGroup on page 201
See Also TibrvQueue on page 182 TibrvQueueGroup on page 201
TIBCO Rendezvous C++ Reference 176 | Chapter 5 Events and Queues
TibrvDispatchable::destroy() Method
Declaration virtual TibrvStatus destroy () = 0;
Purpose Destroy a queue or queue group.
Remarks When a queue is destroyed, events that remain in the queue are discarded. When a queue group is destroyed, the individual queues in the group continue to exist, even though the group has been destroyed.
See Also TibrvQueue::destroy() on page 186 TibrvQueueGroup::destroy() on page 205
TIBCO Rendezvous C++ Reference TibrvDispatchable::dispatch() | 177
TibrvDispatchable::dispatch() Method
Declaration virtual TibrvStatus dispatch () = 0;
Purpose Dispatch an event; if no event is ready, block.
Remarks If an event is ready to dispatch, then this call dispatches it, and then returns. If no events are waiting, then this call blocks indefinitely while waiting for the object to receive an event. Both TibrvQueue and TibrvQueueGroup implement this method.
See Also TibrvDispatchable on page 175 TibrvQueue::dispatch() on page 187 TibrvQueueGroup::dispatch() on page 206
TIBCO Rendezvous C++ Reference 178 | Chapter 5 Events and Queues
TibrvDispatchable::getDispatchable() Method
Declaration virtual tibrvDispatchable getDispatchable() const = 0;
Purpose Extract the C handle of a queue or queue group.
Remarks If the event is invalid, this method returns the constant TIBRV_INVALID_ID.
TIBCO Rendezvous C++ Reference TibrvDispatchable::isValid() | 179
TibrvDispatchable::isValid() Method
Declaration virtual tibrv_bool isValid () const = 0;
Purpose Test validity of a queue or queue group.
Remarks Returns TIBRV_TRUE if the dispatchable object is valid; TIBRV_FALSE if the dispatchable object has been destroyed.
TIBCO Rendezvous C++ Reference 180 | Chapter 5 Events and Queues
TibrvDispatchable::poll() Method
Declaration virtual TibrvStatus poll();
Purpose Dispatch an event, if possible.
Remarks If an event is ready to dispatch, then this call dispatches it, and then returns. If no events are waiting, then this call returns immediately. When the call dispatches an event, it returns TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT. This call is equivalent to timedDispatch(0). Both TibrvQueue and TibrvQueueGroup implement this method.
See Also TibrvDispatchable on page 175 TibrvQueue::poll() on page 194 TibrvQueueGroup::poll() on page 209
TIBCO Rendezvous C++ Reference TibrvDispatchable::timedDispatch() | 181
TibrvDispatchable::timedDispatch() Method
Declaration virtual TibrvStatus timedDispatch(tibrv_f64 timeout) = 0;
Purpose Dispatch an event, but if no event is ready to dispatch, limit the time that this call blocks while waiting for an event.
Remarks If an event is ready to dispatch, then this call dispatches it, and then returns. If no events are waiting, this call waits for an event to arrive. If an event arrives before the waiting time elapses, then it dispatches the event and returns. If the waiting time elapses first, then the call returns without dispatching an event. When the call dispatches an event, it returns the status code TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT. Both TibrvQueue and TibrvQueueGroup implement this method.
Parameter Description timeout Maximum time (in seconds) that this call can block while waiting for an event to arrive. TIBRV_NO_WAIT (zero) indicates no blocking (immediate timeout). TIBRV_WAIT_FOREVER (-1) indicates no timeout.
See Also TibrvDispatchable on page 175 TibrvQueue::timedDispatch() on page 198 TibrvQueueGroup::timedDispatch() on page 211
TIBCO Rendezvous C++ Reference 182 | Chapter 5 Events and Queues
TibrvQueue Class
Declaration class TibrvQueue : TibrvDispatchable TibrvQueue(); // Construct empty. virtual ~TibrvQueue(); // Destroy and reclaim storage.
Purpose Event queue.
Remarks Each event is associated with a TibrvQueue object; when the event occurs, Rendezvous software places the event object in its queue. Programs dispatch queues to process events. The constructor produces a hollow object; TibrvQueue::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed.
Default Queue The method Tibrv::defaultQueue() returns a pre-defined queue. Programs that need only one event queue can use this default queue (instead of using TibrvQueue::create() to create one). The default queue has priority 1, can hold an unlimited number of events, and never discards an event (since it never exceeds an event limit). Rendezvous software places all advisories pertaining to queue overflow on the default queue. Programs must not destroy the default queue, except as a side effect of Tibrv::close(). Programs cannot change the parameters of the default queue.
Limit Policy These constants specify the possible strategies for resolving overflow of queue limit.
(Sheet 1 of 2) Constant Description TIBRVQUEUE_DISCARD_NONE Never discard events; use this policy when a queue has no limit on then number of events it can contain.
TIBRVQUEUE_DISCARD_FIRST Discard the first event in the queue (that is, the oldest event in the queue, which would otherwise be the next event to dispatch).
TIBRVQUEUE_DISCARD_LAST Discard the last event in the queue (that is, the youngest event in the queue).
TIBCO Rendezvous C++ Reference TibrvQueue | 183
(Sheet 2 of 2) Constant Description TIBRVQUEUE_DISCARD_NEW Discard the new event (which would otherwise cause the queue to overflow its maximum events limit).
Method Description Page Life Cycle
TibrvQueue::create() Create an event queue. 185
TibrvQueue::destroy() Destroy an event queue. 186
TibrvQueue::getHandle() Extract the C handle of this queue. 189
TibrvQueue::isValid() Test validity of a queue. 193
Dispatch
TibrvQueue::dispatch() Dispatch an event; if no event is ready, block. 187
TibrvQueue::poll() Dispatch an event, if possible. 194
TibrvQueue::timedDispatch() Dispatch an event, but if no event is ready to 198 dispatch, limit the time that this call blocks while waiting for an event.
Properties
TibrvQueue::getCount() Extract the number of events in a queue. 188
TibrvQueue::getLimitPolicy() Extract the limit properties of a queue. 190
TibrvQueue::getName() Extract the name of a queue. 191
TibrvQueue::getPriority() Extract the priority of a queue. 192
TibrvQueue::setName() Set the name of a queue. 196
TibrvQueue::setLimitPolicy() Set the limit properties of a queue. 195
TibrvQueue::setPriority() Set the priority of a queue. 197
TIBCO Rendezvous C++ Reference 184 | Chapter 5 Events and Queues
Inherited Methods
TibrvDispatchable::getDispatchable() TibrvDispatchable::destroy() TibrvDispatchable::dispatch() TibrvDispatchable::isValid() TibrvDispatchable::poll() TibrvDispatchable::timedDispatch()
Related Classes TibrvDispatchable on page 175 TibrvQueueGroup on page 201
TIBCO Rendezvous C++ Reference TibrvQueue::create() | 185
TibrvQueue::create() Method
Declaration TibrvStatus create ();
Purpose Create an event queue.
Remarks This method creates a C queue and stores its handle in the C++ object. Upon creation, new queues use these default values for properties.
Property Default Value Set Method
limitPolicy TIBRVQUEUE_DISCARD_NONE TibrvQueue::setLimitPolicy() on page 195 maxEvents zero (unlimited)
discardAmount zero
name tibrvQueue TibrvQueue::setName() on page 196
priority 1 TibrvQueue::setPriority() on page 197
TIBCO Rendezvous C++ Reference 186 | Chapter 5 Events and Queues
TibrvQueue::destroy() Method
Declaration TibrvStatus destroy ();
TibrvStatus destroy ( TibrvQueueOnComplete* completeCB, const void* closure = NULL);
Purpose Destroy an event queue.
Remarks When a queue is destroyed, events that remain in the queue are discarded. The destructor calls this method. When a program destroys a queue, all events associated with the queue become invalid. These invalid events still occupy storage until the program explicitly destroys them, or until the program calls Tibrv::close(). A program must not call TibrvQueue::destroy() on the default queue. Closing Tibrv destroys the default queue; see Tibrv::close() on page 19.
Parameter Description completeCB Rendezvous software runs this method immediately after all event callback methods dispatched from the queue have completed. If no event callback methods are running when the queue is destroyed, the destroy call runs the completion method before returning. If this parameter is NULL, this method does not run a completion.
closure Pass this closure argument to the completion method.
TIBCO Rendezvous C++ Reference TibrvQueue::dispatch() | 187
TibrvQueue::dispatch() Method
Declaration virtual TibrvStatus dispatch ();
Purpose Dispatch an event; if no event is ready, block.
Remarks If the queue is not empty, then this call dispatches the event at the head of the queue, and then returns. If the queue is empty, then this call blocks indefinitely while waiting for the queue to receive an event.
See Also TibrvDispatchable on page 175 TibrvDispatchable::dispatch() on page 177 TibrvQueue::poll() on page 194 TibrvQueue::timedDispatch() on page 198 TibrvDispatcher on page 212
TIBCO Rendezvous C++ Reference 188 | Chapter 5 Events and Queues
TibrvQueue::getCount() Method
Declaration TibrvStatus getCount (tibrv_u32& numEvents) const;
Purpose Extract the number of events in a queue.
Parameter Description numEvents The program supplies a variable, and the method stores (a snapshot of) the event count of the queue in that variable.
TIBCO Rendezvous C++ Reference TibrvQueue::getHandle() | 189
TibrvQueue::getHandle() Method
Declaration tibrvQueue getHandle() const;
Purpose Extract the C handle of this queue.
TIBCO Rendezvous C++ Reference 190 | Chapter 5 Events and Queues
TibrvQueue::getLimitPolicy() Method
Declaration TibrvStatus getLimitPolicy ( tibrvQueueLimitPolicy& policy, tibrv_u32& maxEvents, tibrv_u32& discardAmount) const;
Purpose Extract the limit properties of a queue.
Parameter Description policy Each queue has a policy for discarding events when a new event would cause the queue to exceed its maxEvents limit. For an explanation of the policy values, see Limit Policy on page 182. The program supplies a variable, and the method stores the limit policy of the queue in that variable.
maxEvents Programs can limit the number of events that a queue can hold—either to curb queue growth, or implement a specialized dispatch semantics. Zero specifies an unlimited number of events. The program supplies a variable, and the method stores the maximum event limit of the queue in that variable.
discardAmount When the queue exceeds its maximum event limit, discard a block of events. This property specifies the number of events to discard. The program supplies a variable, and the method stores the discard amount of the queue in that variable.
See Also tibrvQueueLimitPolicy on page 170 in TIBCO Rendezvous C Reference TibrvQueue::setLimitPolicy() on page 195 QUEUE.LIMIT_EXCEEDED on page 258 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvQueue::getName() | 191
TibrvQueue::getName() Method
Declaration TibrvStatus getName (const char*& queueName) const;
Purpose Extract the name of a queue.
Remarks Queue names assist programmers and administrators in troubleshooting queues. When Rendezvous software delivers an advisory message pertaining to a queue, it includes the queue’s name; administrators can use queue names to identify specific queues within a program. The default name of every queue is tibrvQueue. We strongly recommend that you relabel each queue with a distinct and informative name, for use in debugging.
Parameter Description queueName The program supplies a variable, and the method stores in that variable a string pointer to the queue name. The program must not modify the string.
See Also TibrvQueue::setName() on page 196
TIBCO Rendezvous C++ Reference 192 | Chapter 5 Events and Queues
TibrvQueue::getPriority() Method
Declaration TibrvStatus getPriority (tibrv_u32& priority) const;
Purpose Extract the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence within queue groups. Higher values dispatch before lower values; queues with equal priority values dispatch in round-robin fashion. When the queue is invalid, this method returns TIBRV_INVALID_QUEUE.
See Also TibrvQueue::setPriority() on page 197
TIBCO Rendezvous C++ Reference TibrvQueue::isValid() | 193
TibrvQueue::isValid() Method
Declaration tibrv_bool isValid () const;
Purpose Test validity of a queue.
Remarks Returns TIBRV_TRUE if the queue is valid; TIBRV_FALSE if the queue has been destroyed.
See Also Tibrv::close() on page 19 TibrvQueue::destroy() on page 186
TIBCO Rendezvous C++ Reference 194 | Chapter 5 Events and Queues
TibrvQueue::poll() Method
Declaration virtual TibrvStatus poll ();
Purpose Dispatch an event, if possible.
Remarks If the queue is not empty, then this call dispatches the event at the head of the queue, and then returns. If the queue is empty, then this call returns immediately. When the call dispatches an event, it returns the status code TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT. This call is equivalent to timedDispatch(0).
See Also TibrvDispatchable on page 175 TibrvDispatchable::poll() on page 180 TibrvQueue::dispatch() on page 187 TibrvQueue::timedDispatch() on page 198
TIBCO Rendezvous C++ Reference TibrvQueue::setLimitPolicy() | 195
TibrvQueue::setLimitPolicy() Method
Declaration TibrvStatus setLimitPolicy ( tibrvQueueLimitPolicy policy, tibrv_u32 maxEvents, tibrv_u32 discardAmount);
Purpose Set the limit properties of a queue.
Remarks This method simultaneously sets three related properties, which together describe the behavior of a queue in overflow situations. Each call must explicitly specify all three properties.
Parameter Description limitPolicy Each queue has a policy for discarding events when a new event would cause the queue to exceed its maxEvents limit. Choose from the values of tibrvQueueLimitPolicy. When maxEvents is zero (unlimited), the policy must be TIBRVQUEUE_DISCARD_NONE. The program supplies a value, and the method sets the limit policy of the queue to that value.
maxEvents Programs can limit the number of events that a queue can hold—either to curb queue growth, or implement a specialized dispatch semantics. Zero specifies an unlimited number of events; in this case, the policy must be TIBRVQUEUE_DISCARD_NONE. The program supplies a value, and the method sets the maximum event limit of the queue to that value.
discardAmount When the queue exceeds its maximum event limit, discard a block of events. This property specifies the number of events to discard. When discardAmount is zero, the policy must be TIBRVQUEUE_DISCARD_NONE. The program supplies a value, and the method sets the discard amount of the queue to that value.
See Also TibrvQueue::getLimitPolicy() on page 190
TIBCO Rendezvous C++ Reference 196 | Chapter 5 Events and Queues
TibrvQueue::setName() Method
Declaration TibrvStatus setName (const char* queueName);
Purpose Set the name of a queue.
Remarks Queue names assist programmers and administrators in troubleshooting queues. When Rendezvous software delivers an advisory message pertaining to a queue, it includes the queue’s name; administrators can use queue names to identify specific queues within a program. The default name of every queue is tibrvQueue. We strongly recommend that you relabel each queue with a distinct and informative name, for use in debugging.
Parameter Description queueName Replace the name of the queue with this new name. It is illegal to supply NULL as the new queue name.
See Also TibrvQueue::getName() on page 191
TIBCO Rendezvous C++ Reference TibrvQueue::setPriority() | 197
TibrvQueue::setPriority() Method
Declaration TibrvStatus setPriority(tibrv_u32 priority);
Purpose Set the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence within queue groups. Higher values dispatch before lower values; queues with equal priority values dispatch in round-robin fashion. Changing the priority of a queue affects its position in all the queue groups that contain it.
Parameter Description priority Replace the priority of the queue with this new value. The priority is a non-negative integer. Priority zero signifies the last queue to dispatch.
See Also TibrvQueue::getPriority() on page 192
TIBCO Rendezvous C++ Reference 198 | Chapter 5 Events and Queues
TibrvQueue::timedDispatch() Method
Declaration virtual TibrvStatus timedDispatch(tibrv_f64 timeout);
Purpose Dispatch an event, but if no event is ready to dispatch, limit the time that this call blocks while waiting for an event.
Remarks If an event is already in the queue, this call dispatches it, and returns immediately. If the queue is empty, this call waits for an event to arrive. If an event arrives before the waiting time elapses, then it dispatches the event and returns. If the waiting time elapses first, then the call returns without dispatching an event. When the call dispatches an event, it returns the status code TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.
Parameter Description timeout Maximum time (in seconds) that this call can block while waiting for an event to arrive in the queue. TIBRV_NO_WAIT (zero) indicates no blocking (immediate timeout). TIBRV_WAIT_FOREVER (-1) indicates no timeout.
See Also TibrvDispatchable on page 175 TibrvDispatchable::timedDispatch() on page 181 TibrvQueue::dispatch() on page 187 TibrvQueue::poll() on page 194
TIBCO Rendezvous C++ Reference TibrvQueueOnComplete | 199
TibrvQueueOnComplete Class
Declaration class TibrvQueueOnComplete
Purpose Run program code after all callback methods of a destroyed queue have completed.
Remarks Implement this interface to post-process destroyed queues.
Method Description Page
TibrvQueueOnComplete::onComplete() A program can destroy a queue object even 200 when callback methods from its events are running in one or more threads. Multi-threaded programs can define methods of this type to discover when all event callback methods in progress have completed.
TIBCO Rendezvous C++ Reference 200 | Chapter 5 Events and Queues
TibrvQueueOnComplete::onComplete() Method
Declaration virtual void onComplete( TibrvQueue* queue, void* closure)
Purpose A program can destroy a queue object even when callback methods from its events are running in one or more threads. Multi-threaded programs can define methods of this type to discover when all event callback methods in progress have completed.
Parameter Description queue This parameter receives the queue object. However, by the time this method runs, the queue is already destroyed; this method cannot use the queue object in Rendezvous calls.
closure This parameter receives the closure object that the program supplied in the destroy call.
Remarks This method is important when several threads dispatch from the same queue, and the program must do additional processing after the callback methods have completed in all threads. Upon return from TibrvQueue::destroy(), the destroyed queue can no longer dispatch events. However, in each thread where an event callback method is already in progress, that callback method does continue to run until complete. TibrvQueue::destroy() accepts an argument of type TibrvQueueOnComplete. Rendezvous software ensures that the completion method runs when the last callback-in-progress has completed.
See Also TibrvQueue::destroy() on page 186
TIBCO Rendezvous C++ Reference TibrvQueueGroup | 201
TibrvQueueGroup Class
Declaration class TibrvQueueGroup : public TibrvDispatchable TibrvQueueGroup(); // Create empty. virtual ~TibrvQueueGroup(); // Destroy and reclaim storage.
Purpose Prioritized dispatch of several queues with one call.
Remarks Queue groups add flexibility and fine-grained control to the event queue dispatch mechanism. Programs can create groups of queues and dispatch them according to their queue priorities. The constructor creates a hollow object; TibrvQueueGroup::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed.
(Sheet 1 of 2) Method Description Page Life Cycle
TibrvQueueGroup::create() Create an event queue group. 204
TibrvQueueGroup::destroy() Destroy an event queue group. 205
TibrvQueueGroup::getHandle() Extract the C handle of this queue group. 207
TibrvQueueGroup::isValid() Test validity of a queue group. 208
Dispatch
TibrvQueueGroup::dispatch() Dispatch an event from a queue group; if no 206 event is ready, block.
TibrvQueueGroup::poll() Dispatch an event, but if no event is ready to 209 dispatch, return immediately (without blocking).
TibrvQueueGroup::timedDispatch() Dispatch an event, but if no event is ready to 211 dispatch, limit the time that this call blocks while waiting for an event.
Queues
TibrvQueueGroup::add() Add an event queue to a queue group. 203
TIBCO Rendezvous C++ Reference 202 | Chapter 5 Events and Queues
(Sheet 2 of 2) Method Description Page
TibrvQueueGroup::remove() Remove an event queue from a queue group. 210
Inherited Methods
TibrvDispatchable::getDispatchable() TibrvDispatchable::destroy() TibrvDispatchable::dispatch() TibrvDispatchable::isValid() TibrvDispatchable::poll() TibrvDispatchable::timedDispatch()
Related Classes TibrvDispatchable on page 175 TibrvQueue on page 182
TIBCO Rendezvous C++ Reference TibrvQueueGroup::add() | 203
TibrvQueueGroup::add() Method
Declaration virtual TibrvStatus add( TibrvQueue* queue);
Purpose Add an event queue to a queue group.
Remarks If the queue is already in the group, adding it again has no effect.
Parameter Description eventQueue Add this event queue to a queue group.
See Also TibrvQueue on page 182
TIBCO Rendezvous C++ Reference 204 | Chapter 5 Events and Queues
TibrvQueueGroup::create() Method
Declaration TibrvStatus create();
Purpose Create an event queue group.
Remarks This method creates a C queue group and stores its handle in the C++ object. The new queue group is empty. The queue group remains valid until the program explicitly destroys it.
See Also TibrvQueueGroup::add() on page 203 TibrvQueueGroup::destroy() on page 205
TIBCO Rendezvous C++ Reference TibrvQueueGroup::destroy() | 205
TibrvQueueGroup::destroy() Method
Declaration TibrvStatus destroy ();
Purpose Destroy an event queue group.
Remarks The individual queues in the group continue to exist, even though the group has been destroyed.
See Also TibrvQueueGroup::create() on page 204
TIBCO Rendezvous C++ Reference 206 | Chapter 5 Events and Queues
TibrvQueueGroup::dispatch() Method
Declaration virtual TibrvStatus dispatch();
Purpose Dispatch an event from a queue group; if no event is ready, block.
Remarks If any queue in the group contains an event, then this call searches the queues in priority order, dispatches an event from the first non-empty queue that it finds, and then returns. If all the queues are empty, then this call blocks indefinitely while waiting for any queue in the group to receive an event. When searching the group for a non-empty queue, this call searches according to the priority values of the queues. If two or more queues have identical priorities, subsequent dispatch and poll calls rotate through them in round-robin fashion.
See Also TibrvDispatchable on page 175 TibrvDispatchable::dispatch() on page 177 TibrvQueueGroup::timedDispatch() on page 211 TibrvQueueGroup::poll() on page 209
TIBCO Rendezvous C++ Reference TibrvQueueGroup::getHandle() | 207
TibrvQueueGroup::getHandle() Method
Declaration tibrvQueueGroup getHandle() const;
Purpose Extract the C handle of this queue group.
TIBCO Rendezvous C++ Reference 208 | Chapter 5 Events and Queues
TibrvQueueGroup::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test validity of a queue group.
Remarks Returns TIBRV_TRUE if the queue group is valid; TIBRV_FALSE if the queue group has been destroyed.
See Also Tibrv::close() on page 19 TibrvQueueGroup::destroy() on page 205
TIBCO Rendezvous C++ Reference TibrvQueueGroup::poll() | 209
TibrvQueueGroup::poll() Method
Declaration virtual TibrvStatus poll();
Purpose Dispatch an event, but if no event is ready to dispatch, return immediately (without blocking).
Remarks If any queue in the group contains an event, then this call searches the queues in priority order, dispatches an event from the first non-empty queue that it finds, and then returns. If all the queues are empty, then this call returns immediately. When searching the group for a non-empty queue, this call searches according to the priority values of the queues. If two or more queues have identical priorities, subsequent dispatch and poll calls rotate through them in round-robin fashion. When the call dispatches an event, it returns the status code TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT. This call is equivalent to timedDispatch(0).
See Also TibrvDispatchable on page 175 TibrvDispatchable::poll() on page 180 TibrvQueueGroup::dispatch() on page 206 TibrvQueueGroup::timedDispatch() on page 211
TIBCO Rendezvous C++ Reference 210 | Chapter 5 Events and Queues
TibrvQueueGroup::remove() Method
Declaration virtual TibrvStatus remove(TibrvQueue* queue);
Purpose Remove an event queue from a queue group.
Remarks If the queue is not in the group, this call returns the status code TIBRV_INVALID_QUEUE.
Parameter Description eventQueue Remove this event queue from a queue group.
See Also TibrvQueue on page 182
TIBCO Rendezvous C++ Reference TibrvQueueGroup::timedDispatch() | 211
TibrvQueueGroup::timedDispatch() Method
Declaration virtual TibrvStatus timedDispatch(tibrv_f64 timeout);
Purpose Dispatch an event, but if no event is ready to dispatch, limit the time that this call blocks while waiting for an event.
Remarks If any queue in the group contains an event, then this call searches the queues in priority order, dispatches an event from the first non-empty queue that it finds, and then returns. If the queue is empty, this call waits for an event to arrive in any queue. If an event arrives before the waiting time elapses, then the call searches the queues, dispatches the event, and returns. If the waiting time elapses first, then the call returns without dispatching an event. When searching the group for a non-empty queue, this call searches according to the priority values of the queues. If two or more queues have identical priorities, subsequent dispatch calls rotate through them in round-robin fashion. When the call dispatches an event, it returns the status code TIBRV_OK. When the call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.
Parameter Description timeout Maximum time (in seconds) that this call can block while waiting for an event to arrive in the queue group. TIBRV_NO_WAIT (zero) indicates no blocking (immediate timeout). TIBRV_WAIT_FOREVER (-1) indicates no timeout.
See Also TibrvDispatchable on page 175 TibrvDispatchable::timedDispatch() on page 181 TibrvQueueGroup::dispatch() on page 206 TibrvQueueGroup::poll() on page 209
TIBCO Rendezvous C++ Reference 212 | Chapter 5 Events and Queues
TibrvDispatcher Class
Declaration class TibrvDispatcher TibrvDispatcher(); // Create empty. virtual ~TibrvDispatcher(); // Halt, destroy & reclaim storage.
Purpose Dispatch events from a queue or queue group.
Remarks A dispatcher thread repeatedly dispatches a queue or queue group by calling TibrvDispatchable::timedDispatch() in a loop. The constructor produces a hollow object; TibrvDispatcher::create() fills in the C handle, which makes the dispatcher thread operational. The destructor calls the destroy method, unless the C handle is already destroyed. This class is a programming convenience. Programs can implement specialized dispatcher threads, and use them instead of this class.
Method Description Page
TibrvDispatcher::create() Start a dispatcher thread. 213
TibrvDispatcher::destroy() Destroy a dispatcher thread. 214
TibrvDispatcher::getDispatchable() Extract the queue or queue group that this 215 thread dispatches.
TibrvDispatcher::getHandle() Extract the C handle of this dispatcher thread. 216
TibrvDispatcher::getName() Extract the name of a dispatcher thread. 217
TibrvDispatcher::isValid() Test whether a dispatcher object has been 218 destroyed.
TibrvDispatcher::setName() Set the name of a dispatcher thread. 219
See Also TibrvDispatchable::timedDispatch() on page 181 DISPATCHER.THREAD_EXITED on page 252 in TIBCO Rendezvous Concepts tibrvDispatcher on page 201 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvDispatcher::create() | 213
TibrvDispatcher::create() Method
Declaration TibrvStatus create( TibrvDispatchable* dispatchable, tibrv_f64 idleTimeout = TIBRV_WAIT_FOREVER);
Purpose Start a dispatcher thread.
Remarks This method creates a C dispatcher thread and stores its handle in the C++ object. A dispatcher thread repeatedly dispatches a queue or queue group. Inside the thread, a loop calls TibrvDispatchable::timedDispatch(). If the timed dispatch call returns without dispatching an event (after waiting for idleTimeout seconds), then the thread exits by calling TibrvDispatcher::destroy().
Parameter Description dispatchable The new thread dispatches this object, which can be either a queue or a queue group.
idleTimeout When this time period (in seconds) elapses without dispatching an event, the thread exits. The special value TIBRV_WAIT_FOREVER instructs the dispatcher to loop indefinitely; the thread does not exit until the program explicitly destroys it. The special value TIBRV_NO_WAIT instructs the dispatcher to poll until no events are ready to dispatch, then exit.
Stack Size On UNIX platforms that use the POSIX thread package (pthread), this call sets the stacksize attribute of the dispatcher thread to the larger of two candidate values—either the default stack size of the operating system, or 64 kilobytes. For programs that require a larger stack size, we recommend that you code a custom dispatcher thread.
See Also TibrvDispatchable::timedDispatch() TibrvDispatchable on page 175 TibrvDispatcher::destroy() on page 214 TibrvDispatcher::setName() on page 219 DISPATCHER.THREAD_EXITED on page 252 in TIBCO Rendezvous Concepts tibrvDispatcher on page 201 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference 214 | Chapter 5 Events and Queues
TibrvDispatcher::destroy() Method
Declaration TibrvStatus destroy();
Purpose Destroy a dispatcher thread.
Remarks We do not recommend destroying a dispatcher thread within the same thread (for example, from within a listener callback function running within that thread). Although it is legal to do so, we discourage this practice, because some operating systems do not properly free internal resources associated with the thread (which can result in memory growth).
See Also DISPATCHER.THREAD_EXITED on page 252 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvDispatcher::getDispatchable() | 215
TibrvDispatcher::getDispatchable() Method
Declaration TibrvDispatchable* getDispatchable() const;
Purpose Extract the queue or queue group that this thread dispatches.
TIBCO Rendezvous C++ Reference 216 | Chapter 5 Events and Queues
TibrvDispatcher::getHandle() Method
Declaration tibrvDispatcher getHandle() const;
Purpose Extract the C handle of this dispatcher thread.
TIBCO Rendezvous C++ Reference TibrvDispatcher::getName() | 217
TibrvDispatcher::getName() Method
Declaration TibrvStatus getName( const char*& name) const;
Purpose Extract the name of a dispatcher thread.
Parameter Description dispatchName The program supplies a variable, and the method stores the name of the dispatcher thread in that variable.
TIBCO Rendezvous C++ Reference 218 | Chapter 5 Events and Queues
TibrvDispatcher::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test whether a dispatcher object has been destroyed.
Remarks This method returns TIBRV_TRUE if the dispatcher object is valid, and TIBRV_FALSE if it has been destroyed.
TIBCO Rendezvous C++ Reference TibrvDispatcher::setName() | 219
TibrvDispatcher::setName() Method
Declaration TibrvStatus setName (const char* dispatchName);
Purpose Set the name of a dispatcher thread.
Parameter Description dispatchName Use this name as the name of the dispatcher thread.
TIBCO Rendezvous C++ Reference 220 | Chapter 5 Events and Queues
TIBCO Rendezvous C++ Reference | 221
Chapter 6 Transports
Transports manage network connections and send outbound messages. This chapter presents the various transport classes and their methods.
Topics
• TibrvTransport, page 222 • tibrvTransportBatchMode, page 237 • TibrvProcessTransport, page 238 • TibrvNetTransport, page 239
See Also TibrvCmTransport on page 305 TibrvCmQueueTransport on page 354
TIBCO Rendezvous C++ Reference 222 | Chapter 6 Transports
TibrvTransport Class
Declaration class TibrvTransport virtual ~TibrvTransport(); // Destroy and reclaim storage.
Purpose A transport object represents a delivery mechanism for messages.
Remarks A transport describes a carrier for messages—whether across a network, among processes on a single computer, or within a process. Transports manage network connections, and send outbound messages. A transport also defines the delivery scope of a message—that is, the set of possible destinations for the messages it sends. Destroying a transport object invalidates subsequent send calls on that transport, and invalidates any listeners using that transport. The destructor calls the destroy method, unless the C object is already destroyed. This class is the superclass of all other transport classes. Methods defined by this class are implemented by all transport subclasses (except TibrvCmQueueTransport, for which some methods do not apply).
Intra-Process Each process has exactly one intra-process transport; the call Tibrv::open() Transport automatically creates it, and the call Tibrv::processTransport() extracts it. Programs must not destroy the intra-process transport.
(Sheet 1 of 2) Method Description Page
TibrvTransport::createInbox() Create a unique inbox subject name. 224
TibrvTransport::destroy() Destroy a transport. 226
TibrvTransport::isValid() Test validity of a transport. 229
TibrvTransport::getDescription() Extract the program description parameter 227 from a transport.
TibrvTransport::getHandle() Extract the C handle of this transport object. 228
TibrvTransport::requestReliability() Request reliability interval (message 230 retention time) for a service.
TibrvTransport::send() Send a message. 232
TibrvTransport::sendReply() Send a reply message. 233
TIBCO Rendezvous C++ Reference TibrvTransport | 223
(Sheet 2 of 2) Method Description Page
TibrvTransport::sendRequest() Send a request message and wait for a reply. 234
TibrvTransport::setDescription() Set the program description parameter of a 236 transport.
Descendants TibrvProcessTransport on page 238 TibrvNetTransport on page 239 TibrvVcTransport on page 250 TibrvCmTransport on page 305 TibrvCmQueueTransport on page 354
See Also Transport on page 79 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 224 | Chapter 6 Transports
TibrvTransport::createInbox() Method
Declaration TibrvStatus createInbox( char* subjectString, tibrv_u32 subjectLimit) const;
Purpose Create a unique inbox subject name.
Remarks This method creates inbox names that are unique throughout the transport scope. • For network transports, inbox subject names are unique across all processes within the local router domain—that is, anywhere that direct multicast contact is possible. The inbox name is not necessarily unique outside of the local router domain. • For the intra-process transport, inbox names are unique across all threads of the process.
This method creates only the unique name for an inbox; it does not begin listening for messages on that subject name. To begin listening, pass the inbox name as the subject argument to TibrvListener::create(). The inbox name is only valid for use with the same transport that created it. When calling TibrvListener::create(), you must pass the same transport object that created the inbox subject name. Remember that other programs have no information about an inbox subject name until the listening program uses it as a reply subject in an outbound message. Use inbox subject names for delivery to a specific destination. In the context of a network transport, an inbox destination specifies unicast (point-to-point) delivery. Rendezvous routing daemons (rvrd) translate inbox subject names that appear as the send subject or reply subject of a message. They do not translate inbox subject names within the data fields of a message. This inherited method is disabled for TibrvCmQueueTransport objects.
This method is the only legal way for programs to create inbox subject names.
TIBCO Rendezvous C++ Reference TibrvTransport::createInbox() | 225
Parameter Description subjectString The program supplies a string buffer, and the method stores the new inbox subject string in that buffer.
subjectLimit The number of bytes that the program has allocated to receive the new inbox subject string.
See Also TibrvMsg::setReplySubject() on page 93
TIBCO Rendezvous C++ Reference 226 | Chapter 6 Transports
TibrvTransport::destroy() Method
Declaration TibrvStatus destroy()
Purpose Destroy a transport.
Remarks Programs must explicitly destroy each transport object, either using this method, or by calling Tibrv::close() (which destroys all transports). Destroying a transport achieves these effects: • The transport flushes all outbound data to the Rendezvous daemon. This effect is especially important, and neither exiting the program nor calling Tibrv::close() is sufficient to flush outbound data. • The transport invalidates (but does not destroy) all associated listeners. • Subsequent calls that use the destroyed transport return an error status. • Storage for the transport object is freed.
See Also TibrvTransport::isValid() on page 229
TIBCO Rendezvous C++ Reference TibrvTransport::getDescription() | 227
TibrvTransport::getDescription() Method
Declaration TibrvStatus getDescription( const char** description) const;
Purpose Extract the program description parameter from a transport.
Remarks The description identifies your program to Rendezvous components. Browser administration interfaces display the description string.
See Also TibrvTransport on page 222 TibrvTransport::setDescription() on page 236
TIBCO Rendezvous C++ Reference 228 | Chapter 6 Transports
TibrvTransport::getHandle() Method
Declaration tibrvTransport getHandle() const;
Purpose Extract the C handle of this transport object.
TIBCO Rendezvous C++ Reference TibrvTransport::isValid() | 229
TibrvTransport::isValid() Method
Declaration virtual tibrv_bool isValid() const;
Purpose Test validity of a transport.
Remarks Returns TIBRV_TRUE if the transport is valid; TIBRV_FALSE if the transport has been destroyed.
See Also Tibrv::close() on page 19 TibrvTransport::destroy() on page 226 TibrvCmTransport::destroy() on page 317 TibrvCmQueueTransport::destroy() on page 361
TIBCO Rendezvous C++ Reference 230 | Chapter 6 Transports
TibrvTransport::requestReliability() Method
Declaration TibrvStatus requestReliability( tibrv_f64 reliability);
Purpose Request reliability interval (message retention time) for a service.
Parameter Description reliability Request this reliability interval (in seconds). This value must be greater than zero.
Remarks This call lets application programs shorten the reliability interval of the specific service associated with a transport object. Successful calls change the daemon’s reliability interval for all transports within the application process that use the same service. An application can request a shorter retention time than the value that governs the daemon as a whole (either the factory default or the daemons -reliability parameter). The daemon’s governing value silently overrides calls that request a longer retention time. For managed daemons, instructions from RVDM override all other reliability specifications.
Maximum Value Client transport objects that connect to the same daemon could specify different Rule reliability intervals on the same service—whether by requesting a reliability value, or by using the daemon’s effective value. In this situation, the daemon selects the largest potential value from among all the transports on that service, and uses that maximum value as the effective reliability interval for the service (that is, for all the transports on the service). This method of resolution favors the more stringent reliability requirements. (Contrast this rule with the Lower Value Rule that applies between two daemons.)
Recomputing the Whenever a transport connects, requests reliability, or disconnects from the Reliability daemon, the daemon recalculates the reliability interval for the corresponding service, by selecting the largest value of all transports communicating on that service.
TIBCO Rendezvous C++ Reference TibrvTransport::requestReliability() | 231
When recomputing the reliability interval would result in a shorter retention time, the daemon delays using the new value until after an interval equivalent to the older (longer) retention time. This delay ensures that the daemon retains message data at least as long as the effective reliability interval at the time the message is sent.
See Also TibrvTransport on page 222 Reliability and Message Retention Time on page 29 in TIBCO Rendezvous Administration Lower Value Rule on page 30 in TIBCO Rendezvous Administration Changing the Reliability Interval within an Application Program on page 31 in TIBCO Rendezvous Administration Reliable Message Delivery on page 38 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 232 | Chapter 6 Transports
TibrvTransport::send() Method
Declaration virtual TibrvStatus send( const TibrvMsg& message);
Purpose Send a message.
Remarks The message must have a valid destination subject; see TibrvMsg::setSendSubject() on page 94.
Parameter Description message Send this message.
See Also TibrvMsg::setSendSubject() on page 94
TIBCO Rendezvous C++ Reference TibrvTransport::sendReply() | 233
TibrvTransport::sendReply() Method
Declaration virtual TibrvStatus sendReply( const TibrvMsg& replyMessage, const TibrvMsg& requestMessage);
Purpose Send a reply message.
Remarks This convenience call extracts the reply subject of an inbound request message, and sends an outbound reply message to that subject. In addition to the convenience, this call is marginally faster than using separate calls to extract the subject and send the reply. This method overwrites any existing send subject of the reply message with the reply subject of the request message.
Parameter Description replyMessage Send this outbound reply message.
requestMessage Send a reply to this inbound request message; extract its reply subject to use as the subject of the outbound reply message.
Give special attention to the order of the arguments to this method. Reversing the inbound and outbound messages can cause an infinite loop, in which the program repeatedly resends the inbound message to itself (and all other recipients).
See Also TibrvMsg::getReplySubject() on page 83
TIBCO Rendezvous C++ Reference 234 | Chapter 6 Transports
TibrvTransport::sendRequest() Method
Declaration virtual TibrvStatus sendRequest ( const TibrvMsg& message, TibrvMsg& reply, tibrv_f64 timeout);
Purpose Send a request message and wait for a reply.
Blocking can Stall Event Dispatch
This call blocks all other activity on its program thread. If appropriate, programmers must ensure that other threads continue dispatching events on its queues.
Parameter Description message Send this message.
reply The program supplies a variable, and the method stores the inbound reply in that variable. The program owns the reply message, and must call its destructor to reclaim storage.
timeout Maximum time (in seconds) that this call can block while waiting for a reply. TIBRV_WAIT_FOREVER (-1) indicates no timeout (wait without limit for a reply).
Remarks The status code TIBRV_TIMEOUT indicates that the specified time expired before receiving a reply. Programs that receive and process the request message cannot determine that the sender has blocked until a reply arrives. The request message must have a valid destination subject; see TibrvMsg::setSendSubject() on page 94.
Operation This method operates in several synchronous steps: 1. Create an inbox name, and an event that listens to it. Overwrite any existing reply subject of message with the inbox name.
TIBCO Rendezvous C++ Reference TibrvTransport::sendRequest() | 235
2. Send the outbound message. 3. Block until the listener receives a reply; if the time limit expires before a reply arrives, then return TIBRV_TIMEOUT. (The reply circumvents the event queue mechanism, so it is not necessary to explicitly call dispatch methods in the program.) 4. Store the reply in the variable specified as the reply parameter. 5. Return.
TIBCO Rendezvous C++ Reference 236 | Chapter 6 Transports
TibrvTransport::setDescription() Method
Declaration TibrvStatus setDescription( const char* description);
Purpose Set the program description parameter of a transport.
Remarks The description identifies your program to Rendezvous components. Browser administration interfaces display the description string of ordinary transport objects (however they do not display the description string of TibrvCmTransport or TibrvCmQueueTransport objects. As a debugging aid, we recommend setting a unique description string for each transport. Use a string that distinguishes both the application and the role of the transport within it.
Parameter Description description Use this string as the new program description.
See Also TibrvTransport on page 222 TibrvTransport::getDescription() on page 227
TIBCO Rendezvous C++ Reference tibrvTransportBatchMode | 237 tibrvTransportBatchMode Type
Declaration typedef enum { TIBRV_TRANSPORT_DEFAULT_BATCH, TIBRV_TRANSPORT_TIMER_BATCH } tibrvTransportBatchMode;
Purpose Specify the batch mode of a transport.
Value Description TIBRV_TRANSPORT_DEFAULT_B Default batch behavior. The transport transmits outbound ATCH messages to rvd as soon as possible. This value is the initial default for all transports.
TIBRV_TRANSPORT_TIMER_BAT Timer batch behavior. The transport accumulates outbound CH messages, and transmits them to rvd in batches—either when its buffer is full, or when a timer interval expires. (Programs cannot adjust the timer interval.)
See Also TibrvNetTransport::setBatchMode() on page 247 Batch Modes for Transports on page 97 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 238 | Chapter 6 Transports
TibrvProcessTransport Class
Declaration class TibrvProcessTransport : public TibrvTransport
Purpose The intra-process transport delivers messages among the threads of a program.
Remarks The intra-process transport does not access the network. This class does not introduce any new methods. The call Tibrv::open() automatically creates the intra-process transport; Tibrv::close() automatically destroys it; Tibrv::processTransport() extracts it from the Rendezvous environment. Programs cannot create additional instances of this class, and cannot destroy the intra-process transport.
Inherited Methods
TibrvTransport::createInbox() TibrvTransport::destroy() TibrvTransport::isValid() TibrvTransport::getHandle() TibrvTransport::send() TibrvTransport::sendReply() TibrvTransport::sendRequest() TibrvTransport::setDescription()
Related Classes TibrvTransport on page 222 TibrvNetTransport on page 239 TibrvCmTransport on page 305
See Also Tibrv::open() on page 21 Tibrv::processTransport() on page 22
TIBCO Rendezvous C++ Reference TibrvNetTransport | 239
TibrvNetTransport Class
Declaration class TibrvNetTransport : public TibrvTransport TibrvNetTransport(); // Construct empty. virtual ~TibrvNetTransport(); // Destroy and reclaim storage.
Purpose Deliver messages across a network.
Remarks This class connects to rvd for network communications. The constructor creates a hollow object; TibrvNetTransport::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed.
Method Description Page
TibrvNetTransport::create() Create a transport that 241 connects to a Rendezvous daemon.
TibrvNetTransport::getDaemon() Extract the daemon 244 parameter from this transport.
TibrvNetTransport::getNetwork() Return the network 245 interface that this transport uses for communication.
TibrvNetTransport::getService() Return the effective 246 service that this transport uses for communication.
TibrvNetTransport::setBatchMode() Set the batch mode 247 parameter of a transport.
TIBCO Rendezvous C++ Reference 240 | Chapter 6 Transports
Inherited Methods
TibrvTransport::createInbox() TibrvTransport::destroy() TibrvTransport::isValid() TibrvTransport::getHandle() TibrvTransport::send() TibrvTransport::sendReply() TibrvTransport::sendRequest() TibrvTransport::setDescription()
Related Classes TibrvTransport on page 222 TibrvProcessTransport on page 238 TibrvCmTransport on page 305 TibrvCmQueueTransport on page 354
TIBCO Rendezvous C++ Reference TibrvNetTransport::create() | 241
TibrvNetTransport::create() Method
Declaration TibrvStatus create( const char* service = NULL, const char* network = NULL, const char* daemon = NULL );
TibrvStatus createLicensed( const char* service, const char* network, const char* daemon, const char* license_ticket);
Purpose Create a transport that connects to a Rendezvous daemon.
Remarks This method creates a C network transport and stores its handle in the C++ object.
Parameter Description service The Rendezvous daemon divides the network into logical partitions. Each TibrvNetTransport communicates on a single service; a transport can communicate only with other transports on the same service. To communicate on more than one service, a program must create more than one transport—one transport for each service. You can specify the service in several ways. For details, see Service Parameter on page 83 in TIBCO Rendezvous Concepts. NULL specifies the default rendezvous service.
network Every network transport communicates with other transports over a single network interface. On computers with more than one network interface, the network parameter instructs the Rendezvous daemon to use a particular network for all outbound messages from this transport. To communicate over more than one network, programs must create more than one transport. You can specify the network in several ways. For details, see Network Parameter on page 86 in TIBCO Rendezvous Concepts. NULL specifies the primary network interface for the host computer.
TIBCO Rendezvous C++ Reference 242 | Chapter 6 Transports
Parameter Description daemon The daemon parameter instructs the transport object about how and where to find the Rendezvous daemon and establish communication. For details, see Daemon Parameter on page 89 in TIBCO Rendezvous Concepts. You can specify a daemon on a remote computer. For details, see Remote Daemon on page 90 in TIBCO Rendezvous Concepts. If you specify a secure daemon, this string must be identical to as the daemonName argument of TibrvSdContext:setDaemonCert() on page 25. See also, Secure Daemon on page 90 in TIBCO Rendezvous Concepts. null specifies the default—find the local daemon on TCP socket 7500. (This default is not valid when the local daemon is a secure daemon.)
licenseTicket Embed this special license ticket in the transport object. When a licensed transport connects to rvd, it presents this special ticket to validate its connection (rvd uses the longest-running ticket available, which can be either this special ticket, or a ticket from the ticket file, tibrv.tkt). Ordinary license tickets are not valid for this parameter; see also, Embedded License on page 242.
Connecting to Rendezvous daemon processes do the work of moving messages across a the Rendezvous network. Every TibrvNetTransport must connect to a Rendezvous daemon. Daemon If a Rendezvous daemon process with a corresponding daemon parameter is already running, the transport connects to it. If an appropriate Rendezvous local daemon is not running, the transport tries to start it. However, the transport does not attempt to start a remote daemon when none is running. If the transport cannot connect to the Rendezvous daemon, it returns the status code TIBRV_DAEMON_NOT_CONNECTED, and does not create a C transport object.
Description As a debugging aid, we recommend setting a unique description string for each String transport. Use a string that distinguishes both the application and the role of the transport within it. See TibrvTransport::setDescription() on page 236.
Embedded Specially-licensed third-party developers can use the second form of this method. License To use this alternate form, a developer must first purchase a special license ticket. This call embeds the special ticket in the program, so that end-users do not need to purchase Rendezvous to use the program. To purchase an embedded license, contact TIBCO Software Inc.
TIBCO Rendezvous C++ Reference TibrvNetTransport::create() | 243
See Also TibrvNetTransport::getDaemon() on page 244 TibrvNetTransport::getNetwork() on page 245 TibrvNetTransport::getService() on page 246
TIBCO Rendezvous C++ Reference 244 | Chapter 6 Transports
TibrvNetTransport::getDaemon() Method
Declaration TibrvStatus getDaemon( const char*& daemonString ) const;
Purpose Extract the daemon parameter from this transport.
Parameter Description daemonString The program supplies a variable, and the method places in that variable a string pointer to the daemon information. The program must not modify nor free the string.
TIBCO Rendezvous C++ Reference TibrvNetTransport::getNetwork() | 245
TibrvNetTransport::getNetwork() Method
Declaration TibrvStatus getNetwork( const char*& networkString) const;
Purpose Return the network interface that this transport uses for communication.
Parameter Description networkString The program supplies a variable, and the method places in that variable a string pointer to the network information. The program must not modify nor free the string.
TIBCO Rendezvous C++ Reference 246 | Chapter 6 Transports
TibrvNetTransport::getService() Method
Declaration TibrvStatus getService( const char*& serviceString) const;
Purpose Return the effective service that this transport uses for communication.
Parameter Description serviceString The program supplies a variable, and the method places in that variable a string pointer to the service information. The program must not modify nor free the string.
TIBCO Rendezvous C++ Reference TibrvNetTransport::setBatchMode() | 247
TibrvNetTransport::setBatchMode() Method
Declaration TibrvStatus setBatchMode( tibrvTransportBatchMode mode);
Purpose Set the batch mode parameter of a transport.
Remarks The batch mode determines when the transport transmits outbound message data to rvd: • As soon as possible (the initial default for all transports) • Either when its buffer is full, or when a timer interval expires—either event triggers transmission to the daemon
Parameter Description mode Use this value as the new batch mode.
See Also tibrvTransportBatchMode on page 237 Batch Modes for Transports on page 97 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 248 | Chapter 6 Transports
TIBCO Rendezvous C++ Reference | 249
Chapter 7 Virtual Circuits
Virtual circuits feature Rendezvous communication between two terminals over an exclusive, continuous, monitored connection.
See Also Virtual Circuits on page 99 in TIBCO Rendezvous Concepts
Topics
• TibrvVcTransport, page 250
TIBCO Rendezvous C++ Reference 250 | Chapter 7 Virtual Circuits
TibrvVcTransport Class
Declaration class TibrvVcTransport : public TibrvTransport TibrvVcTransport(); // Construct empty. virtual ~TibrvVcTransport(); // Destroy and reclaim storage.
Purpose A virtual circuit transport object represents a terminal in a potential circuit.
Remarks A virtual circuit transport can fill the same roles as an ordinary transport. Programs can use them to create inbox names, send messages, create listeners and other events. The constructor creates a hollow object; programs call one of the two create methods to makes operational. The destructor calls the destroy method, unless the C object is already destroyed. Two methods determine the protocol role of the transport object—one method creates a terminal that accepts connections, and another method creates a terminal that attempts to connect. The two types of terminal play complementary roles as they attempt to establish a connection. However, this difference soon evaporates. After the connection is complete, the two terminals behave identically.
Method Description Page
TibrvVcTransport::createAcceptVc() Create a virtual circuit accept object. 252
TibrvVcTransport::createConnectVc() Create a virtual circuit connect object. 254
TibrvVcTransport::waitForVcConnection() Test the connection status of a virtual 255 circuit.
Broken The following conditions can close a virtual circuit connection: Connection • Contact is broken between the object and its terminal. • The virtual circuit loses data in either direction (see DATALOSS on page 250 in TIBCO Rendezvous Concepts). • The partner program destroys its terminal object (or that terminal becomes invalid). •The program destroys the object.
TIBCO Rendezvous C++ Reference TibrvVcTransport | 251
• The program destroys the object’s ordinary transport.
Destroying VC Destroying a transport object precludes subsequent communications on that Transports transport. Attempting to use a destroyed transport in any way is an error. Destroying a virtual circuit transport does not affect the ordinary transport that the terminal employs. To free storage, call the object’s destructor. (The destroy method does not automatically free storage.)
Direct Because virtual circuits rely on point-to-point messages between the two Communication terminals, they can use direct communication to good advantage. To do so, both terminals must use network transports that enable direct communication. For an overview, see Direct Communication on page 95 in TIBCO Rendezvous Concepts. For programming details, see Specifying Direct Communication on page 84 in TIBCO Rendezvous Concepts.
Inherited Methods Legal Methods TibrvTransport::createInbox() TibrvTransport::destroy() TibrvTransport::getHandle() TibrvTransport::isValid() TibrvTransport::send() TibrvTransport::sendReply() TibrvTransport::sendRequest()
Disabled Methods TibrvTransport::getDescription() TibrvTransport::setDescription()
See Also Virtual Circuits on page 99 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 252 | Chapter 7 Virtual Circuits
TibrvVcTransport::createAcceptVc() Method
Declaration TibrvStatus createAcceptVc( const char** connectSubject, TibrvTransport* transport);
Purpose Create a virtual circuit accept object.
Remarks This method creates a C accept transport and stores its handle in the C++ object.
Parameter Description connectSubject The program supplies a location, and the method stores the connect subject of the new virtual circuit accept transport in that location. After this call returns, the program must send a message to another program, inviting it to establish a virtual circuit. Furthermore, the reply subject of that invitation message must be this connect subject. To complete the virtual circuit, the second program must extract this subject from the invitation, and supply it to TibrvVcTransport::createConnectVc().
transport The virtual circuit uses this ordinary transport for communications. Programs may use this transport for other purposes. It is illegal to supply a virtual circuit transport object for this parameter (that is, you cannot nest a virtual circuit within another virtual circuit).
Test Before Either of two conditions indicate that the connection is ready to use: Using • The transport presents the VC.CONNECTED advisory. • TibrvVcTransport::waitForVcConnection() returns without error. Immediately after this call, test both conditions with these two steps (in this order): 1. Listen on the virtual circuit transport object for the VC.CONNECTED advisory. 2. Call TibrvVcTransport::waitForVcConnection() with zero as the timeout parameter.
For an explanation, see Testing the New Connection on page 103 in TIBCO Rendezvous Concepts.
See Also TibrvVcTransport::createConnectVc() on page 254
TIBCO Rendezvous C++ Reference TibrvVcTransport::createAcceptVc() | 253
TibrvVcTransport::waitForVcConnection() on page 255 VC.CONNECTED on page 266 in TIBCO Rendezvous Concepts VC.DISCONNECTED on page 267 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 254 | Chapter 7 Virtual Circuits
TibrvVcTransport::createConnectVc() Method
Declaration TibrvStatus createConnectVc( const char* connectSubject, TibrvTransport* transport);
Purpose Create a virtual circuit connect object.
Remarks This method creates a C connect transport and stores its handle in the C++ object.
Parameter Description connectSubject The connect transport uses this connect subject to establish a virtual circuit with an accept transport in another program. The program must receive this connect subject from the accepting program. The call to TibrvVcTransport::createAcceptVc() creates this subject.
transport The virtual circuit uses this ordinary transport for communications. Programs may use this transport for other purposes. It is illegal to supply a virtual circuit transport object for this parameter (that is, you cannot nest a virtual circuit within another virtual circuit).
Test Before Either of two conditions indicate that the connection is ready to use: Using • The transport presents the VC.CONNECTED advisory. • TibrvVcTransport::waitForVcConnection() returns without error. Immediately after this call, test both conditions with these two steps (in this order): 1. Listen on the virtual circuit transport object for the VC.CONNECTED advisory. 2. Call TibrvVcTransport::waitForVcConnection() with zero as the timeout parameter.
For an explanation, see Testing the New Connection on page 103 in TIBCO Rendezvous Concepts.
See Also TibrvVcTransport::createAcceptVc() on page 252 TibrvVcTransport::waitForVcConnection() on page 255 VC.CONNECTED on page 266 in TIBCO Rendezvous Concepts VC.DISCONNECTED on page 267 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvVcTransport::waitForVcConnection() | 255
TibrvVcTransport::waitForVcConnection() Method
Declaration TibrvStatus waitForVcConnection( tibrv_f64 timeout);
Purpose Test the connection status of a virtual circuit.
Remarks This method tests (and can block) until this virtual circuit transport object has established a connection with its opposite terminal. You may call this method for either an accept terminal or a connect terminal. This method produces the same information as the virtual circuit advisory messages—but it produces it synchronously (while advisories are asynchronous). Programs can use this method not only to test the connection, but also to block until the connection is ready to use. For example, a program can create a terminal object, then call this method to wait until the connection completes.
Parameter Description timeout This parameter determines the behavior of the call: • For a quick test of current connection status, supply zero. The call returns immediately, without blocking. • To wait for a new terminal to establish a connection, supply a reasonable positive value. The call returns either when the connection is complete, or when this time limit elapses. • To wait indefinitely for a usable connection, supply -1. The call returns when the connection is complete. If the connection was already complete and is now broken, the call returns immediately.
(Sheet 1 of 2) Status Description
TIBRV_OK The connection is complete (ready to use).
TIBRV_TIMEOUT The connection is not yet complete, but the non-negative time limit for waiting has expired.
TIBCO Rendezvous C++ Reference 256 | Chapter 7 Virtual Circuits
(Sheet 2 of 2) Status Description
TIBRV_VC_NOT_CONNECTED The connection was formerly complete, but is now irreparably broken.
See Also TibrvVcTransport::createAcceptVc() on page 252 TibrvVcTransport::createConnectVc() on page 254 Testing the New Connection on page 103 in TIBCO Rendezvous Concepts VC.CONNECTED on page 266 in TIBCO Rendezvous Concepts VC.DISCONNECTED on page 267 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference | 257
Chapter 8 Fault Tolerance
Rendezvous fault tolerance software coordinates a group of redundant processes into a fault-tolerant distributed program. Some processes actively fulfill the tasks of the program, while other processes wait in readiness. When one of the active processes fails, another process rapidly assumes active duty.
Topics
• Fault Tolerance Road Map, page 258 • tibrvftAction, page 259 • TibrvFtMember, page 260 • TibrvFtMemberCallback, page 274 • TibrvFtMemberOnComplete, page 277 • TibrvFtMonitor, page 279 • TibrvFtMonitorCallback, page 290 • TibrvFtMonitorOnComplete, page 292
TIBCO Rendezvous C++ Reference 258 | Chapter 8 Fault Tolerance
Fault Tolerance Road Map
For a complete discussion of concepts and operating principles, see Fault Tolerance Concepts on page 175 in TIBCO Rendezvous Concepts. For suggestions to help you design programs using fault tolerance features, see Fault Tolerance Programming on page 193 in TIBCO Rendezvous Concepts. For step-by-step hints for implementing fault-tolerant systems, see Developing Fault-Tolerant Programs on page 207 in TIBCO Rendezvous Concepts. Fault tolerance software uses advisory messages to inform programs of status changes. For details, see Fault Tolerance (RVFT) Advisory Messages on page 293 in TIBCO Rendezvous Concepts. If your application distributes fault-tolerant processes across network boundaries, you must configure the Rendezvous routing daemons to exchange _RVFT administrative messages. For details, see Fault Tolerance on page 389 in TIBCO Rendezvous Administration, and discuss with your network administrator.
TIBCO Rendezvous C++ Reference tibrvftAction | 259 tibrvftAction Type
Declaration typedef enum { TIBRVFT_PREPARE_TO_ACTIVATE = 1, TIBRVFT_ACTIVATE = 2, TIBRVFT_DEACTIVATE = 3
} tibrvftAction;
Purpose Instruct fault tolerance callback methods to react to changing circumstances.
Remarks Each token of this enumerated type designates a command to a fault tolerance callback method. The program’s callback method receives one of these tokens in a parameter, and interprets it as an instruction from the Rendezvous fault tolerance software as described in this table (see also, Fault Tolerance Callback Actions on page 194 in TIBCO Rendezvous Concepts).
Token Description TIBRVFT_PREPARE_TO_ACTIVATE Prepare to activate (hint). Rendezvous fault tolerance software passes this token to the callback method to instruct the program to make itself ready to activate on short notice—so that if the callback method subsequently receives the instruction to activate, it can do so without delay. This token is a hint, indicating that the program might soon receive an instruction to activate. It does not guarantee that an activate instruction will follow, nor that any minimum time will elapse before an activate instruction follows.
TIBRVFT_ACTIVATE Activate immediately. Rendezvous fault tolerance software passes this token to the callback method to instruct the program to activate.
TIBRVFT_DEACTIVATE Deactivate immediately. Rendezvous fault tolerance software passes this token to the callback method to instruct the program to deactivate.
See Also TibrvFtMemberCallback::onFtAction() on page 275 TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference 260 | Chapter 8 Fault Tolerance
TibrvFtMember Class
Declaration class TibrvFtMember TibrvFtMember(); // Create empty. virtual ~TibrvFtMember(); // Destroy and reclaim storage.
Purpose Represent membership in a fault tolerance group.
Remarks The constructor creates a hollow object; TibrvFtMember::create() makes it operational and joins a fault tolerance group. By destroying a member object, the program withdraws its membership in the fault tolerance group. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue or transport of a member object invalidates the member object, but does not destroy it. Programs must explicitly call the member’s destructor to reclaim storage.
(Sheet 1 of 2) Method Description Page Life Cycle
TibrvFtMember::create() Create a member of a fault 262 tolerance group.
TibrvFtMember::destroy() Destroy a member of a fault 265 tolerance group.
TibrvFtMember::getHandle() Extract the C handle of a fault 268 tolerance member.
TibrvFtMember::isValid() Test validity of a fault tolerance 272 member object.
Properties
TibrvFtMember::getClosure() Extract the closure data of a 266 fault tolerance member.
TibrvFtMember::getGroupName() Extract the group name of a 267 fault tolerance member.
TIBCO Rendezvous C++ Reference TibrvFtMember | 261
(Sheet 2 of 2) Method Description Page
TibrvFtMember::getQueue() Extract the event queue of a 269 fault tolerance member.
TibrvFtMember::getTransport() Extract the transport of a fault 270 tolerance member.
TibrvFtMember::getWeight() Extract the weight of a fault 271 tolerance member.
TibrvFtMember::setWeight() Change the weight of a fault 273 tolerance member within its group.
Related Classes TibrvFtMonitor on page 279
See Also TibrvFtMemberCallback on page 274
TIBCO Rendezvous C++ Reference 262 | Chapter 8 Fault Tolerance
TibrvFtMember::create() Method
Declaration TibrvStatus create( TibrvQueue* queue, TibrvFtMemberCallback* callback, TibrvTransport* transport, const char* groupName, tibrv_u16 weight, tibrv_u16 activeGoal, tibrv_f64 heartbeatInterval, tibrv_f64 preparationInterval, tibrv_f64 activationInterval, const void* closure = NULL);
Purpose Create a member of a fault tolerance group.
Remarks This method creates a C fault tolerance member object, and stores it in the C++ object. The program becomes a member of the fault tolerance group. A program may hold simultaneous memberships in several distinct fault tolerance groups. For examples, see Multiple Groups on page 197 in TIBCO Rendezvous Concepts. Avoid joining the same group twice. It is illegal for a program to maintain more than one membership in any one fault tolerance group. This method does not guard against this illegal situation, and results are unpredictable. All arguments are required except for preparationInterval (which may be zero) and closure (which may be NULL).
Intervals The heartbeat interval must be less than the activation interval. If the preparation interval is non-zero, it must be greater than the heartbeat interval and less than the activation interval. It is an error to violate these rules. In addition, intervals must be reasonable for the hardware and network conditions. For information and examples, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts.
Group Name The group name must be a legal Rendezvous subject name (see Subject Names on page 41 in TIBCO Rendezvous Concepts). You may use names with several elements; for examples, see Multiple Groups on page 197 in TIBCO Rendezvous Concepts.
(Sheet 1 of 3) Parameter Description queue Place fault tolerance events for this member on this event queue.
TIBCO Rendezvous C++ Reference TibrvFtMember::create() | 263
(Sheet 2 of 3) Parameter Description callback On dispatch, process the event with this callback object. transport Use this transport for fault tolerance internal protocol messages (such as heartbeat messages). groupName Join the fault tolerant group with this name. The group name must conform to the syntax required for Rendezvous subject names. For details, see Subject Names on page 41 in TIBCO Rendezvous Concepts. weight Weight represents the ability of this member to fulfill its purpose, relative to other members of the same fault tolerance group. Rendezvous fault tolerance software uses relative weight values to select which members to activate; members with higher weight take precedence over members with lower weight. Acceptable values range from 1 to 65535. Zero is a special, reserved value; Rendezvous fault tolerance software assigns zero weight to processes with resource errors, so they only activate when no other members are available. For more information, see Rank and Weight on page 184 in TIBCO Rendezvous Concepts. activeGoal Rendezvous fault tolerance software sends callback instructions to maintain this number of active members. Acceptable values range from 1 to 65535. heartbeatInterval When this member is active, it sends heartbeat messages at this interval (in seconds). The interval must be positive. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts.
TIBCO Rendezvous C++ Reference 264 | Chapter 8 Fault Tolerance
(Sheet 3 of 3) Parameter Description preparationInterval When the heartbeat signal from one or more active members has been silent for this interval (in seconds), Rendezvous fault tolerance software issues an early warning hint (TIBRVFT_PREPARE_TO_ACTIVATE) to the ranking inactive member. This warning lets the inactive member prepare to activate, for example, by connecting to a database server, or allocating memory. The interval must be non-negative. Zero is a special value, indicating that the member does not need advance warning to activate; Rendezvous fault tolerance software never issues a TIBRVFT_PREPARE_TO_ACTIVATE hint when this value is zero. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts.
activationInterval When the heartbeat signal from one or more active members has been silent for this interval (in seconds), Rendezvous fault tolerance software considers the silent member to be lost, and issues the instruction to activate (TIBRVFT_ACTIVATE) to the ranking inactive member. When a new member joins a group, Rendezvous fault tolerance software identifies the new member to existing members (if any), and then waits for this interval to receive identification from them in return. If, at the end of this interval, it determines that too few members are active, it issues the activate instruction (TIBRVFT_ACTIVATE) to the new member. Then interval must be positive. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts.
closure Store this closure data in the member object.
See Also TibrvFtMember on page 260. TibrvFtMemberCallback on page 274. TibrvFtMember::destroy() on page 265. Step 1: Choose a Group Name, page 208 in TIBCO Rendezvous Concepts Step 2: Choose the Active Goal, page 210 in TIBCO Rendezvous Concepts Step 4: Choose the Intervals, page 215 in TIBCO Rendezvous Concepts Step 5: Program Start Sequence, page 219 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvFtMember::destroy() | 265
TibrvFtMember::destroy() Method
Declaration TibrvStatus destroy( TibrvFtMemberOnComplete* completeCB = NULL);
Purpose Destroy a member of a fault tolerance group.
Remarks By destroying a member object, the program cancels or withdraws its membership in the group. If the member is active, it stops sending the heartbeat signal. Once a program withdraws from a group, it no longer receives fault tolerance events. One direct consequence is that an active program that withdraws can never receive an instruction to deactivate. To free storage, call the object’s destructor. (The destroy method does not automatically free storage.)
See Also TibrvFtMember::create() on page 262 TibrvFtMember::isValid() on page 272 TibrvFtMemberOnComplete on page 277 TibrvFtMemberOnComplete::onComplete on page 278
TIBCO Rendezvous C++ Reference 266 | Chapter 8 Fault Tolerance
TibrvFtMember::getClosure() Method
Declaration void* getClosure() const;
Purpose Extract the closure data of a fault tolerance member.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference TibrvFtMember::getGroupName() | 267
TibrvFtMember::getGroupName() Method
Declaration TibrvStatus getGroupName( const char *& groupName) const;
Purpose Extract the group name of a fault tolerance member.
Parameter Description groupName The program supplies a variable, and the method stores the group name in that variable. The program must not modify this string nor free its storage.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference 268 | Chapter 8 Fault Tolerance
TibrvFtMember::getHandle() Method
Declaration tibrvftMember getHandle() const;
Purpose Extract the C handle of a fault tolerance member.
See Also TibrvFtMember::create() on page 262 tibrvftMember on page 244 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvFtMember::getQueue() | 269
TibrvFtMember::getQueue() Method
Declaration TibrvQueue* getQueue () const;
Purpose Extract the event queue of a fault tolerance member.
Remarks If the member is invalid, this method returns NULL.
See Also TibrvQueue on page 182 TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference 270 | Chapter 8 Fault Tolerance
TibrvFtMember::getTransport() Method
Declaration TibrvTransport* getTransport() const;
Purpose Extract the transport of a fault tolerance member.
See Also TibrvTransport on page 222 TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference TibrvFtMember::getWeight() | 271
TibrvFtMember::getWeight() Method
Declaration TibrvStatus getWeight( tibrv_u16& weight) const;
Purpose Extract the weight of a fault tolerance member.
Parameter Description weight The program supplies a variable, and the method stores the weight in that variable.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference 272 | Chapter 8 Fault Tolerance
TibrvFtMember::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test validity of a fault tolerance member object.
Remarks Returns TIBRV_TRUE if the C member is valid; TIBRV_FALSE if the member has been destroyed or is otherwise invalid.
See Also TibrvFtMember::destroy() on page 265
TIBCO Rendezvous C++ Reference TibrvFtMember::setWeight() | 273
TibrvFtMember::setWeight() Method
Declaration TibrvStatus setWeight( tibrv_u16 weight);
Purpose Change the weight of a fault tolerance member within its group.
Remarks Weight summarizes the relative suitability of a member for its task, relative to other members of the same fault tolerance group. That suitability is a combination of computer speed and load factors, network bandwidth, computer and network reliability, and other factors. Programs may reset their weight when any of these factors change, overriding the previous assigned weight. You can use relative weights to indicate priority among group members. Zero is a special value; Rendezvous fault tolerance software assigns zero weight to processes with resource errors, so they only activate when no other members are available. Programs must always assign weights greater than zero. When Rendezvous fault tolerance software requests a resource but receives an error (for example, the member process cannot allocate memory, or start a timer), it attempts to send the member process a DISABLING_MEMBER advisory message, and sets the member’s weight to zero, effectively disabling the member. Weight zero implies that this member is active only as a last resort—when no other members outrank it. (However, if the disabled member process does become active, it might not operate correctly.)
Parameter Description
weight The new weight value. See weight on page 263.
See Also Adjusting Member Weights on page 205 in TIBCO Rendezvous Concepts.
TIBCO Rendezvous C++ Reference 274 | Chapter 8 Fault Tolerance
TibrvFtMemberCallback Class
Declaration class TibrvFtMemberCallback
Purpose Process fault tolerance events for a group member.
Remarks Implement this interface to process fault tolerance events.
Method Description Page
TibrvFtMemberCallback::onFtAction() Process fault tolerance events for a group 275 member.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference TibrvFtMemberCallback::onFtAction() | 275
TibrvFtMemberCallback::onFtAction() Method
Declaration virtual void onFtAction( TibrvFtMember* ftMember, const char* groupName, tibrvftAction action ) = 0;
Purpose Process fault tolerance events for a group member.
Remarks Each member program of a fault tolerance group must implement this method. Programs register a member callback object (and this method) with each call to TibrvFtMember::create(). Rendezvous fault tolerance software queues a member action event in three situations. In each case, it passes a different action argument, instructing the callback method to activate, deactivate, or prepare to activate the program. • When the number of active members drops below the active goal, the fault tolerance callback method (in the ranking inactive member process) receives the token TIBRVFT_ACTIVATE; the callback method must respond by assuming the duties of an active member. • When the number of active members exceeds the active goal, the fault tolerance callback method (in any active member that is outranked by another active member) receives the action token TIBRVFT_DEACTIVATE; the callback method must respond by switching the program to its inactive state. • When the number of active members equals the active goal, and Rendezvous fault tolerance software detects that it might soon decrease below the active goal, the fault tolerance callback method (in the ranking inactive member) receives the action token TIBRVFT_PREPARE_TO_ACTIVATE; the callback method must respond by making the program ready to activate immediately. For example, preparatory steps might include time-consuming tasks such as connecting to a database. If the callback method subsequently receives the TIBRVFT_ACTIVATE token, it will be ready to activate without delay. This token is a hint, indicating that the program might soon receive an instruction to activate. It does not guarantee that an activate instruction will follow, nor that any minimum time will elapse before an activate instruction follows.
For additional information see Fault Tolerance Callback Actions on page 194 in TIBCO Rendezvous Concepts.
TIBCO Rendezvous C++ Reference 276 | Chapter 8 Fault Tolerance
Parameter Description ftMember This parameter receives the member object.
groupName This parameter receives a string denoting the name of the fault tolerance group.
action This parameter receives a token that instructs the callback method to activate, deactivate or prepare to activate. See tibrvftAction on page 259.
See Also TibrvFtMember::create() on page 262 Fault Tolerance Callback Actions on page 194 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvFtMemberOnComplete | 277
TibrvFtMemberOnComplete Class
Declaration class TibrvFtMemberOnComplete
Purpose A program can destroy a member object even when its callback method is running in one or more threads. Multi-threaded programs can define a subclass of this interface class to discover when all callback methods in progress have completed.
Method Description Page
TibrvFtMemberOnComplete::onComplete A program can destroy a member object 278 even when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference 278 | Chapter 8 Fault Tolerance
TibrvFtMemberOnComplete::onComplete Method
Declaration virtual void onComplete( TibrvFtMember* ftMember) = 0;
Purpose A program can destroy a member object even when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
Parameter Description ftMember This parameter receives the member event object. This object is identical to the object that the program created to join the fault tolerance group. However, by the time this method runs, the member is already destroyed; this method cannot use the member object in Rendezvous calls.
Remarks This type of method is important in two situations: • Internal fault tolerance callback methods run in several threads (because several threads dispatch the member’s event queue), and the program must do additional processing after these callback methods have completed in all threads. • A member callback method calls TibrvFtMember::destroy() to withdraw from a fault tolerance group, and the program must do additional processing after the rest of the callback method has completed.
Upon return from TibrvFtMember::destroy(), the destroyed member’s callback method can no longer begin to run (this is also true of internal callback methods). However, in each thread where a callback method is already in progress, that callback method does continue to run until complete. TibrvFtMember::destroy() accepts a completion argument of type TibrvFtMemberOnComplete. Rendezvous software ensures that the completion method runs when the last callback-in-progress has completed.
Timing and This information in completely analogous to Context TibrvEventOnComplete::onComplete() on page 138. See that section for important details.
See Also TibrvFtMember::create() on page 262
TIBCO Rendezvous C++ Reference TibrvFtMonitor | 279
TibrvFtMonitor Class
Declaration class TibrvFtMonitor TibrvFtmonitor(); // Create empty. virtual ~TibrvFtmonitor(); // Destroy and reclaim storage.
Purpose Monitor a fault tolerance group.
Remarks The constructor creates a hollow object; TibrvFtMonitor::create() makes it operational, and monitors a fault tolerance group. Monitors are passive—they do not affect the group members in any way. Rendezvous fault tolerance software queues a monitor event whenever the number of active members in the group changes—either it detects a new heartbeat, or it detects that the heartbeat from a previously active member is now silent, or it receives a message from the fault tolerance component of an active member indicating deactivation or termination. The monitor callback method receives the number of active members as an argument. By destroying a monitor object, the program stops monitoring the fault tolerance group. The destructor calls the destroy method, unless the C object is already destroyed. Destroying the queue or transport of a monitor automatically destroys the monitor as well.
(Sheet 1 of 2) Method Description Page Life Cycle
TibrvFtMonitor::create() Monitor a fault tolerance group. 281
TibrvFtMonitor::destroy() Stop monitoring a fault tolerance group, and free 283 associated resources.
TibrvFtMonitor::getHandle() Extract the C handle of a fault tolerance monitor. 286
TibrvFtMonitor::isValid() Test validity of a fault tolerance monitor object. 289
Properties
TibrvFtMonitor::getClosure() Extract the closure data of a fault tolerance 284 monitor.
TIBCO Rendezvous C++ Reference 280 | Chapter 8 Fault Tolerance
(Sheet 2 of 2) Method Description Page
TibrvFtMonitor::getGroupName() Extract the group name of a fault tolerance 285 monitor.
TibrvFtMonitor::getQueue() Extract the event queue of a fault tolerance 287 monitor.
TibrvFtMonitor::getTransport() Extract the transport of a fault tolerance monitor. 288
Related Classes TibrvFtMember on page 260
See Also TibrvFtMonitorCallback on page 290
TIBCO Rendezvous C++ Reference TibrvFtMonitor::create() | 281
TibrvFtMonitor::create() Method
Declaration TibrvStatus create( TibrvQueue* queue, TibrvFtMonitorCallback* callback, TibrvTransport* transport, const char* groupName, tibrv_f64 lostInterval, const void* closure = NULL);
Purpose Monitor a fault tolerance group.
Remarks The monitor callback method receives the number of active members as an argument. The group need not have any members at the time of this create call.
Parameter Description queue Place events for this monitor on this event queue.
callback On dispatch, process the event with this callback method.
transport Listen on this transport for fault tolerance internal protocol messages (such as heartbeat messages).
groupName Monitor the fault tolerant group with this name. The group name must conform to the syntax required for Rendezvous subject names. For details, see Subject Names on page 41 in TIBCO Rendezvous Concepts. See also, Group Name on page 282.
lostInterval When the heartbeat signal from an active member has been silent for this interval (in seconds), Rendezvous fault tolerance software considers that member lost, and queues a monitor event. The interval must be positive. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts. See also, Lost Interval on page 282.
closure Store this closure data in the monitor object.
TIBCO Rendezvous C++ Reference 282 | Chapter 8 Fault Tolerance
Lost Interval The monitor uses the lostInterval to determine whether a member is still active. When the heartbeat signal from an active member has been silent for this interval (in seconds), the monitor considers that member lost, and queues a monitor event. We recommend setting the lostInterval identical to the group’s activationInterval, so the monitor accurately reflects the behavior of the group members.
Group Name The group name must be a legal Rendezvous subject name (see Subject Names on page 41 in TIBCO Rendezvous Concepts). You may use names with several elements; for examples, see Multiple Groups on page 197 in TIBCO Rendezvous Concepts.
See Also TibrvFtMonitorCallback on page 290. TibrvFtMonitor::destroy() on page 283.
TIBCO Rendezvous C++ Reference TibrvFtMonitor::destroy() | 283
TibrvFtMonitor::destroy() Method
Declaration TibrvStatus destroy( TibrvFtMonitorOnComplete* completeCB=NULL);
Purpose Stop monitoring a fault tolerance group, and free associated resources.
Remarks This method returns an error when the monitor object is already invalid, or when its queue or transport are invalid.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference 284 | Chapter 8 Fault Tolerance
TibrvFtMonitor::getClosure() Method
Declaration void* getClosure() const;
Purpose Extract the closure data of a fault tolerance monitor.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference TibrvFtMonitor::getGroupName() | 285
TibrvFtMonitor::getGroupName() Method
Declaration TibrvStatus getGroupName( const char*& groupName) const;
Purpose Extract the group name of a fault tolerance monitor.
Parameter Description groupName The program supplies a variable, and the method stores the group name in that variable.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference 286 | Chapter 8 Fault Tolerance
TibrvFtMonitor::getHandle() Method
Declaration tibrvftMonitor getHandle() const;
Purpose Extract the C handle of a fault tolerance monitor.
See Also TibrvFtMonitor::create() on page 281 tibrvftMonitor on page 259 in TIBCO Rendezvous C Reference
TIBCO Rendezvous C++ Reference TibrvFtMonitor::getQueue() | 287
TibrvFtMonitor::getQueue() Method
Declaration TibrvQueue* getQueue() const;
Purpose Extract the event queue of a fault tolerance monitor.
Remarks If the monitor is invalid, this method returns NULL.
See Also TibrvQueue on page 182 TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference 288 | Chapter 8 Fault Tolerance
TibrvFtMonitor::getTransport() Method
Declaration TibrvTransport* getTransport() const;
Purpose Extract the transport of a fault tolerance monitor.
See Also TibrvTransport on page 222 TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference TibrvFtMonitor::isValid() | 289
TibrvFtMonitor::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test validity of a fault tolerance monitor object.
Remarks Returns TIBRV_TRUE if the C monitor is valid; TIBRV_FALSE if the monitor has been destroyed or is otherwise invalid.
See Also TibrvFtMonitor::destroy() on page 283
TIBCO Rendezvous C++ Reference 290 | Chapter 8 Fault Tolerance
TibrvFtMonitorCallback Class
Declaration class TibrvFtMonitorCallback
Purpose Process fault tolerance events for a monitor.
Remarks Implement this interface to process fault tolerance monitor events.
Method Description Page
TibrvFtMonitorCallback::onFtMonitor() Process fault tolerance events for a 291 monitor.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference TibrvFtMonitorCallback::onFtMonitor() | 291
TibrvFtMonitorCallback::onFtMonitor()
Declaration virtual void onFtMonitor( TibrvFtMonitor* ftMonitor, const char* groupName, tibrv_u32 numActiveMembers ) = 0;
Purpose Process fault tolerance events for a monitor.
Remarks A program must define a method of this type as a prerequisite to monitor a fault tolerance group. Programs register a monitor callback method with each call to TibrvFtMonitor::create() on page 281. Rendezvous fault tolerance software queues a monitor event whenever the number of active members in the group changes. A program need not be a member of a group in order to monitor that group.
Parameter Description ftMonitor This parameter receives the monitor object.
groupName This parameter receives a string denoting the name of the fault tolerance group.
numActiveMembers This parameter receives the number of group members now active.
See Also TibrvFtMonitor::create() on page 281.
TIBCO Rendezvous C++ Reference 292 | Chapter 8 Fault Tolerance
TibrvFtMonitorOnComplete Class
Declaration class TibrvFtMonitorOnComplete
Purpose A program can destroy a monitor object even when its callback method is running in one or more threads. Multi-threaded programs can define a subclass of this interface class to discover when all callback methods in progress have completed.
Method Description Page
TibrvFtMonitorOnComplete::onComplete A program can destroy a monitor object 293 even when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference TibrvFtMonitorOnComplete::onComplete | 293
TibrvFtMonitorOnComplete::onComplete Method
Declaration virtual void onComplete( TibrvFtMonitor* ftMonitor) = 0;
Purpose A program can destroy a monitor object even when its callback method is running in one or more threads. Multi-threaded programs can define methods of this type to discover when all callback methods in progress have completed.
Parameter Description ftMonitor This parameter receives the monitor event object. This object is identical to the object that the program created to begin monitoring the fault tolerance group. However, by the time this method runs, the monitor is already destroyed; this method cannot use the monitor object in Rendezvous calls.
Remarks This type of method is important in two situations: • Internal fault tolerance callback methods run in several threads (because several threads dispatch the monitor’s event queue), and the program must do additional processing after these callback methods have completed in all threads. • A member callback method calls TibrvFtMonitor::destroy() to stop monitoring a fault tolerance group, and the program must do additional processing after the rest of the callback method has completed.
Upon return from TibrvFtMonitor::destroy(), the destroyed monitor’s callback method can no longer begin to run (this is also true of internal callback methods). However, in each thread where a callback method is already in progress, that callback method does continue to run until complete. TibrvFtMonitor::destroy() accepts a completion argument of type TibrvFtMonitorOnComplete. Rendezvous software ensures that the completion method runs when the last callback-in-progress has completed.
Timing and This information in completely analogous to Context TibrvEventOnComplete::onComplete() on page 138. See that section for important details.
See Also TibrvFtMonitor::create() on page 281
TIBCO Rendezvous C++ Reference 294 | Chapter 8 Fault Tolerance
TIBCO Rendezvous C++ Reference | 295
Chapter 9 Certified Message Delivery
Although Rendezvous communications are highly reliable, some applications require even stronger assurances of delivery. Certified delivery features offers greater certainty of delivery—even in situations where processes and their network connections are unstable.
See Also This API implements Rendezvous certified delivery features. For a complete discussion, see Certified Message Delivery on page 119 in TIBCO Rendezvous Concepts. Certified delivery software uses advisory messages extensively. For example, advisories inform sending and receiving programs of the delivery status of each message. For complete details, see Certified Message Delivery (RVCM) Advisory Messages on page 269 in TIBCO Rendezvous Concepts. If your application sends or receives certified messages across network boundaries, you must configure the Rendezvous routing daemons to exchange _RVCM administrative messages. For details, see Certified Message Delivery on page 385 in TIBCO Rendezvous Administration. Some programs require certified delivery to one of n worker processes. See Distributed Queue on page 161 in TIBCO Rendezvous Concepts.
Topics
• TibrvCmListener, page 296 • TibrvCmTransport, page 305 • TibrvCmTransportOnComplete, page 339 • TibrvCmReviewCallback, page 341 • TibrvCmMsg, page 344 • TibrvCmMsgCallback, page 350
TIBCO Rendezvous C++ Reference 296 | Chapter 9 Certified Message Delivery
TibrvCmListener Class
Declaration class TibrvCmListener : TibrvEvent TibrvCmListener(); // Create empty. virtual ~TibrvCmListener(); // Destroy and reclaim storage.
Purpose A certified delivery listener object listens for labeled messages and certified messages.
Remarks The constructor creates a hollow object; TibrvCmListener::create() makes it operational—starting a C certified delivery listener, which represents your program’s listening interest in a stream of labeled messages and certified messages. Rendezvous software uses the same listener object to signal each occurrence of such an event. We recommend that programs explicitly destroy each certified delivery listener object using TibrvCmListener::destroy(). Destroying a certified listener object cancels the program’s immediate interest in that event; nonetheless, a parameter to the destroy call determines whether certified delivery agreements continue to persist beyond the destroy call. The destructor calls the destroy() method, unless the C object is already destroyed. Destroying the queue, the certified delivery transport, or the transport of a listener object automatically invalidates the listener as well (but certified delivery agreements continue to persist).
(Sheet 1 of 2) Method Description Page Life Cycle
TibrvCmListener::create() Listen for messages that match the 299 subject, and request certified delivery when available.
TibrvCmListener::destroy() Destroy a certified delivery listener. 300
TibrvCmListener::isValid() Test whether a certified delivery listener 303 has been destroyed.
TIBCO Rendezvous C++ Reference TibrvCmListener | 297
(Sheet 2 of 2) Method Description Page Confirmation
TibrvCmListener::confirmMsg() Explicitly confirm delivery of a certified 298 message.
TibrvCmListener::setExplicitConfirm() Override automatic confirmation of 304 delivery for this listener.
Properties
TibrvCmListener::getSubject() Extract the subject from a certified 301 delivery listener.
TibrvCmListener::getTransport() Extract the transport from a certified 302 delivery listener.
Inherited Methods
TibrvEvent::destroy() TibrvEvent::getClosure() TibrvEvent::getHandle() TibrvEvent::getType() TibrvEvent::getQueue() TibrvEvent::isValid() TibrvEvent::isListener() TibrvEvent::isTimer() TibrvEvent::isIOEvent()
Related Classes TibrvEvent on page 123 TibrvListener on page 141
TIBCO Rendezvous C++ Reference 298 | Chapter 9 Certified Message Delivery
TibrvCmListener::confirmMsg() Method
Declaration TibrvStatus confirmMsg( const TibrvMsg& msg);
Purpose Explicitly confirm delivery of a certified message.
Remarks Use this method only in programs that override automatic confirmation (see TibrvCmListener::setExplicitConfirm() on page 304). The default behavior of certified listeners is to automatically confirm delivery when the callback method returns.
Parameter Description message Confirm receipt of this message.
Unregistered When a CM listener receives a labeled message, its behavior depends on context: Message • If a CM listener is registered for certified delivery, it presents the supplementary information to the callback method. If the sequence number is present, then the receiving program can confirm delivery. • If a CM listener is not registered for certified delivery with the sender, it presents the sender’s name to the callback method, but omits the sequence number. In this case, the receiving program cannot confirm delivery; TibrvCmListener::confirmMsg() returns the status code TIBRV_NOT_PERMITTED. Notice that the first labeled message that a program receives on a subject might not be certified; that is, the sender has not registered a certified delivery agreement with the listener. If appropriate, the certified delivery library automatically requests that the sender register the listener for certified delivery. (See Discovery and Registration for Certified Delivery on page 134 in TIBCO Rendezvous Concepts.) A labeled but uncertified message can also result when the sender explicitly disallows or removes the listener.
See Also TibrvCmListener on page 296 TibrvCmListener::setExplicitConfirm() on page 304
TIBCO Rendezvous C++ Reference TibrvCmListener::create() | 299
TibrvCmListener::create() Method
Declaration TibrvStatus create( TibrvQueue* queue, TibrvCmMsgCallback* cmMsgCallback, TibrvCmTransport* cmTransport, const char* subject, const void* closure = NULL);
Purpose Listen for messages that match the subject, and request certified delivery when available.
Parameter Description queue For each inbound message, place the listener event on this event queue.
cmMsgCallback On dispatch, process the event with this callback object.
cmTransport Listen for inbound messages on this certified delivery transport.
subject Listen for inbound messages with subjects that match this specification. Wildcard subjects are permitted. The empty string is not a legal subject name.
closure Store this closure data in the event object.
Activation and Details of listener event semantics are identical to those for ordinary listeners; see Dispatch Activation and Dispatch on page 141.
Inbox Listener To receive unicast (point-to-point) messages, listen to a unique inbox subject name. First call TibrvTransport::createInbox() to create the unique inbox name; then call TibrvListener::create() to begin listening. Remember that other programs have no information about an inbox until the listening program uses it as a reply subject in an outbound message.
See Also TibrvCmListener on page 296 TibrvCmTransport::destroy() on page 317 TibrvListener::getSubject() on page 145 TibrvTransport::createInbox() on page 224
TIBCO Rendezvous C++ Reference 300 | Chapter 9 Certified Message Delivery
TibrvCmListener::destroy() Method
Declaration TibrvStatus destroy( tibrv_bool cancelAgreements, TibrvEventOnComplete* completeCB = NULL);
Purpose Destroy a certified delivery listener.
Parameter Description
cancelAgreements TIBRV_TRUE cancels all certified delivery agreements of this listener; certified senders delete from their ledgers all messages sent to this listener. TIBRV_FALSE leaves all certified delivery agreements in effect, so certified senders continue to store messages.
Canceling When destroying a certified delivery listener, a program can either cancel its Agreements certified delivery agreements with senders, or let those agreements persist (so a successor listener can receive the messages covered by those agreements). When canceling agreements, each (previously) certified sender transport receives a REGISTRATION.CLOSED advisory. Successor listeners cannot receive old messages.
See Also TibrvEventOnComplete on page 137 TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference TibrvCmListener::getSubject() | 301
TibrvCmListener::getSubject() Method
Declaration TibrvStatus getSubject( const char*& subject) const;
Purpose Extract the subject from a certified delivery listener.
Parameter Description subject The program supplies a variable. The method stores the subject of the listener event object in that variable. The program must not modify this string nor free its storage.
See Also TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference 302 | Chapter 9 Certified Message Delivery
TibrvCmListener::getTransport() Method
Declaration TibrvCmTransport* getTransport() const;
Purpose Extract the transport from a certified delivery listener.
See Also TibrvCmListener on page 296
TIBCO Rendezvous C++ Reference TibrvCmListener::isValid() | 303
TibrvCmListener::isValid() Method
Declaration tibrv_bool isValid() const;
Purpose Test whether a certified delivery listener has been destroyed.
Remarks This method returns TIBRV_TRUE if the listener is valid, and TIBRV_FALSE if it has been destroyed. Notice that TibrvCmListener::destroy() invalidates the event immediately, even though active callback methods may continue to run.
See Also TibrvCmListener::destroy() on page 300
TIBCO Rendezvous C++ Reference 304 | Chapter 9 Certified Message Delivery
TibrvCmListener::setExplicitConfirm() Method
Declaration TibrvStatus setExplicitConfirm();
Purpose Override automatic confirmation of delivery for this listener.
Remarks The default behavior of certified listeners is to automatically confirm delivery when the callback method returns (see TibrvMsgCallback::onMsg() on page 148). This call selectively overrides this behavior for this specific listener (without affecting other listeners). By overriding automatic confirmation, the listener assumes responsibility to explicitly confirm each inbound certified message by calling TibrvCmListener::confirmMsg(). Consider overriding automatic confirmation when the processing of inbound messages involves activity that is asynchronous with respect to the message callback method; for example, computations in other threads or additional network communications. No method exists to restore the default behavior—that is, to reverse the effect of this method.
See Also TibrvCmListener on page 296 TibrvMsgCallback::onMsg() on page 148 TibrvCmListener::confirmMsg() on page 298
TIBCO Rendezvous C++ Reference TibrvCmTransport | 305
TibrvCmTransport Class
Declaration class TibrvCmTransport : public TibrvTransport
Purpose A certified delivery transport object implements the CM delivery protocol for messages.
Remarks Each certified delivery transport employs a TibrvTransport for network communications. The TibrvCmTransport adds the accounting mechanisms needed for delivery tracking and certified delivery. Several TibrvCmTransport objects can employ a TibrvTransport, which also remains available for its own ordinary listeners and for sending ordinary messages. The constructor creates a hollow object; TibrvCmTransport::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed. Programs must explicitly destroy each certified delivery transport object. Destroying a certified delivery transport object invalidates subsequent certified send calls on that object, invalidates any certified listeners using that transport (while preserving the certified delivery agreements of those listeners).
(Sheet 1 of 3) Method Description Page
TibrvCmTransport::create() Create a transport for certified 312 delivery.
TibrvCmTransport::addListener() Pre-register an anticipated 308 listener.
TibrvCmTransport::allowListener() Invite the named receiver to 309 reinstate certified delivery for its listeners, superseding the effect of any previous disallow calls.
TibrvCmTransport::connectToRelayAgent() Connect a certified delivery 310 transport to its designated relay agent.
TibrvCmTransport::destroy() Destroy a certified delivery 317 transport.
TIBCO Rendezvous C++ Reference 306 | Chapter 9 Certified Message Delivery
(Sheet 2 of 3) Method Description Page
TibrvCmTransport::disallowListener() Cancel certified delivery to all 318 listeners at a specific correspondent. Deny subsequent certified delivery registration requests from those listeners.
TibrvCmTransport::disconnectFromRelayAgent() Disconnect a certified delivery 319 transport from its relay agent.
TibrvCmTransport::getDefaultTimeLimit() Get the default message time limit 321 for all outbound certified messages from a transport.
TibrvCmTransport::getLedgerName() Extract the ledger name of a 322 certified delivery transport.
TibrvCmTransport::getName() Extract the correspondent name 323 of a certified delivery transport or distributed queue member.
TibrvCmTransport::getRelayAgent() Extract the name of the relay 324 agent used by a certified delivery transport.
TibrvCmTransport::getRequestOld() Extract the request old messages 325 flag of a certified delivery transport.
TibrvCmTransport::getSyncLedger() Extract the sync ledger flag of a 326 certified delivery transport.
TibrvCmTransport::getTransport() Extract the transport employed 327 by a certified delivery transport or a distributed queue member.
TibrvCmTransport::removeListener() Unregister a specific listener at a 328 specific correspondent, and free associated storage in the sender’s ledger.
TibrvCmTransport::removeSendState() Reclaim ledger space from 330 obsolete subjects.
TIBCO Rendezvous C++ Reference TibrvCmTransport | 307
(Sheet 3 of 3) Method Description Page
TibrvCmTransport::reviewLedger() Query the ledger for stored items 331 related to a subject name.
TibrvCmTransport::send() Send a labeled message. 332
TibrvCmTransport::sendReply() Send a labeled reply message. 333
TibrvCmTransport::sendRequest() Send a labeled request message 334 and wait for a reply.
TibrvCmTransport::setDefaultTimeLimit() Set the default message time limit 336 for all outbound certified messages from a transport.
TibrvCmTransport::setPublisherInactivityDisc Set a time limit after which a 337 ardInterval() listening CM transport can discard state for inactive CM senders.
TibrvCmTransport::syncLedger() Synchronize the ledger to its 338 storage medium.
Inherited Methods
TibrvTransport::createInbox() TibrvTransport::destroy() TibrvTransport::isValid() TibrvTransport::getHandle() TibrvTransport::send() TibrvTransport::sendReply() TibrvTransport::sendRequest() TibrvTransport::setDescription()
Related Classes TibrvTransport on page 222 TibrvNetTransport on page 239 TibrvCmQueueTransport on page 354
TIBCO Rendezvous C++ Reference 308 | Chapter 9 Certified Message Delivery
TibrvCmTransport::addListener() Method
Declaration TibrvStatus addListener( const char* cmName, const char* subject);
Purpose Pre-register an anticipated listener.
Remarks Some sending programs can anticipate requests for certified delivery—even before the listening programs actually register. In such situations, the sending transport can pre-register listeners, so Rendezvous software begins storing outbound messages in the sender’s ledger; when the listener requests certified delivery, it receives the backlogged messages. If the correspondent with this cmName already receives certified delivery of this subject from this sender transport, then TibrvCmTransport::addListener() has no effect. If the correspondent with this cmName is disallowed, TibrvCmTransport::addListener() returns the status TIBRV_NOT_PERMITTED. You can call TibrvCmTransport::allowListener() to supersede the effect of a prior call to TibrvCmTransport::disallowListener(); then call TibrvCmTransport::addListener() again. It is not sufficient for a sender to use this method to anticipate listeners; the anticipated listening programs must also require old messages when creating certified delivery transports.
Parameter Description cmName Anticipate a listener from a correspondent with this reusable name.
subject Anticipate a listener for this subject. Wildcard subjects are illegal.
See Also Name, page 314 TibrvCmTransport::allowListener() on page 309 TibrvCmTransport::disallowListener() on page 318 TibrvCmTransport::removeListener() on page 328 Anticipating a Listener, page 141 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvCmTransport::allowListener() | 309
TibrvCmTransport::allowListener() Method
Declaration TibrvStatus allowListener( const char* cmName);
Purpose Invite the named receiver to reinstate certified delivery for its listeners, superseding the effect of any previous disallow calls.
Remarks Upon receiving the invitation to reinstate certified delivery, Rendezvous software at the listening program automatically sends new registration requests. The sending program accepts these requests, restoring certified delivery.
Parameter Description cmName Accept requests for certified delivery to listeners at the transport with this correspondent name.
See Also Name, page 314 TibrvCmTransport::disallowListener() on page 318 Disallowing Certified Delivery, page 143 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 310 | Chapter 9 Certified Message Delivery
TibrvCmTransport::connectToRelayAgent() Method
Declaration TibrvStatus connectToRelayAgent();
Purpose Connect a certified delivery transport to its designated relay agent.
Remarks Programs may specify a relay agent when creating a CM transport object. Connect calls are non-blocking; they immediately return control to the program, and asynchronously attempt to connect to the relay agent (continuing until they succeed, or until the program makes a disconnect call). When a transport attempts to connect to a relay agent, Rendezvous software automatically locates the relay agent process (if it exists). When the program successfully connects to the relay agent, they synchronize: • The transport receives a RELAY.CONNECTED advisory, informing it of successful contact with the relay agent. (Listen for all advisory messages on the ordinary TibrvTransport that the TibrvCmTransport employs.) (When a program cannot locate its relay agent, certified delivery software produces DELIVERY.NO_RESPONSE advisories; however, we recommend against designing programs to rely on this side effect.) • If the client transport is a CM listener, the relay agent listens to the same set of subjects on behalf of the client. The relay agent also updates its confirmation state to reflect the state of the transport. • If the client transport is a CM sender, the relay agent updates its acceptance state to reflect the state of the transport. The sending client updates its confirmation state to reflect the state of the relay agent. • The transport and relay agent exchange the CM data messages that they have been storing during the time they were disconnected.
We recommend that programs remain connected for a minimum of two minutes, to allow time for this synchronization to complete. (Two minutes is a generous estimate, which is sufficient for most situations. Actual time synchronization time can be much shorter, and varies with the number of stored messages and the degree to which protocol state has changed.) If the transport is already connected to its relay agent, then this method returns normally, and does not trigger a RELAY.CONNECTED advisory. TibrvCmTransport::create() automatically connects a transport to its designated relay agent upon creation.
TIBCO Rendezvous C++ Reference TibrvCmTransport::connectToRelayAgent() | 311
Errors The status code TIBRV_INVALID_ARG indicates that the transport does not have a relay agent.
See Also TibrvCmTransport::create() on page 312 TibrvCmTransport::disconnectFromRelayAgent() on page 319 Relay Agent, page 149 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 312 | Chapter 9 Certified Message Delivery
TibrvCmTransport::create() Method
Declaration TibrvStatus create( TibrvTransport* transport);
TibrvStatus create( TibrvTransport* transport, const char* cmName, tibrv_bool requestOld, const char* ledgerName = NULL, tibrv_bool syncLedger = TIBRV_FALSE, const char* relayAgent = NULL);
Purpose Create a transport for certified delivery.
Remarks This method creates a C certified delivery transport and stores its handle in the C++ object. The new certified delivery transport must employ a valid transport for network communications. The certified delivery transport remains valid until the program explicitly destroys it.
(Sheet 1 of 2) Parameter Description
transport The new TibrvCmTransport employs this transport object for network communications. Despite the declaration as a TibrvTransport, this object must be an instance of TibrvNetTransport. In particular, it cannot be the TibrvProcessTransport nor TibrvVcTransport. Destroying the TibrvCmTransport does not affect this TibrvTransport object.
cmName Bind this reusable name to the new TibrvCmTransport, so the TibrvCmTransport represents a persistent correspondent with this name. If non-NULL, the name must conform to the syntax rules for Rendezvous subject names. It cannot begin with reserved tokens. It cannot be a non-reusable name generated by another call to TibrvCmTransport::create(). It cannot be the empty string. If omitted or NULL, then TibrvCmTransport::create() generates a unique, non-reusable name for the duration of the transport. For more information, see Name on page 314.
TIBCO Rendezvous C++ Reference TibrvCmTransport::create() | 313
(Sheet 2 of 2) Parameter Description requestOld This parameter indicates whether a persistent correspondent requires delivery of messages sent to a previous certified delivery transport with the same name, for which delivery was not confirmed. Its value affects the behavior of other CM sending transports. If this parameter is TIBRV_TRUE and cmName is non-NULL, then the new TibrvCmTransport requires certified senders to retain unacknowledged messages sent to this persistent correspondent. When the new TibrvCmTransport begins listening to the appropriate subjects, the senders can complete delivery. (It is an error to supply true when cmName is NULL.) If this parameter is TIBRV_FALSE (or omitted), then the new TibrvCmTransport does not require certified senders to retain unacknowledged messages. Certified senders may delete those messages from their ledgers. ledgerName If this argument is non-NULL, then the new TibrvCmTransport uses a file-based ledger. The argument must represent a valid file name. Actual locations corresponding to relative file names conform to operating system conventions. We strongly discourage using the empty string as a ledger file name. If omitted or NULL, then the new TibrvCmTransport uses a process-based ledger. For more information, see Ledger File on page 314. syncLedger If this argument is TIBRV_TRUE, then operations that update the ledger file do not return until the changes are written to the storage medium. If this argument is TIBRV_FALSE (or omitted), the operating system writes changes to the storage medium asynchronously. relayAgent Designate the rvrad process with this name as the new transport’s relay agent. If NULL or omitted, the new TibrvCmTransport does not use a relay agent. If non-NULL, the relay agent name must conform to the syntax rules for reusable names. For details, see Reusable Names on page 146 in TIBCO Rendezvous Concepts. It is illegal for a relay agent to have the same name as a CM correspondent. We strongly discourage using the empty string as a relay agent name. For more information, see Relay Agent on page 314.
Method Forms With only a transport, create a transient correspondent, with a unique, non-reusable name. (Supplying NULL as the cmName has the same effect.) All other parameters are optional, with default values when omitted.
TIBCO Rendezvous C++ Reference 314 | Chapter 9 Certified Message Delivery
Name If cmName is NULL, then TibrvCmTransport::create() generates a unique, non-reusable name for the new certified delivery transport. If cmName is non-NULL, then the new transport binds that name. A correspondent can persist beyond transport destruction only when it has both a reusable name and a file-based ledger. For more information about the use of reusable names, see CM Correspondent Name on page 130 in TIBCO Rendezvous Concepts, and Persistent Correspondents on page 139 in TIBCO Rendezvous Concepts. For details of reusable name syntax, see Reusable Names on page 146 in TIBCO Rendezvous Concepts.
Relay Agent TibrvCmTransport::create() automatically connects a transport to its designated relay agent upon creation; see TibrvCmTransport::connectToRelayAgent() on page 310.
Ledger File Every certified delivery transport stores the state of its certified communications in a ledger. If ledgerFile is NULL, then the new transport stores its ledger exclusively in process-based storage. When you destroy the transport or the process terminates, all information in the ledger is lost. If ledgerFile specifies a valid file name, then the new transport uses that file for ledger storage. If the transport is destroyed or the process terminates with incomplete certified communications, the ledger file records that state. When a new transport binds the same reusable name, it reads the ledger file and continues certified communications from the state stored in the file. Even though a transport uses a ledger file, it may sometimes replicate parts of the ledger in process-based storage for efficiency; however, programmers cannot rely on this replication. The syncLedger parameter determines whether writing to the ledger file is a synchronous operation: • To specify synchronous writing, supply TIBRV_TRUE. Each time Rendezvous software writes a ledger item, the call does not return until the data is safely stored in the storage medium. • To specify asynchronous writing (the default), supply TIBRV_FALSE. Certified delivery calls may return before the data is safely stored in the storage medium, which results in greater speed at the cost of certainty. The ledger file might not accurately reflect program state in cases of hardware or operating system kernel failure (but it is accurate in cases of sudden program failure). Despite this small risk, we strongly recommend this option for maximum performance. A program that uses an asynchronous ledger file can explicitly synchronize it by calling TibrvCmTransport::syncLedger() on page 338.
TIBCO Rendezvous C++ Reference TibrvCmTransport::create() | 315
Destroying a transport with a file-based ledger always leaves the ledger file intact; it neither erases nor removes a ledger file. The ledger file must reside on the same host computer as the program that uses it.
See Also TibrvCmTransport::destroy() on page 317 TibrvCmTransport::connectToRelayAgent() on page 310
TIBCO Rendezvous C++ Reference 316 | Chapter 9 Certified Message Delivery
TibrvCmTransport::createInbox() Method
Declaration TibrvStatus createInbox( char* subjectString, tibrv_u32 subjectLimit) const;
Purpose Create a unique inbox subject name.
Remarks This convenience method extracts the network transport, and then calls TibrvTransport::createInbox(). For details, see the documentation for that method.
Parameter Description subjectString The program supplies a string buffer, and the method stores the new inbox subject string in that buffer.
subjectLimit The number of bytes that the program has allocated to receive the new inbox subject string.
See Also TibrvMsg::setReplySubject() on page 93 TibrvTransport::createInbox() on page 224
TIBCO Rendezvous C++ Reference TibrvCmTransport::destroy() | 317
TibrvCmTransport::destroy() Method
Declaration TibrvStatus destroy();
TibrvStatus destroyEx( TibrvCmTransportOnComplete* completeCB = NULL);
Purpose Destroy a certified delivery transport.
Remarks Destroying a certified delivery transport with a file-based ledger always leaves the ledger file intact; it neither erases nor removes a ledger file. This method automatically disconnects the transport from its relay agent before destroying the object; see TibrvCmTransport::disconnectFromRelayAgent().
Parameter Description completeCB Rendezvous software runs this completion callback immediately after all queued tasks are complete. Do not destroy the transport’s listeners until after this callback signals that cleanup has completed. See TibrvCmTransportOnComplete::onComplete on page 340.
Distributed To destroy a distributed queue transport, call destroyEx(). With the ordinary Queue destroy call, the distributed queue can lose reliable (non-certified) task messages before they are processed. The distributed queue needs the listeners, queues and dispatchers (associated with the transport) to remain operational—programs must wait until after the transport has been completely destroyed before destroying these associated objects.
See Also TibrvCmTransport::create() on page 312 TibrvCmTransport::disconnectFromRelayAgent() on page 319 TibrvCmTransportOnComplete on page 339
TIBCO Rendezvous C++ Reference 318 | Chapter 9 Certified Message Delivery
TibrvCmTransport::disallowListener() Method
Declaration TibrvStatus disallowListener( const char* cmName);
Purpose Cancel certified delivery to all listeners at a specific correspondent. Deny subsequent certified delivery registration requests from those listeners.
Remarks Disallowed listeners still receive subsequent messages from this sender, but delivery is not certified. In other words: • The first labeled message causes the listener to initiate registration. Registration fails, and the listener discards that labeled message. • The listener receives a REGISTRATION.NOT_CERTIFIED advisory, informing it that the sender has canceled certified delivery of all subjects. • If the sender’s ledger contains messages sent to the disallowed listener (for which this listener has not confirmed delivery), then Rendezvous software removes those ledger items, and does not attempt to redeliver those messages. • Rendezvous software presents subsequent messages (from the canceling sender) to the listener without a sequence number, to indicate that delivery is not certified. Senders can promptly revoke the acceptance of certified delivery by calling TibrvCmTransport::disallowListener() within the callback method that processes the REGISTRATION.REQUEST advisory. This method disallows a correspondent by name. If the correspondent terminates, and another process instance (with the same reusable name) takes its place, the new process is still disallowed by this sender. To supersede the effect of TibrvCmTransport::disallowListener(), call TibrvCmTransport::allowListener() on page 309.
Parameter Description cmName Cancel certified delivery to listeners of the transport with this name.
See Also Name, page 314 TibrvCmTransport::allowListener() on page 309 Disallowing Certified Delivery, page 143 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvCmTransport::disconnectFromRelayAgent() | 319
TibrvCmTransport::disconnectFromRelayAgent() Method
Declaration TibrvStatus disconnectFromRelayAgent();
Purpose Disconnect a certified delivery transport from its relay agent.
Remarks Disconnect calls are non-blocking; they immediately return control to the program, and asynchronously proceed with these clean-up tasks: • If the client transport is a CM listener, the relay agent attempts to synchronize its listening state with the transport (to assure that the relay agent adequately represents the listening interest of the client). • The transport stops communicating with the relay agent. • The transport stores subsequent outbound events—including data messages and protocol state changes. If the transport is a certified sender, it cancels its request for delivery confirmation of outstanding unconfirmed messages. (See also, Requesting Confirmation on page 137 in TIBCO Rendezvous Concepts.) • The relay agent stores subsequent inbound events for the transport— including data messages and protocol state changes. • A transport that explicitly disconnects without terminating receives a RELAY.DISCONNECTED advisory, informing it that is safe to sever the physical network connection. (Terminating transports never receive this advisory; instead, it is safe to sever the connection when the destroy call returns.)
TibrvCmTransport::destroy() automatically disconnects a CM transport from its relay agent before termination.
Errors The status code TIBRV_INVALID_ARG indicates that the transport does not have a relay agent.
See Also TibrvCmTransport::connectToRelayAgent() on page 310 TibrvCmTransport::destroy() on page 317 Relay Agent, page 149 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 320 | Chapter 9 Certified Message Delivery
TibrvCmTransport::expireMessages() Method
Declaration TibrvStatus expireMessages( const char* subject, tibrv_u64 sequenceNumber);
Purpose Mark specified outbound CM messages as expired.
Remarks This call checks the ledger for messages that match both the subject and sequence number criteria, and immediately marks them as expired. Once a message has expired, the CM transport no longer attempts to redeliver it to registered listeners. Rendezvous software presents each expired message to the sender in a DELIVERY.FAILED advisory. Each advisory includes all the fields of an expired message. (This call can cause many messages to expire simultaneously.)
Use with extreme caution. This call exempts the expired messages from certified delivery semantics. It is appropriate only in very few situations. For example, consider an application program in which an improperly formed CM message causes registered listeners to exit unexpectedly. When the listeners restart, the sender attempts to redeliver the offending message, which again causes the listeners to exit. To break this cycle, the sender can expire the offending message (along with all prior messages bearing the same subject).
Parameter Description subject Mark messages with this subject. Wildcards subjects are permitted, but must exactly reflect the send subject of the message. For example, if the program sends to A.* then you may expire messages with subject A.* (however, A.> does not resolve to match A.*).
sequenceNumber Mark messages with sequence numbers less than or equal to this value.
See Also DELIVERY.FAILED on page 276 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvCmTransport::getDefaultTimeLimit() | 321
TibrvCmTransport::getDefaultTimeLimit() Method
Declaration TibrvStatus getDefaultTimeLimit( tibrv_f64& timeLimit) const;
Purpose Get the default message time limit for all outbound certified messages from a transport.
Remarks Every labeled message has a time limit, after which the sender no longer certifies delivery. Sending programs can explicitly set the time limit on a message (see TibrvCmMsg::setTimeLimit() on page 349). If a time limit is not already set for the outbound message, the transport sets it to the transport’s default time limit (extractable with this method); if this default is not set for the transport (nor for the message), the default time limit is zero (no time limit). Time limits represent the minimum time that certified delivery is in effect.
Parameter Description timeLimit The program supplies a variable, and the method stores the time limit in that variable.
See Also TibrvCmTransport::setDefaultTimeLimit() on page 336 TibrvCmMsg::setTimeLimit() on page 349
TIBCO Rendezvous C++ Reference 322 | Chapter 9 Certified Message Delivery
TibrvCmTransport::getLedgerName() Method
Declaration TibrvStatus getLedgerName( const char*& ledgerName) const;
Purpose Extract the ledger name of a certified delivery transport.
Parameter Description ledgerName The program supplies a variable, and the method stores the ledger name in that variable.
Errors The status code TIBRV_ARG_CONFLICT indicates that the transport does not have a ledger file.
See Also Ledger File, page 314 TibrvCmTransport::create() on page 312
TIBCO Rendezvous C++ Reference TibrvCmTransport::getName() | 323
TibrvCmTransport::getName() Method
Declaration TibrvStatus getName( const char*& cmName) const;
Purpose Extract the correspondent name of a certified delivery transport or distributed queue member.
Parameter Description cmName The program supplies a variable, and the method stores the correspondent name in that variable.
See Also Name, page 314 TibrvCmTransport::create() on page 312 TibrvCmQueueTransport::create() on page 357
TIBCO Rendezvous C++ Reference 324 | Chapter 9 Certified Message Delivery
TibrvCmTransport::getRelayAgent() Method
Declaration TibrvStatus getRelayAgent( const char*& relayAgent) const;
Purpose Extract the name of the relay agent used by a certified delivery transport.
Parameter Description relayAgent The program supplies a variable, and the method stores the relay agent name in that variable.
Errors The status code TIBRV_ARG_CONFLICT indicates that the transport does not have a relay agent.
See Also Relay Agent, page 314 TibrvCmTransport::create() on page 312
TIBCO Rendezvous C++ Reference TibrvCmTransport::getRequestOld() | 325
TibrvCmTransport::getRequestOld() Method
Declaration TibrvStatus getRequestOld( tibrv_bool& requestOld) const;
Purpose Extract the request old messages flag of a certified delivery transport.
Parameter Description requestOld The program supplies a variable, and the method stores the request old messages flag name in that variable.
See Also requestOld on page 313 TibrvCmTransport::create() on page 312
TIBCO Rendezvous C++ Reference 326 | Chapter 9 Certified Message Delivery
TibrvCmTransport::getSyncLedger() Method
Declaration TibrvStatus getSyncLedger( tibrv_bool& syncLedger) const;
Purpose Extract the sync ledger flag of a certified delivery transport.
Parameter Description syncLedger The program supplies a variable, and the method stores the sync ledger flag name in that variable.
Errors The status code TIBRV_ARG_CONFLICT indicates that the transport does not have a ledger file.
See Also Ledger File, page 314 TibrvCmTransport::create() on page 312
TIBCO Rendezvous C++ Reference TibrvCmTransport::getTransport() | 327
TibrvCmTransport::getTransport() Method
Declaration TibrvTransport* getTransport() const;
Purpose Extract the transport employed by a certified delivery transport or a distributed queue member.
See Also TibrvTransport on page 222 TibrvNetTransport on page 239 TibrvCmTransport::create() on page 312 TibrvCmQueueTransport::create() on page 357
TIBCO Rendezvous C++ Reference 328 | Chapter 9 Certified Message Delivery
TibrvCmTransport::removeListener() Method
Declaration TibrvStatus removeListener( const char* cmName, const char* subject);
Purpose Unregister a specific listener at a specific correspondent, and free associated storage in the sender’s ledger.
Remarks This method cancels certified delivery of the specific subject to the correspondent with this name. The listening correspondent may subsequently re-register for certified delivery of the subject. (In contrast, TibrvCmTransport::disallowListener() cancels certified delivery of all subjects to the correspondent, and prohibits re-registration.) Senders can call this method when the ledger item for a listening correspondent has grown very large. Such growth indicates that the listener is not confirming delivery, and may have terminated. Removing the listener reduces the ledger size by deleting messages stored for the listener. When a sending program calls this method, certified delivery software in the sender behaves as if the listener had closed the endpoint for the subject. The sending program deletes from its ledger all information about delivery of the subject to the correspondent with this cmName. The sending program receives a REGISTRATION.CLOSED advisory, to trigger any operations in the callback method for the advisory. If the listening correspondent is available (running and reachable), it receives a REGISTRATION.NOT_CERTIFIED advisory, informing it that the sender no longer certifies delivery of the subject. If the correspondent with this name does not receive certified delivery of the subject from this sender TibrvCmTransport, then TibrvCmTransport::removeListener() the status code TIBRV_INVALID_SUBJECT.
Parameter Description cmName Cancel certified delivery of the subject to listeners of this correspondent.
subject Cancel certified delivery of this subject to the named listener. Wildcard subjects are illegal.
See Also Name, page 314 TibrvCmTransport::addListener() on page 308
TIBCO Rendezvous C++ Reference TibrvCmTransport::removeListener() | 329
TibrvCmTransport::disallowListener() on page 318 Canceling Certified Delivery, page 142 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 330 | Chapter 9 Certified Message Delivery
TibrvCmTransport::removeSendState() Method
Declaration TibrvStatus removeSendState( const char* subject);
Purpose Reclaim ledger space from obsolete subjects.
Background In some programs subject names are useful only for a limited time; after that time, they are never used again. For example, consider a server program that sends certified reply messages to client inbox names; it only sends one reply message to each inbox, and after delivery is confirmed and complete, that inbox name is obsolete. Nonetheless, a record for that inbox name remains in the server’s ledger. As such obsolete records accumulate, the ledger size grows. To counteract this growth, programs can use this method to discard obsolete subject records from the ledger. The DELIVERY.COMPLETE advisory is a good opportunity to clear the send state of an obsolete subject. Another strategy is to review the ledger periodically, sweeping to detect and remove all obsolete subjects.
Do not use this method to clear subjects that are still in use.
Parameter Description subject Remove send state for this obsolete subject.
Remarks As a side-effect, this method resets the sequence numbering for the subject, so the next message sent on the subject would be number 1. In proper usage, this side-effect is never detected, since obsolete subjects are truly obsolete.
See Also TibrvCmTransport::reviewLedger() on page 331 TibrvCmTransport::send() on page 332 DELIVERY.COMPLETE on page 274 in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvCmTransport::reviewLedger() | 331
TibrvCmTransport::reviewLedger() Method
Declaration TibrvStatus reviewLedger( TibrvCmReviewCallback* reviewCallback, const char* subject, const void* closure=NULL);
Purpose Query the ledger for stored items related to a subject name.
Remarks The callback method receives one message for each matching subject of outbound messages stored in the ledger. For example, when FOO.* is the subject, TibrvCmTransport::reviewLedger() calls its callback method separately for each matching subject—once for FOO.BAR, once for FOO.BAZ, and once for FOO.BOX. However, if the callback method returns non-NULL, then TibrvCmTransport::reviewLedger() returns immediately. If the ledger does not contain any matching items, TibrvCmTransport::reviewLedger() returns normally without calling the callback method. For information about the content and format of the callback messages, see TibrvCmReviewCallback::onLedgerMsg() on page 342.
Parameter Description reviewCallback This object receives the review messages.
subject Query for items related to this subject name. If this subject contains wildcard characters (* or >), then review all items with matching subject names. The callback method receives a separate message for each matching subject in the ledger.
closure Pass this closure data to the review callback method.
See Also TibrvCmReviewCallback::onLedgerMsg() on page 342
TIBCO Rendezvous C++ Reference 332 | Chapter 9 Certified Message Delivery
TibrvCmTransport::send() Method
Declaration TibrvStatus send( const TibrvMsg& msg);
Purpose Send a labeled message.
Remarks This method sends the message, along with its certified delivery protocol information: the correspondent name of the TibrvCmTransport, a sequence number, and a time limit. The protocol information remains on the message within the sending program, and also travels with the message to all receiving programs. Programs can explicitly set the message time limit; see TibrvCmMsg::setTimeLimit() on page 349. If a time limit is not already set for the outbound message, this method sets it to the transport’s default time limit (see TibrvCmTransport::setDefaultTimeLimit() on page 336); if that default is not set for the transport, the default time limit is zero (no time limit).
Parameter Description msg Send this message. Wildcard subjects are illegal.
See Also TibrvCmTransport::sendReply() on page 333 TibrvCmTransport::sendRequest() on page 334 TibrvCmTransport::setDefaultTimeLimit() on page 336 TibrvCmMsg::setTimeLimit() on page 349
TIBCO Rendezvous C++ Reference TibrvCmTransport::sendReply() | 333
TibrvCmTransport::sendReply() Method
Declaration TibrvStatus sendReply( const TibrvMsg& replyMsg, const TibrvMsg& requestMsg);
Purpose Send a labeled reply message.
Remarks This convenience call extracts the reply subject of an inbound request message, and sends a labeled outbound reply message to that subject. In addition to the convenience, this call is marginally faster than using separate calls to extract the subject and send the reply. This method can send a labeled reply to an ordinary message. This method automatically registers the requesting CM transport, so the reply message is certified.
Parameter Description replyMsg Send this outbound reply message.
requestMsg Send a reply to this inbound request message; extract its reply subject to use as the subject of the outbound reply message. If this message has a wildcard reply subject, the method produces an error.
Give special attention to the order of the arguments to this method. Reversing the inbound and outbound messages can cause an infinite loop, in which the program repeatedly resends the inbound message to itself (and all other recipients).
See Also TibrvCmTransport::send() on page 332 TibrvCmTransport::sendRequest() on page 334
TIBCO Rendezvous C++ Reference 334 | Chapter 9 Certified Message Delivery
TibrvCmTransport::sendRequest() Method
Declaration TibrvStatus sendRequest( const TibrvMsg& requestMsg, TibrvMsg& replyMsg, tibrv_f64 timeout);
Purpose Send a labeled request message and wait for a reply.
Blocking can Stall Event Dispatch
This call blocks all other activity on its program thread. If appropriate, programmers must ensure that other threads continue dispatching events on its queues.
Parameter Description requestMsg Send this request message. Wildcard subjects are illegal.
replyMsg The program supplies a variable, and the method stores the inbound reply in that variable. The program need not create the reply message, nor allocate space for it. However, the program must destroy the reply message, even though it did not create it.
timeout Maximum time (in seconds) that this call can block while waiting for a reply. TIBRV_WAIT_FOREVER (-1) indicates no timeout (wait without limit for a reply).
Remarks Programs that receive and process the request message cannot determine that the sender has blocked until a reply arrives. The sender and receiver must already have a certified delivery agreement, otherwise the request is not certified. The request message must have a valid destination subject; see TibrvMsg::setSendSubject() on page 94. A certified request does not necessarily imply a certified reply; the replying program determines the type of reply message that it sends.
TIBCO Rendezvous C++ Reference TibrvCmTransport::sendRequest() | 335
Operation This method operates in several synchronous steps: 1. Create a TibrvCmListener that listens for messages on the reply subject of requestMsg. 2. Label and send the outbound requestMsg. 3. Block until the listener receives a reply; if the time limit expires before a reply arrives, then return the status code TIBRV_TIMEOUT. (The reply event uses a private queue that is not accessible to the program.) 4. Store the reply in the variable specified by the replyMsg parameter. 5. Return.
See Also TibrvCmTransport::send() on page 332 TibrvCmTransport::sendReply() on page 333
TIBCO Rendezvous C++ Reference 336 | Chapter 9 Certified Message Delivery
TibrvCmTransport::setDefaultTimeLimit() Method
Declaration TibrvStatus setDefaultTimeLimit( tibrv_f64 timeLimit);
Purpose Set the default message time limit for all outbound certified messages from a transport.
Remarks Every labeled message has a time limit, after which the sender no longer certifies delivery. Sending programs can explicitly set the time limit on a message (see TibrvCmMsg::setTimeLimit() on page 349). If a time limit is not already set for the outbound message, the transport sets it to the transport’s default time limit (set with this method); if this default is not set for the transport, the default time limit is zero (no time limit). Time limits represent the minimum time that certified delivery is in effect.
Parameter Description timeLimit Use this time limit (in whole seconds). The time limit must be non-negative.
See Also TibrvCmTransport::getDefaultTimeLimit() on page 321 TibrvCmMsg::setTimeLimit() on page 349
TIBCO Rendezvous C++ Reference TibrvCmTransport::setPublisherInactivityDiscardInterval() | 337
TibrvCmTransport::setPublisherInactivityDiscardInterval() Method
Declaration TibrvStatus setPublisherInactivityDiscardInterval( tibrv_i32 timeout);
Purpose Set a time limit after which a listening CM transport can discard state for inactive CM senders.
Remarks The timeout value limits the time that can elapse during which such a sender does not send a message. When the elapsed time exceeds this limit, the listening transport declares the sender inactive, and discards internal state corresponding to the sender.
We discourage programmers from using this call except to solve a very specific problem, in which a long-running CM listener program accumulates state for a large number of obsolete CM senders with non-reusable names. Before using this call, review every subject for which the CM transport has a listener; ensure that only CM senders with non-reusable names send to those subjects. (If senders with reusable names send messages to such subjects, the listening transport can discard their state, and incorrect behavior can result.)
Parameter Description timeout Use this time limit (in whole seconds). The time limit must be non-negative.
TIBCO Rendezvous C++ Reference 338 | Chapter 9 Certified Message Delivery
TibrvCmTransport::syncLedger() Method
Declaration TibrvStatus syncLedger();
Purpose Synchronize the ledger to its storage medium.
Remarks When this method returns, the transport’s current state is safely stored in the ledger file. Transports that use synchronous ledger files need not call this method, since the current state is automatically written to the storage medium before returning. Transports that use process-based ledger storage need not call this method, since they have no ledger file.
Errors The status code TIBRV_INVALID_ARG indicates that the transport does not have a ledger file.
See Also Ledger File, page 314 TibrvCmTransport::create() on page 312 TibrvCmTransport::getSyncLedger() on page 326
TIBCO Rendezvous C++ Reference TibrvCmTransportOnComplete | 339
TibrvCmTransportOnComplete Class
Declaration class TibrvCmTransportOnComplete
Purpose Callback class to signal completion of clean-up tasks after destroying a CM or CMQ transport.
Method Description Page
TibrvCmTransportOnComplete::onComplete Destroying a CM or CMQ transport 278 involves cleanup operations that can sometimes be lengthy. Programs can define this method to discover when the cleanup has completed.
See Also TibrvCmTransport::destroy() on page 317
TIBCO Rendezvous C++ Reference 340 | Chapter 9 Certified Message Delivery
TibrvCmTransportOnComplete::onComplete Method
Declaration virtual void onComplete( TibrvCmTransport* destroyedTransport) = 0;
Purpose Destroying a CM or CMQ transport involves cleanup operations that can sometimes be lengthy. Programs can define this method to discover when the cleanup has completed.
Remarks Programs must not destroy the transport’s listeners, nor any queue nor dispatcher that pertains to the transport, until after this callback signals that cleanup has completed.
Parameter Description destroyedTransport This parameter receives the transport object. However, by the time this method runs, the transport is already destroyed; this method cannot use the transport object in Rendezvous calls.
See Also TibrvCmTransport::destroy() on page 317
TIBCO Rendezvous C++ Reference TibrvCmReviewCallback | 341
TibrvCmReviewCallback Class
Declaration class TibrvCmReviewCallback
Purpose Process ledger review messages.
Remarks Implement this interface to process ledger review messages.
Method Description Page
TibrvCmReviewCallback::onLedgerMsg() Programs define this method to process 291 ledger review messages.
See Also TibrvCmTransport::reviewLedger() on page 331
TIBCO Rendezvous C++ Reference 342 | Chapter 9 Certified Message Delivery
TibrvCmReviewCallback::onLedgerMsg() Method
Declaration virtual void* onLedgerMsg( TibrvCmTransport* cmTransport, const char* subject, TibrvMsg& msg, void* closure) = 0;
Purpose Programs define this method to process ledger review messages.
Remarks TibrvCmTransport::reviewLedger() calls this callback method once for each matching subject stored in the ledger. To continue reviewing the ledger, return NULL from this callback method. To stop reviewing the ledger, return non-NULL from this callback method; TibrvCmTransport::reviewLedger() cancels the review and returns immediately.
Parameter Description cmTransport This parameter receives the transport.
subject This parameter receives the subject for this ledger item.
msg This parameter receives a summary message describing the delivery status of messages in the ledger. The table Message Content on page 342 describes the fields of the summary message.
closure This parameter receives closure data that the program supplied to TibrvCmTransport::reviewLedger().
Message This callback method receives ledger summary messages with these fields. Content
(Sheet 1 of 2) Field Name Description subject The subject that this message summarizes. This field has datatype TIBRVMSG_STRING.
TIBCO Rendezvous C++ Reference TibrvCmReviewCallback::onLedgerMsg() | 343
(Sheet 2 of 2) Field Name Description seqno_last_sent The sequence number of the most recent message sent with this subject name. This field has datatype TIBRVMSG_U64. total_msgs The total number of messages stored at this subject name. This field has datatype TIBRVMSG_U32. total_size The total storage (in bytes) occupied by all messages with this subject name. If the ledger contains several messages with this subject name, then this field sums the storage space over all of them. This field has datatype TIBRVMSG_U64. listener Each summary message can contain one or more fields named listener. Each listener field contains a nested submessage with details about a single registered listener. This field has datatype TIBRVMSG_MSG. listener.name Within each listener submessage, the name field contains the name of the listener transport. This field has datatype TIBRVMSG_STRING. listener.last_confirmed Within each listener submessage, the last_confirmed field contains the sequence number of the last message for which the listener confirmed delivery. This field has datatype TIBRVMSG_U64.
See Also TibrvCmTransport::reviewLedger() on page 331
TIBCO Rendezvous C++ Reference 344 | Chapter 9 Certified Message Delivery
TibrvCmMsg Class
Declaration class TibrvCmMsg
Purpose Define methods to manipulate labeled messages.
Remarks This class is a collection of accessor methods. Programs do not create instances of TibrvCmMsg. Instead, programs use its static methods to get and set certified delivery information of TibrvMsg objects.
Method Description Page
TibrvCmMsg::getSender() Extract the correspondent name of 345 the sender from a certified message.
TibrvCmMsg::getSequence() Extract the sequence number from a 346 certified message.
TibrvCmMsg::getTimeLimit() Extract the message time limit from 348 a certified message.
TibrvCmMsg::setTimeLimit() Set the message time limit of a 349 certified message.
See Also TibrvMsg on page 39
TIBCO Rendezvous C++ Reference TibrvCmMsg::getSender() | 345
TibrvCmMsg::getSender() Method
Declaration static TibrvStatus getSender( TibrvMsg& msg, const char*& name);
Purpose Extract the correspondent name of the sender from a certified message.
Parameter Description msg Extract the sender name from this message.
name The program supplies a variable. The method stores the name in that variable.
Status This method returns a status code that discriminates between labeled messages and other messages. • If the message is from a CM sender, then TibrvCmMsg::getSender() returns the status code TIBRV_OK and yields a valid CM correspondent name. • If the message is not from a CM sender, then TibrvCmMsg::getSender() returns the status code TIBRV_NOT_FOUND.
See Also TibrvCmTransport::create() on page 312 TibrvCmTransport::getName() on page 323
TIBCO Rendezvous C++ Reference 346 | Chapter 9 Certified Message Delivery
TibrvCmMsg::getSequence() Method
Declaration static TibrvStatus getSequence( TibrvMsg& msg, tibrv_u64& sequenceNumber);
Purpose Extract the sequence number from a certified message.
Remarks Rendezvous certified delivery sending methods automatically generate positive sequence numbers for outbound labeled messages. In receiving programs, zero is a special value, indicating that an inbound message is not certified.
Parameter Description msg Extract the sequence number from this message.
sequenceNumber The program supplies a variable. The method stores the sequence number in that variable.
Status This method returns a status code that discriminates between certified messages (with a certified delivery agreement) and other messages. • If the message is from a CM sender, and the CM listener is registered for certified delivery with that sender, then TibrvCmMsg::getSequence() returns the status code TIBRV_OK and yields a valid sequence number. • If the message is from a CM sender, but the listener is not registered for certified delivery, then TibrvCmMsg::getSequence() in the context of a TibrvCmMsgCallback::onCmMsg() method returns the status code TIBRV_NOT_FOUND. (In any other context, it returns the actual sequence number stored on the message.) Notice that the first labeled message that a program receives on a subject might not be certified; that is, the sender has not registered a certified delivery agreement with the listener. If appropriate, the certified delivery library automatically requests that the sender register the listener for certified delivery. (See Discovery and Registration for Certified Delivery on page 134 in TIBCO Rendezvous Concepts.) A labeled but uncertified message can also result when the sender explicitly disallows or removes the listener. • If the message is not from a CM sender, then TibrvCmMsg::getSequence() (in any context) returns the status code TIBRV_NOT_FOUND.
TIBCO Rendezvous C++ Reference TibrvCmMsg::getSequence() | 347
Release 5 In release 6 (and later) the sequence number is a 64-bit unsigned integer, while in Interaction older releases (5 and earlier) it is a 32-bit unsigned integer. When 32-bit senders overflow the sequence number, behavior is undefined. When 64-bit senders send sequence numbers greater than 32 bits, 32-bit receivers detect malformed label information, and process the message as an ordinary reliable message (uncertified and unlabeled).
See Also TibrvCmTransport::send() on page 332
TIBCO Rendezvous C++ Reference 348 | Chapter 9 Certified Message Delivery
TibrvCmMsg::getTimeLimit() Method
Declaration static TibrvStatus getTimeLimit( TibrvMsg& msg, tibrv_f64& timeLimit);
Purpose Extract the message time limit from a certified message.
Remarks Programs can explicitly set the message time limit (see TibrvCmMsg::setTimeLimit() on page 349). Zero is a special value, indicating no time limit. If a time limit is not set for a message, this method returns the status code TIBRV_NOT_FOUND. This situation can occur only for unsent outbound messages, and for inbound unlabeled messages. Time limits represent the minimum time that certified delivery is in effect. This value represents the total time limit of the message, not the time remaining.
Parameter Description msg Extract the time limit from this message.
timeLimit The program supplies a variable. The method stores the time limit in that variable.
See Also TibrvCmTransport::send() on page 332 TibrvCmMsg::setTimeLimit() on page 349
TIBCO Rendezvous C++ Reference TibrvCmMsg::setTimeLimit() | 349
TibrvCmMsg::setTimeLimit() Method
Declaration static TibrvStatus setTimeLimit ( TibrvMsg& msg, tibrv_f64 timeLimit);
Purpose Set the message time limit of a certified message.
Remarks Every labeled message has a time limit, after which the sender no longer certifies delivery. Sending programs can explicitly set the message time limit using this method. If a time limit is not already set for the outbound message, TibrvCmTransport::send() sets it to the transport’s default time limit (see TibrvCmTransport::setDefaultTimeLimit() on page 336); if that default is not set for the transport, the default time limit is zero (no time limit). Time limits represent the minimum time that certified delivery is in effect. It is meaningless for receiving programs to call this method.
Parameter Description msg Set the time limit of this message.
timeLimit Use this time limit (in whole seconds) for the message. The time limit must be non-negative.
See Also TibrvCmTransport::getDefaultTimeLimit() on page 321 TibrvCmTransport::setDefaultTimeLimit() on page 336 TibrvCmMsg::getTimeLimit() on page 348
TIBCO Rendezvous C++ Reference 350 | Chapter 9 Certified Message Delivery
TibrvCmMsgCallback Class
Declaration class TibrvCmMsgCallback : public TibrvCallback
Purpose Process inbound messages (CM listener events).
Remarks Implement this interface to process inbound certified delivery messages.
Method Description Page
TibrvCmMsgCallback::onCmMsg() Process inbound certified delivery messages (CM 351 listener events).
Related Classes TibrvCallback on page 135 TibrvMsgCallback on page 147
See Also TibrvCmListener::create() on page 299
TIBCO Rendezvous C++ Reference TibrvCmMsgCallback::onCmMsg() | 351
TibrvCmMsgCallback::onCmMsg() Method
Declaration virtual void onCmMsg( TibrvCmListener* cmListener, TibrvMsg& msg) = 0;
Purpose Process inbound certified delivery messages (CM listener events).
Remarks Implement this method to process inbound certified delivery messages.
Parameter Description cmListener This parameter receives the listener event.
msg This parameter receives the inbound message.
CM Label The callback method for certified delivery messages can use CM label information Information to discriminate these situations: •If TibrvCmMsg::getSender() returns status code TIBRV_NOT_FOUND, then the message uses the reliable protocol (that is, it was sent from an ordinary transport). •If TibrvCmMsg::getSender() returns a valid sender name, then the message uses the certified delivery protocol (that is, it is a labeled message, sent from a CM transport). Once the callback method determines that the message uses the certified delivery protocol, it can discriminate further: —If TibrvCmMsg::getSequence() returns status code TIBRV_NOT_FOUND, then the listener is not registered for certified delivery from the sender. —If TibrvCmMsg::getSequence() returns TIBRV_OK, then a certified delivery agreement is in effect for this subject with the sender.
See Also TibrvCmListener::create() on page 299 TibrvCmMsg::getSender() on page 345 TibrvCmMsg::getSequence() on page 346 TibrvCmMsg::getTimeLimit() on page 348
TIBCO Rendezvous C++ Reference 352 | Chapter 9 Certified Message Delivery
TIBCO Rendezvous C++ Reference | 353
Chapter 10 Distributed Queue
Programs can use distributed queues for one of n certified delivery to a group of worker processes. A distributed queue is a group of TibrvCmQueueTransport objects, each in a separate process. From the outside, a distributed queue appears as though a single transport object; inside, the group members act in concert to process inbound task messages. Ordinary transports and CM transports can send task messages to the group. Notice that the senders are not group members, and do not do anything special to send messages to a group; rather, they send messages to ordinary subject names. Inside the group, the member acting as scheduler assigns each task message to exactly one of the other members (which act as workers); only that worker processes the task message. Each member uses CM listener objects to receive task messages. Distributed queues depend upon the certified delivery methods and the fault tolerance methods.
We do not recommend sending messages across network boundaries to a distributed queue, nor distributing queue members across network boundaries. However, when crossing network boundaries in either of these ways, you must configure the Rendezvous routing daemons to exchange _RVCM and _RVCMQ administrative messages. For details, see Distributed Queues on page 393 in TIBCO Rendezvous Administration.
See Also Distributed Queue, page 161 in TIBCO Rendezvous Concepts
Topics
• TibrvCmQueueTransport, page 354
TIBCO Rendezvous C++ Reference 354 | Chapter 10 Distributed Queue
TibrvCmQueueTransport Class
Declaration class TibrvCmQueueTransport : public TibrvCmTransport TibrvCmQueueTransport(); // Create empty. virtual ~TibrvCmQueueTransport(); // Destroy and reclaim storage.
Purpose Coordinate a distributed queue for one-of-n delivery.
Remarks Each TibrvCmQueueTransport object employs a TibrvTransport for network communications. The TibrvCmQueueTransport adds the accounting and coordination mechanisms needed for one-of-n delivery. Several TibrvCmQueueTransport objects can employ one TibrvTransport, which also remains available for its own ordinary listeners and for sending ordinary messages. The constructor creates a hollow object; TibrvCmQueueTransport::create() makes it operational. The destructor calls the destroy method, unless the C object is already destroyed. Programs must explicitly destroy each TibrvCmQueueTransport object. Destroying a TibrvCmQueueTransport invalidates any certified listeners using that transport (while preserving their certified delivery agreements). All members of a distributed queue must listen to exactly the same set of subjects. See Enforcing Identical Subscriptions on page 164 in TIBCO Rendezvous Concepts. Scheduler recovery and task rescheduling are available only when the task message is a certified message (that is, a certified delivery agreement is in effect between the task sender and the distributed queue transport scheduler).
Disabled Although TibrvCmQueueTransport is a subclass of TibrvCmTransport, all Methods methods related to sending messages are disabled in TibrvCmQueueTransport; for a list, see Disabled Methods on page 356. See also Certified Delivery Behavior in Queue Members on page 163 in TIBCO Rendezvous Concepts.
Method Description Page
TibrvCmQueueTransport::create() Create a transport as a distributed 357 queue member.
TibrvCmQueueTransport::destroy() Destroy a distributed queue member 361 object.
TibrvCmQueueTransport::getCompleteTime() Extract the worker complete time 362 limit of a distributed queue member.
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport | 355
Method Description Page
TibrvCmQueueTransport::getUnassignedMess Extract the number of unassigned 363 ageCount() task messages from a distributed queue transport.
TibrvCmQueueTransport::getWorkerWeight() Extract the worker weight of a 364 distributed queue member.
TibrvCmQueueTransport::getWorkerTasks() Extract the worker task capacity of a 365 distributed queue member.
TibrvCmQueueTransport::setCompleteTime() Set the worker complete time limit of 366 a distributed queue member.
TibrvCmQueueTransport::setTaskBacklogLim Set the scheduler task queue limits of 367 it...() a distributed queue transport.
TibrvCmQueueTransport::setWorkerWeight() Set the worker weight of a distributed 368 queue member.
TibrvCmQueueTransport::setWorkerTasks() Set the worker task capacity of a 369 distributed queue member.
(Sheet 1 of 2) Inherited Methods
Legal Methods TibrvCmTransport::getName() TibrvCmTransport::getTransport()
TibrvTransport::destroy() TibrvTransport::isValid() TibrvTransport::getHandle() TibrvTransport::setDescription()
TIBCO Rendezvous C++ Reference 356 | Chapter 10 Distributed Queue
(Sheet 2 of 2) Inherited Methods
Disabled Methods TibrvCmTransport::addListener() TibrvCmTransport::allowListener() TibrvCmTransport::connectToRelayAgent() TibrvCmTransport::disallowListener() TibrvCmTransport::disconnectFromRelayAgent() TibrvCmTransport::getDefaultTimeLimit() TibrvCmTransport::getLedgerName() TibrvCmTransport::getRelayAgent() TibrvCmTransport::getRequestOld() TibrvCmTransport::getSyncLedger() TibrvCmTransport::removeListener() TibrvCmTransport::removeSendState() TibrvCmTransport::reviewLedger() TibrvCmTransport::send() TibrvCmTransport::sendReply() TibrvCmTransport::sendRequest() TibrvCmTransport::setDefaultTimeLimit() TibrvCmTransport::syncLedger()
TibrvTransport::createInbox() TibrvTransport::send() TibrvTransport::sendReply() TibrvTransport::sendRequest()
Related Classes TibrvTransport on page 222 TibrvNetTransport on page 239 TibrvCmTransport on page 305
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::create() | 357
TibrvCmQueueTransport::create() Method
Declaration TibrvStatus create( TibrvTransport* transport, const char* cmName, tibrv_u32 workerWeight = TIBRVCM_DEFAULT_WORKER_WEIGHT, tibrv_u32 workerTasks = TIBRVCM_DEFAULT_WORKER_TASKS, tibrv_u16 schedulerWeight = TIBRVCM_DEFAULT_SCHEDULER_WEIGHT, tibrv_f64 schedulerHeartbeat = TIBRVCM_DEFAULT_SCHEDULER_HB, tibrv_f64 schedulerActivation = TIBRVCM_DEFAULT_SCHEDULER_ACTIVE );
Purpose Create a transport as a distributed queue member.
Remarks This method creates a new C distributed queue member, and stores it in the C++ object. The new TibrvCmQueueTransport must employ a valid TibrvTransport for network communications.
(Sheet 1 of 3) Parameter Description
transport The new TibrvCmQueueTransport employs this TibrvTransport object for network communications. Destroying the TibrvCmQueueTransport does not affect this transport.
cmName Bind this reusable name to the new transport object, which becomes a member of the distributed queue with this name. The name must be non-NULL, and conform to the syntax rules for Rendezvous subject names. It cannot begin with reserved tokens. It cannot be a non-reusable name generated by a call to TibrvCmTransport::create(). It cannot be the empty string. For more information, see Reusable Names on page 146 in TIBCO Rendezvous Concepts.
TIBCO Rendezvous C++ Reference 358 | Chapter 10 Distributed Queue
(Sheet 2 of 3) Parameter Description workerWeight When the scheduler receives a task, it assigns the task to the available worker with the greatest worker weight. A worker is considered available unless either of these conditions are true: • The pending tasks assigned to the worker member exceed its task capacity. • The worker is also the scheduler. (The scheduler assigns tasks to its own worker role only when no other workers are available.) When omitted, the default value is 1.
workerTasks Task capacity is the maximum number of tasks that a worker can accept. When the number of accepted tasks reaches this maximum, the worker cannot accept additional tasks until it completes one or more of them. When the scheduler receives a task, it assigns the task to the worker with the greatest worker weight—unless the pending tasks assigned to that worker exceed its task capacity. When the preferred worker has too many tasks, the scheduler assigns the new inbound task to the worker with the next greatest worker weight. The value must be a non-negative integer. When omitted, the default value is 1. Zero is a special value, indicating that this distributed queue member is a dedicated scheduler (that is, it never accepts tasks).
Tuning task capacity to compensate for communication time lag is more complicated than it might seem. Before setting this value to anything other than 1, see Task Capacity on page 166 in TIBCO Rendezvous Concepts.
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::create() | 359
(Sheet 3 of 3) Parameter Description schedulerWeight Weight represents the ability of this member to fulfill the role of scheduler, relative to other members with the same name. Cooperating members use relative scheduler weight values to elect one member as the scheduler; members with higher scheduler weight take precedence. When omitted, the default value is 1. Acceptable values range from 0 to 65535. Zero is a special value, indicating that the member can never be the scheduler. For more information, see Rank and Weight on page 184 in TIBCO Rendezvous Concepts. schedulerHeartbeat The scheduler sends heartbeat messages at this interval (in seconds). All TibrvCmQueueTransport objects with the same name must specify the same value for this parameter. The value must be strictly positive. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts. When omitted, the default value is 1.0. schedulerActivation When the heartbeat signal from the scheduler has been silent for this interval (in seconds), the cooperating member with the greatest scheduler weight takes its place as the new scheduler. All TibrvCmQueueTransport objects with the same name must specify the same value for this parameter. The value must be strictly positive. To determine the correct value, see Step 4: Choose the Intervals on page 215 in TIBCO Rendezvous Concepts. When omitted, the default value is 3.5.
Constant Value
TIBRVCM_DEFAULT_COMPLETE_TIME 0
TIBRVCM_DEFAULT_WORKER_WEIGHT 1
TIBRVCM_DEFAULT_WORKER_TASKS 1
TIBRVCM_DEFAULT_SCHEDULER_WEIGHT 1
TIBRVCM_DEFAULT_SCHEDULER_HB 1.0
TIBRVCM_DEFAULT_SCHEDULER_ACTIVE 3.5
TIBCO Rendezvous C++ Reference 360 | Chapter 10 Distributed Queue
See Also TibrvCmQueueTransport::destroy() on page 361 Distributed Queue, page 161, in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::destroy() | 361
TibrvCmQueueTransport::destroy() Method
Declaration TibrvStatus destroy();
Purpose Destroy a distributed queue member object.
Remarks Destroying a TibrvCmQueueTransport object removes the program from the distributed queue group.
See Also TibrvCmQueueTransport::create() on page 357
TIBCO Rendezvous C++ Reference 362 | Chapter 10 Distributed Queue
TibrvCmQueueTransport::getCompleteTime() Method
Declaration TibrvStatus getCompleteTime( tibrv_f64& completeTime) const;
Purpose Extract the worker complete time limit of a distributed queue member.
Parameter Description completeTime The program supplies a variable, and the method stores the worker complete time in that variable.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::setCompleteTime() on page 366
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::getUnassignedMessageCount() | 363
TibrvCmQueueTransport::getUnassignedMessageCount() Function
Declaration TibrvStatus getUnassignedMessageCount( tibrv_u32& msgCount) const;
Purpose Extract the number of unassigned task messages from a distributed queue transport.
Remarks An unassigned task message is a message received by the scheduler, but not yet assigned to any worker in the distributed queue. This call produces a valid count only within a scheduler process. Within a worker process, this call always produces zero.
Parameter Description msgCount The program supplies a variable, and the function stores the unassigned task count in that variable.
TIBCO Rendezvous C++ Reference 364 | Chapter 10 Distributed Queue
TibrvCmQueueTransport::getWorkerWeight() Method
Declaration TibrvStatus getWorkerWeight( tibrv_u32& workerWeight) const;
Purpose Extract the worker weight of a distributed queue member.
Parameter Description workerWeight The program supplies a variable, and the method stores the worker weight in that variable.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::create() on page 357 TibrvCmQueueTransport::setWorkerWeight() on page 368
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::getWorkerTasks() | 365
TibrvCmQueueTransport::getWorkerTasks() Method
Declaration TibrvStatus getWorkerTasks( tibrv_u32& workerTasks) const;
Purpose Extract the worker task capacity of a distributed queue member.
Parameter Description workerTasks The program supplies a variable, and the method stores the worker task capacity in that variable.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::create() on page 357 TibrvCmQueueTransport::setWorkerTasks() on page 369
TIBCO Rendezvous C++ Reference 366 | Chapter 10 Distributed Queue
TibrvCmQueueTransport::setCompleteTime() Method
Declaration TibrvStatus setCompleteTime( tibrv_f64 completeTime);
Purpose Set the worker complete time limit of a distributed queue member.
Remarks If the complete time is non-zero, the scheduler waits for a worker member to complete an assigned task. If the complete time elapses before the scheduler receives completion from the worker member, the scheduler reassigns the task to another worker member. Zero is a special value, which specifies no limit on the completion time—that is, the scheduler does not set a timer, and does not reassign tasks when task completion is lacking. All members implicitly begin with a default complete time value of zero; programs can change this parameter using this method.
Parameter Description completeTime Use this complete time (in seconds). The time must be non-negative.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::getCompleteTime() on page 362
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::setTaskBacklogLimit...() | 367
TibrvCmQueueTransport::setTaskBacklogLimit...() Method
Declaration TibrvStatus setTaskBacklogLimitInBytes( tibrv_u32 byteLimit);
TibrvStatus setTaskBacklogLimitInMessages( tibrv_u32 msgLimit);
Purpose Set the scheduler task queue limits of a distributed queue transport.
Remarks The scheduler stores tasks in a queue. These properties limit the maximum size of that queue—by number of bytes or number of messages (or both). When no value is set for these properties, the default is no limit. When the task messages in the queue exceed either of these limits, Rendezvous software deletes new inbound task messages. Programs may call each of these methods at most once. Those calls must occur before the transport assumes the scheduler role; after a transport acts as a scheduler, these values are fixed, and subsequent attempts to change them result in status code TIBRV_NOT_PERMITTED.
Parameter Description byteLimit Use this size limit (in bytes). Zero is a special value, indicating no size limit.
msgLimit Use this message limit (number of messages). Zero is a special value, indicating no limit on the number of messages.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts
TIBCO Rendezvous C++ Reference 368 | Chapter 10 Distributed Queue
TibrvCmQueueTransport::setWorkerWeight() Method
Declaration TibrvStatus setWorkerWeight( tibrv_u32 workerWeight);
Purpose Set the worker weight of a distributed queue member.
Remarks Relative worker weights assist the scheduler in assigning tasks. When the scheduler receives a task, it assigns the task to the available worker with the greatest worker weight. The default worker weight is 1; programs can set this parameter at creation using TibrvCmQueueTransport::create(), or change it dynamically using this method.
Parameter Description workerWeight Use this worker weight.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::create() on page 357 TibrvCmQueueTransport::getWorkerWeight() on page 364
TIBCO Rendezvous C++ Reference TibrvCmQueueTransport::setWorkerTasks() | 369
TibrvCmQueueTransport::setWorkerTasks() Method
Declaration TibrvStatus setWorkerTasks( tibrv_u32 workerTasks);
Purpose Set the worker task capacity of a distributed queue member.
Remarks Task capacity is the maximum number of tasks that a worker can accept. When the number of accepted tasks reaches this maximum, the worker cannot accept additional tasks until it completes one or more of them. When the scheduler receives a task, it assigns the task to the worker with the greatest worker weight—unless the pending tasks assigned to that worker exceed its task capacity. When the preferred worker has too many tasks, the scheduler assigns the new inbound task to the worker with the next greatest worker weight. The default worker task capacity is 1. Zero is a special value, indicating that this distributed queue member is a dedicated scheduler (that is, it never accepts tasks).
Tuning task capacity to compensate for communication time lag is more complicated than it might seem. Before setting this value to anything other than 1, see Task Capacity on page 166 in TIBCO Rendezvous Concepts.
Parameter Description workerTasks Use this task capacity. The value must be a non-negative integer.
See Also Distributed Queue, page 161, in TIBCO Rendezvous Concepts TibrvCmQueueTransport::create() on page 357 TibrvCmQueueTransport::getWorkerTasks() on page 365
TIBCO Rendezvous C++ Reference 370 | Chapter 10 Distributed Queue
TIBCO Rendezvous C++ Reference | 371
Chapter 11 Datatypes
Rendezvous wire format datatypes are a standard, platform-independent convention for types and sizes. A parallel set of C datatypes represents data within programs. This chapter summarizes the two sets of datatypes, and the conversions among the various types.
Topics
• Wire Format Datatypes, page 372. • C Datatypes, page 374. • Datatype Conversion, page 376.
TIBCO Rendezvous C++ Reference 372 | Chapter 11 Datatypes
Wire Format Datatypes
(Sheet 1 of 2) Wire Format Type Type Description Notes Special Types
TIBRVMSG_MSG Rendezvous message
TIBRVMSG_DATETIME Rendezvous datetime
TIBRVMSG_OPAQUE opaque byte sequence
TIBRVMSG_STRING ISO 8859-1 character string (also called Latin-1) NULL-terminated.
TIBRVMSG_XML XML data (byte sequence)
Scalar Types
TIBRVMSG_BOOL boolean TIBRV_FALSE, TIBRV_TRUE
TIBRVMSG_I8 8-bit integer
TIBRVMSG_I16 16-bit integer
TIBRVMSG_I32 32-bit integer
TIBRVMSG_I64 64-bit integer
TIBRVMSG_U8 8-bit unsigned integer
TIBRVMSG_U16 16-bit unsigned integer
TIBRVMSG_U32 32-bit unsigned integer
TIBRVMSG_U64 64-bit unsigned integer
TIBRVMSG_F32 32-bit floating point
TIBRVMSG_F64 64-bit floating point
TIBRVMSG_IPADDR32 4-byte IP address Network byte order. String representation is four-part dot-delimited notation.
TIBCO Rendezvous C++ Reference Wire Format Datatypes | 373
(Sheet 2 of 2) Wire Format Type Type Description Notes TIBRVMSG_IPPORT16 2-byte IP port Network byte order. String representation is a 16-bit decimal integer.
Array Types
TIBRVMSG_I8ARRAY 8-bit integer array The count property of the field reflects the TIBRVMSG_I16ARRAY 16-bit integer array number of elements in the array. TIBRVMSG_I32ARRAY 32-bit integer array
TIBRVMSG_I64ARRAY 64-bit integer array
TIBRVMSG_U8ARRAY 8-bit unsigned integer array
TIBRVMSG_U16ARRAY 16-bit unsigned integer array
TIBRVMSG_U32ARRAY 32-bit unsigned integer array
TIBRVMSG_U64ARRAY 64-bit unsigned integer array
TIBRVMSG_F32ARRAY 32-bit floating point array
TIBRVMSG_F64ARRAY 64-bit floating point array
TIBCO Rendezvous C++ Reference 374 | Chapter 11 Datatypes
C Datatypes
(Sheet 1 of 2) C Type Type Description Notes
tibrv_bool boolean TIBRV_FALSE, TIBRV_TRUE
tibrv_f32 32-bit floating point
tibrv_f64 64-bit floating point
tibrv_i8 8-bit integer
tibrv_i16 16-bit integer
tibrv_i32 32-bit integer
tibrv_i64 64-bit integer
tibrv_u8 8-bit unsigned integer
tibrv_u16 16-bit unsigned integer
tibrv_u32 32-bit unsigned integer
tibrv_u64 64-bit unsigned integer
tibrv_ipaddr32 4-byte IP address Stored in network byte order. String representation is four-part dot-delimited notation.
tibrv_ipport16 2-byte IP port Stored in network byte order. String representation is a decimal integer (all 16-bits).
tibrvMsgDateTime Rendezvous datetime struct See TibrvMsgDateTime on page 116. See also tibrvMsgDateTime on page 53 in TIBCO Rendezvous C Reference.
tibrv_f32* 32-bit floating point array
tibrv_f64* 64-bit floating point array
tibrv_i8* 8-bit integer array
TIBCO Rendezvous C++ Reference C Datatypes | 375
(Sheet 2 of 2) C Type Type Description Notes tibrv_i16* 16-bit integer array tibrv_i32* 32-bit integer array tibrv_i64* 64-bit integer array tibrv_u8* 8-bit unsigned integer array tibrv_u16* 16-bit unsigned integer array tibrv_u32* 32-bit unsigned integer array tibrv_u64* 64-bit unsigned integer array tibrvMsg Rendezvous message See TibrvMsg on page 39. See also tibrvMsg on page 52 in TIBCO Rendezvous C Reference. char* character string ISO 8859-1 (Latin-1) character encoding void* opaque byte sequence
TIBCO Rendezvous C++ Reference 376 | Chapter 11 Datatypes
Datatype Conversion
Rendezvous software converts datatypes in two situations: • As it translates a message to wire format (when sending a message). • As it extracts data from a message field.
Convenience methods that extract a field from a Rendezvous message automatically decode the field’s data to a homologous C type. Figure 14 on page 378 specifies the homologous decodings as well as conversions to other types. See also, TibrvMsg::getField() on page 65. Convenience methods that add a field to a Rendezvous message or update an existing field severely restrict type encoding. These methods encode only to homologous types (the solid dots along the diagonal of Figure 14 indicate pairs of homologous types).
General Rules These general rules govern most conversions.
Supported • All wire format types decode to the homologous C datatypes (in get calls), and all C datatypes encode to the homologous wire format types (in add and update calls). • All wire format numeric scalar types convert to all C numeric scalar types. • All wire format numeric array types convert to all C numeric array types.
Caution • Converting a wire format opaque or XML byte sequence to a C character string creates a printable string, but the string does not capture any of the opaque data bytes (it captures only the number of bytes). • Converting a wire format signed integer to a C unsigned integer discards the sign. • Converting a wire format numeric type to a C numeric type with fewer bits risks loss of precision. • Converting wire format floating point numbers to C integer types discards the fractional part.
TIBCO Rendezvous C++ Reference Datatype Conversion | 377
• Converting large (out-of-range) wire format floating point numbers to C integers results in the maximum integer of the C target size.
Not Supported • Array types do not convert to scalar types. • Scalar types do not convert to array types. • C types do not convert to non-homologous wire format types (when adding or updating a field).
Converting to Boolean • When converting a string to a boolean, all strings in which the first character is either t or T map to boolean true. All other strings map to boolean false. • When converting a numeric value to a boolean, zero maps to boolean false. All non-zero numeric values map to boolean true.
TIBCO Rendezvous C++ Reference 378 | Chapter 11 Datatypes
Figure 14 Wire Format to C Datatype Conversion Matrix C Destination Type Get tibrv_bool tibrv_f32 tibrv_f64 tibrv_i8 tibrv_i16 tibrv_i32 tibrv_i64 tibrv_u8 tibrv_u16 tibrv_u32 tibrv_u64 tibrv_ipaddr32 tibrv_ipport16 tibrvMsgDateTime tibrv_f32[] tibrv_f64[] tibrv_i8[] tibrv_i16[] tibrv_i32[] tibrv_i64[] tibrv_u8[] tibrv_u16[] tibrv_u32[] tibrv_u64[] tibrvMsg void* char* tibrvMsg[] char*[] TIBRVMSG_BOOL S S S S S S S S S S S TIBRVMSG_F32 S N N N N N N N N N S TIBRVMSG_F64 S N N N N N N N N N S TIBRVMSG_I8 S N N N N N N N N N S TIBRVMSG_I16 S N N N N N N N N N S TIBRVMSG_I32 S N N N N N N N N N S TIBRVMSG_I64 S N N N N N N N N N S TIBRVMSG_U8 S N N N N N N N N N S TIBRVMSG_U16 S N N N N N N N N N S TIBRVMSG_U32 S N N N N N N N N N S TIBRVMSG_U64 S N N N N N N N N N S TIBRVMSG_IPADDR32 N S TIBRVMSG_IPPORT16 N N N S TIBRVMSG_DATETIME C TIBRVMSG_F32ARRAY N N N N N N N N N S TIBRVMSG_F64ARRAY N N N N N N N N N S TIBRVMSG_I8ARRAY N N N N N N N N N S TIBRVMSG_I16ARRAY N N N N N N N N N S TIBRVMSG_I32ARRAY N N N N N N N N N S tibrvMsg Source Type Source tibrvMsg TIBRVMSG_I64ARRAY N N N N N N N N N S TIBRVMSG_U8ARRAY N N N N N N N N N S TIBRVMSG_U16ARRAY N N N N N N N N N S TIBRVMSG_U32ARRAY N N N N N N N N N S TIBRVMSG_U64ARRAY N N N N N N N N N S TIBRVMSG_MSG S TIBRVMSG_OPAQUE C TIBRVMSG_STRING P P P P P P P P P P P P P TIBRVMSG_XML C TIBRVMSG_MSGARRAY TIBRVMSG_STRINGARRAY
Key Homologous types; conversion always supported; no loss of information S Supported conversion; always supported N Numeric conversion; loss of information is possible (without warning) P Parsed conversion; supported only when sensible and syntactically correct C Caution; supported, but results sometimes can be misleading Unsupported conversion
TIBCO Rendezvous C++ Reference | 379
Chapter 12 Status and Errors
Topics
• TibrvStatus, page 380
TIBCO Rendezvous C++ Reference 380 | Chapter 12 Status and Errors
TibrvStatus Class
Declaration class TibrvStatus TibrvStatus(); // Construct empty. TibrvStatus(tibrv_status status); // Construct from C status. ~TibrvStatus(); // Reclaim storage.
Purpose Encapsulate status codes.
Remarks Status codes are the enumerated values of tibrv_status.
Method Description Page
TibrvStatus::getCode() Extract the C status code from a status 385 object.
TibrvStatus::getText() Extract an interpretive string from a 386 status object.
(Sheet 1 of 5) Constant Description TIBRV_OK The method returned without error.
TIBRV_INIT_FAILURE Cannot create the network transport.
TIBRV_INVALID_TRANSPORT The transport has been destroyed, or is otherwise unusable.
TIBRV_INVALID_ARG An argument is invalid. Check arguments other than messages, subject names, transports, events, queues and queue groups (which have separate status codes).
TIBRV_NOT_INITIALIZED The method cannot run because the Rendezvous environment is not initialized (open).
TIBRV_ARG_CONFLICT Two arguments that require a specific relation are in conflict. For example, the upper end of a numeric range is less than the lower end.
TIBRV_SERVICE_NOT_FOUND TibrvNetTransport::create() cannot match the service name using getservbyname().
TIBCO Rendezvous C++ Reference TibrvStatus | 381
(Sheet 2 of 5) Constant Description
TIBRV_NETWORK_NOT_FOUND TibrvNetTransport::create() cannot match the network name using getnetbyname().
TIBRV_DAEMON_NOT_FOUND TibrvNetTransport::create() cannot match the daemon port number.
TIBRV_NO_MEMORY The method could not allocate dynamic storage.
TIBRV_INVALID_SUBJECT The method received a subject name with incorrect syntax.
TIBRV_DAEMON_NOT_CONNECTED The Rendezvous daemon process (rvd) exited, or was never started. This status indicates that the program cannot start the daemon and connect to it.
TIBRV_VERSION_MISMATCH The library, header files and Rendezvous daemon are incompatible.
TIBRV_SUBJECT_COLLISION It is illegal to create two certified listener events on the same CM transport with overlapping subjects.
TIBRV_VC_NOT_CONNECTED A virtual circuit terminal was once complete, but is now irreparably broken.
TIBRV_NOT_PERMITTED The program attempted an illegal operation. For example: • Cannot create ledger file. • Cannot confirm an uncertified message (that is, it has no sequence number).
TIBRV_INVALID_NAME The field name is too long; see Field Name Length on page 46.
TIBRV_INVALID_TYPE 1. The field type is not registered. 2. Cannot update field to a type that differs from the existing field’s type.
TIBRV_INVALID_SIZE The explicit size in the field does not match its explicit type.
TIBRV_INVALID_COUNT The explicit field count does not match its explicit type.
TIBRV_NOT_FOUND The method could not find the specified field in the message.
TIBCO Rendezvous C++ Reference 382 | Chapter 12 Status and Errors
(Sheet 3 of 5) Constant Description TIBRV_ID_IN_USE Cannot add this field because its identifier is already present in the message; identifiers must be unique.
TIBRV_ID_CONFLICT After field search by identifier fails, search by name succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied).
TIBRV_CONVERSION_FAILED The method found the specified field, but could not convert it to the desired datatype.
TIBRV_RESERVED_HANDLER The datatype handler number is reserved for Rendezvous internal datatype handlers.
TIBRV_ENCODER_FAILED The program’s datatype encoder failed.
TIBRV_DECODER_FAILED The program’s datatype decoder failed.
TIBRV_INVALID_MSG The method received a message argument that is not a well-formed message; for example, NULL.
TIBRV_INVALID_FIELD The program supplied an invalid field as an argument.
TIBRV_INVALID_INSTANCE The program supplied zero as the field instance number (the first instance is number 1).
TIBRV_CORRUPT_MSG The method detected a corrupt message argument. The most common cause is that the program corrupted storage by accessing the message in two threads simultaneously (without proper locking).
TIBRV_TIMEOUT A timed dispatch call returned without dispatching an event. A send request call returned without receiving a reply message. A virtual circuit terminal is not yet ready for use.
TIBRV_INTR Interrupted operation.
TIBRV_INVALID_DISPATCHABLE The method received an event queue or queue group that has been destroyed, or is otherwise unusable.
TIBRV_INVALID_DISPATCHER The method received a dispatcher that is invalid or has been destroyed.
TIBCO Rendezvous C++ Reference TibrvStatus | 383
(Sheet 4 of 5) Constant Description TIBRV_INVALID_EVENT The method received an event that has been destroyed, or is otherwise unusable.
TIBRV_INVALID_CALLBACK The method received NULL instead of a callback method.
TIBRV_INVALID_QUEUE The method received a queue that has been destroyed, or is otherwise unusable.
TIBRV_INVALID_QUEUE_GROUP The method received a queue group that has been destroyed, or is otherwise unusable.
TIBRV_INVALID_TIME_INTERVAL The method received a negative timer interval.
TIBRV_INVALID_IO_SOURCE The method received an invalid I/O source (for this operating system).
TIBRV_INVALID_IO_CONDITION The method received an invalid I/O condition (for this operating system).
TIBRV_SOCKET_LIMIT The operation failed because of an operating system socket limitation.
TIBRV_OS_ERROR Tibrv::open() encountered an operating system error.
TIBRV_INSUFFICIENT_BUFFER The method received a buffer argument that is too small to contain the result.
TIBRV_EOF End of file.
TIBRV_INVALID_FILE 1. Ledger file is not recognizable as such. 2. TibrvSdContext:setUserCertWithKey() or TibrvSdContext:setUserCertWithKeyBin() could not complete a certificate file operation; this status code can indicate either disk I/O failure, or invalid certificate data, or an incorrect password.
TIBRV_FILE_NOT_FOUND Rendezvous software could not find the specified file.
TIBRV_NOT_FILE_OWNER The program cannot open the specified file because another program owns it. For example, ledger files are associated with correspondent names.
TIBCO Rendezvous C++ Reference 384 | Chapter 12 Status and Errors
(Sheet 5 of 5) Constant Description TIBRV_IO_FAILED Cannot write to ledger file.
TIBCO Rendezvous C++ Reference TibrvStatus::getCode() | 385
TibrvStatus::getCode() Method
Declaration tibrv_status getCode() const;
Purpose Extract the C status code from a status object.
TIBCO Rendezvous C++ Reference 386 | Chapter 12 Status and Errors
TibrvStatus::getText() Method
Declaration const char* getText() const;
Purpose Extract an interpretive string from a status object.
TIBCO Rendezvous C++ Reference Index | 387 Index
A C object TibrvDispatchable 178 accept, create virtual circuit 252 TibrvDispatcher 216 action, fault tolerance 259 TibrvEvent 127 activate, fault tolerance 259 TibrvFtMember 268 add message field TibrvFtMonitor 286 array 49 TibrvMsg 81 datetime 55 TibrvQueue 189 nested message 51 TibrvQueueGroup 207 opaque bytes 53 TibrvTransport 228 scalar 47 callback method XML 54 destroy complete add() queue to group 203 CM transport 340 addField() to message 45 event 138 addListener() to CM transport 308 fault tolerance 278 advisory message, see TIBCO Rendezvous Concepts monitor 293 allow listener, CM 309 queue 200 array fault tolerance 275 add 49 monitor 291 get 70 generic 136 update 100 I/O event 174 inbound CM message 351 inbound message 148 inbound message vector 158 B review ledger 342 timer 166 backward compatibility. See release 5. certificate batch mode 247 set daemon certificate 25 batch mode (type) 237 set user certificate 27, 28 bytes, get field as 61 certified delivery 295 add listener 308 allow listener 309 confirm 298 C
C datatypes 374
TIBCO Rendezvous C++ Reference 388 | Index
set explicit 304 character encoding 3 connect to relay agent 310 checklist, programmer’s 5 destroy complete, transport 340 clear references, message 56 disallow listener 318 close() 19 disconnect from relay agent 319 closure expire messages 320 event 126 get fault tolerance message parameter member 266 sender name 345 monitor 284 sequence number 346 CM 295 time limit 348 listener 296 subject from listener 301 validity 303 transport from listener 302 message transport parameter callback method 351 correspondent name 323 methods 344 ledger name 322 queue. See distributed queue. relay agent 324 compatibility. See release 5. request old 325 complete time, distributed queue sync ledger 326 get 362 time limit 321 set 366 transport 327 complete, destroy label information, inbound message 148, 351 CM transport 340 ledger event 138 review 331 fault tolerance callback 341 member 278 sync 338 monitor listener 296 destroy complete callback 293 create 299 queue 200 destroy 300 confirm 298 message callback 350 confirmMsg() 298 message methods 344 set explicit 304 remove connect, create virtual circuit 254 listener 328 connectToRelayAgent() 310 send state 330 constructor send 332 datetime 119 reply 333 message 42 request 334 message field 109 send state, remove 330 conversion, datatype 376 set time limit convert message to string 57 of message 349 copy message 58 of transport, default 336 correspondent, get name 323 sync ledger 338 transport 305 create 312 destroy 317
TIBCO Rendezvous C++ Reference Index | 389 create destroy certified delivery listener 299 completion callback certified delivery transport 312 event 138 dispatcher thread 213 fault tolerance 278 distributed queue member 357 monitor 293 event queue 185 queue 200 event queue group 204 destroy() fault tolerance member 262 certified delivery fault tolerance monitor 281 listener 300 I/O event 170 transport 317 inbox name 224, 316 dispatchable 176 listener 144 dispatcher thread 214 message 42 distributed queue transport 361 network transport 241 event 125 embed license 242 fault tolerance timer 162 member 265 vector listener 150 monitor 283 createAcceptVc() 252 queue 186 createConnectVc() 254 queue group 205 createCopy(), message 58 transport 226 createInbox() 224, 316 destructor current time, get 64 datetime 119 customer support xx message 44 message field 109 detach message 59 disallowListener() 318 D disconnectFromRelayAgent() 319 dispatch, timed 181, 198, 211 daemon TCP socket 241 dispatch() data queue 187 message field 111 queue group 206 validity of snapshot 32 queue or queue group 177 data callback 147 dispatchable 175 vector 157 dispatcher thread 212 datatypes 371 create 213 C 374 destroy 214 conversion 376 object 212 wire format 372 distributed queue 353 date 116 create member 357 constructor 119 destroy 361 deactivate, fault tolerance 259 get default queue 182 complete time 362 defaultQueue() 20 worker task capacity 365 description 227, 236 worker weight 364 set
TIBCO Rendezvous C++ Reference 390 | Index
complete time 366 limit policy 195 scheduler task queue limits 367 name 196 worker task capacity 369 priority 197 worker weight 368 event queue group 201 transport 354 expand message, reallocate storage 60 expire messages, certified delivery 320 expireMessages() 320 extract. See get. E
element count, message field 110 embedded license 242 F encoding 3 environment fault tolerance 257 Tibrv class 18 action token 259 TibrvSdContext class 24 member 260 error codes 380 callback 275 event create 262 callback method, generic 136 destroy 265 class 123 complete callback 278 closure data, get 126 monitor 279, 293 destroy 125 callback 291 destroy complete, callback method 138 create 281 dispatch 177 destroy 283 timed 181 complete callback 293 get count from a queue 188 field get queue 129 add to message 45 get type 128 array 49 poll 180 datetime 55 TibrvMsg 80 nested message 51 validity 133 opaque bytes 53 event queue 198 scalar 47 class 182 string 52 create 185 XML 54 destroy 186 class 107 dispatch 187 get 65 timed 198 array 70 get datetime 76 limit policy 190 nested message 72 name 191 opaque bytes 74 priority 192 scalar 68 is valid 193 string 73 limit policy constants 182 poll 194 set
TIBCO Rendezvous C++ Reference Index | 391
XML 75 getClosure() 126 get by index 78 fault tolerance 266 get instance from message 79 monitor 284 identifier, from field 112 getCode(), status 385 name and identifier 37 getCompleteTime() 362 remove 89 getCount() instance 91 events in a queue 188 update in message 95 fields in a message 110 array 100 getDaemon() 244 datetime 106 getData(), message field 111 nested message 102 getDefaultTimeLimit(), CM transport 321 opaque bytes 104 getDescription(), transport 227 scalar 98 getDispatchable() string 103 C handle from dispatchable object 178 XML 105 from dispatcher thread 215 file, ledger 313 getEvent() TibrvMsg 80 getGroupName() fault tolerance member 267 G fault tolerance monitor 285 getHandle() get TibrvDispatcher 216 byte size of message 63 TibrvEvent 127 current time 64 TibrvFtMember 268 description string of a transport 227 TibrvFtMonitor 286 dispatcher thread name 217 TibrvMsg 81 message field 65 TibrvQueue 189 array 70 TibrvQueueGroup 207 datetime 76 TibrvTransport 228 nested message 72 getId(), message field 112 opaque bytes 74 getInterval(), timer 163 scalar 68 getIOSource() 171 string 73 getIOType() 172 XML 75 getLedgerName() 322 message field by index 78 getLimitPolicy(), queue 190 message field instance 79 getName() subject from listener 145 certified delivery transport 323 certified delivery 301 event queue 191 subject from vector listener 155 message field 113 transport from listener 146 getNetwork() 245 certified delivery 302 getNumFields() 82 transport from vector listener 156 getPriority(), queue 192 unassigned task count 363 getAsBytes(), message field 61
TIBCO Rendezvous C++ Reference 392 | Index
getQueue() I event 129 fault tolerance member 269 I/O fault tolerance monitor 287 callback method 174 getRelayAgent() 324 event object 167 getReplySubject() 83 create 170 getRequestOld() 325 identifier, field 37 getSender(), CM message 345 inbox, create name 224, 316 getSendSubject() 84 include, header files 8 getSequence(), CM message 346 instance (field) getService() 246 get 79 getSize(), message field 114 remove 91 getStatus(), new message 85 internal machinery 19 getSubject(), listener 145 start (open) 21 vector 155 stop (close) 19 getSyncLedger() 326 interval getText(), status 386 get from timer 163 getTimeLimit(), CM message 348 reset timer 164 getTransport() intra-process transport 22, 238 certified delivery transport 327 isDetached() 86 fault tolerance member 270 isIOEvent() 130 fault tolerance monitor 288 isListener() 131 listener 146 isTimer() 132 vector 156 isValid() getType() CM listener 303 message field 115 dispatcher 218 TibrvEvent 128 event 133 getUnassignedMessageCount() 363 event queue 193 getWeight(), FT 271 fault tolerance member 272 getWorkerTasks() 365 fault tolerance monitor 289 getWorkerWeight() 364 queue group 208 group name TibrvDispatchable 179 fault tolerance member 267 transport 229 fault tolerance monitor 285 isVectorListener() 134 group, queue 201
J H join a fault tolerance group 262 header files 8
TIBCO Rendezvous C++ Reference Index | 393
L string 52 XML 54 ledger callback method 148 file 314 vector 158 name, get 322 certified delivery 344 review 331 convert to string 57 sync 338 copy 58 get property 326 create 42 library files 9 destructor 44 licensed transport 242 detach 59 limit policy expand 60 constants 182 field (as a class) 107 get 190 get data as a byte sequence 61, 62 set 195 get field 65 linking 9 array 70 listener 141 datetime 76 CM 296 nested message 72 create 144 opaque bytes 74 CM 299 scalar 68 vector 150 string 73 destroy 125 XML 75 CM 300 get field by index 78 subject, get 145 get field instance 79 CM 301 ownership and control transport, get 146 detach() 59 CM 302 isDetatched() 86 vector 149 references create 150 clear 56 loop, get field by index mark 87 lost interval 282 remove field 89 reply subject 83, 93 reset 92 send 232 M send subject 84, 94 size 63 mark references 87 update field 95 member, fault tolerance 260 array 100 callback 275 datetime 106 message 39 nested message 102 add field 45 opaque bytes 104 array 49 scalar 98 datetime 55 string 103 nested message 51 XML 105 opaque bytes 53 scalar 47
TIBCO Rendezvous C++ Reference 394 | Index
message field open() 21 class 107 constructor 109 element count 110 monitor, fault tolerance 279 P callback 291 PEM 27 PKCS #12 28 poll() N event queue 194 queue group 209 name queue or queue group 180 certified delivery transport 345 prepare-to-activate, fault tolerance 259 creation parameter 314 pre-register certified delivery listener 308 get name 323 priority, of event queue 192 dispatcher thread 217, 219 set 197 event queue 191, 196 process transport 238 fault tolerance group 267 get 22 monitor 285 message field 113 nested message, add field to message 51 network interface 241 Q network transport 239 create 241 queue 182 embed license 242 add to group 203 get daemon (TCP socket) 244 create 185 get network interface 245 default 20 get service 246 destroy 186 set batch mode 247 destroy complete, callback method 200 number of fields in a message 82 dispatch 187 fault tolerance member 269 get event count 188 O limit policy 190 name 191 old messages, request certified delivery 325 priority 192 onCmMsg() 351 get queue from event 129 onEvent() 136 isValid() 193 onFtAction() 275 poll 194 onFtMonitor() 291 set onIOEvent() 174 limit policy 195 onLedgerMsg() 342 name 196 onMsg() 148 priority 197 onMsgs() 158 timed dispatch 198 onTimer() 166
TIBCO Rendezvous C++ Reference Index | 395 queue group 201 reset, message 92 add queue 203 resetInterval(), timer 164 create 204 reviewLedger() 331 destroy 205 callback method 342 dispatch 206 is valid 208 poll 209 remove queue 210 S timed dispatch 211 scalar add field 47 get 68 R update 98 secure daemon raw storage device, as ledger file 314 set daemon certificate 25 reallocate 60 set user certificate 27, 28 reference count 19, 21 set user name 29 references send 232, 232 clear 56 CM 332 mark 87 reply 233 relay agent CM 333 connect to 310 request 234 disconnect from 319 CM 334 get from certified delivery transport 324 send state, remove 330 release 5, interaction send subject sequence numbers, certified delivery 347 get 84 several fields with same name set 94 release number, get 23 sender name, CM 345 reliability, request 230 sendReply() 233 remove(), queue from group 210 CM 333 removeField(), from message 89 sendRequest() 234 removeFieldInstance(), from message 91 CM 334 removeListener(), certified delivery 328 sequence number, CM 346 removeSendState(), certified delivery 330 release 5, interaction 347 reply service, UDP 241 send 233 setBatchMode() 247 send certified 333 setCompleteTime(), distributed queue 366 reply subject setDaemonCert() 25 get 83 setDefaultTimeLimit(), certified delivery 336 set 93 setDescription(), transport 236 request setExplicitConfirm(), CM listener 304 send 234 setLimitPolicy(), queue 195 send certified 334 setName() request old, certified delivery 325 dispatcher thread 219 requestReliability() 230 event queue 196
TIBCO Rendezvous C++ Reference 396 | Index
setPriority(), event queue 197 Tibrv 18 setPublisherInactivityDiscardInterval() 337 close() 19 setReplySubject(), message 93 defaultQueue() 20 setSendSubject(), message 94 open() 21 setTaskBacklogLimit...() 367 processTransport() 22 setTimeLimit(), CM message 349 version() 23 setUserCertWithKey() 27 TibrvCallback 135 setUserCertWithKeyBin() 28 onEvent() 136 setUserNameWithPassword() 29 TibrvCmListener 296 setWeight(), fault tolerance member 273 confirmMsg() 298 setWorkerTasks(), distributed queue 369 create() 299 setWorkerWeight(), distributed queue 368 destroy() 300 size getSubject() 301 message 63 getTransport() 302 message field 114 isValid() 303 snapshot, data 32 setExplicitConfirm() 304 status 380 TibrvCmMsg 344 codes 380 getSender() 345 get code 385 getSequence() 346 get text 386 getTimeLimit() 348 of a newly constructed message object 85 setTimeLimit() 349 string and character encoding 3 TibrvCmMsgCallback 350 string, convert message to 57 onCmMsg() 351 subject TibrvCmQueueTransport 354 listener 145 create() 357 CM 301 destroy() 361 vector 155 getCompleteTime() 362 message getUnassignedMessageCount() 363 reply 83, 93 getWorkerTasks() 365 send 84, 94 getWorkerWeight() 364 support, contacting xx setCompleteTime() 366 sync ledger, certified delivery 338 setTaskBacklogLimit...() 367 get 326 setWorkerTasks() 369 setWorkerWeight() 368 TibrvCmReviewCallback 341 onLedgerMsg() 342 T
task capacity of distributed queue 365, 369 TCP port, network transport, daemon parameter 241 technical support xx thread, create dispatcher 213
TIBCO Rendezvous C++ Reference Index | 397
TibrvCmTransport 305 TibrvEvent 123 addListener() 308 destroy() 125 allowListener() 309 getClosure() 126 connectToRelayAgent() 310 getHandle() 127 create() 312 getQueue() 129 createInbox() 316 getType() 128 destroy() 317 isIOEvent() 130 disallowListener() 318 isListener() 131 disconnectFromRelayAgent 319 isTimer() 132 expireMessages() 320 isValid() 133 getDefaultTimeLimit() 321 isVectorListener() 134 getLedgerName() 322 TibrvEventOnComplete 137 getName() 323 onComplete() 138 getRelayAgent() 324 TIBRVFT_ACTIVATE 259 getRequestOld() 325 TIBRVFT_DEACTIVATE 259 getSyncLedger() 326 TIBRVFT_PREPARE_TO_ACTIVATE 259 getTransport() 327 tibrvftAction 259, 259 removeListener() 328 TibrvFtMember 260 removeSendState() 330 create() 262 reviewLedger() 331 destroy() 265 send() 332 getClosure() 266, 284 sendReply() 333 getGroupName() 267 sendRequest() 334 getHandle() 268 setDefaultTimeLimit() 336 getQueue() 269 setPublisherInactivityDiscardInterval() 337 getTransport() 270 syncLedger() 338 getWeight() 271 TibrvCmTransportOnComplete 339 isValid() 272 onComplete() 340 setWeight() 273 TibrvDispatchable 175 TibrvFtMemberCallback 274 destroy() 176 onFtAction() 275 dispatch() 177 TibrvFtMemberOnComplete 277 getDispatchable() 178 onComplete() 278 isValid() 179 TibrvFtMonitor 279 poll() 180 create() 281 timedDispatch() 181 destroy() 283 TibrvDispatcher 212 getGroupName() 285 create() 213 getHandle() 286 destroy() 214 getQueue() 287 getDispatchable() 215 getTransport() 288 getHandle() 216 isValid() 289 getName() 217 TibrvFtMonitorCallback 290 isValid() 218 onFtMonitor() 291 setName() 219 TibrvFtMonitorOnComplete 292 onComplete() 293, 293
TIBCO Rendezvous C++ Reference 398 | Index
TibrvIOCallback 173 TibrvMsgField 107 onIOEvent() 174 constructor 109 TibrvIOEvent 167 getCount() 110 create() 170 getData() 111 getIOSource() 171 getId() 112 getIOType() 172 getName() 113 TibrvListener 141 getSize() 114 create() 144 getType() 115 getSubject() 145 TibrvNetTransport 239 getTransport() 146 create() 241 TibrvMsg 39 getDaemon() 244 addField() 45 getNetwork() 245 clearReferences() 56 getService() 246 constructor 42 setBatchMode() 247 convertToString() 57 TibrvProcessTransport 238 createCopy() 58 TibrvQueue 182 destructor 44 create() 185 detach() 59 destroy() 186 expand() 60 dispatch() 187 getAsBytes() 61 getCount() 188 getAsBytesCopy() 62 getHandle() 189 getByIndex() 78 getLimitPolicy() 190 getByteSize() 63 getName() 191 getCurrentTime() 64 getPriority() 192 getEvent() 80 isValid() 193 getField() 65 poll() 194 getHandle() 81 setLimitPolicy() 195 getInstance() 79 setName() 196 getNumFields() 82 setPriority 197 getReplySubject() 83 timedDispatch() 198 getSendSubject() 84 TibrvQueueGroup 201 getStatus() 85 add() 203 isDetached() 86 create() 204 markReferences() 87 destroy() 205 removeField() 89 dispatch() 206 removeFieldInstance() 91 getHandle() 207 reset() 92 isValid() 208 setReplySubject() 93 poll() 209 setSendSubject() 94 remove() 210 updateField() 95 timedDispatch() 211 TibrvMsgCallback 147 TibrvQueueOnComplete 199 onMsg() 148 onComplete() 200 TibrvMsgDateTime 116 constructor 119
TIBCO Rendezvous C++ Reference Index | 399
TibrvSdContext 24 timedDispatch() setDaemonCert() 25 queue 198 setUserCertWithKey() 27 queue group 211 setUserCertWithKeyBin() 28 queue or queue group 181 setUserNameWithPassword() 29 timer TibrvStatus 380 callback method 166 getCode() 385 create 162 getText() 386 event object 159 TibrvTimer 159 get interval 163 create() 162 reset interval 164 getInterval() 163 translation, character encoding 3 resetInterval() 164 transport TibrvTimerCallback 165 batch mode 237 onTimer() 166 batch mode, set 247 TibrvTransport 222 certified delivery 305 createInbox() 224 create 312 destroy() 226 create inbox name 224, 316 getDescription() 227 description getHandle() 228 get 227 isValid() 229 set 236 requestReliability() 230 destroy 226 send() 232 certified delivery 317 sendReply() 233 distributed queue 361 sendRequest() 234 distributed queue 354 setDescription() 236 fault tolerance member 270 tibrvTransportBatchMode (type) 237 generic class 222 TibrvVcTransport 250 get from certified delivery listener 302 createAcceptVc() 252 get from certified delivery transport 327 createConnectVc() 254 get from listener 146 waitForVcConnection() 255 get from vector listener 156 TibrvVectorCallback 157 intra-process 22, 238 onMsgs() 158 is valid 229 TibrvVectorListener 149 network 239 create() 150 create 241 getSubject() 155 embed license 242 getTransport() 156 request reliability 230 time 116 send 232 constructor 119 reply 233 get current 64 request 234 time limit, certified delivery virtual circuit 250 get 348 create accept 252 get default 321 create connect 254 set 349 wait for connection 255 set default 336
TIBCO Rendezvous C++ Reference 400 | Index
type 371 W C 374 message field 115 waitForVcConnection() 255 wire format 372 weight, fault tolerance get 271 set 273 wire format datatypes 372 U withdraw from fault tolerance group 265 worker weight, distributed queue unassigned tasks 363 get 364 update message field 95 set 368 array 100 datetime 106 nested message 102 opaque bytes 104 X scalar 98 string 103 XML XML 105 add 54 updateField() 95 get 75 user name and password, set 29 update 105
V
valid CM listener 303 dispatcher 218 event 133 event queue 193 fault tolerance member 272 fault tolerance monitor 289 message data 32 queue group 208 transport 229 vector callback 157 vector listener 149 create 150 subject, get 155 transport, get 156 version() 23 virtual circuit transport class 250 wait for connection 255
TIBCO Rendezvous C++ Reference