TIBCO Rendezvous®

C++ Reference
Software Release 8.3.0
July 2010
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 TIBCO Rendezvous Installation) 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.
This document contains confidential information that 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.
TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, Rendezvous, TIBCO
Rendezvous and Messaging Appliance are either registered trademarks or trademarks of TIBCO Software Inc. in
the United States and/or other countries.
EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries.
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.TXT 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.
Copyright © 1997–2010 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
 | iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Chapter 1 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
32-Bit UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
64-Bit UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Source Code Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3 Rendezvous Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Tibrv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Tibrv::close(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

TIBCO Rendezvous C++ Reference

iv
| Contents
Tibrv::defaultQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Tibrv::open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Tibrv::processTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Tibrv::version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
TibrvSdContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
TibrvSdContext:setDaemonCert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
TibrvSdContext:setUserCertWithKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
TibrvSdContext:setUserCertWithKeyBin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
TibrvSdContext:setUserNameWithPassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Validity of Data Extracted From Message Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Scalar Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Pointer Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Deleting Snapshot References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Multiple Subscription Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Field Names and Field Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Finding a Field Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
TibrvMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
TibrvMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
~TibrvMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
TibrvMsg::addField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Add Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Add Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Add Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Add String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Add Opaque Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Add XML Byte Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Add DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
TibrvMsg::clearReferences() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
TibrvMsg::convertToString(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
TibrvMsg::createCopy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
TibrvMsg::detach(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
TibrvMsg::expand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
TibrvMsg::getAsBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
TibrvMsg::getAsBytesCopy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
TibrvMsg::getByteSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
TibrvMsg::getCurrentTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
TibrvMsg::getField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Get Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Get Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Get Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Get String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

TIBCO Rendezvous C++ Reference

 Contents v
|
Get Opaque Byte Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Get XML Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Get DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
TibrvMsg::getFieldByIndex(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
TibrvMsg::getFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
TibrvMsg::getEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
TibrvMsg::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
TibrvMsg::getNumFields() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TibrvMsg::getReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
TibrvMsg::getSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
TibrvMsg::getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
TibrvMsg::isDetached() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
TibrvMsg::markReferences() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TibrvMsg::removeField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
TibrvMsg::removeFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
TibrvMsg::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
TibrvMsg::setReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
TibrvMsg::setSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
TibrvMsg::updateField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Update Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Update Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Update Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Update String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Update Opaque Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Update XML Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Update DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
TibrvMsgField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
TibrvMsgField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
TibrvMsgField::getCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
TibrvMsgField::getData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
TibrvMsgField::getId(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
TibrvMsgField::getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
TibrvMsgField::getSize(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
TibrvMsgField::getType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
TibrvMsgDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TibrvMsgDateTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 5 Events and Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Event Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
TibrvEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
TibrvEvent::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
TibrvEvent::getClosure(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
TibrvEvent::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

TIBCO Rendezvous C++ Reference

vi
| Contents
TibrvEvent::getType(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
TibrvEvent::getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
TibrvEvent::isIOEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TibrvEvent::isListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
TibrvEvent::isTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TibrvEvent::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TibrvEvent::isVectorListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
TibrvCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
TibrvCallback::onEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
TibrvEventOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
TibrvEventOnComplete::onComplete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
TibrvListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
TibrvListener::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TibrvListener::getSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TibrvListener::getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
TibrvMsgCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TibrvMsgCallback::onMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
TibrvVectorListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
TibrvVectorListener::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
TibrvVectorListener::getSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
TibrvVectorListener::getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
TibrvVectorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
TibrvVectorCallback::onMsgs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
TibrvTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
TibrvTimer::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
TibrvTimer::getInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
TibrvTimer::resetInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
TibrvTimerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
TibrvTimerCallback::onTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
TibrvIOEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
TibrvIOEvent::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
TibrvIOEvent::getIOSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
TibrvIOEvent::getIOType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
TibrvIOCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
TibrvIOCallback::onIOEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
TibrvDispatchable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
TibrvDispatchable::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
TibrvDispatchable::dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
TibrvDispatchable::getDispatchable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
TibrvDispatchable::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
TibrvDispatchable::poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
TibrvDispatchable::timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

TIBCO Rendezvous C++ Reference

 Contents vii
|
TibrvQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
TibrvQueue::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
TibrvQueue::destroy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
TibrvQueue::dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
TibrvQueue::getCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
TibrvQueue::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
TibrvQueue::getLimitPolicy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
TibrvQueue::getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
TibrvQueue::getPriority() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
TibrvQueue::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
TibrvQueue::poll(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
TibrvQueue::setLimitPolicy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
TibrvQueue::setName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
TibrvQueue::setPriority() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
TibrvQueue::timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
TibrvQueueOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
TibrvQueueOnComplete::onComplete(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
TibrvQueueGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
TibrvQueueGroup::add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
TibrvQueueGroup::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
TibrvQueueGroup::destroy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
TibrvQueueGroup::dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
TibrvQueueGroup::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
TibrvQueueGroup::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
TibrvQueueGroup::poll(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
TibrvQueueGroup::remove(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
TibrvQueueGroup::timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
TibrvDispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
TibrvDispatcher::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
TibrvDispatcher::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
TibrvDispatcher::getDispatchable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
TibrvDispatcher::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
TibrvDispatcher::getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
TibrvDispatcher::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
TibrvDispatcher::setName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Chapter 6 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

TibrvTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
TibrvTransport::createInbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
TibrvTransport::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
TibrvTransport::getDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
TibrvTransport::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
TibrvTransport::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

TIBCO Rendezvous C++ Reference

viii
| Contents
TibrvTransport::requestReliability() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
TibrvTransport::send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
TibrvTransport::sendReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
TibrvTransport::sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
TibrvTransport::setDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
tibrvTransportBatchMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
TibrvProcessTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
TibrvNetTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
TibrvNetTransport::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
TibrvNetTransport::getDaemon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
TibrvNetTransport::getNetwork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
TibrvNetTransport::getService(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
TibrvNetTransport::setBatchMode(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Chapter 7 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

TibrvVcTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
TibrvVcTransport::createAcceptVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
TibrvVcTransport::createConnectVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
TibrvVcTransport::waitForVcConnection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Chapter 8 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Fault Tolerance Road Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
tibrvftAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
TibrvFtMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
TibrvFtMember::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
TibrvFtMember::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TibrvFtMember::getClosure(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
TibrvFtMember::getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
TibrvFtMember::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
TibrvFtMember::getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
TibrvFtMember::getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
TibrvFtMember::getWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
TibrvFtMember::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
TibrvFtMember::setWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
TibrvFtMemberCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
TibrvFtMemberCallback::onFtAction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
TibrvFtMemberOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
TibrvFtMemberOnComplete::onComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
TibrvFtMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
TibrvFtMonitor::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TibrvFtMonitor::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
TibrvFtMonitor::getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

TIBCO Rendezvous C++ Reference

 Contents ix
|
TibrvFtMonitor::getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
TibrvFtMonitor::getHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
TibrvFtMonitor::getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
TibrvFtMonitor::getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
TibrvFtMonitor::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
TibrvFtMonitorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
TibrvFtMonitorCallback::onFtMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
TibrvFtMonitorOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
TibrvFtMonitorOnComplete::onComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Chapter 9 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

TibrvCmListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
TibrvCmListener::confirmMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
TibrvCmListener::create(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
TibrvCmListener::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
TibrvCmListener::getSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
TibrvCmListener::getTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
TibrvCmListener::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
TibrvCmListener::setExplicitConfirm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
TibrvCmTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
TibrvCmTransport::addListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
TibrvCmTransport::allowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
TibrvCmTransport::connectToRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
TibrvCmTransport::create(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
TibrvCmTransport::createInbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
TibrvCmTransport::destroy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
TibrvCmTransport::disallowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
TibrvCmTransport::disconnectFromRelayAgent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
TibrvCmTransport::expireMessages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
TibrvCmTransport::getDefaultTimeLimit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
TibrvCmTransport::getLedgerName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
TibrvCmTransport::getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
TibrvCmTransport::getRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
TibrvCmTransport::getRequestOld(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
TibrvCmTransport::getSyncLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
TibrvCmTransport::getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
TibrvCmTransport::removeListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
TibrvCmTransport::removeSendState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
TibrvCmTransport::reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
TibrvCmTransport::send(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
TibrvCmTransport::sendReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
TibrvCmTransport::sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
TibrvCmTransport::setDefaultTimeLimit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

TIBCO Rendezvous C++ Reference

x
| Contents
TibrvCmTransport::setPublisherInactivityDiscardInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
TibrvCmTransport::syncLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
TibrvCmTransportOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
TibrvCmTransportOnComplete::onComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
TibrvCmReviewCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
TibrvCmReviewCallback::onLedgerMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
TibrvCmMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
TibrvCmMsg::getSender() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
TibrvCmMsg::getSequence(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
TibrvCmMsg::getTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
TibrvCmMsg::setTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
TibrvCmMsgCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
TibrvCmMsgCallback::onCmMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Chapter 10 Distributed Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

TibrvCmQueueTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
TibrvCmQueueTransport::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
TibrvCmQueueTransport::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
TibrvCmQueueTransport::getCompleteTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
TibrvCmQueueTransport::getUnassignedMessageCount(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
TibrvCmQueueTransport::getWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
TibrvCmQueueTransport::getWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
TibrvCmQueueTransport::setCompleteTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
TibrvCmQueueTransport::setTaskBacklogLimit...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
TibrvCmQueueTransport::setWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
TibrvCmQueueTransport::setWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

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

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

TIBCO Rendezvous C++ Reference

 | xi

Figures

Figure 1 Extracting a Scalar Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Figure 2 Extracting a Pointer Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 3 Updating a Pointer Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Figure 4 Updating a Submessage Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Figure 5 Mark and Clear References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Figure 6 Completion when Callback Methods are in Progress. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Figure 7 Completion when Callback Methods are Not in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Figure 8 Listener Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Figure 9 Grouping Messages into Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Figure 10 Vector Listener Callbacks in a Single Dispatch Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Figure 11 Vector Listener Callbacks in Multiple Dispatch Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Figure 12 Timer Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Figure 13 I/O Event Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Figure 14 Wire Format to C Datatype Conversion Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

TIBCO Rendezvous C++ Reference

xii
| Figures

TIBCO Rendezvous C++ Reference

 | xiii

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Table 3 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table 4 Linker Flags for 32-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Table 5 Linker Flags for 64-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Table 6 Library Files for Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 7 Library Files for VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Table 8 Date and Time Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

TIBCO Rendezvous C++ Reference

xiv
| Tables

TIBCO Rendezvous C++ Reference

 | xv

Preface

This manual describes the TIBCO Rendezvous® API for C++ programmers. It is
part of the documentation set for Rendezvous Software Release 8.3.0.

Topics

• Manual Organization, page xvi

• Related Documentation, page xvii
• Typographical Conventions, page xix
• How to Contact TIBCO Customer Support, page xxii

TIBCO Rendezvous C++ Reference

xvi
| Manual Organization

Manual Organization

The organization of this book mirrors the underlying object structure of the
Rendezvous C++ API. Each chapter describes a group of closely related objects
and the methods that pertain to them.

TIBCO Rendezvous C++ Reference

 Preface xvii
|

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Product Documentation

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 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
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 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 .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 COM Reference
Detailed descriptions of each class and method in the Rendezvous COM
component. Readers should already be familiar with the programming
environment that uses COM and OLE automation interfaces, as well as the
material in TIBCO Rendezvous Concepts.

TIBCO Rendezvous C++ Reference

xviii Related Documentation
|

• 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 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 Installation
Includes step-by-step instructions for installing Rendezvous software on
various operating system platforms.
• TIBCO Rendezvous Release Notes
Lists new features, changes in functionality, deprecated features, migration
and compatibility information, closed issues and known issues.

TIBCO Rendezvous C++ Reference

 Preface xix
|

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use
TIBCO_HOME All TIBCO products are installed under the same directory. This directory is
TIBRV_HOME referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME
depends on the operating system. For example, on Windows systems, the
default value is C:\tibco.
TIBCO Rendezvous installs into a version-specific directory inside TIBCO_HOME.
This directory is referenced in documentation as TIBRV_HOME. The value of
TIBRV_HOME depends on the operating system. For example on Windows
systems, the default value is C:\tibco\rv\8.3.0.

code font Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use MyCommand to start the foo process.

bold code Bold code font is used in the following ways:

font
• In procedures, to indicate what a user types. For example: Type admin.
• In large code samples, to indicate the parts of the sample that are of
particular interest.
• In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix
BusinessWorks Concepts.
• To introduce new terms For example: A portal page may contain several
portlets. Portlets are mini-applications that run in a portal.
• To indicate a variable in a command or code syntax that you must replace.
For example: MyCommand pathname

TIBCO Rendezvous C++ Reference

xx
| Typographical Conventions

Table 1 General Typographical Conventions (Cont’d)

Convention Use
Key Key name separated by a plus sign indicate keys pressed simultaneously. For
combinations example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example,
data loss or corruption if certain steps are taken or not taken.

Table 2 Syntax Typographical Conventions

Convention Use
[ ] An optional item in a command or code syntax.
For example:
MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3

TIBCO Rendezvous C++ Reference

 Preface xxi
|

Table 2 Syntax Typographical Conventions

Convention Use
{ } A logical group of items in a command. Other syntax notations may appear
within each logical group.
For example, the following command requires two parameters, which can be
either the pair param1 and param2, or the pair param3 and param4.
MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter
can be either param1 or param2 and the second can be either param3 or param4:
MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters.
The first parameter must be param1. You can optionally include param2 as the
second parameter. And the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}

TIBCO Rendezvous C++ Reference

xxii
| How to Contact TIBCO Customer Support

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please
contact TIBCO Support as follows.
• For an overview of TIBCO Support, and information about getting started
with TIBCO Product Support, visit this site:
http://www.tibco.com/services/support
• If you already have a valid maintenance or support contract, visit this site:
http://support.tibco.com
Entry to this site requires a username and password. If you do not have a
username, you can request one.

TIBCO Rendezvous C++ Reference

 |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.
It features a lightweight object model, in which C++ objects refer to C objects
using a pointer or handle.
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.

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 365 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 17

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 14.

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 17.
• 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 17.
• VMS requires programmers to define the link command; see VMS on page 14.

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 41 in TIBCO Rendezvous Administration.
• Be sure that the Rendezvous daemon process can access the Rendezvous
license ticket file, tibrv.tkt. The user’s path must contain this file. For more
information, see Licensing Information on page 11 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 3 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.

32-Bit UNIX
In 32-bit UNIX environments, both shared and static libraries are available. We
recommend shared libraries to ease forward migration.

Table 4 Linker Flags for 32-Bit UNIX (Sheet 1 of 2)

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 this library.

-ltibrv All programs must link this library.

Secure Daemon

-ltibrvsd Programs that connect to secure daemons (rvsd, rvsrd) must also link using
-lssl
these three flags.
-lcrypto

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.

TIBCO Rendezvous C++ Reference

10
| Chapter 2 Programmer’s Checklist

Table 4 Linker Flags for 32-Bit UNIX (Sheet 2 of 2)

Linker Flag Description

-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.

64-Bit UNIX
In 64-bit UNIX environments, both shared and static libraries are available. We
recommend shared libraries to ease forward migration. In this release, 64-bit
libraries are available on HP-UX, Solaris and AIX platforms.

Table 5 Linker Flags for 64-Bit UNIX (Sheet 1 of 2)

Linker Flag Description

Rendezvous C++ Library
All programs must link this library.

-ltibrvcpp64 All programs must link using this library flag.

Communications, Data and Event Manager

All programs must link only one of these two libraries.

-ltibrv64 Programs that connect to ordinary daemons (rvd, rvrd) must link using this
library flag.

Secure Daemon

-ltibrvsd64 Programs that connect to secure daemons (rvd, rvrd) 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.

-ltibrvcm64 Programs that use certified message delivery must link using this library flag.
Programs that use distributed queues must link using this library flag.

-ltibrvft64 Programs that use fault tolerance features must link using this library flag.
Programs that use distributed queues must link using this library flag.

TIBCO Rendezvous C++ Reference

 Link These Library Files 11
|

Table 5 Linker Flags for 64-Bit UNIX (Sheet 2 of 2)

Linker Flag Description

-ltibrvcmq64 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.

Microsoft Windows
Release 8.3.0 supports Visual C++ in the following combinations:
• Visual C++ (VC8 and VC9) on 32-bit and 64-bit Windows (XP, Server 2003,
Server 2008, Vista)

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 17.

Table 6 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.

TIBCO Rendezvous C++ Reference

12
| Chapter 2 Programmer’s Checklist

Table 6 Library Files for Microsoft Windows (Sheet 2 of 3)

Library File Description

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).

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).

TIBCO Rendezvous C++ Reference

 Link These Library Files 13
|

Table 6 Library Files for Microsoft Windows (Sheet 3 of 3)

Library File Description

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.

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

14
| Chapter 2 Programmer’s Checklist

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

 Link These Library Files 15
|
$ 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 7 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

16
| Chapter 2 Programmer’s Checklist

Table 7 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

 Source Code Distribution 17
|

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

18
| Chapter 2 Programmer’s Checklist

TIBCO Rendezvous C++ Reference

 | 19

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 20
• TibrvSdContext, page 26

TIBCO Rendezvous C++ Reference

20
| 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. 23

Tibrv::close() Stop and destroy Rendezvous internal machinery. 21

Tibrv::version() Identify the Rendezvous API release number. 25

Utility Objects

Tibrv::defaultQueue() Extract the default queue object. 22

Tibrv::processTransport() Extract the intra-process transport object. 24

TIBCO Rendezvous C++ Reference

 Tibrv::close() 21
|

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 23

TIBCO Rendezvous C++ Reference

22
| 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 184.

TIBCO Rendezvous C++ Reference

 Tibrv::open() 23
|

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 21

TIBCO Rendezvous C++ Reference

24
| 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 240

TIBCO Rendezvous C++ Reference

 Tibrv::version() 25
|

Tibrv::version()
Method

Declaration static const char* version();

Purpose Identify the Rendezvous API release number.

TIBCO Rendezvous C++ Reference

26
| 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. 27

TibrvSdContext:setUserCertWithKey() Register a (PEM) certificate with 29

private key for identification to secure
daemons.

TibrvSdContext:setUserCertWithKeyBin() Register a (PKCS #12) certificate with 30

private key for identification to secure
daemons.

TibrvSdContext:setUserNameWithPassword() Register a user name with password 31

for identification to secure daemons.

TIBCO Rendezvous C++ Reference

 TibrvSdContext:setDaemonCert() 27
|

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 SSL 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 28.

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 243.
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 SSL
connections.
(This syntax is similar to the syntax connecting to remote daemons, with the
addition of the prefix ssl.)

TIBCO Rendezvous C++ Reference

28
| 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 175 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() 29
|

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 SSL 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 175 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 175 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 30

TIBCO Rendezvous C++ Reference

30
| 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 SSL 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 175 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 175 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 29

www.rsasecurity.com/rsalabs/pkcs

TIBCO Rendezvous C++ Reference

 TibrvSdContext:setUserNameWithPassword() 31
|

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 SSL 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 175 in TIBCO Rendezvous Administration.

TIBCO Rendezvous C++ Reference

32
| Chapter 3 Rendezvous Environment

TIBCO Rendezvous C++ Reference

 | 33

Chapter 4 Data

This chapter describes messages and the data they contain.

Topics

• Validity of Data Extracted From Message Fields, page 34

• Field Names and Field Identifiers, page 39
• TibrvMsg, page 41
• TibrvMsgField, page 109
• TibrvMsgDateTime, page 118

See Also Strings and Character Encodings, page 3

Datatypes, page 371
Custom Datatypes on page 365 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

34
| 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
Update Field

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 35
|

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
Array
Array
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 36), 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

36
| 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
Snapshot
Array Value
of 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 37
|

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

38
| 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 89

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 39
|

Field Names and Field Identifiers

In Rendezvous 5 and earlier releases, programs would specify fields within a

message using a field name. In Rendezvous 6 and later releases, 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 40.

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

40
| 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 81.
• TibrvMsg::removeFieldInstance() on page 93.

TIBCO Rendezvous C++ Reference

 TibrvMsg 41
|

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. 44

~TibrvMsg() Destroy a message object. 46

TibrvMsg::convertToString() Format a message as a string. 59

TibrvMsg::createCopy() Store a copy of this message in another 60

message object.

TibrvMsg::detach() Detach an inbound message from 61

Rendezvous storage; the program
assumes responsibility for destroying the
message.

TibrvMsg::expand() Enlarge a message by allocating 62

additional storage.

TibrvMsg::getAsBytes() Extract the data from a message as a byte 63

sequence.

TibrvMsg::getAsBytesCopy() Extract a copy of the data from a message 64

as a byte sequence.

TibrvMsg::getByteSize() Return the size of a message (in bytes). 65

TibrvMsg::getHandle() Extract the C message handle from a C++ 83

message object.

TibrvMsg::getNumFields() Extract the number of fields in a message. 84

TIBCO Rendezvous C++ Reference

42
| Chapter 4 Data

(Sheet 2 of 3)

Method Description Page

TibrvMsg::getStatus() Extract the status code stored by the 87
message constructor.

TibrvMsg::isDetached() Determine the ownership of the message. 88

TibrvMsg::reset() Clear a message, preparing it for re-use. 94

Fields

TibrvMsg::addField() Add a field object to a message. 47

TibrvMsg::getField() Get a specified field from a message. 67

TibrvMsg::getFieldByIndex() Get a field from a message by an index. 80

TibrvMsg::getFieldInstance() Get a specified instance of a field from a 81

message.

TibrvMsg::removeField() Remove a field from a message. 91

TibrvMsg::removeFieldInstance() Remove a specified instance of a field 93

from a message.

TibrvMsg::updateField() Update a field within a message. 97

Address Information

TibrvMsg::getReplySubject() Extract the reply subject from a message. 85

TibrvMsg::getSendSubject() Extract the subject from a message. 86

TibrvMsg::setReplySubject() Set the reply subject for a message. 95

TibrvMsg::setSendSubject() Set the subject for a message. 96

Field References

TibrvMsg::clearReferences() Clear references in this message. 58

TibrvMsg::markReferences() Mark references in this message. 89

TIBCO Rendezvous C++ Reference

 TibrvMsg 43
|

(Sheet 3 of 3)

Method Description Page

Event Dispatched

TibrvMsg::getEvent() Extract the event associated with a 82

(dispatched) message object.

Time String

TibrvMsg::getCurrentTime() Get the current date and time. 66

See Also Strings and Character Encodings, page 3

TibrvMsgField on page 109
Datatypes, page 371

TIBCO Rendezvous C++ Reference

44
| 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 46).

(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() 45
|

(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 60

TibrvMsg::detach()on page 61
TibrvMsg::getAsBytes() on page 63
TibrvMsg::getStatus() on page 87
TibrvMsg::getHandle() on page 83
tibrvMsg on page 52 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

46
| Chapter 4 Data

~TibrvMsg()
Destructor

Declaration ~TibrvMsg();

Purpose Destroy a message object.

See Also TibrvMsg::detach() on page 61

TIBCO Rendezvous C++ Reference

 TibrvMsg::addField() 47
|

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 Earlier releases of Rendezvous software allowed programs to append fields to a
a Nested nested submessage under certain conditions. Starting with release 6, Rendezvous
Message software no longer supports this special case convenience. Instead, programs
must use this three-step process:
1. Extract the nested submessage (see Get Nested Message on page 74).
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 104).

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.

TIBCO Rendezvous C++ Reference

48
| Chapter 4 Data

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 (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 49.
• Add Array, page 51.
• Add Nested Message, page 53.
• Add String, page 54.
• Add Opaque Byte Sequence, page 55.
• Add XML Byte Sequence, page 56.
• Add DateTime, page 57.

See Also Add Scalar, page 49

TIBCO Rendezvous C++ Reference

 Add Scalar 49
|

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

50
| 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 51
|

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

52
| 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 53
|

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

54
| 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 55
|

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

56
| 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 57
|

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 78.)
#include <limits.h>
TibrvStatus addAsTimeT(
TibrvMsg& msg,
const char* field,
time_t value)
{
examples/c/ d;
d.sec = (tibrv_i64)value;
return msg.addDateTime(field,d);
}

See Also TibrvMsgDateTime on page 118

TIBCO Rendezvous C++ Reference

58
| 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 89.

See Also Validity of Data Extracted From Message Fields, page 34

Deleting Snapshot References, page 38
TibrvMsg::markReferences() on page 89

TIBCO Rendezvous C++ Reference

 TibrvMsg::convertToString() 59
|

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 120

TIBCO Rendezvous C++ Reference

60
| 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 44

TIBCO Rendezvous C++ Reference

 TibrvMsg::detach() 61
|

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 36, or more generally, Validity of Data
Extracted From Message Fields on page 34.

See Also ~TibrvMsg() on page 46

TibrvCallback::onEvent()on page 138
TibrvMsgCallback::onMsg()on page 150
TibrvCmMsgCallback::onCmMsg() on page 353

TIBCO Rendezvous C++ Reference

62
| 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() 63
|

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 44.
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 44

TibrvMsg::getAsBytesCopy() on page 64

TIBCO Rendezvous C++ Reference

64
| 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 65.
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 63

TibrvMsg::getByteSize() on page 65
TibrvMsg() on page 44

TIBCO Rendezvous C++ Reference

 TibrvMsg::getByteSize() 65
|

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 63

TibrvMsg::getAsBytesCopy() on page 64

TIBCO Rendezvous C++ Reference

66
| 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() 67
|

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 39.
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 80.

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

68
| 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 Earlier releases of Rendezvous software allowed programs to get fields from a
Fields from a nested submessage by concatenating field names. Starting with release 6,
Nested Message Rendezvous software no longer supports this special case convenience. Instead,
programs must separately extract the nested submessage using
TibrvMsg::getMsg(), and then get the desired fields from the submessage.

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.)

TIBCO Rendezvous C++ Reference

 TibrvMsg::getField() 69
|

These categories of type-specific convenience methods find a field and get its
data:
• Get Scalar, page 70.
• Get Array, page 72.
• Get Nested Message, page 74.
• Get String, page 75.
• Get Opaque Byte Sequence, page 76.
• Get XML Byte Sequence, page 77.
• Get DateTime, page 78.

See Also Field Names and Field Identifiers, page 39

Get Scalar, page 70
TibrvMsgField on page 109

TIBCO Rendezvous C++ Reference

70
| 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 71
|

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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

72
| 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 35). 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 73
|

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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

74
| 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 37).

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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

 Get String 75
|

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 35). 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 34

Field Names and Field Identifiers, page 39
Datatype Conversion, page 376

TIBCO Rendezvous C++ Reference

76
| 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 35). 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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

 Get XML Byte Sequence 77
|

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 35). 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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

78
| 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 35). 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 57.)
#include <limits.h>

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 79
|
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 34

Field Names and Field Identifiers, page 39

TIBCO Rendezvous C++ Reference

80
| 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 67

TIBCO Rendezvous C++ Reference

 TibrvMsg::getFieldInstance() 81
|

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 67

TIBCO Rendezvous C++ Reference

82
| 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 128

TibrvVectorCallback::onMsgs() on page 160

TIBCO Rendezvous C++ Reference

 TibrvMsg::getHandle() 83
|

TibrvMsg::getHandle()
Method

Declaration tibrvMsg getHandle() const;

Purpose Extract the C message handle from a C++ message object.

See Also TibrvMsg() on page 44

TIBCO Rendezvous C++ Reference

84
| 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() 85
|

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 35,
and Deleting Snapshot References on page 38.

See Also TibrvMsg::setReplySubject() on page 95

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C++ Reference

86
| 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 35, and
Deleting Snapshot References on page 38.

See Also TibrvMsg::setSendSubject() on page 96

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C++ Reference

 TibrvMsg::getStatus() 87
|

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 TibrvMsgon page 41

TibrvMsg()on page 44
TibrvStatus on page 380

TIBCO Rendezvous C++ Reference

88
| 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 61

TIBCO Rendezvous C++ Reference

 TibrvMsg::markReferences() 89
|

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

90
| 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
Array
Snapshot
Value
1
Snapshot 1
Mark 2
Pointer to
Array
Snapshot
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 34

Deleting Snapshot References, page 38
TibrvMsg::clearReferences() on page 58

TIBCO Rendezvous C++ Reference

 TibrvMsg::removeField() 91
|

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

92
| 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 93

TIBCO Rendezvous C++ Reference

 TibrvMsg::removeFieldInstance() 93
|

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 91

TIBCO Rendezvous C++ Reference

94
| 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 44

~TibrvMsg() on page 46

TIBCO Rendezvous C++ Reference

 TibrvMsg::setReplySubject() 95
|

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 85

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C++ Reference

96
| 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 86

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C++ Reference

 TibrvMsg::updateField() 97
|

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

98
| 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 100.
• Update Array, page 102.
• Update Nested Message, page 104.

TIBCO Rendezvous C++ Reference

 TibrvMsg::updateField() 99
|

• Update String, page 105.

• Update Opaque Byte Sequence, page 106
• Update DateTime, page 108

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

100
| 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 101
|

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 39

TIBCO Rendezvous C++ Reference

102
| 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 35.)

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 103
|

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 39

TIBCO Rendezvous C++ Reference

104
| 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 37.)
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 39

TIBCO Rendezvous C++ Reference

 Update String 105
|

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 35.)

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 39

TIBCO Rendezvous C++ Reference

106
| 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 35.)

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 39

TIBCO Rendezvous C++ Reference

 Update XML Byte Sequence 107
|

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 35.)
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 39

TIBCO Rendezvous C++ Reference

108
| 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 39

TIBCO Rendezvous C++ Reference

 TibrvMsgField 109
|

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. 111

TibrvMsgField::getCount() Get the number of elements in a 112

field.

TibrvMsgField::getData() Get the data value of a field. 113

TibrvMsgField::getId() Get the identifier of a field. 114

TibrvMsgField::getName() Get the name of a field. 115

TibrvMsgField::getSize() Get the size of a field. 116

TibrvMsgField::getType() Get the datatype of a field. 117

(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

110
| 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 47

TibrvMsg::getField() on page 67
TibrvMsg::updateField() on page 97
tibrvMsgField on page 55 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

 TibrvMsgField() 111
|

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 47

TibrvMsg::getField()on page 67
TibrvMsg::updateField() on page 97

TIBCO Rendezvous C++ Reference

112
| 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() 113
|

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 55, Get Opaque Byte Sequence on
page 76, or Update Opaque Byte Sequence on page 106.

TIBCO Rendezvous C++ Reference

114
| 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() 115
|

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

116
| 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() 117
|

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

118
| 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. 121

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 119
|

(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 8 on page 119
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 8 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

120
| 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 57

TibrvMsg::convertToString()
Get DateTime, page 78
Update DateTime, page 108
tibrvMsgDateTime on page 53 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

 TibrvMsgDateTime() 121
|

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 118

Representations, page 119

TIBCO Rendezvous C++ Reference

122
| Chapter 4 Data

TIBCO Rendezvous C++ Reference

 | 123

Chapter 5 Events and Queues

This chapter presents classes and methods associated with event interest and
event processing.

Topics

• Event Overview, page 124

• TibrvEvent, page 125
• TibrvCallback, page 137
• TibrvEventOnComplete, page 139
• TibrvListener, page 143
• TibrvMsgCallback, page 149
• TibrvVectorListener, page 151
• TibrvVectorCallback, page 159
• TibrvTimer, page 161
• TibrvTimerCallback, page 167
• TibrvIOEvent, page 169
• TibrvIOCallback, page 175
• TibrvDispatchable, page 177
• TibrvQueue, page 184
• TibrvQueueGroup, page 203
• TibrvDispatcher, page 214

TIBCO Rendezvous C++ Reference

124
| 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 125
|

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 259.

Method Description Page

TibrvEvent::destroy() Destroy an event, canceling interest. 127

TibrvEvent::getClosure() Extract the closure data of an event object. 128

TibrvEvent::getHandle() Return the C event handle of this C++ event object. 129

TibrvEvent::getType() Return the C event type token of an event object. 130

TibrvEvent::getQueue() Extract the queue of an event object. 131

TibrvEvent::isIOEvent() Test whether this event object is an I/O event. 132

TibrvEvent::isListener() Test whether this event object is a listener. 133

TibrvEvent::isTimer() Test whether this event object is a timer. 134

TibrvEvent::isValid() Test whether an event has been destroyed. 135

TibrvEvent::isVectorListener() Test whether this event object is a vector listener. 136

Descendants TibrvListener on page 143

TibrvVectorListener on page 151
TibrvTimer on page 161

TIBCO Rendezvous C++ Reference

126
| Chapter 5 Events and Queues

TibrvIOEvent on page 169

TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

 TibrvEvent::destroy() 127
|

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 140.

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 135

TibrvEventOnComplete on page 139
tibrvEvent_Destroy() on page 151 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

128
| 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() 129
|

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

130
| 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() 131
|

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

132
| 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 143

TibrvTimeron page 161
TibrvIOEvent on page 169
TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

 TibrvEvent::isListener() 133
|

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 143

TibrvTimeron page 161
TibrvIOEvent on page 169
TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

134
| 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 143

TibrvTimeron page 161
TibrvIOEvent on page 169
TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

 TibrvEvent::isValid() 135
|

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 127

TIBCO Rendezvous C++ Reference

136
| 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 151

TIBCO Rendezvous C++ Reference

 TibrvCallback 137
|

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. 138

Descendants TibrvMsgCallback on page 149

TibrvVectorListener on page 151
TibrvCmMsgCallback on page 352
TibrvTimerCallback on page 167
TibrvIOCallback on page 175

TIBCO Rendezvous C++ Reference

138
| 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 139
|

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 140
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

140
| 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 142 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() 141
|

software runs the completion method immediately, in the same thread as the
callback method that completes last.
• Figure 7 on page 142 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

142
| 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 172

TibrvListener::create() on page 146
TibrvTimer::create() on page 164
TibrvEvent::destroy() on page 127

TIBCO Rendezvous C++ Reference

 TibrvListener 143
|

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. 146

TibrvListener::getSubject() Extract the subject from a 147

listener event object.

TibrvListener::getTransport() Extract the transport from a 148

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

144
| 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 127.)

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 145
|

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 125

TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

146
| 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 115 in TIBCO
Rendezvous Concepts.

See Also TibrvListener::getSubject() on page 147

TibrvTransport::createInbox() on page 226

TIBCO Rendezvous C++ Reference

 TibrvListener::getSubject() 147
|

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

148
| 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 149
|

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 150
events).

Related Classes TibrvCallback on page 137

TibrvCmMsgCallback on page 352

See Also TibrvListener::create() on page 146

TIBCO Rendezvous C++ Reference

150
| 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 301

TibrvCmMsg::getSender()on page 347
TibrvCmMsg::getSequence() on page 348
TibrvCmMsg::getTimeLimit() on page 350

TIBCO Rendezvous C++ Reference

 TibrvVectorListener 151
|

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 152
them in a vector.

TibrvVectorListener::getSubject() Extract the subject from a vector listener 157

event object.

TibrvVectorListener::getTransport() Extract the transport from a vector listener 158

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 125

TibrvVectorCallback on page 159

TIBCO Rendezvous C++ Reference

152
| 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() 153
|
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

154
| 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() 155
|

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

50 51
49

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

156
| 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 157

TIBCO Rendezvous C++ Reference

 TibrvVectorListener::getSubject() 157
|

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

158
| 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 159
|

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 160
events).

Related Classes TibrvVectorListener on page 151

See Also TibrvVectorListener::create() on page 152

TIBCO Rendezvous C++ Reference

160
| 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 82

TibrvVectorListener::create() on page 152

TIBCO Rendezvous C++ Reference

 TibrvTimer 161
|

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 127.)

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

162
| 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
Enter queue. Waiting in
Running
Queue
Event
3. Dispatch the event Callback Function
Waiting in
to its callback function. Running
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 163
|
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 114 in TIBCO Rendezvous Concepts.

Method Description Page

TibrvTimer::create() Start a timer. 164

TibrvTimer::getInterval() Extract the interval from a timer 165

event object.

TibrvTimer::resetInterval() Reset the interval of a timer event 166

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 125

TIBCO Rendezvous C++ Reference

164
| 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 114 in TIBCO Rendezvous Concepts.

See Also Timer Event Semantics, page 96 in TIBCO Rendezvous Concepts

TibrvEvent::destroy() on page 127
TibrvTimerCallback on page 167
TibrvTimerCallback::onTimer() on page 168

TIBCO Rendezvous C++ Reference

 TibrvTimer::getInterval() 165
|

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 166

TIBCO Rendezvous C++ Reference

166
| 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 167
|

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. 168

Related Classes TibrvCallback on page 137

See Also TibrvTimer::create() on page 164

TIBCO Rendezvous C++ Reference

168
| 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 169
|

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 127.)
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

170
| 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 171
|

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 172
to occur.

TibrvIOEvent::getIOSource() Extract the source (socket ID) 173

from an I/O event object.

TibrvIOEvent::getIOType() Extract the I/O type from an I/O 174

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 125

See Also TibrvIOCallback on page 175

TIBCO Rendezvous C++ Reference

172
| 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 127

TibrvTimerCallback on page 167
TibrvTimerCallback::onTimer() on page 168
I/O Event Semantics, page 94 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvIOEvent::getIOSource() 173
|

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 172

TIBCO Rendezvous C++ Reference

174
| 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 172

TIBCO Rendezvous C++ Reference

 TibrvIOCallback 175
|

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. 176

Related Classes TibrvCallback on page 137

See Also TibrvIOEvent on page 169

TIBCO Rendezvous C++ Reference

176
| 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 177
|

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. 178

TibrvDispatchable::getDispatchable() Extract the C handle of a queue or queue 180

group.

TibrvDispatchable::isValid() Test validity of a queue or queue group. 181

Dispatch

TibrvDispatchable::dispatch() Dispatch an event; if no event is ready, 179

block.

TibrvDispatchable::poll() Dispatch an event, if possible. 182

TibrvDispatchable::timedDispatch() Dispatch an event, but if no event is ready 183

to dispatch, limit the time that this call
blocks while waiting for an event.

Descendants TibrvQueue on page 184

TibrvQueueGroup on page 203

See Also TibrvQueue on page 184

TibrvQueueGroup on page 203

TIBCO Rendezvous C++ Reference

178
| 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 188

TibrvQueueGroup::destroy() on page 207

TIBCO Rendezvous C++ Reference

 TibrvDispatchable::dispatch() 179
|

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 TibrvDispatchableon page 177

TibrvQueue::dispatch()on page 189
TibrvQueueGroup::dispatch() on page 208

TIBCO Rendezvous C++ Reference

180
| 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() 181
|

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

182
| 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 TibrvDispatchableon page 177

TibrvQueue::poll()on page 196
TibrvQueueGroup::poll() on page 211

TIBCO Rendezvous C++ Reference

 TibrvDispatchable::timedDispatch() 183
|

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 177

TibrvQueue::timedDispatch() on page 200
TibrvQueueGroup::timedDispatch() on page 213

TIBCO Rendezvous C++ Reference

184
| 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 185
|

(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. 187

TibrvQueue::destroy() Destroy an event queue. 188

TibrvQueue::getHandle() Extract the C handle of this queue. 191

TibrvQueue::isValid() Test validity of a queue. 195

Dispatch

TibrvQueue::dispatch() Dispatch an event; if no event is ready, block. 189

TibrvQueue::poll() Dispatch an event, if possible. 196

TibrvQueue::timedDispatch() Dispatch an event, but if no event is ready to 200

dispatch, limit the time that this call blocks while
waiting for an event.

Properties

TibrvQueue::getCount() Extract the number of events in a queue. 190

TibrvQueue::getLimitPolicy() Extract the limit properties of a queue. 192

TibrvQueue::getName() Extract the name of a queue. 193

TibrvQueue::getPriority() Extract the priority of a queue. 194

TibrvQueue::setName() Set the name of a queue. 198

TibrvQueue::setLimitPolicy() Set the limit properties of a queue. 197

TibrvQueue::setPriority() Set the priority of a queue. 199

TIBCO Rendezvous C++ Reference

186
| Chapter 5 Events and Queues

Inherited Methods
TibrvDispatchable::getDispatchable()
TibrvDispatchable::destroy()
TibrvDispatchable::dispatch()
TibrvDispatchable::isValid()
TibrvDispatchable::poll()
TibrvDispatchable::timedDispatch()

Related Classes TibrvDispatchable on page 177

TibrvQueueGroup on page 203

TIBCO Rendezvous C++ Reference

 TibrvQueue::create() 187
|

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 197
maxEvents zero (unlimited)

discardAmount zero

name tibrvQueue TibrvQueue::setName() on page 198

priority 1 TibrvQueue::setPriority() on page 199

TIBCO Rendezvous C++ Reference

188
| 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 21.

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() 189
|

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 177

TibrvDispatchable::dispatch() on page 179
TibrvQueue::poll() on page 196
TibrvQueue::timedDispatch() on page 200
TibrvDispatcher on page 214

TIBCO Rendezvous C++ Reference

190
| 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() 191
|

TibrvQueue::getHandle()
Method

Declaration tibrvQueue getHandle() const;

Purpose Extract the C handle of this queue.

TIBCO Rendezvous C++ Reference

192
| 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 184.
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 197
QUEUE.LIMIT_EXCEEDED on page 276 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvQueue::getName() 193
|

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 198

TIBCO Rendezvous C++ Reference

194
| 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 199

TIBCO Rendezvous C++ Reference

 TibrvQueue::isValid() 195
|

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 21

TibrvQueue::destroy() on page 188

TIBCO Rendezvous C++ Reference

196
| 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 TibrvDispatchableon page 177

TibrvDispatchable::poll() on page 182
TibrvQueue::dispatch() on page 189
TibrvQueue::timedDispatch() on page 200

TIBCO Rendezvous C++ Reference

 TibrvQueue::setLimitPolicy() 197
|

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 192

TIBCO Rendezvous C++ Reference

198
| 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 193

TIBCO Rendezvous C++ Reference

 TibrvQueue::setPriority() 199
|

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 194

TIBCO Rendezvous C++ Reference

200
| 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 177

TibrvDispatchable::timedDispatch() on page 183
TibrvQueue::dispatch() on page 189
TibrvQueue::poll() on page 196

TIBCO Rendezvous C++ Reference

 TibrvQueueOnComplete 201
|

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 202
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

202
| 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 188

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup 203
|

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. 206

TibrvQueueGroup::destroy() Destroy an event queue group. 207

TibrvQueueGroup::getHandle() Extract the C handle of this queue group. 209

TibrvQueueGroup::isValid() Test validity of a queue group. 210

Dispatch

TibrvQueueGroup::dispatch() Dispatch an event from a queue group; if no 208

event is ready, block.

TibrvQueueGroup::poll() Dispatch an event, but if no event is ready to 211

dispatch, return immediately (without
blocking).

TibrvQueueGroup::timedDispatch() Dispatch an event, but if no event is ready to 213

dispatch, limit the time that this call blocks
while waiting for an event.

Queues

TibrvQueueGroup::add() Add an event queue to a queue group. 205

TIBCO Rendezvous C++ Reference

204
| Chapter 5 Events and Queues

(Sheet 2 of 2)

Method Description Page

TibrvQueueGroup::remove() Remove an event queue from a queue group. 212

Inherited Methods
TibrvDispatchable::getDispatchable()
TibrvDispatchable::destroy()
TibrvDispatchable::dispatch()
TibrvDispatchable::isValid()
TibrvDispatchable::poll()
TibrvDispatchable::timedDispatch()

Related Classes TibrvDispatchable on page 177

TibrvQueue on page 184

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup::add() 205
|

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 184

TIBCO Rendezvous C++ Reference

206
| 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 205

TibrvQueueGroup::destroy() on page 207

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup::destroy() 207
|

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 206

TIBCO Rendezvous C++ Reference

208
| 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 177

TibrvDispatchable::dispatch() on page 179
TibrvQueueGroup::timedDispatch() on page 213
TibrvQueueGroup::poll() on page 211

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup::getHandle() 209
|

TibrvQueueGroup::getHandle()
Method

Declaration tibrvQueueGroup getHandle() const;

Purpose Extract the C handle of this queue group.

TIBCO Rendezvous C++ Reference

210
| 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 21

TibrvQueueGroup::destroy() on page 207

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup::poll() 211
|

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 TibrvDispatchableon page 177

TibrvDispatchable::poll() on page 182
TibrvQueueGroup::dispatch() on page 208
TibrvQueueGroup::timedDispatch() on page 213

TIBCO Rendezvous C++ Reference

212
| 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 184

TIBCO Rendezvous C++ Reference

 TibrvQueueGroup::timedDispatch() 213
|

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 177

TibrvDispatchable::timedDispatch() on page 183
TibrvQueueGroup::dispatch() on page 208
TibrvQueueGroup::poll() on page 211

TIBCO Rendezvous C++ Reference

214
| 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. 215

TibrvDispatcher::destroy() Destroy a dispatcher thread. 216

TibrvDispatcher::getDispatchable() Extract the queue or queue group that this 217

thread dispatches.

TibrvDispatcher::getHandle() Extract the C handle of this dispatcher thread. 218

TibrvDispatcher::getName() Extract the name of a dispatcher thread. 219

TibrvDispatcher::isValid() Test whether a dispatcher object has been 220

destroyed.

TibrvDispatcher::setName() Set the name of a dispatcher thread. 221

See Also TibrvDispatchable::timedDispatch() on page 183

DISPATCHER.THREAD_EXITED on page 271 in TIBCO Rendezvous Concepts
tibrvDispatcher on page 201 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

 TibrvDispatcher::create() 215
|

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 177
TibrvDispatcher::destroy() on page 216
TibrvDispatcher::setName() on page 221
DISPATCHER.THREAD_EXITED on page 271 in TIBCO Rendezvous Concepts
tibrvDispatcher on page 201 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

216
| 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 271 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvDispatcher::getDispatchable() 217
|

TibrvDispatcher::getDispatchable()
Method

Declaration TibrvDispatchable* getDispatchable() const;

Purpose Extract the queue or queue group that this thread dispatches.

TIBCO Rendezvous C++ Reference

218
| 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() 219
|

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

220
| 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() 221
|

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

222
| Chapter 5 Events and Queues

TIBCO Rendezvous C++ Reference

 | 223

Chapter 6 Transports

Transports manage network connections and send outbound messages.

This chapter presents the various transport classes and their methods.

Topics

• TibrvTransport, page 224

• tibrvTransportBatchMode, page 239
• TibrvProcessTransport, page 240
• TibrvNetTransport, page 241

See Also
TibrvCmTransport on page 307
TibrvCmQueueTransport on page 356

TIBCO Rendezvous C++ Reference

224
| 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. 226

TibrvTransport::destroy() Destroy a transport. 228

TibrvTransport::isValid() Test validity of a transport. 231

TibrvTransport::getDescription() Extract the program description parameter 229

from a transport.

TibrvTransport::getHandle() Extract the C handle of this transport object. 230

TibrvTransport::requestReliability() Request reliability interval (message 232

retention time) for a service.

TibrvTransport::send() Send a message. 234

TibrvTransport::sendReply() Send a reply message. 235

TIBCO Rendezvous C++ Reference

 TibrvTransport 225
|

(Sheet 2 of 2)

Method Description Page

TibrvTransport::sendRequest() Send a request message and wait for a reply. 236

TibrvTransport::setDescription() Set the program description parameter of a 238

transport.

Descendants TibrvProcessTransport on page 240

TibrvNetTransport on page 241
TibrvVcTransport on page 252
TibrvCmTransport on page 307
TibrvCmQueueTransport on page 356

See Also Transport on page 99 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

226
| 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() 227
|

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 95

TIBCO Rendezvous C++ Reference

228
| 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 231

TIBCO Rendezvous C++ Reference

 TibrvTransport::getDescription() 229
|

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 224

TibrvTransport::setDescription() on page 238

TIBCO Rendezvous C++ Reference

230
| 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() 231
|

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 21

TibrvTransport::destroy()on page 228
TibrvCmTransport::destroy()on page 319
TibrvCmQueueTransport::destroy() on page 362

TIBCO Rendezvous C++ Reference

232
| 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.
Programs can request reliability only from daemons of release 8.2 or later.
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.

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.
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.

TIBCO Rendezvous C++ Reference

 TibrvTransport::requestReliability() 233
|
See Also TibrvTransport on page 224
Reliability and Message Retention Time on page 34 in TIBCO Rendezvous
Administration
Lower Value Rule on page 35 in TIBCO Rendezvous Administration
Changing the Reliability Interval within an Application Program on page 36 in
TIBCO Rendezvous Administration
Reliable Message Delivery on page 58 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

234
| 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 96.

Parameter Description
message Send this message.

See Also TibrvMsg::setSendSubject() on page 96

TIBCO Rendezvous C++ Reference

 TibrvTransport::sendReply() 235
|

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 85

TIBCO Rendezvous C++ Reference

236
| 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 96.

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() 237
|

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

238
| 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 224

TibrvTransport::getDescription() on page 229

TIBCO Rendezvous C++ Reference

 tibrvTransportBatchMode 239
|

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 249

Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

240
| 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 TibrvTransporton page 224

TibrvNetTransport on page 241
TibrvCmTransport on page 307

See Also Tibrv::open() on page 23

Tibrv::processTransport() on page 24

TIBCO Rendezvous C++ Reference

 TibrvNetTransport 241
|

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 243
connects to a Rendezvous
daemon.

TibrvNetTransport::getDaemon() Extract the daemon 246

parameter from this
transport.

TibrvNetTransport::getNetwork() Return the network 247

interface that this
transport uses for
communication.

TibrvNetTransport::getService() Return the effective 248

service that this transport
uses for communication.

TibrvNetTransport::setBatchMode() Set the batch mode 249

parameter of a transport.

TIBCO Rendezvous C++ Reference

242
| Chapter 6 Transports

Inherited Methods
TibrvTransport::createInbox()
TibrvTransport::destroy()
TibrvTransport::isValid()
TibrvTransport::getHandle()
TibrvTransport::send()
TibrvTransport::sendReply()
TibrvTransport::sendRequest()
TibrvTransport::setDescription()

Related Classes TibrvTransporton page 224

TibrvProcessTransport on page 240
TibrvCmTransport on page 307
TibrvCmQueueTransport on page 356

TIBCO Rendezvous C++ Reference

 TibrvNetTransport::create() 243
|

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 103 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 107 in TIBCO Rendezvous Concepts.
NULL specifies the primary network interface for the host computer.

TIBCO Rendezvous C++ Reference

244
| 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 110 in TIBCO Rendezvous Concepts.
You can specify a daemon on a remote computer. For details, see Remote
Daemon on page 111 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 27. See
also, Secure Daemon on page 111 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 245.

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.
The first time a program successfully connects to the Rendezvous daemon
process, rvd starts the clock ticking for temporary license tickets. (See Licensing
Information, page 11 in TIBCO Rendezvous Administration.)

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 238.

TIBCO Rendezvous C++ Reference

 TibrvNetTransport::create() 245
|
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.

See Also TibrvNetTransport::getDaemon()on page 246

TibrvNetTransport::getNetwork() on page 247
TibrvNetTransport::getService() on page 248

TIBCO Rendezvous C++ Reference

246
| 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() 247
|

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

248
| 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() 249
|

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 239

Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

250
| Chapter 6 Transports

TIBCO Rendezvous C++ Reference

 | 251

Chapter 7 Virtual Circuits

Virtual circuits feature Rendezvous communication between two terminals over

an exclusive, continuous, monitored connection.

See Also Virtual Circuits on page 119 in TIBCO Rendezvous Concepts

Topics

• TibrvVcTransport, page 252

TIBCO Rendezvous C++ Reference

252
| 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. 254

TibrvVcTransport::createConnectVc() Create a virtual circuit connect object. 256

TibrvVcTransport::waitForVcConnection() Test the connection status of a virtual 257

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 269
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 253
|

• 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 116 in TIBCO Rendezvous
Concepts.
For programming details, see Specifying Direct Communication on page 105 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 119 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

254
| 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 123 in TIBCO
Rendezvous Concepts.

See Also TibrvVcTransport::createConnectVc() on page 256

TIBCO Rendezvous C++ Reference

 TibrvVcTransport::createAcceptVc() 255
|

TibrvVcTransport::waitForVcConnection() on page 257

VC.CONNECTED on page 284 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 285 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

256
| 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 123 in TIBCO
Rendezvous Concepts.

See Also TibrvVcTransport::createAcceptVc() on page 254

TibrvVcTransport::waitForVcConnection() on page 257
VC.CONNECTED on page 284 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 285 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvVcTransport::waitForVcConnection() 257
|

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

258
| 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 254

TibrvVcTransport::createConnectVc() on page 256
Testing the New Connection on page 123 in TIBCO Rendezvous Concepts
VC.CONNECTED on page 284 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 285 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 | 259

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 260

• tibrvftAction, page 261
• TibrvFtMember, page 262
• TibrvFtMemberCallback, page 276
• TibrvFtMemberOnComplete, page 279
• TibrvFtMonitor, page 281
• TibrvFtMonitorCallback, page 292
• TibrvFtMonitorOnComplete, page 294

TIBCO Rendezvous C++ Reference

260
| Chapter 8 Fault Tolerance

Fault Tolerance Road Map

For a complete discussion of concepts and operating principles, see Fault

Tolerance Concepts on page 195 in TIBCO Rendezvous Concepts.
For suggestions to help you design programs using fault tolerance features, see
Fault Tolerance Programming on page 213 in TIBCO Rendezvous Concepts.
For step-by-step hints for implementing fault-tolerant systems, see Developing
Fault-Tolerant Programs on page 227 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 311
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 405 in TIBCO
Rendezvous Administration, and discuss with your network administrator.

TIBCO Rendezvous C++ Reference

 tibrvftAction 261
|

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 214 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 277

TibrvFtMember::create() on page 264

TIBCO Rendezvous C++ Reference

262
| 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 264

tolerance group.

TibrvFtMember::destroy() Destroy a member of a fault 267

tolerance group.

TibrvFtMember::getHandle() Extract the C handle of a fault 270

tolerance member.

TibrvFtMember::isValid() Test validity of a fault tolerance 274

member object.

Properties

TibrvFtMember::getClosure() Extract the closure data of a 268

fault tolerance member.

TibrvFtMember::getGroupName() Extract the group name of a 269

fault tolerance member.

TIBCO Rendezvous C++ Reference

 TibrvFtMember 263
|

(Sheet 2 of 2)

Method Description Page

TibrvFtMember::getQueue() Extract the event queue of a 271
fault tolerance member.

TibrvFtMember::getTransport() Extract the transport of a fault 272

tolerance member.

TibrvFtMember::getWeight() Extract the weight of a fault 273

tolerance member.

TibrvFtMember::setWeight() Change the weight of a fault 275

tolerance member within its
group.

Related Classes TibrvFtMonitor on page 281

See Also TibrvFtMemberCallback on page 276

TIBCO Rendezvous C++ Reference

264
| 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 217 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 235 in TIBCO Rendezvous Concepts.

Group Name The group name must be a legal Rendezvous subject name (see Subject Names on
page 61 in TIBCO Rendezvous Concepts). You may use names with several
elements; for examples, see Multiple Groups on page 217 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() 265
|

(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 61 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 204 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 235 in TIBCO Rendezvous Concepts.

TIBCO Rendezvous C++ Reference

266
| 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 235
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 235 in TIBCO Rendezvous Concepts.

closure Store this closure data in the member object.

See Also TibrvFtMember on page 262.

TibrvFtMemberCallback on page 276.
TibrvFtMember::destroy() on page 267.
Step 1: Choose a Group Name, page 228 in TIBCO Rendezvous Concepts
Step 2: Choose the Active Goal, page 230 in TIBCO Rendezvous Concepts
Step 4: Choose the Intervals, page 235 in TIBCO Rendezvous Concepts
Step 5: Program Start Sequence, page 239 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvFtMember::destroy() 267
|

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 264

TibrvFtMember::isValid() on page 274
TibrvFtMemberOnComplete on page 279
TibrvFtMemberOnComplete::onComplete on page 280

TIBCO Rendezvous C++ Reference

268
| 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 264

TIBCO Rendezvous C++ Reference

 TibrvFtMember::getGroupName() 269
|

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 264

TIBCO Rendezvous C++ Reference

270
| 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 264

tibrvftMember on page 244 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

 TibrvFtMember::getQueue() 271
|

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 184

TibrvFtMember::create() on page 264

TIBCO Rendezvous C++ Reference

272
| 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 224

TibrvFtMember::create() on page 264

TIBCO Rendezvous C++ Reference

 TibrvFtMember::getWeight() 273
|

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 264

TIBCO Rendezvous C++ Reference

274
| 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 267

TIBCO Rendezvous C++ Reference

 TibrvFtMember::setWeight() 275
|

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 265.

See Also Adjusting Member Weights on page 225 in TIBCO Rendezvous Concepts.

TIBCO Rendezvous C++ Reference

276
| 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 277
member.

See Also TibrvFtMember::create() on page 264

TIBCO Rendezvous C++ Reference

 TibrvFtMemberCallback::onFtAction() 277
|

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 214 in
TIBCO Rendezvous Concepts.

TIBCO Rendezvous C++ Reference

278
| 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 261.

See Also TibrvFtMember::create() on page 264

Fault Tolerance Callback Actions on page 214 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvFtMemberOnComplete 279
|

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 280
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 264

TIBCO Rendezvous C++ Reference

280
| 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 140. See that section for
important details.

See Also TibrvFtMember::create() on page 264

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor 281
|

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. 283

TibrvFtMonitor::destroy() Stop monitoring a fault tolerance group, and free 285

associated resources.

TibrvFtMonitor::getHandle() Extract the C handle of a fault tolerance monitor. 288

TibrvFtMonitor::isValid() Test validity of a fault tolerance monitor object. 291

Properties

TibrvFtMonitor::getClosure() Extract the closure data of a fault tolerance 286

monitor.

TIBCO Rendezvous C++ Reference

282
| Chapter 8 Fault Tolerance

(Sheet 2 of 2)

Method Description Page

TibrvFtMonitor::getGroupName() Extract the group name of a fault tolerance 287
monitor.

TibrvFtMonitor::getQueue() Extract the event queue of a fault tolerance 289

monitor.

TibrvFtMonitor::getTransport() Extract the transport of a fault tolerance monitor. 290

Related Classes TibrvFtMember on page 262

See Also TibrvFtMonitorCallback on page 292

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor::create() 283
|

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 61 in TIBCO Rendezvous Concepts.
See also, Group Name on page 284.

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 235 in TIBCO
Rendezvous Concepts.
See also, Lost Interval on page 284.

closure Store this closure data in the monitor object.

TIBCO Rendezvous C++ Reference

284
| 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 61 in TIBCO Rendezvous Concepts). You may use names with several
elements; for examples, see Multiple Groups on page 217 in TIBCO Rendezvous
Concepts.

See Also TibrvFtMonitorCallback on page 292.

TibrvFtMonitor::destroy() on page 285.

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor::destroy() 285
|

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 283

TIBCO Rendezvous C++ Reference

286
| 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 283

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor::getGroupName() 287
|

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 283

TIBCO Rendezvous C++ Reference

288
| 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 283

tibrvftMonitor on page 259 in TIBCO Rendezvous C Reference

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor::getQueue() 289
|

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 184

TibrvFtMonitor::create() on page 283

TIBCO Rendezvous C++ Reference

290
| 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 224

TibrvFtMonitor::create() on page 283

TIBCO Rendezvous C++ Reference

 TibrvFtMonitor::isValid() 291
|

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 285

TIBCO Rendezvous C++ Reference

292
| 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 293
monitor.

See Also TibrvFtMonitor::create() on page 283

TIBCO Rendezvous C++ Reference

 TibrvFtMonitorCallback::onFtMonitor() 293
|

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 283.

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 283.

TIBCO Rendezvous C++ Reference

294
| 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 295
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 283

TIBCO Rendezvous C++ Reference

 TibrvFtMonitorOnComplete::onComplete 295
|

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 140. See that section for
important details.

See Also TibrvFtMonitor::create() on page 283

TIBCO Rendezvous C++ Reference

296
| Chapter 8 Fault Tolerance

TIBCO Rendezvous C++ Reference

 | 297

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 139 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 287 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 401 in TIBCO Rendezvous Administration.
Some programs require certified delivery to one of n worker processes. See
Distributed Queue on page 181 in TIBCO Rendezvous Concepts.

Topics

• TibrvCmListener, page 298

• TibrvCmTransport, page 307
• TibrvCmTransportOnComplete, page 341
• TibrvCmReviewCallback, page 343
• TibrvCmMsg, page 346
• TibrvCmMsgCallback, page 352

TIBCO Rendezvous C++ Reference

298
| 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 301

subject, and request certified delivery
when available.

TibrvCmListener::destroy() Destroy a certified delivery listener. 302

TibrvCmListener::isValid() Test whether a certified delivery listener 305

has been destroyed.

TIBCO Rendezvous C++ Reference

 TibrvCmListener 299
|

(Sheet 2 of 2)

Method Description Page

Confirmation

TibrvCmListener::confirmMsg() Explicitly confirm delivery of a certified 300

message.

TibrvCmListener::setExplicitConfirm() Override automatic confirmation of 306

delivery for this listener.

Properties

TibrvCmListener::getSubject() Extract the subject from a certified 303

delivery listener.

TibrvCmListener::getTransport() Extract the transport from a certified 304

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 125

TibrvListener on page 143

TIBCO Rendezvous C++ Reference

300
| 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 306). 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 154 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 298

TibrvCmListener::setExplicitConfirm() on page 306

TIBCO Rendezvous C++ Reference

 TibrvCmListener::create() 301
|

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 143.

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 298

TibrvCmTransport::destroy()on page 319
TibrvListener::getSubject()on page 147
TibrvTransport::createInbox() on page 226

TIBCO Rendezvous C++ Reference

302
| 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 139

TibrvCmListener on page 298

TIBCO Rendezvous C++ Reference

 TibrvCmListener::getSubject() 303
|

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 298

TIBCO Rendezvous C++ Reference

304
| 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 298

TIBCO Rendezvous C++ Reference

 TibrvCmListener::isValid() 305
|

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 302

TIBCO Rendezvous C++ Reference

306
| 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 150). 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 298

TibrvMsgCallback::onMsg() on page 150
TibrvCmListener::confirmMsg() on page 300

TIBCO Rendezvous C++ Reference

 TibrvCmTransport 307
|

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 314
delivery.

TibrvCmTransport::addListener() Pre-register an anticipated 310

listener.

TibrvCmTransport::allowListener() Invite the named receiver to 311

reinstate certified delivery for its
listeners, superseding the effect of
any previous disallow calls.

TibrvCmTransport::connectToRelayAgent() Connect a certified delivery 312

transport to its designated relay
agent.

TibrvCmTransport::destroy() Destroy a certified delivery 319

transport.

TIBCO Rendezvous C++ Reference

308
| Chapter 9 Certified Message Delivery

(Sheet 2 of 3)

Method Description Page

TibrvCmTransport::disallowListener() Cancel certified delivery to all 320
listeners at a specific
correspondent. Deny subsequent
certified delivery registration
requests from those listeners.

TibrvCmTransport::disconnectFromRelayAgent() Disconnect a certified delivery 321

transport from its relay agent.

TibrvCmTransport::getDefaultTimeLimit() Get the default message time limit 323

for all outbound certified
messages from a transport.

TibrvCmTransport::getLedgerName() Extract the ledger name of a 324

certified delivery transport.

TibrvCmTransport::getName() Extract the correspondent name 325

of a certified delivery transport or
distributed queue member.

TibrvCmTransport::getRelayAgent() Extract the name of the relay 326

agent used by a certified delivery
transport.

TibrvCmTransport::getRequestOld() Extract the request old messages 327

flag of a certified delivery
transport.

TibrvCmTransport::getSyncLedger() Extract the sync ledger flag of a 328

certified delivery transport.

TibrvCmTransport::getTransport() Extract the transport employed 329

by a certified delivery transport
or a distributed queue member.

TibrvCmTransport::removeListener() Unregister a specific listener at a 330

specific correspondent, and free
associated storage in the sender’s
ledger.

TibrvCmTransport::removeSendState() Reclaim ledger space from 332

obsolete subjects.

TIBCO Rendezvous C++ Reference

 TibrvCmTransport 309
|

(Sheet 3 of 3)

Method Description Page

TibrvCmTransport::reviewLedger() Query the ledger for stored items 333
related to a subject name.

TibrvCmTransport::send() Send a labeled message. 334

TibrvCmTransport::sendReply() Send a labeled reply message. 335

TibrvCmTransport::sendRequest() Send a labeled request message 336

and wait for a reply.

TibrvCmTransport::setDefaultTimeLimit() Set the default message time limit 338

for all outbound certified
messages from a transport.

TibrvCmTransport::setPublisherInactivityDisc Set a time limit after which a 339

ardInterval() listening CM transport can
discard state for inactive CM
senders.

TibrvCmTransport::syncLedger() Synchronize the ledger to its 340

storage medium.

Inherited Methods
TibrvTransport::createInbox()
TibrvTransport::destroy()
TibrvTransport::isValid()
TibrvTransport::getHandle()
TibrvTransport::send()
TibrvTransport::sendReply()
TibrvTransport::sendRequest()
TibrvTransport::setDescription()

Related Classes TibrvTransporton page 224

TibrvNetTransporton page 241
TibrvCmQueueTransport on page 356

TIBCO Rendezvous C++ Reference

310
| 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 316

TibrvCmTransport::allowListener() on page 311
TibrvCmTransport::disallowListener() on page 320
TibrvCmTransport::removeListener() on page 330
Anticipating a Listener, page 161 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::allowListener() 311
|

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 316

TibrvCmTransport::disallowListener() on page 320
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

312
| 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() 313
|
Errors The status code TIBRV_INVALID_ARG indicates that the transport does not have a
relay agent.

See Also TibrvCmTransport::create() on page 314

TibrvCmTransport::disconnectFromRelayAgent() on page 321
Relay Agent, page 169 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

314
| 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 316.

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::create() 315
|

(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 316.

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 166 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 316.

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

316
| 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 150 in TIBCO Rendezvous Concepts, and Persistent Correspondents
on page 159 in TIBCO Rendezvous Concepts. For details of reusable name syntax,
see Reusable Names on page 166 in TIBCO Rendezvous Concepts.

Relay Agent TibrvCmTransport::create() automatically connects a transport to its

designated relay agent upon creation; see
TibrvCmTransport::connectToRelayAgent() on page 312.

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 340.

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::create() 317
|

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 319

TibrvCmTransport::connectToRelayAgent() on page 312

TIBCO Rendezvous C++ Reference

318
| 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 95

TibrvTransport::createInbox() on page 226

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::destroy() 319
|

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 342.

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 314

TibrvCmTransport::disconnectFromRelayAgent() on page 321
TibrvCmTransportOnComplete on page 341

TIBCO Rendezvous C++ Reference

320
| 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 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 311.

Parameter Description
cmName Cancel certified delivery to listeners of the transport with this
name.

See Also Name, page 316

TibrvCmTransport::allowListener() on page 311
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::disconnectFromRelayAgent() 321
|

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 157 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 312

TibrvCmTransport::destroy() on page 319
Relay Agent, page 169 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

322
| 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 294 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::getDefaultTimeLimit() 323
|

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 351). 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 338

TibrvCmMsg::setTimeLimit() on page 351

TIBCO Rendezvous C++ Reference

324
| 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 316

TibrvCmTransport::create() on page 314

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::getName() 325
|

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 316

TibrvCmTransport::create() on page 314
TibrvCmQueueTransport::create() on page 359

TIBCO Rendezvous C++ Reference

326
| 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 316

TibrvCmTransport::create() on page 314

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::getRequestOld() 327
|

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 315

TibrvCmTransport::create() on page 314

TIBCO Rendezvous C++ Reference

328
| 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 316

TibrvCmTransport::create() on page 314

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::getTransport() 329
|

TibrvCmTransport::getTransport()
Method

Declaration TibrvTransport* getTransport() const;

Purpose Extract the transport employed by a certified delivery transport or a distributed

queue member.

See Also TibrvTransporton page 224

TibrvNetTransporton page 241
TibrvCmTransport::create() on page 314
TibrvCmQueueTransport::create() on page 359

TIBCO Rendezvous C++ Reference

330
| 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 316

TibrvCmTransport::addListener() on page 310

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::removeListener() 331
|

TibrvCmTransport::disallowListener() on page 320

Canceling Certified Delivery, page 162 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

332
| 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 333

on page 334
TibrvCmTransport::send()
DELIVERY.COMPLETE on page 292 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::reviewLedger() 333
|

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 344.

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 344

TIBCO Rendezvous C++ Reference

334
| 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 351. 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 338); 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 335

TibrvCmTransport::sendRequest() on page 336
TibrvCmTransport::setDefaultTimeLimit() on page 338
TibrvCmMsg::setTimeLimit() on page 351

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::sendReply() 335
|

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 334

TibrvCmTransport::sendRequest() on page 336

TIBCO Rendezvous C++ Reference

336
| 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 96.

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() 337
|
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 334

TibrvCmTransport::sendReply() on page 335

TIBCO Rendezvous C++ Reference

338
| 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 351). 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 323

TibrvCmMsg::setTimeLimit() on page 351

TIBCO Rendezvous C++ Reference

 TibrvCmTransport::setPublisherInactivityDiscardInterval() 339
|

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

340
| 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 316

TibrvCmTransport::create() on page 314
TibrvCmTransport::getSyncLedger() on page 328

TIBCO Rendezvous C++ Reference

 TibrvCmTransportOnComplete 341
|

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 280
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 319

TIBCO Rendezvous C++ Reference

342
| 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 319

TIBCO Rendezvous C++ Reference

 TibrvCmReviewCallback 343
|

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 293
ledger review messages.

See Also TibrvCmTransport::reviewLedger() on page 333

TIBCO Rendezvous C++ Reference

344
| 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 344 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() 345
|

(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 333

TIBCO Rendezvous C++ Reference

346
| 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 347
the sender from a certified message.

TibrvCmMsg::getSequence() Extract the sequence number from a 348

certified message.

TibrvCmMsg::getTimeLimit() Extract the message time limit from 350

a certified message.

TibrvCmMsg::setTimeLimit() Set the message time limit of a 351

certified message.

See Also TibrvMsg on page 41

TIBCO Rendezvous C++ Reference

 TibrvCmMsg::getSender() 347
|

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 314

TibrvCmTransport::getName() on page 325

TIBCO Rendezvous C++ Reference

348
| 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 154 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() 349
|
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 334

TIBCO Rendezvous C++ Reference

350
| 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 351).

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 334

TibrvCmMsg::setTimeLimit() on page 351

TIBCO Rendezvous C++ Reference

 TibrvCmMsg::setTimeLimit() 351
|

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 338); 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 323

TibrvCmTransport::setDefaultTimeLimit() on page 338
TibrvCmMsg::getTimeLimit() on page 350

TIBCO Rendezvous C++ Reference

352
| 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 353
listener events).

Related Classes TibrvCallback on page 137

TibrvMsgCallback on page 149

See Also TibrvCmListener::create() on page 301

TIBCO Rendezvous C++ Reference

 TibrvCmMsgCallback::onCmMsg() 353
|

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 301

TibrvCmMsg::getSender()on page 347
TibrvCmMsg::getSequence() on page 348
TibrvCmMsg::getTimeLimit() on page 350

TIBCO Rendezvous C++ Reference

354
| Chapter 9 Certified Message Delivery

TIBCO Rendezvous C++ Reference

 | 355

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 409 in
TIBCO Rendezvous Administration.

See Also Distributed Queue, page 181 in TIBCO Rendezvous Concepts

Topics

• TibrvCmQueueTransport, page 356

TIBCO Rendezvous C++ Reference

356
| 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 184 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 358. See also Certified Delivery Behavior
in Queue Members on page 183 in TIBCO Rendezvous Concepts.

Method Description Page

TibrvCmQueueTransport::create() Create a transport as a distributed 359
queue member.

TibrvCmQueueTransport::destroy() Destroy a distributed queue member 362

object.

TibrvCmQueueTransport::getCompleteTime() Extract the worker complete time 363

limit of a distributed queue member.

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport 357
|

Method Description Page

TibrvCmQueueTransport::getUnassignedMess Extract the number of unassigned 364
ageCount() task messages from a distributed
queue transport.

TibrvCmQueueTransport::getWorkerWeight() Extract the worker weight of a 365

distributed queue member.

TibrvCmQueueTransport::getWorkerTasks() Extract the worker task capacity of a 366

distributed queue member.

TibrvCmQueueTransport::setCompleteTime() Set the worker complete time limit of 367

a distributed queue member.

TibrvCmQueueTransport::setTaskBacklogLim Set the scheduler task queue limits of 368

it...() a distributed queue transport.

TibrvCmQueueTransport::setWorkerWeight() Set the worker weight of a distributed 369

queue member.

TibrvCmQueueTransport::setWorkerTasks() Set the worker task capacity of a 370

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

358
| 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 TibrvTransporton page 224

TibrvNetTransport on page 241
TibrvCmTransport on page 307

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport::create() 359
|

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 166 in TIBCO

Rendezvous Concepts.

TIBCO Rendezvous C++ Reference

360
| 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.
When omitted, the default value is 1. Value must be greater than zero.

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 186 in TIBCO Rendezvous
Concepts.

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 204 in TIBCO Rendezvous
Concepts.

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport::create() 361
|

(Sheet 3 of 3)

Parameter Description
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 235
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 235
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

See Also TibrvCmQueueTransport::destroy() on page 362

Distributed Queue, page 181, in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

362
| Chapter 10 Distributed Queue

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 359

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport::getCompleteTime() 363
|

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 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::setCompleteTime() on page 367

TIBCO Rendezvous C++ Reference

364
| Chapter 10 Distributed Queue

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

 TibrvCmQueueTransport::getWorkerWeight() 365
|

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 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::create() on page 359
TibrvCmQueueTransport::setWorkerWeight() on page 369

TIBCO Rendezvous C++ Reference

366
| Chapter 10 Distributed Queue

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 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::create() on page 359
TibrvCmQueueTransport::setWorkerTasks() on page 370

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport::setCompleteTime() 367
|

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 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::getCompleteTime() on page 363

TIBCO Rendezvous C++ Reference

368
| Chapter 10 Distributed Queue

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 181, in TIBCO Rendezvous Concepts

TIBCO Rendezvous C++ Reference

 TibrvCmQueueTransport::setWorkerWeight() 369
|

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 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::create() on page 359
TibrvCmQueueTransport::getWorkerWeight() on page 365

TIBCO Rendezvous C++ Reference

370
| Chapter 10 Distributed Queue

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.

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 186 in TIBCO Rendezvous Concepts.

Parameter Description
workerTasks Use this task capacity. Value must be greater than zero.

See Also Distributed Queue, page 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport::create() on page 359
TibrvCmQueueTransport::getWorkerTasks() on page 366

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 118.

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 41.

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 67.
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

tibrvMsgDateTime
tibrv_ipaddr32
tibrv_ipport16

tibrv_u16[]
tibrv_u32[]
tibrv_u64[]
tibrv_f32[]
tibrv_f64[]

tibrv_i16[]
tibrv_i32[]
tibrv_i64[]

tibrvMsg[]
tibrv_bool

tibrv_u16
tibrv_u32
tibrv_u64

tibrv_u8[]
tibrv_f32
tibrv_f64

tibrvMsg
tibrv_i16
tibrv_i32
tibrv_i64

tibrv_i8[]
tibrv_u8
tibrv_i8

char*[]
char*
void*
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 Source Type

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_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 48.

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

 | 387

Index

A C object
TibrvDispatchable 180
accept, create virtual circuit 254 TibrvDispatcher 218
action, fault tolerance 261 TibrvEvent 129
activate, fault tolerance 261 TibrvFtMember 270
add message field TibrvFtMonitor 288
array 51 TibrvMsg 83
datetime 57 TibrvQueue 191
nested message 53 TibrvQueueGroup 209
opaque bytes 55 TibrvTransport 230
scalar 49 callback method
XML 56 destroy complete
add() queue to group 205 CM transport 342
addField() to message 47 event 140
addListener() to CM transport 310 fault tolerance 280
advisory message, see TIBCO Rendezvous Concepts monitor 295
allow listener, CM 311 queue 202
array fault tolerance 277
add 51 monitor 293
get 72 generic 138
update 102 I/O event 176
inbound CM message 353
inbound message 150
inbound message vector 160
B review ledger 344
timer 168
backward compatibility. See release 5. certificate
batch mode 249 set daemon certificate 27
batch mode (type) 239 set user certificate 29, 30
bytes, get field as 63 certified delivery 297
add listener 310
allow listener 311
confirm 300
C
C datatypes 374

TIBCO Rendezvous C++ Reference

388
| Index
set explicit 306 character encoding 3
connect to relay agent 312 checklist, programmer’s 5
destroy complete, transport 342 clear references, message 58
disallow listener 320 close() 21
disconnect from relay agent 321 closure
expire messages 322 event 128
get fault tolerance
message parameter member 268
sender name 347 monitor 286
sequence number 348 CM 297
time limit 350 listener 298
subject from listener 303 validity 305
transport from listener 304 message
transport parameter callback method 353
correspondent name 325 methods 346
ledger name 324 queue. See distributed queue.
relay agent 326 compatibility. See release 5.
request old 327 complete time, distributed queue
sync ledger 328 get 363
time limit 323 set 367
transport 329 complete, destroy
label information, inbound message 150, 353 CM transport 342
ledger event 140
review 333 fault tolerance
callback 343 member 280
sync 340 monitor
listener 298 destroy complete callback 295
create 301 queue 202
destroy 302 confirm 300
message callback 352 confirmMsg() 300
message methods 346 set explicit 306
remove connect, create virtual circuit 256
listener 330 connectToRelayAgent() 312
send state 332 constructor
send 334 datetime 121
reply 335 message 44
request 336 message field 111
send state, remove 332 conversion, datatype 376
set time limit convert message to string 59
of message 351 copy message 60
of transport, default 338 correspondent, get name 325
sync ledger 340
transport 307
create 314
destroy 319

TIBCO Rendezvous C++ Reference

 Index 389
|
create destroy
certified delivery listener 301 completion callback
certified delivery transport 314 event 140
dispatcher thread 215 fault tolerance 280
distributed queue member 359 monitor 295
event queue 187 queue 202
event queue group 206 destroy()
fault tolerance member 264 certified delivery
fault tolerance monitor 283 listener 302
I/O event 172 transport 319
inbox name 226, 318 dispatchable 178
listener 146 dispatcher thread 216
message 44 distributed queue transport 362
network transport 243 event 127
embed license 245 fault tolerance
timer 164 member 267
vector listener 152 monitor 285
createAcceptVc() 254 queue 188
createConnectVc() 256 queue group 207
createCopy(), message 60 transport 228
createInbox() 226, 318 destructor
current time, get 66 datetime 121
customer support xxii message 46
message field 111
detach message 61
disallowListener() 320
D disconnectFromRelayAgent() 321
dispatch, timed 183, 200, 213
daemon TCP socket 243 dispatch()
data queue 189
message field 113 queue group 208
validity of snapshot 34 queue or queue group 179
data callback 149 dispatchable 177
vector 159 dispatcher thread 214
datatypes 371 create 215
C 374 destroy 216
conversion 376 object 214
wire format 372 distributed queue 355
date 118 create member 359
constructor 121 destroy 362
deactivate, fault tolerance 261 get
default queue 184 complete time 363
defaultQueue() 22 worker task capacity 366
description 229, 238 worker weight 365
set

TIBCO Rendezvous C++ Reference

390
| Index
complete time 367 limit policy 197
scheduler task queue limits 368 name 198
worker task capacity 370 priority 199
worker weight 369 event queue group 203
transport 356 expand message, reallocate storage 62
expire messages, certified delivery 322
expireMessages() 322
extract. See get.
E
element count, message field 112
embedded license 245 F
encoding 3
environment fault tolerance 259
Tibrv class 20 action token 261
TibrvSdContext class 26 member 262
error codes 380 callback 277
event create 264
callback method, generic 138 destroy 267
class 125 complete callback 280
closure data, get 128 monitor 281, 295
destroy 127 callback 293
destroy complete, callback method 140 create 283
dispatch 179 destroy 285
timed 183 complete callback 295
get count from a queue 190 field
get queue 131 add to message 47
get type 130 array 51
poll 182 datetime 57
TibrvMsg 82 nested message 53
validity 135 opaque bytes 55
event queue 200 scalar 49
class 184 string 54
create 187 XML 56
destroy 188 class 109
dispatch 189 get 67
timed 200 array 72
get datetime 78
limit policy 192 nested message 74
name 193 opaque bytes 76
priority 194 scalar 70
is valid 195 string 75
limit policy constants 184
poll 196
set

TIBCO Rendezvous C++ Reference

 Index 391
|
XML 77 getClosure() 128
get by index 80 fault tolerance 268
get instance from message 81 monitor 286
identifier, from field 114 getCode(), status 385
name and identifier 39 getCompleteTime() 363
remove 91 getCount()
instance 93 events in a queue 190
update in message 97 fields in a message 112
array 102 getDaemon() 246
datetime 108 getData(), message field 113
nested message 104 getDefaultTimeLimit(), CM transport 323
opaque bytes 106 getDescription(), transport 229
scalar 100 getDispatchable()
string 105 C handle from dispatchable object 180
XML 107 from dispatcher thread 217
file, ledger 315 getEvent()
TibrvMsg 82
getGroupName()
fault tolerance member 269
G fault tolerance monitor 287
getHandle()
get TibrvDispatcher 218
byte size of message 65 TibrvEvent 129
current time 66 TibrvFtMember 270
description string of a transport 229 TibrvFtMonitor 288
dispatcher thread name 219 TibrvMsg 83
message field 67 TibrvQueue 191
array 72 TibrvQueueGroup 209
datetime 78 TibrvTransport 230
nested message 74 getId(), message field 114
opaque bytes 76 getInterval(), timer 165
scalar 70 getIOSource() 173
string 75 getIOType() 174
XML 77 getLedgerName() 324
message field by index 80 getLimitPolicy(), queue 192
message field instance 81 getName()
subject from listener 147 certified delivery transport 325
certified delivery 303 event queue 193
subject from vector listener 157 message field 115
transport from listener 148 getNetwork() 247
certified delivery 304 getNumFields() 84
transport from vector listener 158 getPriority(), queue 194
unassigned task count 364
getAsBytes(), message field 63

TIBCO Rendezvous C++ Reference

392
| Index
getQueue() I
event 131
fault tolerance member 271 I/O
fault tolerance monitor 289 callback method 176
getRelayAgent() 326 event object 169
getReplySubject() 85 create 172
getRequestOld() 327 identifier, field 39
getSender(), CM message 347 inbox, create name 226, 318
getSendSubject() 86 include, header files 8
getSequence(), CM message 348 instance (field)
getService() 248 get 81
getSize(), message field 116 remove 93
getStatus(), new message 87 internal machinery 21
getSubject(), listener 147 start (open) 23
vector 157 stop (close) 21
getSyncLedger() 328 interval
getText(), status 386 get from timer 165
getTimeLimit(), CM message 350 reset timer 166
getTransport() intra-process transport 24, 240
certified delivery transport 329 isDetached() 88
fault tolerance member 272 isIOEvent() 132
fault tolerance monitor 290 isListener() 133
listener 148 isTimer() 134
vector 158 isValid()
getType() CM listener 305
message field 117 dispatcher 220
TibrvEvent 130 event 135
getUnassignedMessageCount() 364 event queue 195
getWeight(), FT 273 fault tolerance member 274
getWorkerTasks() 366 fault tolerance monitor 291
getWorkerWeight() 365 queue group 210
group name TibrvDispatchable 181
fault tolerance member 269 transport 231
fault tolerance monitor 287 isVectorListener() 136
group, queue 203

J
H
join a fault tolerance group 264
header files 8

TIBCO Rendezvous C++ Reference

 Index 393
|

L string 54
XML 56
ledger callback method 150
file 316 vector 160
name, get 324 certified delivery 346
review 333 convert to string 59
sync 340 copy 60
get property 328 create 44
library files 9 destructor 46
licensed transport 245 detach 61
limit policy expand 62
constants 184 field (as a class) 109
get 192 get data as a byte sequence 63, 64
set 197 get field 67
linking 9 array 72
listener 143 datetime 78
CM 298 nested message 74
create 146 opaque bytes 76
CM 301 scalar 70
vector 152 string 75
destroy 127 XML 77
CM 302 get field by index 80
subject, get 147 get field instance 81
CM 303 ownership and control
transport, get 148 detach() 61
CM 304 isDetatched() 88
vector 151 references
create 152 clear 58
loop, get field by index mark 89
lost interval 284 remove field 91
reply subject 85, 95
reset 94
send 234
M send subject 86, 96
size 65
mark references 89 update field 97
member, fault tolerance 262 array 102
callback 277 datetime 108
message 41 nested message 104
add field 47 opaque bytes 106
array 51 scalar 100
datetime 57 string 105
nested message 53 XML 107
opaque bytes 55
scalar 49

TIBCO Rendezvous C++ Reference

394
| Index
message field open() 23
class 109
constructor 111
element count 112
monitor, fault tolerance 281 P
callback 293
PEM 29
PKCS #12 30
poll()
N event queue 196
queue group 211
name queue or queue group 182
certified delivery transport 347 prepare-to-activate, fault tolerance 261
creation parameter 316 pre-register certified delivery listener 310
get name 325 priority, of event queue 194
dispatcher thread 219, 221 set 199
event queue 193, 198 process transport 240
fault tolerance group 269 get 24
monitor 287
message field 115
nested message, add field to message 53
network interface 243 Q
network transport 241
create 243 queue 184
embed license 245 add to group 205
get daemon (TCP socket) 246 create 187
get network interface 247 default 22
get service 248 destroy 188
set batch mode 249 destroy complete, callback method 202
number of fields in a message 84 dispatch 189
fault tolerance member 271
get
event count 190
O limit policy 192
name 193
old messages, request certified delivery 327 priority 194
onCmMsg() 353 get queue from event 131
onEvent() 138 isValid() 195
onFtAction() 277 poll 196
onFtMonitor() 293 set
onIOEvent() 176 limit policy 197
onLedgerMsg() 344 name 198
onMsg() 150 priority 199
onMsgs() 160 timed dispatch 200
onTimer() 168

TIBCO Rendezvous C++ Reference

 Index 395
|
queue group 203 reset, message 94
add queue 205 resetInterval(), timer 166
create 206 reviewLedger() 333
destroy 207 callback method 344
dispatch 208
is valid 210
poll 211
remove queue 212 S
timed dispatch 213
scalar
add field 49
get 70
R update 100
secure daemon
raw storage device, as ledger file 316 set daemon certificate 27
reallocate 62 set user certificate 29, 30
reference count 21, 23 set user name 31
references send 234, 234
clear 58 CM 334
mark 89 reply 235
relay agent CM 335
connect to 312 request 236
disconnect from 321 CM 336
get from certified delivery transport 326 send state, remove 332
release 5, interaction send subject
sequence numbers, certified delivery 349 get 86
several fields with same name set 96
release number, get 25 sender name, CM 347
reliability, request 232 sendReply() 235
remove(), queue from group 212 CM 335
removeField(), from message 91 sendRequest() 236
removeFieldInstance(), from message 93 CM 336
removeListener(), certified delivery 330 sequence number, CM 348
removeSendState(), certified delivery 332 release 5, interaction 349
reply service, UDP or PGM 243
send 235 setBatchMode() 249
send certified 335 setCompleteTime(), distributed queue 367
reply subject setDaemonCert() 27
get 85 setDefaultTimeLimit(), certified delivery 338
set 95 setDescription(), transport 238
request setExplicitConfirm(), CM listener 306
send 236 setLimitPolicy(), queue 197
send certified 336 setName()
request old, certified delivery 327 dispatcher thread 221
requestReliability() 232 event queue 198

TIBCO Rendezvous C++ Reference

396
| Index
setPriority(), event queue 199 Tibrv 20
setPublisherInactivityDiscardInterval() 339 close() 21
setReplySubject(), message 95 defaultQueue() 22
setSendSubject(), message 96 open() 23
setTaskBacklogLimit...() 368 processTransport() 24
setTimeLimit(), CM message 351 version() 25
setUserCertWithKey() 29 TibrvCallback 137
setUserCertWithKeyBin() 30 onEvent() 138
setUserNameWithPassword() 31 TibrvCmListener 298
setWeight(), fault tolerance member 275 confirmMsg() 300
setWorkerTasks(), distributed queue 370 create() 301
setWorkerWeight(), distributed queue 369 destroy() 302
size getSubject() 303
message 65 getTransport() 304
message field 116 isValid() 305
snapshot, data 34 setExplicitConfirm() 306
status 380 TibrvCmMsg 346
codes 380 getSender() 347
get code 385 getSequence() 348
get text 386 getTimeLimit() 350
of a newly constructed message object 87 setTimeLimit() 351
string and character encoding 3 TibrvCmMsgCallback 352
string, convert message to 59 onCmMsg() 353
subject TibrvCmQueueTransport 356
listener 147 create() 359
CM 303 destroy() 362
vector 157 getCompleteTime() 363
message getUnassignedMessageCount() 364
reply 85, 95 getWorkerTasks() 366
send 86, 96 getWorkerWeight() 365
support, contacting xxii setCompleteTime() 367
sync ledger, certified delivery 340 setTaskBacklogLimit...() 368
get 328 setWorkerTasks() 370
setWorkerWeight() 369
TibrvCmReviewCallback 343
onLedgerMsg() 344
T
task capacity of distributed queue 366, 370
TCP port, network transport, daemon parameter 243
technical support xxii
thread, create dispatcher 215
TIBCO_HOME xix

TIBCO Rendezvous C++ Reference

 Index 397
|
TibrvCmTransport 307 TibrvEvent 125
addListener() 310 destroy() 127
allowListener() 311 getClosure() 128
connectToRelayAgent() 312 getHandle() 129
create() 314 getQueue() 131
createInbox() 318 getType() 130
destroy() 319 isIOEvent() 132
disallowListener() 320 isListener() 133
disconnectFromRelayAgent 321 isTimer() 134
expireMessages() 322 isValid() 135
getDefaultTimeLimit() 323 isVectorListener() 136
getLedgerName() 324 TibrvEventOnComplete 139
getName() 325 onComplete() 140
getRelayAgent() 326 TIBRVFT_ACTIVATE 261
getRequestOld() 327 TIBRVFT_DEACTIVATE 261
getSyncLedger() 328 TIBRVFT_PREPARE_TO_ACTIVATE 261
getTransport() 329 tibrvftAction 261, 261
removeListener() 330 TibrvFtMember 262
removeSendState() 332 create() 264
reviewLedger() 333 destroy() 267
send() 334 getClosure() 268, 286
sendReply() 335 getGroupName() 269
sendRequest() 336 getHandle() 270
setDefaultTimeLimit() 338 getQueue() 271
setPublisherInactivityDiscardInterval() 339 getTransport() 272
syncLedger() 340 getWeight() 273
TibrvCmTransportOnComplete 341 isValid() 274
onComplete() 342 setWeight() 275
TibrvDispatchable 177 TibrvFtMemberCallback 276
destroy() 178 onFtAction() 277
dispatch() 179 TibrvFtMemberOnComplete 279
getDispatchable() 180 onComplete() 280
isValid() 181 TibrvFtMonitor 281
poll() 182 create() 283
timedDispatch() 183 destroy() 285
TibrvDispatcher 214 getGroupName() 287
create() 215 getHandle() 288
destroy() 216 getQueue() 289
getDispatchable() 217 getTransport() 290
getHandle() 218 isValid() 291
getName() 219 TibrvFtMonitorCallback 292
isValid() 220 onFtMonitor() 293
setName() 221 TibrvFtMonitorOnComplete 294
onComplete() 295, 295

TIBCO Rendezvous C++ Reference

398
| Index
TibrvIOCallback 175 TibrvMsgField 109
onIOEvent() 176 constructor 111
TibrvIOEvent 169 getCount() 112
create() 172 getData() 113
getIOSource() 173 getId() 114
getIOType() 174 getName() 115
TibrvListener 143 getSize() 116
create() 146 getType() 117
getSubject() 147 TibrvNetTransport 241
getTransport() 148 create() 243
TibrvMsg 41 getDaemon() 246
addField() 47 getNetwork() 247
clearReferences() 58 getService() 248
constructor 44 setBatchMode() 249
convertToString() 59 TibrvProcessTransport 240
createCopy() 60 TibrvQueue 184
destructor 46 create() 187
detach() 61 destroy() 188
expand() 62 dispatch() 189
getAsBytes() 63 getCount() 190
getAsBytesCopy() 64 getHandle() 191
getByIndex() 80 getLimitPolicy() 192
getByteSize() 65 getName() 193
getCurrentTime() 66 getPriority() 194
getEvent() 82 isValid() 195
getField() 67 poll() 196
getHandle() 83 setLimitPolicy() 197
getInstance() 81 setName() 198
getNumFields() 84 setPriority 199
getReplySubject() 85 timedDispatch() 200
getSendSubject() 86 TibrvQueueGroup 203
getStatus() 87 add() 205
isDetached() 88 create() 206
markReferences() 89 destroy() 207
removeField() 91 dispatch() 208
removeFieldInstance() 93 getHandle() 209
reset() 94 isValid() 210
setReplySubject() 95 poll() 211
setSendSubject() 96 remove() 212
updateField() 97 timedDispatch() 213
TibrvMsgCallback 149 TibrvQueueOnComplete 201
onMsg() 150 onComplete() 202
TibrvMsgDateTime 118
constructor 121

TIBCO Rendezvous C++ Reference

 Index 399
|
TibrvSdContext 26 timedDispatch()
setDaemonCert() 27 queue 200
setUserCertWithKey() 29 queue group 213
setUserCertWithKeyBin() 30 queue or queue group 183
setUserNameWithPassword() 31 timer
TibrvStatus 380 callback method 168
getCode() 385 create 164
getText() 386 event object 161
TibrvTimer 161 get interval 165
create() 164 reset interval 166
getInterval() 165 translation, character encoding 3
resetInterval() 166 transport
TibrvTimerCallback 167 batch mode 239
onTimer() 168 batch mode, set 249
TibrvTransport 224 certified delivery 307
createInbox() 226 create 314
destroy() 228 create inbox name 226, 318
getDescription() 229 description
getHandle() 230 get 229
isValid() 231 set 238
requestReliability() 232 destroy 228
send() 234 certified delivery 319
sendReply() 235 distributed queue 362
sendRequest() 236 distributed queue 356
setDescription() 238 fault tolerance member 272
tibrvTransportBatchMode (type) 239 generic class 224
TibrvVcTransport 252 get from certified delivery listener 304
createAcceptVc() 254 get from certified delivery transport 329
createConnectVc() 256 get from listener 148
waitForVcConnection() 257 get from vector listener 158
TibrvVectorCallback 159 intra-process 24, 240
onMsgs() 160 is valid 231
TibrvVectorListener 151 network 241
create() 152 create 243
getSubject() 157 embed license 245
getTransport() 158 request reliability 232
time 118 send 234
constructor 121 reply 235
get current 66 request 236
time limit, certified delivery virtual circuit 252
get 350 create accept 254
get default 323 create connect 256
set 351 wait for connection 257
set default 338

TIBCO Rendezvous C++ Reference

400
| Index
type 371 W
C 374
message field 117 waitForVcConnection() 257
wire format 372 weight, fault tolerance
get 273
set 275
wire format datatypes 372
U withdraw from fault tolerance group 267
worker weight, distributed queue
unassigned tasks 364 get 365
update message field 97 set 369
array 102
datetime 108
nested message 104
opaque bytes 106 X
scalar 100
string 105 XML
XML 107 add 56
updateField() 97 get 77
user name and password, set 31 update 107

V
valid
CM listener 305
dispatcher 220
event 135
event queue 195
fault tolerance member 274
fault tolerance monitor 291
message data 34
queue group 210
transport 231
vector callback 159
vector listener 151
create 152
subject, get 157
transport, get 158
version() 25
virtual circuit
transport class 252
wait for connection 257

TIBCO Rendezvous C++ Reference