TIB RV Com Reference

TIBCO Rendezvous®
COM Reference
Software Release 8.4
February 2012
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE
LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED
IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS
AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN
AGREEMENT TO BE BOUND BY THE SAME.
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.
TIBCO, The Power of Now, TIB, Information Bus, 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 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–2012 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
Contents iii
|
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
New or Modified Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xix
TIBCO Rendezvous Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xix
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
How to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Chapter 1 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
General Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Programming Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Object Safety in Scripting Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Events in Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Destroy Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Validity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Callback Methods and Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Strings and Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Numeric Datatypes and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Closure Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
TIBCO Rendezvous COM Reference

iv
| Contents
Multi-Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 2 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Referencing the Rendezvous COM Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Select the Appropriate Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Shared Library Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3 Rendezvous Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Tibrv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Tibrv.close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Tibrv.getAutoDispatchQueueGroup(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Tibrv.getDefaultQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Tibrv.getProcessTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Tibrv.getVersion(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Tibrv.isOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Tibrv.open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
TibrvSdContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
TibrvSdContext.setDaemonCert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
TibrvSdContext.setUserCertWithKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
TibrvSdContext.setUserCertWithKeyBin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
TibrvSdContext.setUserNameWithPassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 4 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Message Ownership and Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Field Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Validity of Data Extracted from Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Snapshot Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Snapshot Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Multiple Subscription Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Field Names and Field Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Finding a Field Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Release 5 Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
TibrvMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
TibrvMsg.add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
TibrvMsg.addField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Contents v
|
TibrvMsg.clearReferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
TibrvMsg.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
TibrvMsg.createCopy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
TibrvMsg.createFromByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
TibrvMsg.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
TibrvMsg.detach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
TibrvMsg.get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
TibrvMsg.getAsByteArray(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
TibrvMsg.getByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
TibrvMsg.getByteSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
TibrvMsg.getDefaultInboundEncoding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
TibrvMsg.getField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
TibrvMsg.getFieldByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
TibrvMsg.getFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
TibrvMsg.getInstance(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
TibrvMsg.getMsgEncoding(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
TibrvMsg.getNumFields() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
TibrvMsg.getOutboundEncoding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
TibrvMsg.getProperty(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
TibrvMsg.getReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TibrvMsg.getSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
TibrvMsg.isDetached() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
TibrvMsg.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
TibrvMsg.markReferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
TibrvMsg.remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
TibrvMsg.removeInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
TibrvMsg.reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
TibrvMsg.setDefaultInboundEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
TibrvMsg.setOutboundEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TibrvMsg.setProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
TibrvMsg.setReplySubject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
TibrvMsg.setSendSubject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
TibrvMsg.toString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
TibrvMsg.update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TibrvMsg.updateField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
TibrvMsgField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
TibrvMsgField.getData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
TibrvMsgField.getId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
TibrvMsgField.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
TibrvMsgField.getType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
TibrvMsgField.initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
TibrvInt64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
TibrvInt64.getAsHexString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
TibrvInt64.getAsString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

vi
| Contents
TibrvInt64.getAsUnsignedString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
TibrvInt64.getLowOrderPart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
TibrvInt64.getHighOrderPart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
TibrvInt64.setFromString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Chapter 5 Events and Queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

TibrvListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
TibrvListener.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
TibrvListener.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
TibrvListener.getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
TibrvListener.getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
TibrvListener.getSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
TibrvListener.getTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TibrvListener.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
TibrvListener_onMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
TibrvTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
TibrvTimer.create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
TibrvTimer.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
TibrvTimer.getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
TibrvTimer.getInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
TibrvTimer.getQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
TibrvTimer.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
TibrvTimer_onTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
TibrvTimer.resetInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TibrvQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
TibrvQueue.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
TibrvQueue.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
TibrvQueue.dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
TibrvQueue.getCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
TibrvQueue.getDiscardAmount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
TibrvQueue.getLimitPolicy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
TibrvQueue.getMaxEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
TibrvQueue.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
TibrvQueue.getPriority() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
TibrvQueue.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
TibrvQueue.poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TibrvQueue.setLimitPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TibrvQueue.setName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
TibrvQueue.setPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TibrvQueue.timedDispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
TibrvQueueGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
TibrvQueueGroup.add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
TibrvQueueGroup.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Contents vii
|
TibrvQueueGroup.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
TibrvQueueGroup.dispatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
TibrvQueueGroup.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
TibrvQueueGroup.poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
TibrvQueueGroup.remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
TibrvQueueGroup.timedDispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Chapter 6 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163

TibrvTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
TibrvTransport.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
TibrvTransport.createInbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
TibrvTransport.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
TibrvTransport.getDaemon(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
TibrvTransport.getDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
TibrvTransport.getNetwork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
TibrvTransport.getService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
TibrvTransport.isValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
TibrvTransport.send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
TibrvTransport.sendReply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
TibrvTransport.sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
TibrvTransport.setBatchMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
TibrvTransport.setDescription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Chapter 7 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Virtual Circuit Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
TibrvTransport.createAcceptVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
TibrvTransport.createConnectVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
TibrvTransport.getVcConnectSubject(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
TibrvTransport.waitForVcConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Chapter 8 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Fault Tolerance Road Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
TibrvFtMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
TibrvFtMember.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
TibrvFtMember.destroy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
TibrvFtMember.getClosure(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
TibrvFtMember.getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
TibrvFtMember.getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
TibrvFtMember.getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
TibrvFtMember.getWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
TibrvFtMember.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
TibrvFtMember_onFtAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
TibrvFtMember.setWeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

viii
| Contents
TibrvFtMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
TibrvFtMonitor.create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
TibrvFtMonitor.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
TibrvFtMonitor.getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
TibrvFtMonitor.getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
TibrvFtMonitor.getQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
TibrvFtMonitor.getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
TibrvFtMonitor.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
TibrvFtMonitor_onFtMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Chapter 9 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

TibrvCmListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
TibrvCmListener.confirmMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
TibrvCmListener.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
TibrvCmListener.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
TibrvCmListener.getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
TibrvCmListener.getCmTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
TibrvCmListener.getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
TibrvCmListener.getSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
TibrvCmListener.isValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
TibrvCmListener_onCmMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
TibrvCmListener.setExplicitConfirm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
TibrvCmTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
TibrvCmTransport.addListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
TibrvCmTransport.allowListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
TibrvCmTransport.connectToRelayAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
TibrvCmTransport.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
TibrvCmTransport.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
TibrvCmTransport.disallowListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
TibrvCmTransport.disconnectFromRelayAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
TibrvCmTransport.expireMessages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
TibrvCmTransport.getDefaultTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
TibrvCmTransport.getLedgerName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
TibrvCmTransport.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
TibrvCmTransport.getRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
TibrvCmTransport.getRequestOld(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
TibrvCmTransport.getSyncLedger(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
TibrvCmTransport.getTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
TibrvCmTransport.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
TibrvCmTransport_onLedgerMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
TibrvCmTransport.removeListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
TibrvCmTransport.removeSendState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
TibrvCmTransport.reviewLedger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
TibrvCmTransport.send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Contents ix
|
TibrvCmTransport.sendReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
TibrvCmTransport.sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
TibrvCmTransport.setDefaultTimeLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
TibrvCmTransport.setTaskBacklogLimit... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
TibrvCmTransport.stopReview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
TibrvCmTransport.syncLedger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Chapter 10 Distributed Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275

Distributed Queue Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
TibrvCmTransport.createDistributedQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
TibrvCmTransport.getCompleteTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
TibrvCmTransport.getWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TibrvCmTransport.getWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
TibrvCmTransport.isDistributed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
TibrvCmTransport.setCompleteTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
TibrvCmTransport.setWorkerTasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
TibrvCmTransport.setWorkerWeight. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Chapter 11 Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Error Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Continuing after Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Rendezvous Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Component Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
VB Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303

x
| Contents

Figures xi
|
Figures
Figure 1 VB to Wire Format Datatype Conversion Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Figure 2 Wire Format to VB Datatype Conversion Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Figure 3 Mark and Clear References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Figure 4 Listener Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Figure 5 Timer Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

xii
| Figures

Tables xiii
|
Tables
Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Table 3 Thread Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 4 Environment Variables for Shared Library Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 5 Datatype Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Table 6 Base Constants for HRESULT Computations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Table 7 Rendezvous HRESULT Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Table 8 TIBRVCOM HRESULT Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Table 9 VB Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

xiv
| Tables

New or Modified Sections
| xv
New or Modified Sections
TibrvCmTransport.createDistributedQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
TibrvCmTransport.setWorkerTasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

xvi
| New or Modified Sections

Preface xvii
|
Preface
TIBCO Rendezvous® is a messaging infrastructure product.

TIBCO is proud to announce the latest release of TIBCO Rendezvous®. This
release is the latest in a long history of TIBCO products that leverage the power of
the Information Bus® to enable truly event-driven IT environments. To find out
more about how TIBCO Rendezvous and other TIBCO products are powered by
TIB® technology, please visit us at www.tibco.com.
This manual describes the TIBCO Rendezvous API for COM and programming
systems that use COM. It is part of the documentation set for Rendezvous
Software Release 8.4.0.
Topics
• Manual Organization, page xviii

• Related Documentation, page xix
• Typographical Conventions, page xxi
• Connecting with TIBCO Resources, page xxiv

xviii Manual Organization
|
Manual Organization
The organization of this book mirrors the underlying object structure of the
Rendezvous COM component. Each chapter describes a group of closely related
objects and the methods that pertain to them.
Within each object, methods appear in alphabetical order.

Preface xix
|
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Rendezvous Documentation

The documentation road map shows the relationships between the books and
online references in this product’s documentation set.
z/OS Only
z/OS Installation
Installation Concepts and Configuration
COBOL
Administration C Reference
Reference
C++ Reference
Configuration
COM Reference
Tools
Java Reference
RVDM JMX
MBean API
.NET Reference
Reference Pages
Legend PDF HTML
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.

xx
| Related Documentation
• 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 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.

Preface xxi
|
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention Use
TIBCO_HOME Many TIBCO products must be installed within the same home directory. This
directory is referenced in documentation as TIBCO_HOME. The value of
ENV_HOME
TIBCO_HOME depends on the operating system. For example, on Windows
TIBRV_HOME systems, the default value is C:\tibco.
Other TIBCO products are installed into an installation environment. Incompatible
products and multiple instances of the same product are installed into different
installation environments. An environment home directory is referenced in
documentation as ENV_HOME. The default value of ENV_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.4.
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]

xxii
| Typographical Conventions
Table 1 General Typographical Conventions (Cont’d)
Convention Use
italic font Italic font is used in the following ways:
• To indicate a document title. For example: See TIBCO FTL 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
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

Preface xxiii
|
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}

xxiv Connecting with TIBCO Resources
|
Connecting with TIBCO Resources
How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts. It is a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to http://www.tibcommunity.com.
How to Access All TIBCO Documentation

You can access TIBCO documentation here:
http://docs.tibco.com
How to Contact TIBCO Support

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

Concepts 1
|
Chapter 1 Concepts
This chapter presents concepts specific to the TIBCO Rendezvous® COM

component. For concepts that pertain to Rendezvous software in general, see the
book TIBCO Rendezvous Concepts.
Topics
• General Description, page 2

• Programming Environments, page 3
• Objects, page 4
• Callback Methods and Event Handlers, page 6
• Strings and Character Encodings, page 7
• Numeric Datatypes and Arrays, page 8
• Date and Time, page 9
• Closure Data, page 10
• Multi-Threading, page 11

2
| Chapter 1 Concepts
General Description
The Rendezvous COM component is a set of COM automation objects that allow
a variety of programming language environments to access Rendezvous message
middleware. The Rendezvous COM component supports several qualities of
Rendezvous service—ordinary messages, fault tolerance, certified message
delivery, and distributed queues.
The range of programming environments includes Visual Basic, Delphi, Visual
C++, J++, Microsoft Office products, as well as scripts in Internet Explorer and
Active Server Pages.
The automation objects feature dual interfaces—a custom vtable interface (for
most programming languages, including Visual Basic) and a dispatch table
interface (for scripting environments).
TIBCO Rendezvous no longer adds new features to the Microsoft COM interface.
However, we continue to maintain a COM interface to support legacy
applications.

Programming Environments 3
|
Programming Environments
This document is oriented toward programmers using the Visual Basic (VB)
programming environment. This book presents method names using VB dot
notation, and code fragments using VB syntax. It is also possible to use
Rendezvous COM in other environments that accept COM components.
The release contains example programs for several environments—such as VB,
Excel (VBA), VBScript, and JavaScript—however, the examples are not
exhaustive.
Constants
The Rendezvous component defines all constants using enumerators in the type
library. These constants are available in all programming environments.
To view these constants in VB, use the object browser.
Constants include message datatypes, queue limit policies, queue default priority,
fault tolerance actions, distributed queue constants, queue dispatch constants,
and error status codes.
Object Safety in Scripting Environments

Scripts can use the Rendezvous COM component without explicit confirmation in
the object safety dialog box.
Certified delivery transports can write data to their ledger files. This is the only
situation in which the Rendezvous component makes permanent changes to the
host system.
Events in Excel
Excel drops events during certain operations (for example, while calculating a
spreadsheet or editing a sheet). This behavior can result in missed Rendezvous
messages and timer events.
Error Handling
See Error Overview on page 290.

4
Objects
This COM component implements Rendezvous objects in two layers. Each COM
object is an outer shell, with a corresponding internal implementation object.
Programs create the outer object using the techniques of the programming
environment, such as the New or CreateObject methods. Programs initialize the
internal implementation using the Create method of the object class.
Once an object’s internal structure is initialized, we say that the outer COM object
is valid.
Programs can delete the internal implementation (which stops its activity) by
using the Destroy method of an outer COM object. However, destroying the
object in this way affects only the inner structure (in this situation we say that the
remaining outer object is invalid). In contrast, VB programs delete an outer object
by severing all references to it; to sever a variable reference, either set the object
variable to Nothing, or exit the scope of the variable. (Other programming
languages use similar constructs.) As a side effect of deleting the outer object, the
inner object is also tacitly destroyed.
Creation
Object creation involves three steps—declare a variable, create the outer COM
object, create the inner structure. To illustrate, these examples create message
objects (the sequence is analogous for other objects).
To create an empty message object in a VB program, use this sequence:
Dim myMsg as TibrvMsg ’Declare the variable
set myMsg = new TibrvMsg ’Create the COM shell object
myMsg.create ’Init the internal message
structure
To create an empty message object in VBScript, use this sequence:

Dim myMsg as Object ’Declare the variable
set myMsg = CreateObject("TIBRVCOM.TibrvMsg") ’Create the
COM obj
myMsg.create ’Init the internal message
structure
To create an empty message object in JavaScript, use this sequence:

var msg //Declare the variable
msg = new ActiveXObject("TIBRVCOM.TibRvMsg"); //Create the
JS/COM obj
msg.create(); //Init the internal message
structure

Objects 5
|
Deletion
VB program code can delete an object by severing all variable references to it.
Sever each variable reference in one of two ways:
• Explicit—set the variable to Nothing.
• Implicit—exit the scope of the variable.
Calling methods of a variable that is set to Nothing can yield error 91.
Destroy Method
The destroy method invalidates the internal implementation of an object. The
outer object remains as an empty shell.
A program may call the destroy method of an object more than once without
error.
Validity
The isValid method tests the validity of an object. If its internal implementation
is intact, then it is valid. (In contrast, checking that the value of a variable is not
Nothing merely tests that the variable refers to an outer object.)
Calling any other methods of an object that is invalid yields the error
TIBRVCOM_NOT_INITIALIZED. Conversely, calling the create method on a valid
object yields the error TIBRVCOM_ALREADY_INITIALIZED.

6
Callback Methods and Event Handlers
Event processing in COM is more complicated than in other supported languages

in the Rendezvous software family.
In the other languages, dispatching an event object triggers Rendezvous software
to call back into your program code—invoking a callback method (or callback
function) to process the event.
In COM, dispatching an event object triggers a longer sequence. That is, dispatch
triggers a callback in the tibrvcom DLL, which fires a COM event, which in turn
invokes the program’s event handler method (which is associated with the event
object). For consistency with other languages, this manual uses the term callback
method to refer to that event handler method—even though (strictly speaking)
COM cannot directly call back into the program.
Limitations
In the single-threaded apartment model (STA), the Rendezvous component does
not trigger dispatch while a program callback method is already running. Visual
Basic is subject to this limitation.
This restriction does not apply in the multi-threaded apartment model (MTA).

Strings and Character Encodings 7
|
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 (CM) correspondent names
• Group names (fault tolerance)
These strings exist in two representations:

• VB and COM BSTRs (binary strings) use the Unicode 2-byte character set (also
called wide characters).
• Rendezvous wire format (internal implementation) uses the character
encoding appropriate to the locale (that is, the system default ANSI code page
associated with the default language installed on the computer).
For example, the United States is locale English_USA.1252, and uses the
Latin-1 character encoding (also called ISO 8859-1); Japan is locale
Japanese_Japan.932, and uses the Shift-JIS character encoding.
These strings can use either 1-byte or 2-byte character sets.

Rendezvous strings must not contain any null characters. (Rendezvous
software could truncate strings with embedded null characters. COM
software stops processing BSTRs at the first null character.)
When two programs exchange messages within the same locale, the automatic
translation between these two representations is correct. However, when a
message sender and receiver use different locales, the receiving program must
retranslate between code pages as needed.

8
Numeric Datatypes and Arrays
In many cases, Rendezvous methods present numeric data using a larger

datatype. For example, field identifiers are limited to the range of 16-bit unsigned
integers, but COM methods present them as 32-bit signed integers (with zeroes
padding the high 16 bits). For details, see Decoding and Type Conversion on
page 56.
Some methods use 64-bit integer data (for example, TibrvMsg.getProperty()
can extract a CM sequence number). The Rendezvous COM component
represents such values using the object TibrvInt64.
The Rendezvous COM component does not support arrays in scripting languages,
such as VBScript and JavaScript.

Date and Time 9
|
Date and Time
Programs represent date and time values as a VB Date, or as a Object that

contains a Date.
Rendezvous does not do time zone conversions, which are the responsibility of
sending and receiving programs.
When printing time values, TibrvMsg.toString() treats all date and time values
as UTC time; for more information, see Converting Dates to Strings on page 88.
The range of the VB type Date is from January 1, 100 to December 31, 9999. Notice
that this range is narrower than the range for the corresponding Rendezvous type
TIBRVCOM_MSG_DATETIME.
See Also DateTime Format, page 77 in TIBCO Rendezvous Concepts

10
Closure Data
Several object creation calls require a closure argument. These methods store the
closure data on the object, and pass it to the callback method.
The closure data is an Object.

Multi-Threading 11
|
Multi-Threading
Table 3 compares the two models for multi-thread behavior in COM. Rendezvous
7.0 (and later) supports both models. Rendezvous objects are thread-safe in either
model.
Table 3 Thread Models
Apartment Model Free Thread Model

Single-threaded apartments (STA) Multi-threaded apartments (MTA)
Restrictions
Programs using this model require Programs must not use a GUI in
the Windows message queue. threads that use this model.
Windows GUI programs
Such programs can not use the
automatically administer the
Rendezvous automatic dispatch
Windows message queue. Use this
queue group; instead, they must
model in the GUI thread.
explicitly dispatch Rendezvous events.
Such programs can use the
Rendezvous automatic dispatch
queue group.
See Also Tibrv.getAutoDispatchQueueGroup() on page 20

12

| 13
Chapter 2 Programmer’s Checklist
Topics
• Checklist, page 14
• Referencing the Rendezvous COM Component, page 15
• Shared Library Files, page 16

14
| Chapter 2 Programmer’s Checklist
Checklist
Developers of Rendezvous programs can use this checklist during the three
phases of the development cycle: installing Rendezvous software, coding your
program, and running your program.
Install
• Install the Rendezvous software release.
• Register (only one) Rendezvous component in the Windows registry, using
either these commands:
regsvr32 path\bin\tibrvcom.dll
regsvr32 path\bin\tibrvsdcom.dll
Code
• The project must set a reference to the Rendezvous component; see
Referencing the Rendezvous COM Component on page 15.
• Excel programs (and other applications that use VBA) must enable macros in
order to execute code using the Rendezvous component.
• The type library contains constant definitions that are available in all
programming environments. To view these constants in VB, use the object
browser. Select the appropriate constant library for your program (one
includes secure daemon features, the other does not).
Run
• rvd must be in one of the path directories.
• rvd requires valid licensing.
See Licensing Information on page 11 in TIBCO Rendezvous Administration.

Referencing the Rendezvous COM Component 15
|
Referencing the Rendezvous COM Component
This Rendezvous COM component is not an ActiveX control (in contrast, in

release 5 and earlier, it was packaged as a control). As a result, programmers no
longer create control objects in forms using drag-and-drop gestures from the
control tool in the programming environment. Instead, programmers set the
project to reference this component.
Select the Appropriate Component

Reference only one of these two components:
• TIBCO Rendezvous TibrvCOM m.n Type Library—for programs that
connect to ordinary daemons (rvd, rvrd).
• TIBCO Rendezvous Secure Daemon TibrvsdCOM m.n Type Library—for
programs that connect to secure daemons (rvsd, rvsrd) using SSL. For further
details, see TibrvSdContext on page 26.
VB
For example, in VB, select Project>References... In the resulting dialog box, check
either the item TibrvCOM or the item TibrvsdCOM—but not both simultaneously.
Visual Basic reads the type library to define all the objects, constants and
capabilities of the Rendezvous component.
Excel
For example, in Excel, select Tools>References... In the resulting dialog box,
check either the item TibrvCOM or the item TibrvsdCOM—but not both
simultaneously. Excel reads the type library to define all the objects, constants and
capabilities of the Rendezvous component.

16
| Chapter 2 Programmer’s Checklist
Shared Library Files
VB Programs must be able to access Rendezvous shared library files (C libraries).

Table 4 details the environment variables that direct VB programs to the
Rendezvous installation directory. The installation directory must contain the
required shared library files.
Table 4 Environment Variables for Shared Library Files
Platform Environment Variable

Windows PATH must include \install_dir\bin
The installation procedure sets this variable automatically.

| 17
Chapter 3 Rendezvous Environment
This chapter describes the methods related to the internal machinery upon which
Rendezvous software depends.
Topics
• Tibrv, page 18
• TibrvSdContext, page 26

18
| Chapter 3 Rendezvous Environment
Tibrv
Class
Purpose The Rendezvous environment.
Remarks Each program creates only one instance of Tibrv, and uses its methods to open
and close the Rendezvous environment, refer to Rendezvous resources, and
extract version information.
All other objects require an open Tibrv environment, and are inoperative when
the environment is not open. The only exceptions to this rule are the objects
defined in Chapter 4, Data, on page 33 (namely, TibrvMsg, TibrvMsgField, and
TibrvInt64).
Method Description Page

Open and Close
Tibrv.open Start Rendezvous internal machinery. 25
Tibrv.close Stop and destroy Rendezvous internal 19

machinery.
Tibrv.isOpen() Determine whether the Rendezvous 24

machinery is open.
Accessors
Tibrv.getAutoDispatchQueueGroup() Return a reference to the automatic dispatch 20

queue group object.
Tibrv.getDefaultQueue() Return a reference to the default queue object. 21
Tibrv.getProcessTransport() Return a reference to the intra-process 22

transport object.
Tibrv.getVersion() Return the version string. 23

Tibrv.getCmVersion()
Tibrv.getFtVersion()

Tibrv.close 19
|
Tibrv.close
Method
Declaration Tibrv.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; all calls to any methods of these
objects will fail.
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.
To ascertain the actual state of the internal machinery, use Tibrv.isOpen() on

page 24.
See Also Tibrv.open on page 25

20
Tibrv.getAutoDispatchQueueGroup()
Method
Declaration set autoDispatchGroup = Tibrv.getAutoDispatchQueueGroup()
Purpose Return a reference to the automatic dispatch queue group object.
Remarks This method returns a special queue group, which detects the presence of an
event in any of its queues, and automatically dispatches the queues (according to
their priority) until no more events are waiting.
To automatically dispatch a queue, add it to this queue group.
To disable automatic dispatch of queue, remove it from this group, and arrange
explicit dispatch calls instead. (It is crucial to dispatch all queues promptly—
otherwise queues can overflow or discard events. A queue without a discard limit
can cause the program to exceed available process storage.)
The automatic dispatch queue group is a convenience for programmers
developing GUI applications. GUI programs operate best with automatic event
dispatch. We do not recommend using explicit dispatch in GUI application
programs; see also Multi-Threading on page 11.
Each process can have at most one automatic dispatch queue group. A program
can use this queue group in at most one (STA) thread. Programs cannot destroy
this queue group.
If Rendezvous is not open, this method throws the error
TIBRVCOM_TIBRV_NOT_OPEN.
Parameter Description
autoDispatchGroup TibrvQueueGroup
Return the automatic dispatch queue group.
Automatic dispatch continues until all the queues in this group are empty. During
that time, COM does not service GUI events.
VB GUI programs can ameliorate that difficulty by including DoEvents
statements in callback methods—but this solution requires attention to reentrance
issues.
See Also TibrvQueue on page 133

TibrvQueueGroup on page 151
TibrvQueueGroup.add on page 153
TibrvQueueGroup.remove on page 159

Tibrv.getDefaultQueue() 21
|
Tibrv.getDefaultQueue()
Method
Declaration set defaultQueue = Tibrv.getDefaultQueue()
Purpose Return a reference to the default queue object.
Remarks If Rendezvous is not open, this method reports the error

TIBRVCOM_TIBRV_NOT_OPEN, and returns a null object.
Each process has exactly one default queue. Tibrv.open automatically creates the
default queue. Programs cannot destroy the default queue.
defaultQueue TibrvQueue
Return the default queue.

22
Tibrv.getProcessTransport()
Method
Declaration set processTransport = Tibrv.getProcessTransport()
Purpose Return a reference to the intra-process transport object.
Remarks A program can use the intra-process transport to send messages to itself.
If Rendezvous is not open, this method reports the error
TIBRVCOM_TIBRV_NOT_OPEN, and returns a null object.
Each process has exactly one intra-process transport. Tibrv.open automatically

creates it. Programs cannot destroy the intra-process transport.
processTransport TibrvTransport
Return the intra-process transport.
See Also TibrvTransport on page 164

Tibrv.getVersion() 23
|
Tibrv.getVersion()
Method
Declaration version = Tibrv.getVersion()

version = Tibrv.getCmVersion()
version = Tibrv.getFtVersion()
Purpose Return the version string.
Remarks getVersion() returns the version numbers of the Rendezvous COM component
and the underlying C implementation of the core library.
getCmVersion() returns the version number of the underlying C implementation
of the certified delivery library.
getFtVersion() returns the version number of the underlying C implementation
of the fault tolerance library.
Version strings use this template:

TibrvCOM Component Version a.b.c using C API version x.y.z
It is important that x.y represent a DLL at least as recent as the component a.b. If
not, you must reinstall a later version of Rendezvous software.
version String
Return a string describing the software version numbers.

24
Tibrv.isOpen()
Method
Declaration open = Tibrv.isOpen()
Purpose Determine whether the Rendezvous machinery is open.
Remarks This method returns True after the method Tibrv.open has returned
successfully.
Otherwise this method returns False. The value False usually indicates one of
these situations:
• The program has not opened the Rendezvous environment.
• Attempts to open the environment failed.
• The environment was open, but the program closed it with Tibrv.close.
open Boolean
Return a state indicator.
See Also Tibrv.open on page 25

Tibrv.close on page 19

Tibrv.open 25
|
Tibrv.open
Method
Declaration Tibrv.open
Purpose Start Rendezvous internal machinery.
Remarks This call creates the internal machinery that Rendezvous software requires for its
operation:
• Internal data structures.
• Default event queue.
• Intra-process transport.
• Event driver.
Until the first call to Tibrv.open creates the internal machinery, all events,
transports, queues and queue groups are unusable. Messages and their methods
do not depend on the internal machinery.
Reference Count A reference count protects against interactions between programs and third-party
packages that call Tibrv.open and Tibrv.close. Each call to Tibrv.open
increments an internal counter; each call to Tibrv.close decrements that counter.
A call to Tibrv.open actually creates internal machinery only when the reference
counter is zero; subsequent calls merely increment the counter, but do not
duplicate the machinery. A call to Tibrv.close actually destroys the internal
machinery only when the call decrements the counter to zero; other calls merely
decrement the counter. In each program, the number of calls to Tibrv.open and
Tibrv.close must match.
See Also Tibrv.close on page 19

26
TibrvSdContext
Class
Purpose This class defines static methods for interacting with secure Rendezvous
daemons.
Remarks Each program creates only one instance of TibrvSdContext, and uses its static
methods to configure user names, passwords and certificates, and to register trust
in daemon certificates.
Before using any methods of this class, ensure that your programming
environment reference the secure daemon TibrvsdCOM component; see Referencing
the Rendezvous COM Component on page 15.
Programs that use methods of this class must also use the type library
Secure Daemon TIBRVSDCOMLib (rather than TIBRVCOMLib) when defining
callback methods.

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 32

for identification to secure daemons.

TibrvSdContext.setDaemonCert() 27
|
TibrvSdContext.setDaemonCert()
Method
Declaration TibrvSdContext.setDaemonCert daemonName, daemonCert
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.
daemonName String
Register a certificate for a secure daemon with this name. For

the syntax and semantics of this parameter, see Daemon
Name, below.
daemonCert String
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 TibrvTransport.create on page 166.
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.)

28
In place of this three-part string, you can also supply the null string
(vbNullString). 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 177 in TIBCO
Rendezvous Administration.
In place of an actual certificate, you can also supply the null string
(vbNullString). 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 supplying the null string (vbNullString) as either argument
Any Certificate eliminates one of the two security checks before transmitting sensitive
identification data to a secure daemon. We strongly discourage using the null
string for both parameters simultaneously, because that would eliminate all
security checks, leaving the program vulnerable to unauthorized daemons.
See Also TibrvSdContext on page 26

TibrvSdContext.setUserCertWithKey() 29
|
TibrvSdContext.setUserCertWithKey()
Method
Declaration TibrvSdContext.setUserCertWithKey userCertWithKey, 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.
userCertWithKey String
Register this user certificate with private key. The text of

this certificate must be in PEM encoding.
password String
Use this password to decrypt the private key.
For important information about password security, see Security Factors on

page 177 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
Exceptions An exception that reports status TIBRVCOM_INVALID_FILE can indicate either disk
I/O failure, or invalid certificate data, or an incorrect password.

TibrvSdContext.setUserCertWithKeyBin() on page 30

30
TibrvSdContext.setUserCertWithKeyBin()
Method
Declaration TibrvSdContext.setUserCertWithKeyBin
userCertWithKey,
userCertWithKey_size,
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 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.
userCertWithKey Object
Register this user certificate with private key. The binary data of this
certificate must be in PKCS #12 format.
userCertWithKey_size Long
Length of the certificate data (in bytes).
password String
Use this password to decrypt the private key.

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

TibrvSdContext.setUserCertWithKeyBin() 31
|
Exceptions An exception that reports status TIBRVCOM_INVALID_FILE can indicate either disk
I/O failure, or invalid certificate data, or an incorrect password.

TibrvSdContext.setUserCertWithKey() on page 29
www.rsasecurity.com/rsalabs/pkcs

32
TibrvSdContext.setUserNameWithPassword()
Method
Declaration TibrvSdContext.setUserNameWithPassword userName, 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
userName Register this user name for communicating with secure
daemons.
password Register this password for communicating with secure

daemons.


| 33
Chapter 4 Data
This chapter describes messages and the data they contain.
Topics
• Message Ownership and Control, page 34

• Field Objects, page 35
• Validity of Data Extracted from Message Fields, page 36
• Field Names and Field Identifiers, page 38
• TibrvMsg, page 40
• TibrvMsgField, page 93
• TibrvInt64, page 101
See Also
Strings and Character Encodings, page 7

34
| Chapter 4 Data
Message Ownership and Control
The internal structure of each Rendezvous message belongs either to Rendezvous

software or to your program. These three situations determine message
ownership:
• When a program creates the internal structure of a message object (by calling
TibrvMsg.create, TibrvMsg.createCopy() or
TibrvMsg.createFromByteArray), the program owns that message. The
program is responsible for destroying that message (by deleting all variable
references to the outer message object).
• When a program receives a reply message as the return value of
TibrvTransport.sendRequest(), the program owns that message. The
program is responsible for destroying that message.
• When a program receives a message in a callback method, Rendezvous software
owns that message. Rendezvous software destroys such messages when the
callback method returns (unless the program explicitly detaches the message
and assigns it to a global variable).
• When a program’s callback method detaches an inbound message and sets a
persistent reference to it, then the program owns the message, and must
explicitly delete it.
• When a program receives a parent message, a, and extracts a submessage, b,
from a field of a, then the program owns b. (That is, extracting b automatically
detaches it.) When a is destroyed, b remains, and the program must explicitly
delete it.
Rendezvous software controls the storage in which all messages reside. Programs
can change the contents of a message only by using Rendezvous methods that
add, remove or update fields.
See Also
TibrvMsg.destroy on page 53
TibrvMsg.detach on page 54

Field Objects 35
|
Field Objects
When a program must extract information about a message field—such as its field
name, field identifier, or datatype—it can extract the field as a TibrvMsgField
object. A TibrvMsgField object contains complete detail about the field.
The methods TibrvMsg.getField(), TibrvMsg.getFieldByIndex(), and
TibrvMsg.getFieldInstance() return TibrvMsgField objects.
All TibrvMsgField objects always belongs to your program, so the program is
always responsible for deleting the field object.
Reference Datatypes
Five datatypes are called reference datatypes: array, message, opaque, XML, and
string.
When a message field contains a reference datatype, and a program extracts it as a
field object, then the data in the field object depends on a reference to a snapshot
in the parent message. For details, see Snapshot Reference on page 36.
See Also
Validity of Data Extracted from Message Fields, page 36
TibrvMsgField on page 93
TibrvMsg.getField() on page 63

36
| Chapter 4 Data
Validity of Data Extracted from Message Fields
To extract data values from the fields of a message, programs use the get 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—snapshot copy and snapshot reference.
Snapshot Copy
A snapshot copy is independent of the original message. The program can modify
this snapshot at any time without affecting the original message. The program can
update or delete the original field form the message at any time without affecting
the snapshot copy.
These methods always return an independent snapshot copy of the data:
• TibrvMsg.get()
• TibrvMsg.getByIndex()
• TibrvMsg.getInstance()
• TibrvMsgField.getData()
Snapshot Reference
A snapshot reference is a reference to data that still resides within the original
message. The validity of the reference depends on the continued validity of the
original message.
These are the only methods that can produce a snapshot reference; moreover,
these methods only produce a snapshot reference when the datatype of the field is
array, message, opaque, XML, or string:
• TibrvMsg.getField()
• TibrvMsg.getFieldByIndex() (see TibrvMsg.getByIndex() on page 60)

• TibrvMsg.getFieldInstance() (see TibrvMsg.getInstance() on page 68)
Extracting the data from the resulting field object with

TibrvMsgField.getData() uses the reference to yield an independent snapshot
copy of the data.

Validity of Data Extracted from Message Fields 37
|
When a field object contains a reference datatype (array, message, opaque, XML,
or string), the data in the field object depends on a reference into the parent
message. If the parent message is deleted, the program can no longer extract these
datatypes from the field object; attempting to extract them references freed
storage, which is illegal, and can cause serious consequences.
Deleting Snapshot References

Ordinarily, snapshot references remain part of the message until the program
destroys the message. However, repeated getField calls can cause snapshots to
accumulate within a message, 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 77
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.

38
| Chapter 4 Data
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.
An identifier has the range of a 16-bit unsigned integer, [0, 65535]. We
represent identifiers with Long values (32-bit signed integers) in this range.
Message methods specify fields using a combination of a field name and a unique
field identifier. When absent, the default field identifier is zero.
To compare the speed and space characteristics of these two options, see Search
Characteristics on page 38.
Rules and Restrictions

It is illegal for a field to have both a null field name (vbNullString) and a
non-zero identifier.
Adding a New Field

When a program adds a new field to a message, it can specify 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 and reports the error TIBRVCOM_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.

Field Names and Field Identifiers 39
|
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.getInstance() on page 68
• TibrvMsg.removeInstance on page 81
Release 5 Interaction
Rendezvous 5 (and earlier) did not support array datatypes. Some older
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 one-dimensional array datatypes within message fields. The
method TibrvMsg.getInstance() 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.

40
| Chapter 4 Data
TibrvMsg
Class
Purpose Represent Rendezvous messages.
(Sheet 1 of 3)

Life Cycle
TibrvMsg.create Initialize the message object. 50
TibrvMsg.createCopy() Copy a message object. 51
TibrvMsg.destroy Destroy a message object. 53
TibrvMsg.detach Detach an inbound message from 54

Rendezvous storage; the program assumes
responsibility for destroying the message.
TibrvMsg.isDetached() Test the ownership of a message object. 75
TibrvMsg.isValid() Test the validity of a message object. 76
TibrvMsg.reset Clear a message, preparing it for re-use. 82
Fields
TibrvMsg.add Add a field to a message. 45
TibrvMsg.addField Add a field object to a message. 48
TibrvMsg.get() Get the value of a specified field from a 55

message.
TibrvMsg.getByIndex() Get the value of a field from a message by 60

an index.
TibrvMsg.getField() Get a specified field from a message. 63
TibrvMsg.getFieldByIndex() Get a field from a message by an index. 65
TibrvMsg.getFieldInstance() Get the value of a specific field instance 66

from a message.

TibrvMsg 41
|
(Sheet 2 of 3)

TibrvMsg.getInstance() Get the value of a specific field instance 68
from a message.
TibrvMsg.remove Remove a field from a message. 79
TibrvMsg.removeInstance Remove a specified instance of a field from 81

a message.
TibrvMsg.update Update a field within a message. 89
TibrvMsg.updateField Update a field within a message. 92
Address Information and Properties
TibrvMsg.getProperty() Extract a property from a message. 72
TibrvMsg.getReplySubject() Extract the reply subject from a message. 73
TibrvMsg.getSendSubject() Extract the subject from a message. 74
TibrvMsg.setProperty Set a property on a message. 85
TibrvMsg.setReplySubject Set the reply subject for a message. 86
TibrvMsg.setSendSubject Set the subject for a message. 87
Archive
TibrvMsg.createFromByteArray Initialize a message with data from a byte 52

sequence.
TibrvMsg.getAsByteArray() Convert the data from a message to a byte 59

sequence.
Accessors
TibrvMsg.getByteSize() Get the size of the message. 61
TibrvMsg.getNumFields() Extract the number of fields in a message. 70
String
TibrvMsg.toString() Format a message as a string. 88

42
| Chapter 4 Data
(Sheet 3 of 3)

References
TibrvMsg.markReferences Mark references in this message. 77
TibrvMsg.clearReferences Clear references in this message. 49
Encoding
TibrvMsg.getDefaultInboundEncoding() Get the global default encoding for 62

inbound messages.
TibrvMsg.getMsgEncoding() Get the character encoding of a message. 69
TibrvMsg.getOutboundEncoding() Get the global encoding for outbound 71

messages.
TibrvMsg.setDefaultInboundEncoding Set the global default encoding for inbound 83

messages.
TibrvMsg.setOutboundEncoding Set the global encoding for outbound 84

messages.
Datatype The type library defines these constants, which denote wire format datatypes.
Constants
Table 5 Datatype Constants (Sheet 1 of 2)
Constant Comments
TIBRVCOM_MSG_NO_TAG
TIBRVCOM_MSG_MSG
TIBRVCOM_MSG_DATETIME
TIBRVCOM_MSG_OPAQUE
TIBRVCOM_MSG_STRING
TIBRVCOM_MSG_XML Byte-array, compressed for network

transmission.
TIBRVCOM_MSG_BOOL
TIBRVCOM_MSG_I8

TibrvMsg 43
|
Table 5 Datatype Constants (Sheet 2 of 2)
Constant Comments
TIBRVCOM_MSG_U8
TIBRVCOM_MSG_I16
TIBRVCOM_MSG_U16
TIBRVCOM_MSG_I32
TIBRVCOM_MSG_U32
TIBRVCOM_MSG_I64
TIBRVCOM_MSG_U64
TIBRVCOM_MSG_F32
TIBRVCOM_MSG_F64
TIBRVCOM_MSG_IPPORT16
TIBRVCOM_MSG_IPADDR32
TIBRVCOM_MSG_I8ARRAY
TIBRVCOM_MSG_U8ARRAY
TIBRVCOM_MSG_F32ARRAY
TIBRVCOM_MSG_USER_FIRST
TIBRVCOM_MSG_USER_LAST

44
| Chapter 4 Data
See Also Strings and Character Encodings, page 7


TibrvMsg.add 45
|
TibrvMsg.add
Method
Declaration TibrvMsg.add fieldName, data, tibrvType, fieldId
Purpose Add a field to a message.
Remarks This method copies the information into the new message field. Subsequent
changes to the arguments do not affect the field in the message object.
fieldName String
Add a field with this name.

vbNullString is a legal name. However, if fieldId is non-zero, then fieldName
must be non-null.
data Object
Add a field with this data value.

Pass the data as any VB type or Rendezvous object type.
When this parameter is a TibrvMsgField object, this method cannot convert it to
another type. The tibrvType parameter must be zero (or omitted).
tibrvType Byte optional

When absent or zero, determine the field’s type from the type of the object data. In
Figure 1 on page 47, filled dots indicate default encodings between homologous
types.
When present, explicitly convert the data to this type. For a list of types, see Datatype
Constants on page 42. Figure 1 on page 47 indicates permissible conversions.
fieldId Long optional

Add a field with this identifier. All field identifiers must be unique within each
message.
An identifier has the numeric range of a 16-bit unsigned integer, [0, 65535].
When absent or zero, add a field without an identifier.
Zero is a special value, indicating no identifier. It is illegal to add a field that has both
a null field name and a non-zero field identifier.

46
| Chapter 4 Data
Encoding and This method automatically converts VB data to its corresponding Rendezvous
Type wire format type. Figure 1 on page 47 specifies default encodings with filled
Conversion circles; you can override the default encoding by supplying an explicit tibrvType
argument (numeric and supported conversions). This feature lets you add fields
with datatypes that the programming language does not directly support (for
example, a signed byte or an unsigned integer.
When adding a numeric value as a TIBRVMSG_BOOL, zero maps to False, and all
non-zero values map to True.
When adding a boolean value as a numeric scalar type, False maps to zero, and
True maps to 1.
When adding an unsigned value as a signed type, this method interprets the high
bit as a sign bit. When adding a numeric value as a type with lesser precision, this
method discards bits of precision without warning. When adding a numeric value
as a type with smaller range, this method checks the range and reports an error if
the target type cannot accommodate the value.
Encoding XML As a convenience, Visual Basic lets you add a string value as an XML field; the
resulting XML is encoded as UTF-16LE (16-bit Unicode, little-endian byte order).
However, other language APIs might not support this encoding. For this reason,
we discourage programmers from directly adding string values as XML fields.
Instead, we recommend converting the XML document string to a byte sequence,
using the encoding that corresponds to your locale. This practice ensures that all
receivers can easily parse the resulting XML document. For more information, see
Decoding XML on page 57.
Nested Message When the data argument is a message object, this method adds only the data
portion of the nested message; it does not include any address information or
certified delivery information.
Field Name The the longest possible field name is 127 bytes.
Length

TibrvMsg.add 47
|
Figure 1 VB to Wire Format Datatype Conversion Matrix

VB Native Type
Add
TibrvMsgInt64()
TibrvInt64
TibrvMsg
Double()
Integer()
Boolean
Single()
Double
Integer
Long()
Single
Byte()
String
Long
Date
Byte
TIBRVCOM_MSG_BOOL S S S S S P
TIBRVCOM_MSG_F32 S N S S N P
TIBRVCOM_MSG_F64 S S S S N P
TIBRVCOM_MSG_I8 S N N + N N P
TIBRVCOM_MSG_I16 S N N S S P
TIBRVCOM_MSG_I32 S N N S S P
TIBRVCOM_MSG_I64 S N N S S S P
TIBRVCOM_MSG_U8 S N N N N P
TIBRVCOM_MSG_U16 S N N S + N P
TibrvMsg Destination Type
TIBRVCOM_MSG_U32 S N N S S + P
TIBRVCOM_MSG_U64 S N N S S S + P
TIBRVCOM_MSG_IPADDR32 N N S S S P
TIBRVCOM_MSG_IPPORT16 N N S S N P
TIBRVCOM_MSG_DATETIME
TIBRVCOM_MSG_I8ARRAY +
TIBRVCOM_MSG_U8ARRAY S
TIBRVCOM_MSG_U16ARRAY +
TIBRVCOM_MSG_MSG
TIBRVCOM_MSG_OPAQUE S
TIBRVCOM_MSG_STRING
TIBRVCOM_MSG_XML S S
Key
Homologous types; conversion always supported; no loss of information
S Supported conversion; always supported
N Numeric conversion; out of range is an error; loss of sign or precision is OK
+ Signed interpreted as unsigned integer, or unsigned interpreted as signed
P Parsed conversion; supported when string has appropriate format
Unsupported conversion
See Also TibrvMsg.addField on page 48

48
| Chapter 4 Data
TibrvMsg.addField
Method
Declaration TibrvMsg.addField field
Purpose Add a field object to a message.
Remarks This method copies the information into a new message field, without type
conversion.
It is illegal to add a field that has both a null field name (vbNullString), and a
non-zero field identifier.
field TibrvMsgField
Add this field to the message.
See Also TibrvMsg.add on page 45

TibrvMsg.clearReferences 49
|
TibrvMsg.clearReferences
Method
Declaration TibrvMsg.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 77.
See Also Validity of Data Extracted from Message Fields, page 36

Deleting Snapshot References, page 37
TibrvMsg.markReferences on page 77

50
| Chapter 4 Data
TibrvMsg.create
Method
Declaration TibrvMsg.create initialSize
Purpose Initialize the message object.
Remarks This method initializes the internal structure of the message object, allocating
storage for it.
Calling this method on a valid object yields the error
TIBRVCOM_ALREADY_INITIALIZED.
initialSize Long; optional
Allocate a message of this non-negative size (in bytes).
(Messages can grow dynamically.)
When absent or zero, Rendezvous allocates initial storage
automatically. We recommend omitting this argument.

TibrvMsg.createCopy() 51
|
TibrvMsg.createCopy()
Method
Declaration set msgCopy = TibrvMsg.createCopy()
Purpose Copy a message object.
Remarks Create an independent copy of the message, copying all its fields (that is, field
values are also independent copies).
This method does not copy subject information, certified delivery information,
nor other supplementary information or properties.
This method does not copy snapshot references into the new copy message.
msgCopy TibrvMsg
Return an independent copy of the message.

52
| Chapter 4 Data
TibrvMsg.createFromByteArray
Method
Declaration TibrvMsg.createFromByteArray byteArray
Purpose Initialize a message with data from a byte sequence.
Remarks This method is an alternative to TibrvMsg.create. It initializes the message with

data from the byte sequence.
To extract a byte sequence from a message, see TibrvMsg.getAsByteArray() on
page 59.
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.
byteArray Object
Initialize the message with data from this one-dimensional

byte array.
See Also TibrvMsg.create on page 50

TibrvMsg.getAsByteArray() on page 59

TibrvMsg.destroy 53
|
TibrvMsg.destroy
Method
Declaration TibrvMsg.destroy
Purpose Destroy a message object.
Remarks This method destroys only the internal structure of the message object.
Rendezvous software automatically destroys a message when program execution
leaves the scope of the object, or deletes all references to the object.
See Also Message Ownership and Control, page 34

54
| Chapter 4 Data
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.
Example In this example, msgref is accessible after the callback method returns.
Dim msgref as TibrvMsg
Private Sub mylis_OnMsg( _

ByVal lisn as TIBRVCOMLib.ITibrvListener, _
ByVal message as TIBRVCOMLib.ITibrvMsg)
set msgref = message
msgref.detach
End Sub
See Also Message Ownership and Control on page 34

TibrvMsg.destroy on page 53
TibrvMsg.isDetached() on page 75
TibrvListener_onMsg on page 120

TibrvMsg.get() 55
|
TibrvMsg.get()
Method
Declaration data = TibrvMsg.get(fieldName, tibrvType, fieldId)
Purpose Get the value of a specified field from a message.
Remarks Programs specify the field to retrieve using the fieldName and fieldId
parameters.
This method returns an independent snapshot copy of the field value. For details,
see Snapshot Copy on page 36.
Programs can use a related method to loop through all the fields of a message; to
retrieve each field of a message, see TibrvMsg.getByIndex() on page 60.
fieldName String
Get a field with this name. See Field Search Algorithm.

vbNullString is a legal field name.

Convert the data value to the object datatype corresponding to
this type, if possible. For a list of types, see Datatype Constants
on page 42.
When absent or zero, automatically convert the data to its
homologous type. Figure 2 on page 58 indicates default
decodings between homologous types.

Get the field with this identifier. See Field Search Algorithm.
An identifier has the range of a 16-bit unsigned integer,
[0, 65535].
data Object
Return the data value of the field.
Field Search TibrvMsg.get(), TibrvMsg.getField(), TibrvMsg.getInstance() and

Algorithm TibrvMsg.getFieldInstance() use this algorithm to find a field within a
message, as specified by a field identifier and a field name.

56
| Chapter 4 Data
1. If the program supplied zero as the identifier, or omitted any identifier, then
begin at 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.
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 zero, return the
field.
If the name search succeeds, but the actual identifier in the field is non-zero
(so it does not match the identifier supplied) then report the error
TIBRVCOM_ID_CONFLICT.
On failure, or if the program supplied vbNullString as the field name, report

the error TIBRVCOM_NOT_FOUND.
3. When the program supplied zero as the identifier, or omitted any identifier,
then begin here.
Search for a field with the specified name—even if that name is
vbNullString.
If the search succeeds, return the field.

On failure, report the error TIBRVCOM_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.
When an error occurs, the method returns an empty object.
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.get()
(or a related method), and then get the desired fields from the submessage.
Decoding and This method automatically decodes the extracted field data from its Rendezvous
Type wire format type to a corresponding VB type. In Figure 2 on page 58, filled circles
Conversion (as well as + and - symbols) specify default decodings between homologous
types; you can override the default decoding by supplying an explicit tibrvType
argument (numeric and supported conversions).

TibrvMsg.get() 57
|
The default conversion for extracting a TIBRVCOM_MSG_I8 yields an Integer, with

zeroes padding the high 8 bits. (Similarly for TIBRVCOM_MSG_I8ARRAY.)
The default conversion for extracting a TIBRVCOM_MSG_U16 yields a Long, with
zeroes padding the high 16 bits. (Similarly for TIBRVCOM_MSG_U16ARRAY.)
The default conversion for extracting a TIBRVCOM_MSG_U32 yields a Long,
interpreting the high bit as a sign bit. (Similarly for TIBRVCOM_MSG_U32ARRAY.)
When extracting a numeric value as a boolean, zero maps to boolean False. All
non-zero numeric values map to boolean True.
When extracting a TIBRVMSG_BOOL as a numeric value, False maps to zero, and
Truemaps to 1.
When extracting a TIBRVMSG_STRING as a boolean, if the first character is either t
or T, then it maps to boolean True. All other strings map to boolean False.
Extracting a TIBRVCOM_MSG_IPADDR32 as a string yields the standard dot notation
(a.b.c.d).
To determine the datatype of the original message field, use
TibrvMsg.getField() and TibrvMsgField.getType().
Decoding XML As a convenience, Visual Basic lets you extract an XML field as a string value;
however, the resulting string is only valid if the XML field uses UTF-16LE
encoding. Other language APIs might not support this encoding. For this reason,
we discourage programmers from directly extracting an XML field as a string
value. Instead, we recommend extracting the XML document as a byte array, and
then explicitly converting it to a string using the encoding that corresponds to
your locale. For more information, see Encoding XML on page 46.

58
| Chapter 4 Data
Figure 2 Wire Format to VB Datatype Conversion Matrix

VB Destination Type
Get
TibrvInt64()
TibrvInt64
TibrvMsg
Double()
Integer()
Boolean
Single()
Double
Integer
Long()
Single
Byte()
String
Long
Date
Byte
TIBRVCOM_MSG_BOOL S S S S S S
TIBRVCOM_MSG_F32 S S N N N S
TIBRVCOM_MSG_F64 S N N N N S
TIBRVCOM_MSG_I8 S N N + S S
TIBRVCOM_MSG_I16 S N N N N S
TIBRVCOM_MSG_I32 S N N N N S
TIBRVCOM_MSG_I64 S
TIBRVCOM_MSG_U8 S N N S S S
TIBRVCOM_MSG_U16 S N N N + S
TIBRVCOM_MSG_U32 S N N N N + S
tibrvMsg Source Type
TIBRVCOM_MSG_U64 S
TIBRVCOM_MSG_IPADDR32 S
TIBRVCOM_MSG_IPPORT16 S S
TIBRVCOM_MSG_DATETIME S
TIBRVCOM_MSG_F32ARRAY S
TIBRVCOM_MSG_F64ARRAY S
TIBRVCOM_MSG_I8ARRAY + S
TIBRVCOM_MSG_I16ARRAY S
TIBRVCOM_MSG_U16ARRAY + S
TIBRVCOM_MSG_U32ARRAY + S
TIBRVCOM_MSG_MSG S
TIBRVCOM_MSG_OPAQUE C
TIBRVCOM_MSG_STRING
TIBRVCOM_MSG_XML C
Key
Homologous types; conversion always supported
S Supported conversion; always supported
N Numeric conversion; loss of sign or precision OK; out of range truncated (no error)
+ Signed interpreted as unsigned integer, or unsigned interpreted as signed
+ Homologous types; conversion always supported, but sign bit interpretation as with +
C Caution; supported, but results sometimes can be misleading
Unsupported conversion
See Also TibrvMsg.getByIndex() on page 60

TibrvMsg.getInstance() on page 68

TibrvMsg.getAsByteArray() 59
|
TibrvMsg.getAsByteArray()
Method
Declaration byteArray = TibrvMsg.getAsByteArray()
Purpose Convert the data from a message to a byte sequence.
Remarks Return a copy of the data as a byte sequence, suitable for archiving in a file. To
reconstruct the message from bytes, see TibrvMsg.createFromByteArray on
page 52.
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 zero bytes.
byteArray Object
Return the message data as a one-dimensional byte array.
See Also TibrvMsg.createFromByteArray on page 52

TibrvMsg.getByteSize() on page 61

60
| Chapter 4 Data
TibrvMsg.getByIndex()
Method
Declaration data = TibrvMsg.getByIndex(index)
Purpose Get the value of 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.
These two related methods differ only in the form of their return values. The first
returns the field’s data value; the second returns a TibrvMsgField object.
Add, remove and update calls can perturb the order of fields (which, in turn, affects
the order when a program gets fields by index).
index Long
Get the field with this index. Zero specifies the first field.
data Object

TibrvMsg.getByteSize() 61
|
TibrvMsg.getByteSize()
Method
Declaration byteSize = TibrvMsg.getByteSize()
Purpose Get the size of the message.
Remarks This method returns the size of the message. Programs can use this size in
conjunction with TibrvMsg.getAsByteArray(); for example, when writing the
message byte array to a file, and reading it in again (using binary file I/O).
byteSize Long
Return the size of the wire-format message (in bytes).
See Also TibrvMsg.createFromByteArray on page 52

TibrvMsg.getAsByteArray() on page 59

62
| Chapter 4 Data
TibrvMsg.getDefaultInboundEncoding()
Method
Declaration encoding = TibrvMsg.getDefaultInboundEncoding()
Purpose Get the global default encoding for inbound messages.
Remarks When an inbound message arrives without an explicit encoding tag,

TibrvMsg.getMsgEncoding() in the receiving program infers this default
encoding.
If no global default is set, this call yields vbNullString and returns normally.
encoding String
The program supplies a location in this parameter; the function

stores the name of the encoding (as a string) in that location.
See Also TibrvMsg.getMsgEncoding() on page 69

TibrvMsg.setDefaultInboundEncoding on page 83

TibrvMsg.getField() 63
|
TibrvMsg.getField()
Method
Declaration set field = TibrvMsg.getField(fieldName, fieldId)
Purpose Get a specified field from a message.
Remarks When a program must extract information about a message field—such as its field
Programs specify the field to retrieve using the fieldName and fieldId
parameters. The method returns a TibrvMsgField object. Unlike
TibrvMsg.get(), this method does not attempt any datatype conversions.
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 65.
fieldName String
Get a field with this name. See Field Search Algorithm on

page 55.

Get the field with this identifier. See Field Search Algorithm on
page 55.
[0, 65535].
field TibrvMsgField
Return the field object.
When a field object contains a reference datatype (array, message, opaque, or

string), the data in the field object depends on a reference into the parent message.
If the parent message is deleted, the program can no longer extract these

64
| Chapter 4 Data
See Also Field Objects, page 35

TibrvMsg.get() on page 55

TibrvMsg.getFieldByIndex() 65
|
TibrvMsg.getFieldByIndex()
Method
Declaration set field = TibrvMsg.getFieldByIndex(index)
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.
Add, remove and update calls can perturb the order of fields (which, in turn, affects
the order when a program gets fields by index).
index Long
Get the field with this index. Zero specifies the first field.
field TibrvMsgField
See Also TibrvMsg.getByIndex() on page 60


66
| Chapter 4 Data
TibrvMsg.getFieldInstance()
Method
Declaration set field = TibrvMsg.getFieldInstance(fieldName, instance)
Purpose Get a specific 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 first instance of the named field is instance 1.
When the instance argument is greater than the actual number of instances of
the field in the message, this method reports the error TIBRVCOM_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
(Sheet 1 of 2)
fieldName String
Get an instance of a field with this name.

instance Long
Get this instance of the specified field name. The argument 1

denotes the first instance of the named field.

TibrvMsg.getFieldInstance() 67
|
(Sheet 2 of 2)
field TibrvMsgField
See Also TibrvMsg.getInstance() on page 68


68
| Chapter 4 Data
TibrvMsg.getInstance()
Method
Declaration data = TibrvMsg.getInstance(fieldName, instance)
Purpose Get the value of a specific field instance from a message.
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 first instance of the named field is instance 1.
When the instance argument is greater than the actual number of instances of
the field in the message, this method reports the error TIBRVCOM_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
fieldName String
Get an instance of a field with this name.

instance Long
Get this instance of the specified field name. The argument 1

denotes the first instance of the named field.
data Object
See Also TibrvMsg.getFieldInstance() on page 66


TibrvMsg.getMsgEncoding() 69
|
TibrvMsg.getMsgEncoding()
Method
Declaration encoding = TibrvMsg.getMsgEncoding()
Purpose Get the character encoding of a message.
Remarks This call yields either the actual encoding stored with a message, or (if none is
stored) a reasonable estimate:
• When a message is created locally, and its send subject is set, then its encoding
is also set, and this call gets the actual encoding from the message. (This value
is identical to the program’s global outbound encoding.)
• When the message is created locally and its send subject is not set, then its
encoding is also not set, and this call gets the program’s global outbound
encoding. If no global value is set, this call yields the string UNKNOWN.
• If the message is inbound, and bears an explicit encoding, then this call gets
that encoding.
• If the message is inbound, and does not bear an explicit encoding, then this
call gets the program’s global default inbound encoding. If no global default is
set, this call yields the string UNKNOWN.
encoding String

See Also TibrvMsg.getDefaultInboundEncoding() on page 62

TibrvMsg.getOutboundEncoding() on page 71
TibrvMsg.setDefaultInboundEncoding on page 83
TibrvMsg.setOutboundEncoding on page 84
TibrvMsg.setSendSubject on page 87

70
| Chapter 4 Data
TibrvMsg.getNumFields()
Method
Declaration numFields = TibrvMsg.getNumFields()
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.
numFields Long
Return the number of fields in the message.

TibrvMsg.getOutboundEncoding() 71
|
TibrvMsg.getOutboundEncoding()
Method
Declaration encoding = TibrvMsg.getOutboundEncoding()
Purpose Get the global encoding for outbound messages.
Remarks If no global value is set, this call yields vbNullString and returns normally.
encoding String


TibrvMsg.setOutboundEncoding on page 84

72
| Chapter 4 Data
TibrvMsg.getProperty()
Method
Declaration value = TibrvMsg.getProperty(name)
Purpose Extract a property from a message.
Remarks Properties are supplementary information—they are not part of the message itself.
name String
Extract the property with this name.
value Object
Return this property value.

If the property is not set, this method reports an error, and the
object is empty.
Property Description
cmSender String
The correspondent name of the CM transport that sent a labeled message.

When the message is not labeled with this CM property, the method
reports the error TIBRVCOM_NOT_FOUND.
cmSequenceNumber TibrvInt64
cmSequence The sequence number of labeled message.
(either name extracts When the message is not labeled with this CM property, the method
the same property) reports the error TIBRVCOM_NOT_FOUND, and the TibrvInt64 contains zero.
cmTimeLimit Double
The CM time limit of a labeled message.

If the message is not labeled, the value is zero.
This value is always a positive integer.
See Also TibrvMsg.setProperty on page 85

CM Label Information, page 235
Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TibrvMsg.getReplySubject() 73
|
TibrvMsg.getReplySubject()
Method
Declaration replySubject = TibrvMsg.getReplySubject()
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.
replySubject String
Return the reply subject of the message.

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 Snapshot Reference on page 36,
and Deleting Snapshot References on page 37.
If the reply subject is not set, this method reports the error
TIBRVCOM_NOT_FOUND, and the string is vbNullString.
See Also TibrvMsg.setReplySubject on page 86

Concepts

74
| Chapter 4 Data
TibrvMsg.getSendSubject()
Method
Declaration sendSubject = TibrvMsg.getSendSubject()
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.
sendSubject String
Return the subject of the message.

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 Snapshot Reference on page 36, and
Deleting Snapshot References on page 37.
If the destination subject is not set, this method reports the
error TIBRVCOM_NOT_FOUND, and the string is
vbNullString.
See Also TibrvMsg.setSendSubject on page 87

Concepts

TibrvMsg.isDetached() 75
|
TibrvMsg.isDetached()
Method
Declaration isDetached = TibrvMsg.isDetached()
Purpose Test the ownership of a message object.
isDetached Boolean
Return True if the message is detached (the program owns the

object, and must destroy it).
Return False if the message is not detached (Rendezvous
software owns the object, and will destroy it).
See Also TibrvMsg.destroy on page 53

TibrvMsg.detach on page 54

76
| Chapter 4 Data
TibrvMsg.isValid()
Method
Declaration isValid = TibrvMsg.isValid()
Purpose Test the validity of a message object.
isValid Boolean
Return True if the message is valid.

Return False if the internal structure of the message has been
destroyed.

TibrvMsg.markReferences 77
|
TibrvMsg.markReferences
Method
Declaration TibrvMsg.markReferences
Purpose Mark references in this message.
Remarks Extracting a field object from a message creates a snapshot of that data. When the
field contains a reference datatype, the snapshot is a reference that depends on the
parent message. A reference snapshot remains associated with the message until
the program destroys the message. Repeatedly extracting field objects can cause
reference snapshots to 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 extract a message field object.
For example, consider a program fragment that repeatedly sends a template
message, extracting field objects from the message before each send call. Each call
to extract a field produces a snapshot reference. By surrounding the getField
operation with a mark and clear pair (with the clear call occurring at any time after
the getField call), the program releases the reference, which helps control memory
usage.
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 3 on page 78 illustrates that each clear call deletes snapshots
back to the most recent mark.
Unless a program explicitly marks and clears references, references persist until
the message is destroyed or reset.
Example This first code fragment exits the loop with 10000 unneeded references to the field
named myFld:
For i = 1 to 10000
set myFld = msg.getField("fld_name") ’Creates a snapshot refr
...myFld.getData()... ’Uses the reference
next i
This second code fragment clears the reference at the end of each iteration:
For i = 1 to 10000
msg.markReferences
set myFld = msg.getField("fld_name") ’Creates a snapshot refr
...myFld.getData()... ’Uses the reference
msg.clearReferences
next i

78
| Chapter 4 Data
Figure 3 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).
See Also Reference Datatypes on page 35

Validity of Data Extracted from Message Fields, page 36
Deleting Snapshot References, page 37
TibrvMsg.clearReferences on page 49

TibrvMsg.remove 79
|
TibrvMsg.remove
Method
Declaration TibrvMsg.remove fieldName, fieldId
Purpose Remove a field from a message.
fieldName String
Remove a field with this name. See Field Search Algorithm.


Remove the field with this identifier. See Field Search
Algorithm.
[0, 65535].
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.
begin at step 3.
with that identifier. If the search succeeds, remove the field.
On the search does not find a field, continue to step 2.
On the search does not find a field, or if the program supplied vbNullString
as the field name, report the error TIBRVCOM_NOT_FOUND.
If the search succeeds, remove the field.

then begin here.
vbNullString.

80
| Chapter 4 Data
If the search succeeds, remove the field.

If the search does not find a field, report the error TIBRVCOM_NOT_FOUND.
If a message contains several fields with the same name, searching by name
removes the first instance of the field with that name.

TibrvMsg.removeInstance 81
|
TibrvMsg.removeInstance
Method
Declaration TibrvMsg.remove fieldName, instance
Purpose Remove a specified instance of a field from a message.
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 reports the error
TIBRVCOM_NOT_FOUND.
fieldName String
Remove a field with this name.

instance Long
Remove this instance of the field. The argument 1 specifies the

first instance of the named field.

82
| Chapter 4 Data
TibrvMsg.reset
Method
Declaration TibrvMsg.reset
Purpose Clear a message, preparing it for re-use.
Remarks This method is the equivalent of destroying the message object and creating a
new, except that the new object re-uses the same storage for the outer message
object.
When this method returns, the message has no fields; it is like a newly created
message. The message’s address information and other properties are also reset.
Snapshot references of the old message are freed. Field objects previously
extracted from the old message may contain references into the freed storage.

TibrvMsg.setDefaultInboundEncoding 83
|
TibrvMsg.setDefaultInboundEncoding
Method
Declaration TibrvMsg.setDefaultInboundEncoding encoding
Purpose Set the global default encoding for inbound messages.
Remarks When an inbound message arrives without an explicit encoding tag,

TibrvMsg.getMsgEncoding() in the receiving program infers this default
encoding.
If no global default is set, TibrvMsg.getMsgEncoding() infers an UNKNOWN
encoding.
encoding String
Set the global default inbound encoding to this value.

TibrvMsg.getDefaultInboundEncoding() on page 62

84
| Chapter 4 Data
TibrvMsg.setOutboundEncoding
Method
Declaration TibrvMsg.setOutboundEncoding encoding
Purpose Set the global encoding for outbound messages.
Remarks Outbound messages bear this tag, indicating the encoding of all strings within the
message.
When no global encoding is set, outbound messages do not bear any encoding
tag.
encoding String
Set the global encoding to this value.

TibrvMsg.getOutboundEncoding() on page 71

TibrvMsg.setProperty 85
|
TibrvMsg.setProperty
Method
Declaration TibrvMsg.setProperty name, value
Purpose Set a property on a message.
Remarks Properties are supplementary information—they are not part of the message itself.
name String
Set the property with this name.
value Object
Set this property value.
Property Description
cmTimeLimit Double
The CM time limit (in whole seconds) of a message.

Setting this property overrides the default time limit of the
sending CM transport.
Fractional values are truncated.
See Also TibrvMsg.getProperty() on page 72

Concepts

86
| Chapter 4 Data
TibrvMsg.setReplySubject
Method
Declaration TibrvMsg.setReplySubject 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.
replySubject String
Use this string as the new reply subject, replacing any

existing reply subject.
The reply subject vbNullString removes the previous
reply subject.
The empty string is not a legal subject name.
See Also TibrvMsg.getReplySubject() on page 73

Concepts
Names and Subject-Based Addressing on page 43 in TIBCO Rendezvous Concepts

TibrvMsg.setSendSubject 87
|
TibrvMsg.setSendSubject
Method
Declaration TibrvMsg.setSendSubject 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.
sendSubject String
Use this string as the new subject, replacing any existing

subject.
The subject vbNullString removes the previous subject,
leaving the message unsendable.
The empty string is not a legal subject name.
See Also TibrvMsg.getSendSubject() on page 74

Concepts
Names and Subject-Based Addressing on page 43 in TIBCO Rendezvous Concepts

88
| Chapter 4 Data
TibrvMsg.toString()
Method
Declaration formattedString = tibrvMsg.toString()
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 each field to the output
string; however, these two types are exceptions:
TIBRVCOM_MSG_OPAQUE This method abbreviates the value of an opaque field;
for example, [472 opaque bytes].
TIBRVCOM_MSG_XML This method abbreviates the value of an XML field; for
example, [XML document: 472 bytes].
The size measures uncompressed data.
This method formats TIBRVCOM_MSG_IPADDR32 fields as four dot-separated

decimal integers.
This method formats TIBRVCOM_MSG_IPPORT16 fields as one decimal integer.
formattedString String
Return a string denoting the message.
Converting TibrvMsg.toString() prints times in UTC format (also known as Zulu time or
Dates to Strings GMT). The ISO-8601 standard requires appending a Z character in this notation.
TibrvMsg.toString() 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.toString() 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.

TibrvMsg.update 89
|
TibrvMsg.update
Method
Declaration TibrvMsg.update fieldName, data, tibrvType, fieldId
Purpose Update a field within a message.
Remarks This method copies the new data into the message field.
This method locates a field within the message by matching the fieldName and
fieldId arguments. Then it updates the message field using the data argument.
(Notice that the program may not supply a different field name, field identifier, or
datatype.)
If no existing field matches the specifications in the fieldName and fieldId
arguments, then this method adds a new field to the message.
The type of the existing message field and the updating tibrvType argument
must be identical; otherwise, the method reports the error
TIBRVCOM_INVALID_TYPE.
When updating, a new array may have a different count (number of elements); a
new string, opaque or XML may have different length.
(Sheet 1 of 2)
fieldName String
Update a field with this name. See Field Search Algorithm on page 90.
vbNullString is a legal name. However, if fieldId is non-zero, then
fieldName must be non-null.
data Object
Update the field to this data value.

Pass the data as any VB type or Rendezvous object type.
When this parameter is a TibrvMsgField object, this method cannot convert it
to another type.
To remove a field, use TibrvMsg.remove on page 79.

90
| Chapter 4 Data
(Sheet 2 of 2)
Update a field with this type.
When absent or zero, determine the field’s type from the type of the data.
Default encodings and possible conversions are identical to methods that add
fields; see Figure 1 on page 47.

Update the field with this identifier. All field identifiers must be unique within
each message. See Field Search Algorithm on page 90.
An identifier has the range of a 16-bit unsigned integer, [0, 65535].
Zero is a special default value, indicating no identifier. It is illegal to add a field
that has both a null field name and a non-zero field identifier.
Field Search Algorithm

The methods TibrvMsg.update and TibrvMsg.updateField use this algorithm
to find and update a field within a message, as specified by a field identifier and a
field name.
begin at step 3.
with that identifier.
If the search succeeds, then update that field.
On failure, continue to step 2.
If the search succeeds, then update that field.
If the search fails, add the field as specified (with name and identifier).
However, if the program supplied vbNullString as the field name, then do
not search for the field name; instead, report the error TIBRVCOM_NOT_FOUND.

TibrvMsg.update 91
|
then begin here.
vbNullString.
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.
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 subject address information or
certified delivery information.

92
| Chapter 4 Data
TibrvMsg.updateField
Method
Declaration TibrvMsg.updateField field
Purpose Update a field within a message.
Remarks This method copies the new data into the existing message field.
This method locates a field within the message by matching the name and
identifier of the field argument. Then it updates the message field using the data
of the field object. (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 object’s name and
identifier, then this method adds a new field to the message.
The type of the existing message field and the type of the updating field
argument must be identical; otherwise, the method reports the error
TIBRVCOM_INVALID_TYPE.
When updating, a new array may have a different count (number of elements); a
new string, opaque or XML may have different length.
field TibrvMsgField
Update the existing message field using this field.

TibrvMsgField 93
|
TibrvMsgField
Class
Purpose Represent a message field.
Remarks Programs use field objects in two situations:

• When a program must repeatedly add similar information to several
messages, it may be convenient to initialize a field object with that
information, and supply that object to TibrvMsg.addField or
TibrvMsg.updateField.
• When a program must extract information about a message field—such as its

field name, field identifier, or datatype—it can extract the field as a
TibrvMsgField object. A TibrvMsgField object contains complete detail
about the field.
All TibrvMsgField objects always belong to your program, so the program is

The validity of the data in a field object depends on its origin:
• When a program creates and initializes a field (by calling New
TibrvMsgField, and then TibrvMsgField.initialize), the field object’s
data remains valid indefinitely.
• When a program extracts a field object from a message, and the field contains
a reference datatype (array, message, opaque, XML, or string), then the field
object’s data is a reference into the message—so the data remains valid only
until the message is destroyed or deleted (or TibrvMsg.clearReferences
explicitly clears the reference).
For example, consider a listener callback method that extracts a field from the
inbound message. That is, it calls TibrvMsg.getField(), and receives a field
object as the return value. When the callback method exits, the inbound
message is destroyed, and the field object’s data reference snapshot becomes
invalid.
(Sheet 1 of 2)

TibrvMsgField.initialize Set the contents of a message field object. 99
TibrvMsgField.getData() Extract the data portion of a field object. 95
TibrvMsgField.getId() Extract the field identifier of a field object. 96

94
| Chapter 4 Data
(Sheet 2 of 2)

TibrvMsgField.getName() Extract the field name of a field object. 97
TibrvMsgField.getType() Extract the type of a field object. 98
See Also Field Objects, page 35

TibrvMsg.addField on page 48
TibrvMsg.updateField on page 92

TibrvMsgField.getData() 95
|
TibrvMsgField.getData()
Method
Declaration data = TibrvMsgField.getData() ’For non-object data.
Set data = TibrvMsgField.getData() ’For object data
Purpose Extract the data portion of a field object.
Remarks This method always yields an independent snapshot copy of the field data—as
does TibrvMsg.get().
Field Description
data Object
Return the data content of the field.

96
| Chapter 4 Data
TibrvMsgField.getId()
Method
Declaration fieldId = TibrvMsgField.getId()
Purpose Extract the field identifier of a field object.
Field Description
fieldId Long
Return the identifier of the field.

Zero is a special default value, indicating no identifier.

TibrvMsgField.getName() 97
|
TibrvMsgField.getName()
Method
Declaration fieldName = TibrvMsgField.getName()
Purpose Extract the field name of a field object.
Field Description
fieldName String
Return the field name of the field.

Names must be strings; vbNullString is a special value that
indicates no name.

98
| Chapter 4 Data
TibrvMsgField.getType()
Method
Declaration tibrvType = TibrvMsgField.getType()
Purpose Extract the type of a field object.
Field Description
tibrvType Byte
Return the Rendezvous type designator of the field.

For a list of types, see Datatype Constants on page 42.

TibrvMsgField.initialize 99
|
TibrvMsgField.initialize
Method
Declaration TibrvMsgField.initialize fieldName, data, tibrvType, fieldId
Purpose Set the contents of a message field object.
Remarks This method does not verify that the data and type of the field are consistent.
Methods that add the field object into a message verify consistency (for example
TibrvMsg.addField and TibrvMsg.updateField).
When a program creates a field object (using the New operator), the program owns
the object, and can initialize it using this method—even repeatedly. This method
discards any old field content, and replaces it with the new content from the
method’s arguments.
(Sheet 1 of 2)
fieldName String
Store this name in the field object.

vbNullString is a legal name. However, if fieldId is non-zero, then
fieldName must be non-null.
data Object
Store this data value in the field object.

Pass the data as any VB type or Rendezvous object type (except for
TibrvMsgField).

Store this explicit type in the field object, and convert the data to this type. For
a list of types, see Datatype Constants on page 42.
When absent or zero, determine the field’s type from the type of the object
data.
In Figure 1 on page 47, filled dots indicate default encodings between
homologous types.

100
| Chapter 4 Data
(Sheet 2 of 2)
Store this identifier in the field object. All field identifiers must be unique
within each message.
When absent or zero, add a field without an identifier.
Zero is a special value, indicating no identifier. It is illegal to add a field that
has both a null field name and a non-zero field identifier.
See Also TibrvMsg.addField on page 48

TibrvMsg.updateField on page 92

TibrvInt64 101
|
TibrvInt64
Class
Purpose Represent a 64-bit integer.
Remarks Inbound messages can contain 64-bit integers, which COM and VB do not directly
support. Programs can store signed or unsigned 64-bit values in this object; it is
the responsibility of the program to use the high-order bit consistently (either as a
sign bit or a value bit).
Certified delivery software attaches 64-bit sequence numbers to messages.
TIBRVCOM includes this object to represent those sequence numbers.
Rendezvous software does not support arithmetic on this object. However, VB

programmers can use the VB currency type (scaled 64-bit integer) to facilitate
64-bit arithmetic; programs must handle scale factor appropriately.

TibrvInt64.getAsHexString() Get the value of a 64-bit integer as a hexidecimal 102
string.
TibrvInt64.getAsString() Get the value of a 64-bit integer as a string, 103

interpreting the high order bit as a sign bit.
TibrvInt64.getAsUnsignedString() Get the value of a 64-bit integer as a string, 104

interpreting the high order bit as a value bit
(rather than a sign bit).
TibrvInt64.getLowOrderPart() Get the low-order 32 bits of a 64-bit integer. 105
TibrvInt64.getHighOrderPart() Get the high-order 32 bits of a 64-bit integer. 106
TibrvInt64.setFromString Set the value of a 64-bit integer. 107
See Also TibrvMsg.get() on page 55

102
| Chapter 4 Data
TibrvInt64.getAsHexString()
Method
Declaration stringValue = TibrvInt64.getAsHexString()
Purpose Get the value of a 64-bit integer as a hexidecimal string.
Remarks Notice that hexidecimal strings avoid confusion regarding the sign bit.
stringValue String
Return the value as a hexidecimal string.

TibrvInt64.getAsString() 103
|
TibrvInt64.getAsString()
Method
Declaration stringValue = TibrvInt64.getAsString()
Purpose Get the value of a 64-bit integer as a string, interpreting the high order bit as a sign
bit.
stringValue String
Return the value as a string.

104
| Chapter 4 Data
TibrvInt64.getAsUnsignedString()
Method
Declaration stringValue = TibrvInt64.getAsUnsignedString()
Purpose Get the value of a 64-bit integer as a string, interpreting the high order bit as a
value bit (rather than a sign bit).
stringValue String
Return the value as a string.

TibrvInt64.getLowOrderPart() 105
|
TibrvInt64.getLowOrderPart()
Method
Declaration lowOrderPart = TibrvInt64.getLowOrderPart()
Purpose Get the low-order 32 bits of a 64-bit integer.
Remarks If the high order bit of this part is set, the value appears as a negative integer.
lowOrderPart Long
Return the 32 low order bits.

106
| Chapter 4 Data
TibrvInt64.getHighOrderPart()
Method
Declaration highOrderPart = TibrvInt64.getHighOrderPart()
Purpose Get the high-order 32 bits of a 64-bit integer.
Remarks If the high order bit of this part is set, the value appears as a negative integer.
lowOrderPart Long
Return the 32 high order bits.

TibrvInt64.setFromString 107
|
TibrvInt64.setFromString
Method
Declaration TibrvInt64.setFromString stringValue
Purpose Set the value of a 64-bit integer.
Remarks This method parses a string of decimal digits, truncating any fractional part.
String values can be in the range [-263, 264-1], that is,
[-9223372036854775808, +18446744073709551615]. Notice that this range
overloads the high-order bit, using it as a sign bit for string values less than zero,
and as a value bit for string values greater than 263-1. It is the responsibility of the
program to use the high-order bit consistently (either as a sign bit or a value bit).
Values outside the range [-263, 264-1] yield incorrect results, but do not produce
errors.
stringValue String
Set the value by parsing this string.
Recommendations
For the type TIBRVCOM_MSG_I64, limit values to the range
[-9223372036854775808, +9223372036854775807]. Some operating system
platforms cannot correctly construct -9223372036854775808; instead, they limit the
minimum to -9223372036854775807.
For the type TIBRVCOM_MSG_U64, limit values to the range
[0, +18446744073709551615].
(Note that extracting this object from a message field does not retain the original
type designator.)

108
| Chapter 4 Data

| 109
Chapter 5 Events and Queues
Programs can express interest in events of two kinds—inbound messages and

timers. 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. A special queue group, called the automatic dispatch
queue group, automatically dispatches its queues; we recommend this
mechanism, especially for GUI applications.
This chapter presents classes, methods, interfaces and types associated with event
interest and event processing.
Topics
• TibrvListener, page 110

• TibrvTimer, page 121
• TibrvQueue, page 133
• TibrvQueueGroup, page 151
See Also
Objects, page 4
Callback Methods and Event Handlers, page 6
Tibrv.getAutoDispatchQueueGroup() on page 20

110
| Chapter 5 Events and Queues
TibrvListener
Class
Purpose Listen for inbound messages.
Remarks A listener object continues listening for messages until the program destroys or
deletes it.
Destroying the queue or transport of a listener automatically destroys the listener
as well, but does not delete the COM listener object.

Life Cycle
TibrvListener.create Create a listener object to listen for inbound 112

messages.
TibrvListener.destroy Destroy the internal structure of a listener, canceling 114

interest in its inbound messages.
TibrvListener.isValid() Test the validity of a listener. 119
Callback Method
TibrvListener_onMsg Process inbound messages (listener events). 120
Properties
TibrvListener.getClosure() Extract the closure from a listener object. 115
TibrvListener.getQueue() Extract the queue from a listener object. 116
TibrvListener.getSubject() Extract the subject from a listener object. 117
TibrvListener.getTransport() Extract the transport from a listener object. 118
Activation and Dispatch

Inbound messages on the transport that match the subject trigger the event.
TibrvListener.create creates the internal structure of a listener object, and
activates event processing—that is, it begins listening for all inbound messages
with matching subjects. When a message arrives, Rendezvous software places the
listener object and message on its queue. Dispatch removes the listener object

TibrvListener 111
|
from the queue, and runs the callback method to process the message. (To stop
receiving inbound messages on the subject, destroy or delete the listener object;
this action cancels all messages already queued for the listener; see also
TibrvListener.destroy on page 114.)
Figure 4 illustrates that messages can continue to accumulate in the queue, even
while the callback method is processing.
Figure 4 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.

112
TibrvListener.create
Method
Declaration TibrvListener.create queue, transport, subject, closure
Purpose Create a listener object to listen for inbound messages.
Remarks For each inbound message, place this object on the event queue.
Starting a listener requires three steps:
1. Declare a variable for the listener.
Dim WithEvents myListener as TibrvListener
This declaration triggers VB to automatically define a private subroutine

callback stub named myListener_OnMsg. The program must complete this
method stub for each listener object.
2. Create the VB object, and assign it to that variable.
Set myListener = New TibrvListener
3. Create the internal implementation object to begin listening.

myListener.create myQueue, myTransport, mySubject, 0

queue TibrvQueue
For each inbound message, place the listener object on this

queue.
transport TibrvTransport
Listen for inbound messages on this transport.
subject String
Listen for inbound messages with subjects that match this

specification. Wildcard subjects are permitted. The empty
string and vbNullString are not legal subject names.
closure Object
Store this closure data in the listener object.

TibrvListener.create 113
|
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 TibrvListener.destroy on page 114


114
TibrvListener.destroy
Method
Declaration TibrvListener.destroy
Purpose Destroy the internal structure of a listener, canceling interest in its inbound
messages.
Remarks This method destroys only the internal structure of the listener object.
Rendezvous software automatically destroys a listener (using this method) when
program execution leaves the scope of the object, or sets the object to Nothing.
Destroying a listener object cancels interest in it. Upon return from
TibrvListener.destroy, the destroyed listener’s message events are no longer
dispatched. However, an active callback method of this listener continues to run
and return normally, even though the listener is invalid.
It is legal for a listener callback method to destroy its own listener object.
See Also TibrvListener.isValid() on page 119

TibrvListener.getClosure() 115
|
TibrvListener.getClosure()
Method
Declaration closure = TibrvListener.getClosure()
Purpose Extract the closure from a listener object.
closure Object
Return the closure data of the listener object.

116
TibrvListener.getQueue()
Method
Declaration set queue = TibrvListener.getQueue()
Purpose Extract the queue from a listener object.
queue TibrvQueue
Return the queue of the listener object.

TibrvListener.getSubject() 117
|
TibrvListener.getSubject()
Method
Declaration subject = TibrvListener.getSubject()
Purpose Extract the subject from a listener object.
subject String
Return the subject name of the listener object.

118
TibrvListener.getTransport()
Method
Declaration set transport = TibrvListener.getTransport()
Purpose Extract the transport from a listener object.
Return the transport of the listener object.

TibrvListener.isValid() 119
|
TibrvListener.isValid()
Method
Declaration isValid = TibrvListener.isValid()
Purpose Test the validity of a listener.
Remarks Notice that TibrvListener.destroy invalidates the listener immediately, even

though active callback methods may continue to run.
isValid Boolean
Return True if the listener is valid.

Return False if the listener has been destroyed.
See Also TibrvListener.destroy on page 114

120
TibrvListener_onMsg
Method
Declaration Private Sub myListener_onMsg (

ByVal listener As TIBRVCOMLib.ITibrvListener,
ByVal message As TIBRVCOMLib.ITibrvMsg)
Purpose Process inbound messages (listener events).
Remarks Implement this method to process inbound messages.

This method receives its parameters by value, so it cannot delete them.
To stop listening to the message subject, destroy the original listener object
associated with this callback method.
Declaring a variable of class TibrvListener with events triggers VB to
automatically define a COM event callback, and a private subroutine callback
stub named var_OnMsg. The program must complete this method for each listener
object.
listener TibrvListener
This parameter receives the listener object.
message TibrvMsg
This parameter receives the inbound message. To preserve this

message beyond exit from this callback method, the program
must set a persistent reference to it, and detach it.
CM Label The callback method for certified delivery messages can use the certified delivery
Information label property cmSender to discriminate these situations:
• If extracting the cmSender property yields the error TIBRVCOM_NOT_FOUND,
then the message uses the reliable protocol (that is, it was sent from an
ordinary transport).
• If the cmSender property is a valid sender name, then the message uses the
certified delivery protocol (that is, it is a labeled message, sent from a certified
delivery transport).
See Also TibrvMsg.detach on page 54

TibrvCmListener.create on page 227
TibrvMsg.getProperty() on page 72

TibrvTimer 121
|
TibrvTimer
Class
Purpose Timer event.
Remarks All timers are repeating timers. To simulate a once-only timer, code the callback
method to destroy the timer. To stop the timer, destroy or delete it.
Destroying the queue of a timer automatically destroys the timer as well.
However, the program must also delete the timer object to reclaim resources.

Life Cycle
TibrvTimer.create Start a timer. 124
TibrvTimer.destroy Destroy a timer event. 126
TibrvTimer.isValid() Test the validity of a timer. 130
Callback Method
TibrvTimer_onTimer Process timer events. 131
Properties
TibrvTimer.getClosure() Extract the closure from a timer 127

object.
TibrvTimer.getInterval() Extract the interval from a timer 128

object.
TibrvTimer.getQueue() Extract the queue from a timer object. 129
TibrvTimer.resetInterval Reset the interval of a timer object. 132
Activation and Dispatch

TibrvTimer.create creates the internal structure of a timer object, and activates
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

122
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 TibrvTimer.destroy
on page 126.)
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 5 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.
Figure 5 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.

TibrvTimer 123
|
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 VB, 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.

124
TibrvTimer.create
Method
Declaration TibrvTimer.create queue, interval, closure
Purpose Start a timer.
Remarks All timers are repeating timers. To simulate a once-only timer, code the callback
method to destroy the timer. To stop a timer, destroy or delete it.
Starting a timer requires three steps:
1. Declare a variable for the timer.
Dim WithEvents myTimer as TibrvTimer

callback stub named myTimer_OnTimer. The program must complete this
method for each timer object.
Set myTimer = New TibrvTimer
3. Create the internal implementation object to begin counting.

myTimer.create myQueue, myInterval, 0

queue TibrvQueue
At each time interval, place the timer object on this queue.
interval Double
The timer triggers its callback method at this repeating interval

(in seconds).
closure Object
Store this closure data in the timer object.
Timer Express the timer interval (in seconds) as a double (64-bit floating point number).
Granularity This representation allows microsecond granularity for intervals for over 100
years. The actual granularity of intervals depends on VB, hardware and operating
system constraints.

TibrvTimer.create 125
|
See Also TibrvTimer.destroy on page 126
TibrvTimer_onTimer on page 131

126
TibrvTimer.destroy
Method
Declaration TibrvTimer.destroy
Purpose Destroy a timer event.
Remarks This method destroys only the internal structure of the timer object. Rendezvous
software automatically destroys a timer (using this method) when program
execution leaves the scope of the object, or deletes the object.
Destroying a timer object cancels interest in it. Upon return from
TibrvTimer.destroy, the destroyed timer is no longer dispatched. However, an
active callback method of this timer continues to run and return normally, even
though the timer object is invalid.
It is legal for a timer callback method to destroy its own timer object.
See Also TibrvTimer.isValid() on page 130

TibrvTimer.getClosure() 127
|
TibrvTimer.getClosure()
Method
Declaration closure = TibrvTimer.getClosure()
Purpose Extract the closure from a timer object.
closure Object
Return the closure data of the timer object.

128
TibrvTimer.getInterval()
Method
Declaration interval = TibrvTimer.getInterval()
Purpose Extract the interval from a timer object.
interval Double
Return the interval of the timer object.

TibrvTimer.getQueue() 129
|
TibrvTimer.getQueue()
Method
Declaration set queue = TibrvTimer.getQueue()
Purpose Extract the queue from a timer object.
queue TibrvQueue
Return the queue of the timer object.

130
TibrvTimer.isValid()
Method
Declaration isValid = TibrvTimer.isValid()
Purpose Test the validity of a timer.
Remarks Notice that TibrvTimer.destroy invalidates the timer immediately, even though
active callback methods may continue to run.
isValid Boolean
Return True if the timer is valid.

Return False if the timer has been destroyed.
See Also TibrvTimer.destroy on page 126

TibrvTimer_onTimer 131
|
TibrvTimer_onTimer
Method
Declaration Private Sub myTimer_onTimer (

ByVal timer As TIBRVCOMLib.ITibrvTimer)
Purpose Process timer events.
Remarks Declaring a variable of class TibrvTimer with events triggers VB to automatically

define a COM event callback, and a private subroutine callback stub named
var_OnTimer. The program must complete this method for each timer object.
To stop the timer, destroy the original timer object associated with this callback
method.
timer TibrvTimer
This parameter receives the timer object.

132
TibrvTimer.resetInterval
Method
Declaration TibrvTimer.resetInterval newInterval
Purpose Reset the interval of a timer object.
Remarks The timer begins counting the new interval immediately.
newInterval Double
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 for over 100 years.
The actual granularity of intervals depends on VB, 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 a timer 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.)

TibrvQueue 133
|
TibrvQueue
Class
Purpose Event queue.
Remarks Each listener and timer object is associated with a TibrvQueue object; when the
event occurs, Rendezvous software places the object in its queue. Programs
dispatch queues to process events.
Default Queue Programs that need only one event queue can use the 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 cannot destroy the default queue. Programs cannot change the
parameters of the default queue.
For more information, see Tibrv.getDefaultQueue() on page 21.
Priority 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.
Automatic A special queue group, called the automatic dispatch queue group, detects the
Dispatch Queue presence of an event in any of its queues, and automatically dispatches the queues
Group (according to their priority) until no more events are waiting. To automatically
dispatch a queue, add it to that queue group. To retrieve that queue group, see
Tibrv.getAutoDispatchQueueGroup() on page 20.
Limit Policy The type library defines these constants, which specify the possible strategies for
resolving overflow of queue limit.
(Sheet 1 of 2)
Constant Description
TIBRVCOM_QUEUE_DEFAULT_POLICY Never discard events; use this policy when a
TIBRVCOM_QUEUE_DISCARD_NONE queue has no limit on then number of events it
can contain.
TIBRVCOM_QUEUE_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).

134
(Sheet 2 of 2)
TIBRVCOM_QUEUE_DISCARD_LAST Discard the last event in the queue (that is, the
youngest event in the queue).
TIBRVCOM_QUEUE_DISCARD_NEW Discard the new event (which would

otherwise cause the queue to overflow its
maximum events limit).
(Sheet 1 of 2)

Life Cycle
TibrvQueue.create Create an event queue. 136
TibrvQueue.destroy Destroy an event queue. 137
TibrvQueue.isValid() Test the validity of a queue. 145
Dispatch
TibrvQueue.dispatch Dispatch an event; if no event is ready, block. 138
TibrvQueue.poll Dispatch an event, if possible. 146
TibrvQueue.timedDispatch Dispatch an event, but if no event is ready to 150

dispatch, limit the time that this call blocks while
waiting for an event.
Properties
TibrvQueue.getCount() Extract the number of events in a queue. 139
TibrvQueue.getDiscardAmount() Extract the discard amount of a queue. 140
TibrvQueue.getLimitPolicy() Extract the limit policy of a queue. 141
TibrvQueue.getMaxEvents() Extract the maximum event limit of a queue. 142
TibrvQueue.getName() Extract the name of a queue. 143
TibrvQueue.getPriority() Extract the priority of a queue. 144

TibrvQueue 135
|
(Sheet 2 of 2)

TibrvQueue.setName Set the name of a queue. 148
TibrvQueue.setLimitPolicy Set the limit properties of a queue. 147
TibrvQueue.setPriority Set the priority of a queue. 149
See Also TibrvQueueGroup on page 151

136
TibrvQueue.create
Method
Declaration TibrvQueue.create
Purpose Create an event queue.
Remarks Upon creation, new queues set these default values.
Property Default Value Set Method

limitPolicy TIBRVCOM_QUEUE_DISCARD_NONE TibrvQueue.setLimitPolicy on page 147
maxEvents zero (unlimited)
discardAmount zero
name tibrvQueue TibrvQueue.setName on page 148
priority 1 TibrvQueue.setPriority on page 149


TibrvQueue.destroy 137
|
TibrvQueue.destroy
Method
Declaration TibrvQueue.destroy
Purpose Destroy an event queue.
Remarks This method destroys the internal mechanism of the queue, leaving an unusable
object. Rendezvous software automatically destroys a queue (using this method)
when program execution leaves the scope of the object, or the program deletes the
object.
When a queue is destroyed, events that remain in the queue are discarded.
Dispatch calls report an error. Automatic dispatch ignores the destroyed queue.
It is safe to call TibrvQueue.destroy more than once on the same object. Repeat
calls return without error.
Programs cannot destroy the default queue.

138
TibrvQueue.dispatch
Method
Declaration TibrvQueue.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.
The Rendezvous component does not trigger dispatch while a program callback
method is already running. When a program attempts to explicitly dispatch (in
violation of this protective rule), the dispatch method reports the error
TIBRVCOM_EVENT_CALLBACK_ACTIVE.
Blocking effectively freezes the GUI operation of a program. Use with caution.
We recommend automatic dispatch instead.

TibrvQueue.poll on page 146
TibrvQueue.timedDispatch on page 150

TibrvQueue.getCount() 139
|
TibrvQueue.getCount()
Method
Declaration numEvents = tibrvQueue.getCount()
Purpose Extract the number of events in a queue.
numEvents Long
Return the number of events in the queue.

140
TibrvQueue.getDiscardAmount()
Method
Declaration discardAmount = TibrvQueue.getDiscardAmount()
Purpose Extract the discard amount of a queue.
Remarks When the queue exceeds its maximum event limit, discard a block of events. This
property specifies the number of events to discard.
discardAmount Long
Return the discard amount of the queue.
See Also TibrvQueue.setLimitPolicy on page 147

TibrvQueue.getLimitPolicy() 141
|
TibrvQueue.getLimitPolicy()
Method
Declaration limitPolicy = TibrvQueue.getLimitPolicy()
Purpose Extract the limit policy of a queue.
Remarks 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 133.
limitPolicy Long
Return the limit policy of the queue.

142
TibrvQueue.getMaxEvents()
Method
Declaration maxEvents = TibrvQueue.getMaxEvents()
Purpose Extract the maximum event limit of a queue.
Remarks Programs can limit the number events that a queue can hold—either to curb
queue growth, or implement a specialized dispatch semantics.
Zero specifies an unlimited number of events.
maxEvents Long
Return the maximum event limit of the queue.

TibrvQueue.getName() 143
|
TibrvQueue.getName()
Method
Declaration queueName = TibrvQueue.getName()
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.
queueName String
Return the name of the queue.
See Also TibrvQueue.setName on page 148

144
TibrvQueue.getPriority()
Method
Declaration priority = Tibrvqueue.getPriority()
Purpose Extract the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence
priority Long
Return the priority of the queue.
See Also TibrvQueue.setPriority on page 149

TibrvQueue.isValid() 145
|
TibrvQueue.isValid()
Method
Declaration isValid = TibrvQueue.isValid()
Purpose Test the validity of a queue.
isValid Boolean
Return True if the queue is valid.

Return False if the queue has been destroyed.
See Also TibrvQueue.destroy on page 137

146
TibrvQueue.poll
Method
Declaration TibrvQueue.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,
reporting the error TIBRVCOM_TIMEOUT.
This call is equivalent to timedDispatch(0.0).

TibrvQueue.dispatch on page 138
TibrvQueue.timedDispatch on page 150

TibrvQueue.setLimitPolicy 147
|
TibrvQueue.setLimitPolicy
Method
Declaration TibrvQueue.setLimitPolicy limitPolicy, maxEvents, 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.
limitPolicy Long
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 Limit
Policy on page 133.
When maxEvents is zero (unlimited), the policy must be
TIBRVCOM_QUEUE_DISCARD_NONE.
maxEvents Long
Programs can limit the number 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
discardAmount Long
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
See Also TibrvQueue.getDiscardAmount() on page 140

TibrvQueue.getLimitPolicy() on page 141
TibrvQueue.getMaxEvents() on page 142

148
TibrvQueue.setName
Method
Declaration TibrvQueue.setName 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.
queueName String
Replace the name of the queue with this new name.

It is illegal to supply vbNullString as the new queue
name. However, the empty string is a legal queue name.
See Also TibrvQueue.getName() on page 143

TibrvQueue.setPriority 149
|
TibrvQueue.setPriority
Method
Declaration TibrvQueue.setPriority priority
Purpose Set the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence
Changing the priority of a queue affects its position in all the queue groups that
contain it.
priority Long
Replace the priority of the queue with this new value.

The priority must be a non-negative integer. Priority zero
signifies the last queue to dispatch.
See Also TibrvQueue.getPriority() on page 144

150
TibrvQueue.timedDispatch
Method
Declaration TibrvQueue.timedDispatch 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,
reporting the error TIBRVCOM_TIMEOUT.
timeout Double
Maximum time (in seconds) that this call can block while
waiting for an event to arrive in the queue.
Zero indicates no blocking (immediate timeout).
-1 indicates no timeout.
Constants The type library defines these constants for use with timed dispatch methods.
Constant Value
TIBRVCOM_WAIT_FOREVER -1
TIBRVCOM_NO_WAIT 0

TibrvQueue.dispatch on page 138
TibrvQueue.poll on page 146

TibrvQueueGroup 151
|
TibrvQueueGroup
Class
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.
Priority Each queue has a single priority value, which controls its dispatch precedence
Automatic A special queue group, called the automatic dispatch queue group, detects the
Dispatch Queue presence of an event in any of its queues, and automatically dispatches the queues
Group (according to their priority) until no more events are waiting. To automatically
dispatch a queue, add it to that queue group. To stop automatic dispatch, remove
all queues from that group. To retrieve that queue group, see
Tibrv.getAutoDispatchQueueGroup() on page 20.
(Sheet 1 of 2)

Life Cycle
TibrvQueueGroup.create Create an event queue group. 154
TibrvQueueGroup.destroy Destroy an event queue group. 155
TibrvQueueGroup.isValid() Test the validity of a queue group. 157
Queues
TibrvQueueGroup.add Add an event queue to a queue group. 153
TibrvQueueGroup.remove Remove an event queue from a queue group. 159
Dispatch
TibrvQueueGroup.dispatch Dispatch an event from a queue group; if no event 156

is ready, block.
TibrvQueueGroup.poll Dispatch an event, but if no event is ready to 158

dispatch, return immediately (without blocking).

152
(Sheet 2 of 2)

TibrvQueueGroup.timedDispatch Dispatch an event, but if no event is ready to 160
dispatch, limit the time that this call blocks while
waiting for an event.

TibrvQueue on page 133

TibrvQueueGroup.add 153
|
TibrvQueueGroup.add
Method
Declaration TibrvQueueGroup.add 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.
If either the queue or the group is invalid, this method reports an error.
queue TibrvQueue
Add this event to the queue group.

154
TibrvQueueGroup.create
Method
Declaration TibrvQueueGroup.create
Purpose Create an event queue group.
Remarks The new queue group is empty.

The queue group remains valid until the program explicitly destroys it.
See Also TibrvQueueGroup.add on page 153

TibrvQueueGroup.destroy on page 155

TibrvQueueGroup.destroy 155
|
TibrvQueueGroup.destroy
Method
Declaration TibrvQueueGroup.destroy
Purpose Destroy an event queue group.
Remarks This method destroys the internal mechanism of the group, leaving an unusable
object. Rendezvous software automatically destroys a queue group (using this
method) when program execution leaves the scope of the object, or sets the object
to Nothing.
The individual queues in the group continue to exist, even though the group has
been destroyed.
Programs cannot destroy the automatic dispatch queue group. Attempts to
destroy it return without error.
See Also TibrvQueueGroup.create on page 154

156
TibrvQueueGroup.dispatch
Method
Declaration TibrvQueueGroup.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 TibrvQueueGroup.timedDispatch on page 160

TibrvQueueGroup.poll on page 158

TibrvQueueGroup.isValid() 157
|
TibrvQueueGroup.isValid()
Method
Declaration isValid = TibrvQueueGroup.isValid()
Purpose Test the validity of a queue group.
isValid Boolean
Return True if the queue group is valid.

Return False if the queue group has been destroyed.
See Also TibrvQueueGroup.destroy on page 155

158
TibrvQueueGroup.poll
Method
Declaration TibrvQueueGroup.poll
Purpose Dispatch an event, but if no event is ready to dispatch, return immediately

(without blocking).
and then returns. If all the queues are empty, then this call returns immediately,
then this call returns immediately, reporting the error TIBRVCOM_TIMEOUT.
When searching the group for a non-empty queue, this call searches according the
to 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.
This call is equivalent to timedDispatch(0.0).
See Also TibrvQueueGroup.dispatch on page 156

TibrvQueueGroup.timedDispatch on page 160

TibrvQueueGroup.remove 159
|
TibrvQueueGroup.remove
Method
Declaration TibrvQueueGroup.remove queue
Purpose Remove an event queue from a queue group.
Remarks If the queue is not in the group, or if the group is invalid, this call reports the error
TIBRVCOM_INVALID_QUEUE.
To stop automatic dispatch of a queue, remove it from the automatic dispatch

queue group.
queue TibrvQueue
Remove this queue from a queue group.

160
TibrvQueueGroup.timedDispatch
Method
Declaration TibrvQueueGroup.timedDispatch 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.
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, reporting the error
TIBRVCOM_TIMEOUT.
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.
timeout Double
waiting for an event to arrive in the queue group.
Zero indicates no blocking (immediate timeout).
-1 indicates no timeout.
Constants The type library defines these constants for use with timed dispatch methods.
Constant Value
TIBRVCOM_WAIT_FOREVER -1
TIBRVCOM_NO_WAIT 0

TibrvQueueGroup.timedDispatch 161
|
See Also TibrvQueueGroup.dispatch on page 156
TibrvQueueGroup.poll on page 158

162

| 163
Chapter 6 Transports
Transports manage network connections and send outbound messages. Listeners

(and other objects) us transports for communications.
This chapter presents the various transport classes and their methods.
Topics
• TibrvTransport, page 164
See Also
Virtual Circuits on page 183
TibrvCmTransport on page 238
Distributed Queue Transport on page 276

164
| Chapter 6 Transports
TibrvTransport
Class
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. Listeners (and other objects) use
transports for communications.
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,
invalidates any listeners using that transport.
(Sheet 1 of 2)

Life Cycle
TibrvTransport.create Create a network transport. 166
TibrvTransport.destroy Destroy a transport. 170
TibrvTransport.isValid() Test the validity of a transport. 175
Inbox Names
TibrvTransport.createInbox() Create a unique inbox subject name. 169
Send Messages
TibrvTransport.send Send a message. 176
TibrvTransport.sendReply Send a reply message. 177
TibrvTransport.sendRequest() Send a request message and wait for a 178

reply.
Accessors
TibrvTransport.getDaemon() Return the TCP socket where this 171

transport connects to the Rendezvous
daemon.

TibrvTransport 165
|
(Sheet 2 of 2)

TibrvTransport.getDescription() Extract the program description 172
parameter from a transport.
TibrvTransport.getNetwork() Return the network interface that this 173

transport uses for communication.
TibrvTransport.getService() Return the effective service that this 174

transport uses for communication.
TibrvTransport.setDescription Set the program description parameter of 181

a transport.
Virtual Circuits
TibrvTransport.createAcceptVc() Create a virtual circuit accept object. 186
TibrvTransport.createConnectVc() Create a virtual circuit connect object. 187
TibrvTransport.getVcConnectSubject() Return the connect subject of an accept 189

terminal.
TibrvTransport.waitForVcConnection Test the connection status of a virtual 190

circuit.
See Also Chapter 7, Virtual Circuits, on page 183

Transport on page 99 in TIBCO Rendezvous Concepts

166
TibrvTransport.create
Method
Declaration TibrvTransport.create service, network, daemon
TibrvTransport.CreateLicensed service, network, daemon,

licenseTicket
Purpose Create a network transport.
Connecting to Rendezvous daemon processes do the work of moving messages across a

the Rendezvous network. Every network transport must connect to a Rendezvous daemon. (The
Daemon intra-process transport does not connect to a 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 this method cannot connect to the Rendezvous daemon, it reports the error
TIBRVCOM_DAEMON_NOT_CONNECTED.
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.)
(Sheet 1 of 2)
service String
The Rendezvous daemon divides the network into logical partitions. Each
network transport 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.
The empty string and vbNullString both specify the default rendezvous
service.

TibrvTransport.create 167
|
(Sheet 2 of 2)
network String
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.
The empty string and vbNullString both specify the primary network interface
for the host computer.
daemon String
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.
The empty string and vbNullString both specify the default—find the local
daemon on TCP socket 7500. (These defaults are not valid when the local
daemon is a secure daemon.)
licenseTicket String
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 168.

168
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 181.
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 TibrvTransport.getDaemon() on page 171

TibrvTransport.getNetwork() on page 173
TibrvTransport.getService() on page 174

TibrvTransport.createInbox() 169
|
TibrvTransport.createInbox()
Method
Declaration inboxSubject = TibrvTransport.createInbox()
Purpose Create a unique inbox subject name.
inboxSubject String
Return the new 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 throughout 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 method is the only legal way for programs to create inbox subject names.
See Also TibrvMsg.setReplySubject on page 86

170
TibrvTransport.destroy
Method
Declaration TibrvTransport.destroy
Purpose Destroy a transport.
Remarks This method destroys the internal mechanism of the transport, leaving an
unusable object. Rendezvous software automatically destroys a transport (using
this method) when program execution leaves the scope of the object, or sets the
object to Nothing.
Destroying a transport achieves these effects:
• The transport flushes all outbound data to the Rendezvous daemon.
This effect is especially important.
• The transport invalidates all its listeners.
• Subsequent calls to other methods that use the destroyed transport report an
error (usually TIBRVCOM_OBJECT_NOT_INITIALIZED).
Storage for the transport object is freed when all listeners that use it have been
deleted.
See Also TibrvTransport.isValid() on page 175

TibrvTransport.getDaemon() 171
|
TibrvTransport.getDaemon()
Method
Declaration daemon = TibrvTransport.getDaemon()
Purpose Return the TCP socket where this transport connects to the Rendezvous daemon.
Remarks It is an error to call this method on the intra-process transport.
daemon String
Return the daemon parameter of the network transport.

172
TibrvTransport.getDescription()
Method
Declaration description = TibrvTransport.getDescription()
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.
It is an error to call this method on the intra-process transport.
description String
Return the description of the transport.

TibrvTransport.setDescription on page 181

TibrvTransport.getNetwork() 173
|
TibrvTransport.getNetwork()
Method
Declaration network = TibrvTransport.getNetwork()
Purpose Return the network interface that this transport uses for communication.
network String
Return the network parameter of the network transport.

174
TibrvTransport.getService()
Method
Declaration service = TibrvTransport.getService()
Purpose Return the effective service that this transport uses for communication.
service String
Return the service parameter of the network transport.

TibrvTransport.isValid() 175
|
TibrvTransport.isValid()
Method
Declaration isValid = TibrvTransport.isValid()
Purpose Test the validity of a transport.
isValid Boolean
Return True if the transport is valid.

Return False if the transport has been destroyed.
See Also TibrvTransport.destroy on page 170

176
TibrvTransport.send
Method
Declaration TibrvTransport.send message
Purpose Send a message.
Remarks The message must have a valid destination subject; see TibrvMsg.setSendSubject
on page 87.
message TibrvMsg
Send this message.
See Also TibrvMsg.setSendSubject on page 87

TibrvTransport.sendReply 177
|
TibrvTransport.sendReply
Method
Declaration TibrvTransport.sendReply replyMsg, requestMsg
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.
replyMessage TibrvMsg
Send this outbound reply message.
requestMessage TibrvMsg
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 73

TibrvTransport.sendRequest() on page 178

178
TibrvTransport.sendRequest()
Method
Declaration set replyMessage = TibrvTransport.sendRequest(message, timeout)
Purpose Send a request message and wait for a reply.
This call blocks all other activity in the program, including event dispatch and
GUI operation. Use with caution.
message TibrvMsg
Send this message.
timeout Double
waiting for a reply.
-1 indicates no timeout (wait without limit for a reply).
replyMessage TibrvMsg
Return the reply message when it arrives.
Remarks 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 87.
The program owns the reply message object, and must delete it to reclaim its
storage.
Operation This method operates in several synchronous steps:

1. Create an inbox name, and a listener object that listens to it. Overwrite any
existing reply subject of message with the inbox name.
2. Send the outbound message.
3. Block until the listener receives a reply; if the time limit expires before a reply
arrives, report the error TIBRVCOM_TIMEOUT. (The reply circumvents the event
queue mechanism, so it is not necessary to explicitly call dispatch methods in
the program.)

TibrvTransport.sendRequest() 179
|
4. Return the reply as the value of this method.

180
TibrvTransport.setBatchMode
Method
Declaration TibrvTransport.setBatchMode 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
mode Use this value as the new batch mode.
Constants The type library defines these constants for use with this method.
TIBRVCOM_TRANSPORT_DEFAULT_BATCH Default batch behavior. The transport transmits
outbound messages to rvd as soon as possible.
This value is the initial default for all transports.
TIBRVCOM_TRANSPORT_TIMER_BATCH Timer batch behavior. The transport accumulates

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

Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

TibrvTransport.setDescription 181
|
TibrvTransport.setDescription
Method
Declaration TibrvTransport.setDescription 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.
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.
description String
Use this string as the new program description.

TibrvTransport.getDescription() on page 172

182

| 183
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
• Virtual Circuit Transport, page 184

184
| Chapter 7 Virtual Circuits
Virtual Circuit Transport
A virtual circuit transport object represents a terminal in a potential circuit.

Virtual circuit terminals have the same datatype as ordinary transport objects, and
can fill the same roles as ordinary transports. Programs can use them to create
inbox names, send messages, create listeners and other events.
Two create 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.
Both create methods are methods of ordinary transport objects. Calling one of
these methods on an ordinary transport creates a new object (the terminal), which
employs the ordinary transport for network communications. Programs may use
the ordinary transport for other purposes.

TibrvTransport.createAcceptVc() Create a virtual circuit accept object. 186
TibrvTransport.createConnectVc() Create a virtual circuit connect object. 187
TibrvTransport.getVcConnectSubject() Return the connect subject of an accept 189

terminal.
TibrvTransport.waitForVcConnection Test the connection status of a virtual 190

circuit.
Broken Connection
The following conditions can close a virtual circuit connection:
• Contact is broken between the object and its terminal.
• The virtual circuit loses data in either direction (see DATALOSS on page 272
in TIBCO Rendezvous Concepts).
• The partner program destroys its terminal object (or that terminal becomes
invalid).

Virtual Circuit Transport 185
|
• The program destroys the object.

• The program destroys the object’s ordinary transport.
Destroying VC Transports
Programs must explicitly destroy each virtual circuit transport object. Destroying
a transport object precludes subsequent communications on that transport, and
frees its storage. 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.
Direct Communication
Because virtual circuits rely on point-to-point messages between the two
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 Notes

Legal Methods TibrvTransport.createInbox()
TibrvTransport.destroy
TibrvTransport.send
Disabled TibrvTransport.createAcceptVc() After calling either of the two create

Methods TibrvTransport.createConnectVc() methods on an ordinary transport (to
TibrvTransport.getDaemon() create the terminal) these methods are
TibrvTransport.getDescription() disabled in the terminal.
TibrvTransport.getNetwork()
TibrvTransport.getService()
TibrvTransport.setBatchMode
TibrvTransport.setDescription

Virtual Circuits on page 119 in TIBCO Rendezvous Concepts

186
TibrvTransport.createAcceptVc()
Method
Declaration set vcTransport = TibrvTransport.createAcceptVc()
Purpose Create a virtual circuit accept object.
Remarks Note that programs call this method on an ordinary transport. The method creates
and returns a new accept transport object that employs the ordinary transport.
Programs may use the ordinary transport for other purposes.
It is illegal to call this method on a virtual circuit terminal transport object (that is,
you cannot nest a virtual circuit within another virtual circuit).
After this method returns, programs must extract the connect subject; see
TibrvTransport.getVcConnectSubject() on page 189.
vcTransport TibrvTransport
This method creates and returns an accept transport object that employs the
ordinary transport object for communications.
Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The terminal transport presents the VC.CONNECTED advisory.
• TibrvTransport.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 TibrvTransport.waitForVcConnection with TIBRVCOM_NO_WAIT as the
timeout parameter.
For an explanation, see Testing the New Connection on page 123 in TIBCO
Rendezvous Concepts.
See Also TibrvTransport.createConnectVc() on page 187

TibrvTransport.getVcConnectSubject() on page 189
TibrvTransport.waitForVcConnection on page 190
VC.CONNECTED on page 288 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 289 in TIBCO Rendezvous Concepts

TibrvTransport.createConnectVc() 187
|
TibrvTransport.createConnectVc()
Method
Declaration set vcTransport = TibrvTransport.createConnectVc(connectSubject)
Purpose Create a virtual circuit connect object.
Remarks Note that programs call this method on an ordinary transport. The method creates
and returns a new connect transport object that employs the ordinary transport.
Programs may use the ordinary transport for other purposes.
It is illegal to call this method on a virtual circuit terminal transport object (that is,
you cannot nest a virtual circuit within another virtual circuit).
vcTransport TibrvTransport
This method creates and returns a connect transport object that employs the
ordinary transport object for communications.
connectSubject String
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 TibrvTransport.createAcceptVc() creates this subject.
Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The transport presents the VC.CONNECTED advisory.
• TibrvTransport.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 TibrvTransport.waitForVcConnection with TIBRVCOM_NO_WAIT as the
timeout parameter.
For an explanation, see Testing the New Connection on page 123 in TIBCO
See Also TibrvTransport.createAcceptVc() on page 186

TibrvTransport.getVcConnectSubject() on page 189
TibrvTransport.waitForVcConnection on page 190

188


TibrvTransport.getVcConnectSubject() 189
|
TibrvTransport.getVcConnectSubject()
Method
Declaration connectSubject = TibrvTransport.getVcConnectSubject()
Purpose Return the connect subject of an accept terminal.
Remarks After creating an accept terminal, the program must use this method to extract its
connect subject, and send it in 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
TibrvTransport.createConnectVc().
It is an error to call this method on any object other than a virtual circuit accept
terminal.
connectSubject String
The method returns the connect subject of a virtual circuit accept transport.
After this call returns, the program must send a message to another program,
inviting it to establish a virtual circuit. Furtherer, 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 TibrvTransport.createConnectVc().

TibrvTransport.createConnectVc() on page 187

190
TibrvTransport.waitForVcConnection
Method
Declaration TibrvTransport.waitForVcConnection 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.
With a non-zero argument, this call blocks all other activity in the program,
including automatic dispatch of events and GUI operation. Use with caution.
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.
timeout Double
This parameter determines the behavior of the call:
• For a quick test of current connection status, supply the constant
TIBRVCOM_NO_WAIT. 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 the constant
TIBRVCOM_WAIT_FOREVER. The call returns when the connection is
complete. If the connection was already complete and is now broken, the
call returns immediately.

TibrvTransport.waitForVcConnection 191
|
Errors If the connection is complete (ready to use), this call returns without error.
Otherwise it produces an error object; the status code in that error object gives
more detail about why the connection is not usable.
Status Description
TIBRVCOM_TIMEOUT The connection is not yet complete, but the non-negative time
limit for waiting has expired.
TIBRVCOM_VC_NOT_CONNECTED The connection was formerly complete, but is now irreparably

broken.

TibrvTransport.createConnectVc() on page 187
Testing the New Connection on page 123 in TIBCO Rendezvous Concepts

192

| 193
Chapter 8 Fault Tolerance
Rendezvous fault tolerance software coordinates a group of redundant program

processes into a fault-tolerant distributed system. 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 194

• TibrvFtMember, page 195
• TibrvFtMonitor, page 211

194
| Chapter 8 Fault Tolerance
Fault Tolerance Road Map
For a complete discussion of concepts and operating principles, see Fault

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

TibrvFtMember 195
|
TibrvFtMember
Class
Purpose Represent membership in a fault tolerance group.
Remarks Upon creating the internal structure of this object, the process joins a fault
tolerance group.
By destroying or deleting a member object, the process withdraws its
membership in the fault tolerance group.

Life Cycle
TibrvFtMember.create Create a member of a fault tolerance group. 196
TibrvFtMember.destroy Destroy a member of a fault tolerance group. 200
TibrvFtMember.isValid() Test validity of a fault tolerance member object. 206
Callback Method
TibrvFtMember_onFtAction Process fault tolerance events for a group member. 207
Accessors
TibrvFtMember.getClosure() Extract the closure of a fault tolerance member. 201
TibrvFtMember.getGroupName() Extract the group name of a fault tolerance member. 202
TibrvFtMember.getQueue() Extract the event queue of a fault tolerance member. 203
TibrvFtMember.getTransport() Extract the transport of a fault tolerance member. 204
TibrvFtMember.getWeight() Extract the weight of a fault tolerance member. 205
TibrvFtMember.setWeight Change the weight of a fault tolerance member 210

within its group.

196
TibrvFtMember.create
Method
Declaration TibrvFtMember.create queue, transport, groupName, weight,

activeGoal,
heartbeatInterval, preparationInterval, activationInterval,
closure
Purpose Create a member of a fault tolerance group.
Remarks Upon creating a member object, the process becomes a member of the group.
A process may hold simultaneous memberships in several distinct fault tolerance
groups. For examples, see Multiple Groups on page 219 in TIBCO Rendezvous
Concepts.
Avoid joining the same group twice. It is illegal for a process to maintain more
than one membership in any one fault tolerance group. The method does not
guard against this illegal situation, and results are unpredictable.
Joining a fault tolerance group requires three steps:
1. Declare a variable for the member.
Dim WithEvents myFt as TibrvFtMember

callback stub named myFt_OnFtAction. The program must complete this
method for each member object.
set myFt = New TibrvFtMember
3. Create the internal implementation object to join the group.

myFt.create ...

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

TibrvFtMember.create 197
|
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 219 in TIBCO Rendezvous
Concepts.
(Sheet 1 of 2)
queue TibrvQueue
Place fault tolerance events for this member on this event queue.
Use this transport for fault tolerance internal protocol messages (such as
heartbeat messages).
groupName String
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
weight Long
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 206 in TIBCO
activeGoal Long
Rendezvous fault tolerance software sends callback instructions to
maintain this number of active members.
Acceptable values range from 1 to 65535.

198
(Sheet 2 of 2)
heartbeatInterval Double
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 237 in TIBCO Rendezvous Concepts.
preparationInterval Double
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 (TIBRVCOM_FT_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
TIBRVCOM_FT_PREPARE_TO_ACTIVATE hint when this value is zero. To
determine the correct value, see Step 4: Choose the Intervals on page 237
in TIBCO Rendezvous Concepts.
activationInterval Double
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 (TIBRVCOM_FT_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 (TIBRVCOM_FT_ACTIVATE) to the new
member.
Then interval must be positive. To determine the correct value, see Step
4: Choose the Intervals on page 237 in TIBCO Rendezvous Concepts.
closure Object
Store this closure data in the member object.
See Also TibrvFtMember on page 195.

TibrvFtMember.create 199
|
TibrvFtMember_onFtAction on page 207.

TibrvFtMember.destroy on page 200.
Step 1: Choose a Group Name, page 230 in TIBCO Rendezvous Concepts
Step 2: Choose the Active Goal, page 232 in TIBCO Rendezvous Concepts
Step 4: Choose the Intervals, page 237 in TIBCO Rendezvous Concepts
Step 5: Program Start Sequence, page 241 in TIBCO Rendezvous Concepts

200
TibrvFtMember.destroy
Method
Declaration TibrvFtMember.destroy
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.
This method has two effects:
• If this member is active, stop sending the heartbeat signal.
• Reclaim the program storage associated with this member.
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.
This method destroys only the internal structure of the member object.
Rendezvous software automatically destroys a member (using this method) when
See Also TibrvFtMember.create on page 196

TibrvFtMember.isValid() on page 206

TibrvFtMember.getClosure() 201
|
TibrvFtMember.getClosure()
Method
Declaration closure = TibrvFtMember.getClosure()
Purpose Extract the closure of a fault tolerance member.
closure Object
Return the closure of the fault tolerance object.

202
TibrvFtMember.getGroupName()
Method
Declaration groupName = TibrvFtMember.getGroupName()
Purpose Extract the group name of a fault tolerance member.
groupName String
Return the name of the fault tolerance group.

TibrvFtMember.getQueue() 203
|
TibrvFtMember.getQueue()
Method
Declaration set queue = TibrvFtMember.getQueue()
Purpose Extract the event queue of a fault tolerance member.
queue TibrvQueue
Return the event queue of the fault tolerance object.

TibrvFtMember.create on page 196

204
TibrvFtMember.getTransport()
Method
Declaration set transport = TibrvFtMember.getTransport()
Purpose Extract the transport of a fault tolerance member.
Return the transport of the fault tolerance object.

TibrvFtMember.create on page 196

TibrvFtMember.getWeight() 205
|
TibrvFtMember.getWeight()
Method
Declaration weight = TibrvFtMember.getWeight()
Purpose Extract the weight of a fault tolerance member.
weight Long
Return the weight of the fault tolerance member.

206
TibrvFtMember.isValid()
Method
Declaration isValid = TibrvFtMember.isValid()
Purpose Test validity of a fault tolerance member object.
Remarks Returns True if the member is valid; False if the member has been destroyed or is
otherwise invalid.
isValid Boolean
Return the validity of the fault tolerance object.
See Also TibrvFtMember.destroy on page 200

TibrvFtMember_onFtAction 207
|
TibrvFtMember_onFtAction
Method
Declaration Private Sub myFtMember_onFtAction(

ByVal ftMember As TIBRVCOMLib.ITibrvFtMember,
ByVal groupName As String,
ByVal action As Long)
Purpose Process fault tolerance events for a group member.
Remarks Each member program of a fault tolerance group must implement this method.
Declaring a variable of class TibrvFtMember with events triggers VB to
stub named var_OnFtAction. The program must complete this method for each
member object.

To withdraw from a fault tolerance group, destroy or delete the original member
object associated with this callback method.
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 TIBRVCOM_FT_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 TIBRVCOM_FT_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 TIBRVCOM_FT_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
TIBRVCOM_FT_ACTIVATE token, it will be ready to activate without delay.

208
For additional information see Fault Tolerance Callback Actions on page 216 in
TIBCO Rendezvous Concepts.
ftMember TibrvFtMember
This parameter receives the member object.
groupName String
This parameter receives a string denoting the name of the fault

tolerance group.
action Long
This parameter receives a token that instructs the callback

method to activate, deactivate or prepare to activate. See
Action Tokens on page 208.
Action Tokens The type library defines constants to represent the fault tolerance actions. Each
token 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 216 in TIBCO Rendezvous
Concepts).
(Sheet 1 of 2)
Field Description
TIBRVCOM_FT_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.
TIBRVCOM_FT_ACTIVATE Activate immediately.

the callback method to instruct the program to activate.

TibrvFtMember_onFtAction 209
|
(Sheet 2 of 2)
Field Description
TIBRVCOM_FT_DEACTIVATE Deactivate immediately.
the callback method to instruct the program to deactivate.
See Also TibrvFtMember.create on page 196.

210
TibrvFtMember.setWeight
Method
Declaration TibrvFtMember.setWeight 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.)
weight Long
The new weight value. See weight on page 197.
See Also Adjusting Member Weights on page 227 in TIBCO Rendezvous Concepts.

TibrvFtMonitor 211
|
TibrvFtMonitor
Class
Purpose Monitor a fault tolerance group.
Remarks Upon creating this object, the program 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.
Destroying the queue or transport of a monitor automatically destroys the
monitor as well.
(Sheet 1 of 2)

Life Cycle
TibrvFtMonitor.create Monitor a fault tolerance group. 213
TibrvFtMonitor.destroy Stop monitoring a fault tolerance group, and free 215

associated resources.
TibrvFtMonitor.isValid() Test validity of a fault tolerance monitor object. 220
Callback Method
TibrvFtMonitor_onFtMonitor Process fault tolerance events for a monitor. 221
Accessors
TibrvFtMonitor.getClosure() Extract the closure of a fault tolerance monitor. 216
TibrvFtMonitor.getGroupName() Extract the group name of a fault tolerance monitor. 217
TibrvFtMonitor.getQueue() Extract the event queue of a fault tolerance monitor. 218

212
(Sheet 2 of 2)

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

TibrvFtMonitor.create 213
|
TibrvFtMonitor.create
Method
Declaration TibrvFtMonitor.create queue, transport, groupName, lostInterval,

closure
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 method call.
Monitoring a fault tolerance group requires three steps:
1. Declare a variable for the monitor.
Dim WithEvents myMon as TibrvFtMonitor

callback stub named myMon_OnFtMonitor. The program must complete this
method for each monitor object.
set myMon = New TibrvFtMonitor
3. Create the internal implementation object to begin monitoring.

myMon.create ...

(Sheet 1 of 2)
queue TibrvQueue
Place events for this monitor on this event queue.
Listen on this transport for fault tolerance internal protocol

messages (such as heartbeat messages).

214
(Sheet 2 of 2)
groupName String
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
See also, Group Name on page 214.
lostInterval Double
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 237 in TIBCO
See also, Lost Interval on page 214.
closure Object
Store this closure data in the monitor object.
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 219 in TIBCO Rendezvous
Concepts.
See Also TibrvFtMonitor_onFtMonitor on page 221.

TibrvFtMonitor.destroy on page 215.

TibrvFtMonitor.destroy 215
|
TibrvFtMonitor.destroy
Method
Declaration TibrvFtMonitor.destroy
Purpose Stop monitoring a fault tolerance group, and free associated resources.
Remarks This method destroys only the internal structure of the monitor object.
Rendezvous software automatically destroys a monitor (using this method) when
See Also TibrvFtMonitor.create on page 213

216
TibrvFtMonitor.getClosure()
Method
Declaration closure = TibrvFtMonitor.getClosure()
Purpose Extract the closure of a fault tolerance monitor.
closure Object
Return the closure of the fault tolerance monitor object.

TibrvFtMonitor.getGroupName() 217
|
TibrvFtMonitor.getGroupName()
Method
Declaration groupName = TibrvFtMonitor.getGroupName()
Purpose Extract the group name of a fault tolerance monitor.
groupName String
Return the name of the fault tolerance group.

218
TibrvFtMonitor.getQueue()
Method
Declaration set queue = TibrvFtMonitor.getQueue()
Purpose Extract the event queue of a fault tolerance monitor.
queue TibrvQueue
Return the queue of the fault tolerance monitor object.

TibrvFtMonitor.create on page 213

TibrvFtMonitor.getTransport() 219
|
TibrvFtMonitor.getTransport()
Method
Declaration set transport = TibrvFtMonitor.getTransport()
Purpose Extract the transport of a fault tolerance monitor.
Return the transport of the fault tolerance monitor object.

TibrvFtMonitor.create on page 213

220
TibrvFtMonitor.isValid()
Method
Declaration isValid = TibrvFtMonitor.isValid()
Purpose Test validity of a fault tolerance monitor object.
Remarks Returns True if the monitor is valid; False if the monitor has been destroyed or is
otherwise invalid.
isValid Boolean
Return the validity of the fault tolerance monitor object.
See Also TibrvFtMonitor.destroy on page 215

TibrvFtMonitor_onFtMonitor 221
|
TibrvFtMonitor_onFtMonitor
Declaration Private Sub myFtMon_onFtMonitor(

ByVal ftMonitor As TIBRVCOMLib.ITibrvFtMonitor,
ByVal groupName As String,
ByVal numActiveMembers As Long)
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. Declaring a variable of class TibrvFtMonitor with events
triggers VB to automatically define a COM event callback, and a private
subroutine callback stub named var_OnFtMonitor. The program must complete
this method for each member object.
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.
Programs that do not monitor need not define a monitor callback method.
To stop monitoring, destroy the original monitor object associated with this
callback method.
ftMonitor TibrvFtMonitor
This parameter receives the monitor object.
groupName String
This parameter receives a string denoting the name of

the fault tolerance group.
numActiveMembers Long
This parameter receives the number of group

members now active.
See Also TibrvFtMonitor.create on page 213.

222

| 223
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 291 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
Some programs require certified delivery to one of n worker processes. See
Distributed Queue on page 183 in TIBCO Rendezvous Concepts.
Topics
• TibrvCmListener, page 224

• TibrvCmTransport, page 238

224
| Chapter 9 Certified Message Delivery
TibrvCmListener
Class
Purpose A certified delivery listener object listens for labeled messages and certified
messages.
Remarks Each call to the method TibrvCmListener.create results in a new 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 or deleting a certified
listener object cancels the program’s immediate interest in that event, and frees its
storage; nonetheless, a parameter to the destroy call determines whether certified
delivery agreements continue to persist beyond the destroy call.
(Sheet 1 of 2)

Life Cycle
TibrvCmListener.create Listen for messages that match the subject, 227

and request certified delivery when available.
TibrvCmListener.destroy Destroy a certified delivery listener. 229
TibrvCmListener.isValid() Test validity of a CM listener object. 234
Callback Method
TibrvCmListener_onCmMsg Process inbound messages (CM listener 235

events).
Confirm
TibrvCmListener.confirmMsg Explicitly confirm delivery of a certified 226

message.
TibrvCmListener.setExplicitConfirm Override automatic confirmation of delivery 237

for this listener.
Accessors
TibrvCmListener.getClosure() Extract the closure of a CM listener. 230

TibrvCmListener 225
|
(Sheet 2 of 2)

TibrvCmListener.getCmTransport() Extract the CM transport of a CM listener. 231
TibrvCmListener.getQueue() Extract the event queue of a CM listener. 232
TibrvCmListener.getSubject() Extract the subject of a CM listener. 233

226
TibrvCmListener.confirmMsg
Method
Declaration TibrvCmListener.confirmMsg message
Purpose Explicitly confirm delivery of a certified message.
Remarks Use this method only in programs that override automatic confirmation (see
TibrvCmListener.setExplicitConfirm on page 237). The default behavior of
certified listeners is to automatically confirm delivery when the callback method
returns.
message TibrvMsg
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 reports the error TIBRVCOM_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 224

TibrvCmListener.setExplicitConfirm on page 237

TibrvCmListener.create 227
|
TibrvCmListener.create
Method
Declaration TibrvCmListener.create queue, cmTransport, subject, closure
Purpose Listen for messages that match the subject, and request certified delivery when
available.
Starting a listener requires three steps:
1. Declare a variable for the listener.
Dim WithEvents myCmListener as TibrvCmListener

callback stub named myCmListener_OnCmMsg. The program must complete
this method for each listener object.
set myCmListener = New TibrvCmListener
3. Create the internal implementation object to begin listening.

myCmListener.create ...

queue TibrvQueue
For each inbound message, place the listener event on this

event queue.
cmTransport TibrvCmTransport
Listen for inbound messages on this certified delivery

transport.
subject String
Listen for inbound messages with subjects that match this

specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.
closure Object
Store this closure data in the event object.

228
Activation and Details of listener event semantics are identical to those for ordinary listeners; see
Dispatch Activation and Dispatch on page 110.
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 TibrvCmListener.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.

TibrvCmListener_onCmMsg on page 235
TibrvCmTransport.destroy on page 249
TibrvListener.getSubject() on page 117
TibrvTransport.createInbox() on page 169

TibrvCmListener.destroy 229
|
TibrvCmListener.destroy
Method
Declaration TibrvCmListener.destroy cancelAgreements
Purpose Destroy a certified delivery listener.
Remarks This method destroys only the internal structure of the listener object.
Rendezvous software automatically destroys a listener (using this method) when
Destroying an event object cancels interest in it. Upon return from
TibrvCmListener.destroy, the destroyed event is no longer dispatched.
However, an active callback method of this event continues to run and return
normally, even though the event is invalid.
It is legal for an event callback method to destroy its own event.
cancelAgreements Boolean
True cancels all certified delivery agreements of this

listener; certified senders delete from their ledgers all
messages sent to this listener.
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.
Deleting an certified delivery listener object (without first destroying it) cancels its
agreements.

230
TibrvCmListener.getClosure()
Method
Declaration closure = TibrvCmListener.getClosure()
Purpose Extract the closure of a CM listener.
closure Object
Return the closure of the CM listener object.
See Also TibrvCmListener.create on page 227

TibrvCmListener.getCmTransport() 231
|
TibrvCmListener.getCmTransport()
Method
Declaration set cmTransport = TibrvCmListener.getCmTransport()
Purpose Extract the CM transport of a CM listener.
Return the CM transport of the CM listener object.
See Also TibrvCmTransport on page 238

TibrvCmTransport.getTransport() on page 259

232
TibrvCmListener.getQueue()
Method
Declaration set queue = TibrvCmListener.getQueue()
Purpose Extract the event queue of a CM listener.
queue TibrvQueue
Return the event queue of the CM listener object.


TibrvCmListener.getSubject() 233
|
TibrvCmListener.getSubject()
Method
Declaration subject = TibrvCmListener.getSubject()
Purpose Extract the subject of a CM listener.
subject String
Return the subject of the CM listener object.
See Also TibrvCmListener.create on page 227

234
TibrvCmListener.isValid()
Method
Declaration isValid = TibrvCmListener.isValid()
Purpose Test validity of a CM listener object.
Remarks Returns True if the member is valid; False if the member has been destroyed or is
otherwise invalid.
isValid Boolean
Return the validity of the CM listener object.
See Also TibrvCmListener.destroy on page 229

TibrvCmListener_onCmMsg 235
|
TibrvCmListener_onCmMsg
Method
Declaration Private Sub myCmListener_onCmMsg(

ByVal cmListener As TIBRVCOMLib.ITibrvCmListener,
ByVal message As TIBRVCOMLib.ITibrvMsg)
Purpose Process inbound messages (CM listener events).
Remarks Implement this method to process inbound messages.

Declaring a variable of class TibrvCmListener with events triggers VB to
stub named var_OnCmMsg. The program must complete this method for each CM
listener object.
To stop listening to the message subject, destroy the original listener object
associated with this callback method.
cmListener TibrvCmListener
This parameter receives the CM listener object.
message TibrvMsg
This parameter receives the inbound message object. To

preserve this message beyond exit from this callback
method, the program must detach it.
CM Label The callback method for certified delivery messages can use certified delivery
Information label properties to discriminate these situations:
• If extracting the cmSender property yields the error TIBRVCOM_NOT_FOUND,
then the message uses the reliable protocol (that is, it was sent from an
ordinary transport).
• If the cmSender property is a valid sender name, then the message uses the
certified delivery protocol (that is, it is a labeled message, sent from a certified
delivery transport).

236
Once the callback method determines that the message uses the certified
delivery protocol, it can discriminate further:
— If extracting the cmSequenceNumber property yields the error
TIBRVCOM_NOT_FOUND, then the listener is not registered for certified
delivery from the sender.
— If the cmSequenceNumber property is a positive sequence number, then a
certified delivery agreement is in effect for this subject with the sender.
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.)
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 TibrvMsg.detach on page 54

TibrvMsg.getProperty() on page 72

TibrvCmListener.setExplicitConfirm 237
|
TibrvCmListener.setExplicitConfirm
Method
Declaration TibrvCmListener.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 TibrvCmListener_onCmMsg on page 235).
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 processing inbound messages

involves activity that is asynchronous with respect to the message callback
method; for example, additional network communications.
No method exists to restore the default behavior—that is, to reverse the effect of
this method.

TibrvCmListener.confirmMsg on page 226

238
TibrvCmTransport
Class
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.
Programs must explicitly destroy each certified delivery transport object.
Destroying a certified delivery transport object invalidates subsequent certified
send calls on that object, and invalidates any certified listeners using that
transport (while preserving the certified delivery agreements of those listeners).
(Sheet 1 of 3)

Life Cycle
TibrvCmTransport.create Create a transport for certified 245

delivery.
TibrvCmTransport.destroy Destroy a certified delivery 249

transport.
TibrvCmTransport.isValid() Test validity of a CM transport 260

object.
Send Messages
TibrvCmTransport.send Send a labeled message. 267
TibrvCmTransport.sendReply Send a labeled reply message. 268
Certified Delivery Control
TibrvCmTransport.addListener Pre-register an anticipated listener. 241

TibrvCmTransport 239
|
(Sheet 2 of 3)

TibrvCmTransport.allowListener Invite the named receiver to 242
reinstate certified delivery for its
listeners, superseding the effect of
any previous disallow calls.
TibrvCmTransport.connectToRelayAgent Connect a certified delivery 243

transport to its designated relay
agent.
TibrvCmTransport.disallowListener Cancel certified delivery to all 250

listeners at a specific correspondent.
Deny subsequent certified delivery
registration requests from those
listeners.
TibrvCmTransport.disconnectFromRelayAgent Disconnect a certified delivery 251

transport from its relay agent.
TibrvCmTransport.removeListener Unregister a specific listener at a 263

specific correspondent, and free
associated storage in the sender’s
ledger.
Ledger
TibrvCmTransport.expireMessages Mark specified outbound CM 252

messages as expired.
TibrvCmTransport.removeSendState Reclaim ledger space from obsolete 265

subjects.
TibrvCmTransport.reviewLedger Query the ledger for stored items 266

related to a subject name.
TibrvCmTransport_onLedgerMsg Programs define this method to 261

process ledger review messages.
TibrvCmTransport.stopReview Stop a ledger review. 273
TibrvCmTransport.syncLedger Synchronize the ledger to its 274

storage medium.

240
(Sheet 3 of 3)

Accessors
TibrvCmTransport.getDefaultTimeLimit() Get the default message time limit 253

for all outbound certified messages
from a transport.
TibrvCmTransport.getLedgerName() Extract the ledger name of a 254

certified delivery transport.
TibrvCmTransport.getName() Extract the correspondent name of a 255

certified delivery transport or
distributed queue member.
TibrvCmTransport.getRelayAgent() Extract the name of the relay agent 256

used by a certified delivery
transport.
TibrvCmTransport.getRequestOld() Extract the request old messages 257

flag of a certified delivery transport.
TibrvCmTransport.getSyncLedger() Extract the sync ledger flag of a 258

certified delivery transport.
TibrvCmTransport.getTransport() Extract the transport employed by a 259

certified delivery transport or a
TibrvCmTransport.setDefaultTimeLimit Set the default message time limit 271

for all outbound certified messages
from a transport.
TibrvCmTransport.setTaskBacklogLimit... Set the scheduler task queue limits 272

of a distributed queue transport.

TibrvCmTransport.addListener 241
|
TibrvCmTransport.addListener
Method
Declaration TibrvCmTransport.addListener cmName, 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 reports the error TIBRVCOM_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.
cmName String
Anticipate a listener from a correspondent with this reusable

name.
subject String
Anticipate a listener for this subject. Wildcard subjects are

illegal.
See Also Name, page 247

TibrvCmTransport.allowListener on page 242
TibrvCmTransport.disallowListener on page 250
TibrvCmTransport.removeListener on page 263
Anticipating a Listener, page 161 in TIBCO Rendezvous Concepts

242
TibrvCmTransport.allowListener
Method
Declaration TibrvCmTransport.allowListener 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.
cmName String
Accept requests for certified delivery to listeners at the

transport with this correspondent name.

Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TibrvCmTransport.connectToRelayAgent 243
|
TibrvCmTransport.connectToRelayAgent
Method
Declaration TibrvCmTransport.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.

244
Errors The error code TIBRVCOM_UNABLE indicates that the transport does not have a
relay agent.
See Also TibrvCmTransport.create on page 245

TibrvCmTransport.disconnectFromRelayAgent on page 251
Relay Agent, page 170 in TIBCO Rendezvous Concepts

TibrvCmTransport.create 245
|
TibrvCmTransport.create
Method
Declaration TibrvCmTransport.create transport, cmName, requestOld,

ledgerName, syncLedger, relayAgent
Purpose Create a transport for certified delivery.
Remarks 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 3)
The new TibrvCmTransport employs this transport object for network

communications.
Destroying the TibrvCmTransport does not affect this TibrvTransport object.
It is illegal to supply a virtual circuit transport object for this parameter.
cmName String; optional

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.
If absent, the empty string ("") or vbNullString, then TibrvCmTransport.create
generates a unique, non-reusable name for the duration of the transport.
For more information, see Name on page 247.

246
(Sheet 2 of 3)
requestOld Boolean; optional
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 true and cmName is present, 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 omitted.)
If this parameter is false (or absent), then the new TibrvCmTransport does not
require certified senders to retain unacknowledged messages. Certified senders
may delete those messages from their ledgers.
ledgerName String; optional

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 absent, the empty string ("") or vbNullString, then the new TibrvCmTransport
uses a process-based ledger.
For more information, see Ledger File on page 247.
syncLedger Boolean; optional

If this argument is true, then operations that update the ledger file do not return
until the changes are written to the storage medium.
If this argument is false (or absent), the operating system writes changes to the
storage medium asynchronously.

TibrvCmTransport.create 247
|
(Sheet 3 of 3)
relayAgent String; optional
Designate the rvrad process with this name as the new transport’s relay agent.
If absent, the empty string ("") or vbNullString, 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 167 in TIBCO Rendezvous Concepts.
It is illegal for a relay agent to have the same name as a CM correspondent.
For more information, see Relay Agent on page 247.
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.
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 167 in TIBCO Rendezvous Concepts.
Relay Agent TibrvCmTransport.create automatically connects a transport to its designated

relay agent upon creation; see TibrvCmTransport.connectToRelayAgent on
page 243.
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.

248
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 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 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 274.
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 249

TibrvCmTransport.connectToRelayAgent on page 243

TibrvCmTransport.destroy 249
|
TibrvCmTransport.destroy
Method
Declaration TibrvCmTransport.destroy
Purpose Destroy a certified delivery transport.
Remarks This method destroys only the internal structure of the transport object.
Rendezvous software automatically destroys a transport (using this method)
when program execution leaves the scope of the object, or sets the object to
Nothing.
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.
Distributed When calling this method to destroy a distributed queue transport, the
Queue distributed queue needs the listeners, queues and dispatchers (associated with the
transport) to remain operational—otherwise the distributed queue can lose
reliable (non-certified) task messages before they are processed. Programs must
wait until after the transport has been completely destroyed before destroying
these associated objects.

TibrvCmTransport.disconnectFromRelayAgent on page 251

250
TibrvCmTransport.disallowListener
Method
Declaration TibrvCmTransport.disallowListener cmName
Purpose Cancel certified delivery to all listeners at a specific correspondent. Deny

subsequent certified delivery registration requests from those listeners.
Remarks Disallowed listeners still receive subsequent messages from this sender, but
delivery is not certified. In other words:
• The first labeled message causes the listener to initiate registration.
Registration fails, and the listener discards that labeled message.
• The listener receives a REGISTRATION.NOT_CERTIFIED advisory, informing it
that the sender has canceled certified delivery of all subjects.
• If the sender’s ledger contains messages sent to the disallowed listener (for
which this listener has not confirmed delivery), then Rendezvous software
removes those ledger items, and does not attempt to redeliver those messages.
• Rendezvous software presents subsequent messages (from the canceling
sender) to the listener without a sequence number, to indicate that delivery is
not certified.
Senders can promptly revoke the acceptance of certified delivery by calling
TibrvCmTransport.disallowListener within the callback method that
processes the REGISTRATION.REQUEST advisory.
This method disallows a correspondent by name. If the correspondent terminates,
and another process instance (with the same reusable name) takes its place, the
new process is still disallowed by this sender.
To supersede the effect of TibrvCmTransport.disallowListener, call
TibrvCmTransport.allowListener on page 242.
cmName String
Cancel certified delivery to listeners of the transport with this

name.

TibrvCmTransport.allowListener on page 242
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TibrvCmTransport.disconnectFromRelayAgent 251
|
TibrvCmTransport.disconnectFromRelayAgent
Method
Declaration TibrvCmTransport.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.
relay agent.
See Also TibrvCmTransport.connectToRelayAgent on page 243

Relay Agent, page 170 in TIBCO Rendezvous Concepts

252
TibrvCmTransport.expireMessages
Method
Declaration TibrvCmTransport.expireMessages subject, 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).
subject String
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 TibrvInt64
Mark messages with sequence numbers less than or equal

to this value.
See Also DELIVERY.FAILED on page 298 in TIBCO Rendezvous Concepts

TibrvCmTransport.getDefaultTimeLimit() 253
|
TibrvCmTransport.getDefaultTimeLimit()
Method
Declaration timeLimit = TibrvCmTransport.getDefaultTimeLimit()
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
TibrvMsg.setProperty on page 85). 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.
timeLimit Double
Return the default message time limit of the CM transport.
See Also TibrvCmTransport.setDefaultTimeLimit on page 271

TibrvMsg.setProperty on page 85

254
TibrvCmTransport.getLedgerName()
Method
Declaration ledgerName = TibrvCmTransport.getLedgerName()
Purpose Extract the ledger name of a certified delivery transport.
ledgerName String
Return the ledger file name of the CM transport.
Errors The error code TIBRVCOM_CANNOT_RETRIEVE indicates that the transport does not
have a ledger file.
See Also Ledger File, page 247

TibrvCmTransport.create on page 245

TibrvCmTransport.getName() 255
|
TibrvCmTransport.getName()
Method
Declaration cmName = TibrvCmTransport.getName()
Purpose Extract the correspondent name of a certified delivery transport or distributed

queue member.
cmName String
Return the correspondent name of the CM transport.

TibrvCmTransport.createDistributedQueue on page 279

256
TibrvCmTransport.getRelayAgent()
Method
Declaration relayAgent = TibrvCmTransport.getRelayAgent()
Purpose Extract the name of the relay agent used by a certified delivery transport.
relayAgent String
Return the relay agent name of the CM transport.
have a relay agent.
See Also Relay Agent, page 247


TibrvCmTransport.getRequestOld() 257
|
TibrvCmTransport.getRequestOld()
Method
Declaration requestOld = TibrvCmTransport.getRequestOld()
Purpose Extract the request old messages flag of a certified delivery transport.
requestOld Boolean
Return the request old messages flag of the CM transport.
See Also requestOld on page 246


258
TibrvCmTransport.getSyncLedger()
Method
Declaration syncLedger = TibrvCmTransport.getSyncLedger()
Purpose Extract the sync ledger flag of a certified delivery transport.
syncLedger Boolean
Return the sync ledger flag of the CM transport.
have a ledger file.


TibrvCmTransport.getTransport() 259
|
TibrvCmTransport.getTransport()
Method
Declaration set transport = TibrvCmTransport.getTransport()
Purpose Extract the transport employed by a certified delivery transport or a distributed

queue member.
Return the transport of the CM transport object.


260
TibrvCmTransport.isValid()
Method
Declaration isValid = TibrvCmTransport.isValid()
Purpose Test validity of a CM transport object.
Remarks Returns True if the transport is valid; False if the transport has been destroyed or
is otherwise invalid.
isValid Boolean
Return the validity of the CM transport object.


TibrvCmTransport_onLedgerMsg 261
|
TibrvCmTransport_onLedgerMsg
Method
Declaration Private Sub myCmTransport_onLedgerMsg(

ByVal cmTransport As TIBRVCOMLib.ITibrvCmTransport,
ByVal subject As String,
ByVal message As TIBRVCOMLib.ITibrvMsg,
ByVal closure As Object)
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.
When this method returns, TibrvCmTransport.reviewLedger prepares the next
ledger method and calls the method again.
To stop reviewing the ledger, call TibrvCmTransport.stopReview from within
this callback method; TibrvCmTransport.reviewLedger cancels the review and
returns immediately.
Declaring a variable of class TibrvCmTransport with events triggers VB to

stub named var_OnLedgerMsg. The program must complete this method for each
CM transport object (except distributed queue objects).
This parameter receives the CM transport object.
subject String
This parameter receives the subject for this ledger item.
message TibrvMsg
This parameter receives a summary message describing the

delivery status of messages in the ledger. For information
about the fields of the summary message, see the table Field
Name on page 262.
closure Object
This parameter receives closure data that the program

supplied to TibrvCmTransport.reviewLedger.

262
Field Name Description

subject The subject that this message summarizes.
This field has datatype TIBRVCOM_MSG_STRING.
seqno_last_sent The sequence number of the most recent message sent with this
subject name.
This field has datatype TIBRVCOM_MSG_U64.
total_msgs The total number of messages stored at this subject name.

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 TIBRVCOM_MSG_I64.
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 TIBRVCOM_MSG_MSG.
listener.name Within each listener submessage, the name field contains the
name of the listener transport.
This field has datatype TIBRVCOM_MSG_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.
See Also TibrvCmTransport.reviewLedger on page 266

TibrvCmTransport.stopReview on page 273

TibrvCmTransport.removeListener 263
|
TibrvCmTransport.removeListener
Method
Declaration TibrvCmTransport.removeListener cmName, 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 reports the error
TIBRVCOM_INVALID_SUBJECT.
cmName String
Cancel certified delivery of the subject to listeners of this

correspondent.
subject String
Cancel certified delivery of this subject to the named listener.

Wildcard subjects are illegal.

264
TibrvCmTransport.addListener on page 241

Canceling Certified Delivery, page 162 in TIBCO Rendezvous Concepts

TibrvCmTransport.removeSendState 265
|
TibrvCmTransport.removeSendState
Method
Declaration TibrvCmTransport.removeSendState 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.
subject String
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.

TibrvCmTransport.send on page 267
DELIVERY.COMPLETE on page 296 in TIBCO Rendezvous Concepts

266
TibrvCmTransport.reviewLedger
Method
Declaration TibrvCmTransport.reviewLedger subject, closure
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 calls TibrvCmTransport.stopReview, then
TibrvCmTransport.reviewLedger returns immediately (without any further
callbacks).
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
TibrvCmTransport_onLedgerMsg on page 261.
subject String
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 Object
Pass this closure data to the review callback method.
See Also TibrvCmTransport_onLedgerMsg on page 261

TibrvCmTransport.stopReview on page 273

TibrvCmTransport.send 267
|
TibrvCmTransport.send
Method
Declaration TibrvCmTransport.send message
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 TibrvMsg.setProperty on
page 85. 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 271); if that default is not set for
the transport, the default time limit is zero (no time limit).
message TibrvMsg
Send this message.

See Also TibrvCmTransport.sendReply on page 268

TibrvCmTransport.sendRequest() on page 269
TibrvCmTransport.setDefaultTimeLimit on page 271

268
TibrvCmTransport.sendReply
Method
Declaration TibrvCmTransport.sendReply replyMsg, 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.
replyMsg TibrvMsg
Send this outbound reply message.
requestMsg TibrvMsg
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 267

TibrvCmTransport.sendRequest() on page 269

TibrvCmTransport.sendRequest() 269
|
TibrvCmTransport.sendRequest()
Method
Declaration set replyMsg = TibrvCmTransport.sendRequest(message, timeout)
Purpose Send a labeled request message and wait for a reply.
Blocking can Stall Event Dispatch
This call blocks all other activity in the program.
replyMsg TibrvMsg
Return this reply message.
message TibrvMsg
Send this request message.

timeout Double
Maximum time (in seconds) that this call can block while waiting 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 87.
The program owns the reply message object, and must delete it to reclaim its
storage.
A certified request does not necessarily imply a certified reply; the replying
program determines the type of reply message that it sends.
Operation This method operates in several synchronous steps:

270
1. Create a TibrvCmListener that listens for messages on the reply subject of

msg.
2. Label and send the outbound message.

3. Block until the listener receives a reply. (The reply event uses a private queue
that is not accessible to the program.) If the time limit expires before a reply
arrives, then report the error TIBRVCOM_TIMEOUT.
4. Return the reply message as the value of the method call.
See Also TibrvCmTransport.send on page 267

TibrvCmTransport.sendReply on page 268

TibrvCmTransport.setDefaultTimeLimit 271
|
TibrvCmTransport.setDefaultTimeLimit
Method
Declaration TibrvCmTransport.setDefaultTimeLimit 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
TibrvMsg.setProperty on page 85). 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.
timeLimit Double
Use this time limit (in whole seconds). The time limit must be
non-negative. Fractional values are truncated to whole seconds.
See Also TibrvCmTransport.getDefaultTimeLimit() on page 253


272
TibrvCmTransport.setTaskBacklogLimit...
Method
Declaration TibrvCmTransport.setTaskBacklogLimitInBytes limitBySizeInBytes
TibrvCmTransport.setTaskBacklogLimitInMessages limitByMessages
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 either these properties, the default is no limit.
When the task messages in the queue exceed either of the two 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, the values are fixed, and subsequent attempts to change them result in
status code TIBRVCOM_NOT_PERMITTED.
limitBySizeInBytes Long
Use this size limit (in bytes).

Zero is a special value, indicating no size limit.
limitByMessages Long
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 183, in TIBCO Rendezvous Concepts

TibrvCmTransport.stopReview 273
|
TibrvCmTransport.stopReview
Method
Declaration TibrvCmTransport.stopReview
Purpose Stop a ledger review.
Remarks To stop a ledger review, call this method from within

TibrvCmTransport_onLedgerMsg.

TibrvCmTransport_onLedgerMsg on page 261

274
TibrvCmTransport.syncLedger
Method
Declaration TibrvCmTransport.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.
Even when the program does not call this method, Rendezvous software
periodically synchronizes 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.
ledger file.

TibrvCmTransport.getSyncLedger() on page 258

| 275
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 distributed queue transport objects, each in a
separate process. From the outside, a distributed queue group appears as though
it were 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.
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 411 in
TIBCO Rendezvous Administration.
See Also Distributed Queue, page 183 in TIBCO Rendezvous Concepts
Topics
• Distributed Queue Transport, page 276

276
| Chapter 10 Distributed Queue
Distributed Queue Transport
Each distributed queue member uses a distributed queue transport for

communications. A distributed queue transport is a special-case instance of class
TibrvCmTransport.
Each distributed queue transport object employs a TibrvTransport for network

communications. The distributed queue transport adds the accounting and
coordination mechanisms needed for one-of-n delivery.
Disabled Methods
Although each distributed queue transport is an instance of TibrvCmTransport,
all methods related to sending messages are disabled in distributed queue
transports. These disabled methods report the error
TIBRVCOM_INVALID_TRANSPORT_OBJECT. For a list of legal and disabled methods,
see Shared Methods on page 278. See also Certified Delivery Behavior in Queue
Members on page 185 in TIBCO Rendezvous Concepts.
Subscriptions
All members of a distributed queue must listen to exactly the same set of subjects.
See Enforcing Identical Subscriptions on page 186 in TIBCO Rendezvous Concepts.
Certified Task Messages

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).
(Sheet 1 of 2)

Life Cycle
TibrvCmTransport.createDistributedQueue Create a transport as a distributed 279

queue member.
TibrvCmTransport.isDistributed() Test whether a CM transport object 285

implements a distributed queue
member.

Distributed Queue Transport 277
|
(Sheet 2 of 2)

Accessors
When called on a CM transport object (which is not initialized as a distributed transport), these
methods report the error TIBRVCOM_NOT_DISTRIBUTED_TRANSPORT.
TibrvCmTransport.getCompleteTime() Extract the worker complete time limit 282

of a distributed queue member.
TibrvCmTransport.getWorkerTasks() Extract the worker task capacity of a 283

TibrvCmTransport.getWorkerWeight() Extract the worker weight of a 284

TibrvCmTransport.setCompleteTime Set the worker complete time limit of a 286

TibrvCmTransport.setWorkerTasks Set the worker task capacity of a 287

TibrvCmTransport.setWorkerWeight Set the worker weight of a distributed 288

queue member.
Constants The type library defines these constants for use with distributed queue methods.
Constant Value
TIBRVCOM_CM_DEFAULT_COMPLETE_TIME 0
TIBRVCOM_CM_DEFAULT_WORKER_WEIGHT 1
TIBRVCOM_CM_DEFAULT_WORKER_TASKS 1
TIBRVCOM_CM_DEFAULT_SCHEDULER_WEIGHT 1
TIBRVCOM_CM_DEFAULT_SCHEDULER_HB (heartbeat) 1.0

278
Shared Methods
Legal Methods TibrvCmTransport.destroy
TibrvCmTransport.getName()
TibrvCmTransport.getTransport()
TibrvCmTransport.isValid()
Disabled Methods TibrvCmTransport.addListener

TibrvCmTransport.allowListener
TibrvCmTransport.connectToRelayAgent
TibrvCmTransport.create
TibrvCmTransport.disallowListener
TibrvCmTransport.disconnectFromRelayAgent
TibrvCmTransport.getDefaultTimeLimit()
TibrvCmTransport.getLedgerName()
TibrvCmTransport.getRelayAgent()
TibrvCmTransport.getRequestOld()
TibrvCmTransport.getSyncLedger()
TibrvCmTransport_onLedgerMsg
TibrvCmTransport.removeListener
TibrvCmTransport.removeSendState
TibrvCmTransport.reviewLedger
TibrvCmTransport.send
TibrvCmTransport.sendReply
TibrvCmTransport.sendRequest()
TibrvCmTransport.setDefaultTimeLimit
TibrvCmTransport.stopReview
TibrvCmTransport.syncLedger
TibrvTransport.send
When called on a distributed transport object, the disabled methods report the
error TIBRVCOM_NOT_FOR_DISTRIBUTED_TRANSPORT.

TibrvCmTransport.createDistributedQueue 279
|
TibrvCmTransport.createDistributedQueue
Method
Declaration TibrvCmTransport.createDistributedQueue transport, cmName,

workerWeight, workerTasks,
schedulerWeight, schedulerHeartbeat, schedulerActivation
Purpose Create a transport as a distributed queue member.
Remarks The new distributed queue transport must employ a valid TibrvTransport for
network communications.
(Sheet 1 of 3)
The new distributed queue TibrvCmTransport employs this

TibrvTransport object for network communications.
Destroying the distributed queue TibrvCmTransport does not affect this

transport.
cmName String
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 167 in TIBCO


280
(Sheet 2 of 3)
workerWeight Long, optional
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 Long, optional

Task capacity is the maximum number of tasks that a worker can accept.
When the number of accepted tasks reaches this maximum, the worker
cannot accept additional tasks until it completes one or more of them.
When the scheduler receives a task, it assigns the task to the worker with
the greatest worker weight—unless the pending tasks assigned to that
worker exceed its task capacity. When the preferred worker has too
many tasks, the scheduler assigns the new inbound task to the worker
with the next greatest worker weight.
The value must be a non-negative integer. When omitted, the default
value is 1.
Zero is a special value, indicating that this distributed queue member is a
dedicated scheduler (that is, it never accepts tasks).
Tuning task capacity to compensate for communication time lag is more

complicated than it might seem. Before setting this value to anything
other than 1, see Task Capacity on page 188 in TIBCO Rendezvous
Concepts.

TibrvCmTransport.createDistributedQueue 281
|
(Sheet 3 of 3)
schedulerWeight Long, optional
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 206 in TIBCO Rendezvous
Concepts.
schedulerHeartbeat Double, optional

The scheduler sends heartbeat messages at this interval (in seconds).
All Distributed Queue Transport 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
When omitted, the default value is 1.0.
schedulerActivation Double, optional

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 Distributed Queue Transport 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
When omitted, the default value is 3.5.
See Also TibrvCmTransport.destroy on page 249

Distributed Queue, page 183, in TIBCO Rendezvous Concepts

282
TibrvCmTransport.getCompleteTime()
Method
Declaration completeTime = TibrvCmTransport.getCompleteTime()
Purpose Extract the worker complete time limit of a distributed queue member.
completeTime Double
Return the complete time (in seconds).

TibrvCmTransport.setCompleteTime on page 286

TibrvCmTransport.getWorkerTasks() 283
|
TibrvCmTransport.getWorkerTasks()
Method
Declaration workerTasks = TibrvCmTransport.getWorkerTasks()
Purpose Extract the worker task capacity of a distributed queue member.
workerTasks Long
Return the worker task capacity.

TibrvCmTransport.setWorkerTasks on page 287

284
TibrvCmTransport.getWorkerWeight()
Method
Declaration workerWeight = TibrvCmTransport.getWorkerWeight()
Purpose Extract the worker weight of a distributed queue member.
workerWeight Long
Return the worker weight.

TibrvCmTransport.setWorkerWeight on page 288

TibrvCmTransport.isDistributed() 285
|
TibrvCmTransport.isDistributed()
Method
Declaration isDistributed = TibrvCmTransport.isDistributed()
Purpose Test whether a CM transport object implements a distributed queue member.
isDistributed Boolean
Return True if the object implements a distributed queue

member.
Return False if the object implements a CM transport.

TibrvCmTransport on page 238

286
TibrvCmTransport.setCompleteTime
Method
Declaration TibrvCmTransport.setCompleteTime 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.
completeTime Double
Use this complete time (in seconds). The time must be

non-negative.

TibrvCmTransport.getCompleteTime() on page 282

TibrvCmTransport.setWorkerTasks 287
|
TibrvCmTransport.setWorkerTasks
Method
Declaration TibrvCmTransport.setWorkerTasks workerTasks
Purpose Set the worker task capacity of a distributed queue member.
Remarks Task capacity is the maximum number of tasks that a worker can accept. When
the number of accepted tasks reaches this maximum, the worker cannot accept
additional tasks until it completes one or more of them.
When the scheduler receives a task, it assigns the task to the worker with the
greatest worker weight—unless the pending tasks assigned to that worker exceed
its task capacity. When the preferred worker has too many tasks, the scheduler
assigns the new inbound task to the worker with the next greatest worker weight.
The default worker task capacity is 1.
Zero is a special value, indicating that this distributed queue member is a
dedicated scheduler (that is, it never accepts tasks).
Tuning task capacity to compensate for communication time lag is more

complicated than it might seem. Before setting this value to anything other than 1,
see Task Capacity on page 188 in TIBCO Rendezvous Concepts.
workerTasks Long
Use this task capacity. The value must be a non-negative

integer.

TibrvCmTransport.getWorkerTasks() on page 283

288
TibrvCmTransport.setWorkerWeight
Method
Declaration TibrvCmTransport.setWorkerWeight 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
TibrvCmTransport.createDistributedQueue, or change it dynamically using
this method.
workerWeight Long
Use this worker weight.

TibrvCmTransport.getWorkerWeight() on page 284

| 289
Chapter 11 Errors
Topics
• Error Overview, page 290

• Rendezvous Error Codes, page 293
• Component Error Codes, page 297
• VB Error Codes, page 300

290
| Chapter 11 Errors
Error Overview
All Rendezvous COM objects support detailed error information.

VB programmers can see a list of codes in the object browser, in the category
tibrvcom_errorCodes. Programmers using other languages can browse the type
library to see these definitions.
Rendezvous COM methods return errors as HRESULT values—32-bit integers with
hex representations 0x8004nnnn. These values divide into two ranges:
• Values in the range [0x80040200, 0x80040fff] represent errors from the
TIBRVCOM implementation. For details, see Component Error Codes on
page 297.
• Values in the range [0x80048001, 0x80048fff] represent errors from the
Rendezvous API. For details, see Rendezvous Error Codes on page 293.
VB
When VB reports an error, it populates an Err object.
VB programmers can write error handlers to process such errors. Err.Number
extracts the error status code. Err.Source identifies the object that reported the
error. Err.Description interprets the error code as a descriptive string.
• Err.Number extracts the HRESULT numeric error code.
• Err.Source identifies the object that reported the error.
• Err.Description interprets the error code as a descriptive string.
C++
C++ programs must test the HRESULT status code after each method call.
Microsoft Visual C++ defines these convenient macros:
#define FAILED(Status) ((HRESULT)(Status) <0)
#define SUCCEEDED(Status) ((HRESULT)(Status)>=0)
C++ COM programmers can use the IErrorInfo interface to extract more detail
from an object that returns an HRESULT indicating an error:
• GetErrorInfo() returns the error object.
• GetErrorSource() identifies the object that reported the error.
• GetErrorDescription() interprets the error code as a descriptive string.

Error Overview 291
|
Continuing after Errors

Although continuing after an error is not generally considered a good
programming practice, it is sometimes necessary. When you must continue after
an error, consider these guidelines.
• A method that usually returns an object instead returns an uninitialized
object.
• A method that usually returns a value instead returns zero.
• When an error results from incorrect assignment syntax, the program may call
the method again with the correct syntax. Consider these two examples:
On Error Resume Next
value = msg.getByIndex(i)
If IsEmpty(value) then
Set value = msg.getByIndex(i)
End If
For i=0 To msg.getNumFields

On Error Resume Next
var = msg.getByIndex(i) ’This won’t work for objects.
If (IsArray(var)) Then
For j=LBound(var) To UBound(var)
Write #1, "Array element " & CStr(j) & ": " & CStr(var(j))
Next j
Else ’It’s not an array.
If Not IsEmpty(var) Then ’Perhaps it’s an scalar.
Write #1, CStr(var)
End If
End If
If IsEmpty(var)
Set var = msg.getByIndex(i) ’Try to extract it as an object.
Write #1, "Extracted " & TypeName(var) & " object from
message"
If TypeName(var) = "ITIBRVMSG" Then ’It is an object.
Write #1, var.toString ’Write the object.
End If
If TypeName(var) = "ITibrvInt64" Then
Write #1, var.getAsString
Write #1, " or as unsigned " & var.getAsUnsignedString
Write #1, Cstr(var.getHighOrderPart) & ", " & _
CStr(var.getLowOrderPart)
End If
End If

292
| Chapter 11 Errors
Constants
The interface defines these useful constants.
Table 6 Base Constants for HRESULT Computations
Hex Code
TIBRVCOM_ERROR_ITF Base of all HRESULT codes from the TIBRVCOM
0x80040000 interface.
TIBRVCOM_ERROR_TIBRVCOM Base of HRESULT codes from the TIBRVCOM

0x80040200 implementation. See Component Error Codes
on page 297.
TIBRVCOM_ERROR_TIBRV Base of HRESULT codes from Rendezvous API.

0x80048000 See Rendezvous Error Codes on page 293.

Rendezvous Error Codes 293
|
Rendezvous Error Codes
Rendezvous API error codes are 32-bit integers, with hex representations
0x80048nnn.
These constants generally correspond to error codes in the Rendezvous C API—

when the COM interface constant TIBRVCOM_name has the value 0x80048nnn, the
C constant TIBRV_name has the value nnn.
Table 7 Rendezvous HRESULT Error Codes (Sheet 1 of 4)
Constant
Description
Hex Code
TIBRVCOM_INIT_FAILURE Cannot create the network transport.
0x80048001
TIBRVCOM_INVALID_ARG An argument is invalid. Check arguments other than

0x80048003 messages, subject names, transports, events, queues and
queue groups (which have separate error codes).
TIBRVCOM_NOT_INITIALIZED The method cannot run because the Rendezvous

0x80048004 environment is not initialized (open).
TIBRVCOM_ARG_CONFLICT Two arguments that require a specific relation are in

0x80048005 conflict. For example, the upper end of a numeric range is
less than the lower end.
TIBRVCOM_SERVICE_NOT_FOUND Transport creation failed; cannot match the service name

0x80048010 using getservbyname().
TIBRVCOM_NETWORK_NOT_FOUND Transport creation failed; cannot match the network name

0x80048011 using getnetbyname().
TIBRVCOM_DAEMON_NOT_FOUND Transport creation failed; cannot match the daemon port

0x80048012 number.
TIBRVCOM_NO_MEMORY The method could not allocate dynamic storage.

0x80048013
TIBRVCOM_INVALID_SUBJECT The method received a subject name with incorrect syntax.

0x80048014
TIBRVCOM_DAEMON_NOT_CONNECTED The Rendezvous daemon process (rvd) exited, or was

0x80048015 never started. This error indicates that the program cannot
start the daemon and connect to it.

294
| Chapter 11 Errors
Constant
Hex Code Description
TIBRVCOM_VERSION_MISMATCH The library, header files and Rendezvous daemon are

0x80048016 incompatible.
TIBRVCOM_SUBJECT_COLLISION It is illegal to create two certified worker events on the

0x80048017 same CM transport with overlapping subjects.
TIBRVCOM_VC_NOT_CONNECTED A virtual circuit terminal was once complete, but is now

0x80048018 irreparably broken.
TIBRVCOM_NOT_PERMITTED 1. The program attempted an illegal operation.

0x8004801b
2. Cannot create ledger file.
TIBRVCOM_INVALID_NAME The field name is too long; see Field Name Length on
0x8004801e page 46.
TIBRVCOM_INVALID_TYPE 1. The field type is not registered.

0x8004801f
2. Cannot update field to a type that differs from the
existing field’s type.
TIBRVCOM_INVALID_SIZE The explicit size in the field does not match its explicit
0x80048020 type.
TIBRVCOM_INVALID_COUNT The explicit field count does not match its explicit type.
0x80048021
TIBRVCOM_NOT_FOUND Could not find the specified field in the message.

0x80048023
TIBRVCOM_ID_IN_USE Cannot add this field because its identifier is already

0x80048024 present in the message; identifiers must be unique.
TIBRVCOM_ID_CONFLICT After field search by identifier fails, search by name

0x80048025 succeeds, but the actual identifier in the field is non-null
(so it does not match the identifier supplied).
TIBRVCOM_CONVERSION_FAILED Found the specified field, but could not convert it to the
0x80048026 desired datatype.
TIBRVCOM_RESERVED_HANDLER The datatype handler number is reserved for Rendezvous

0x80048027 internal datatype handlers.

Rendezvous Error Codes 295
|
Constant
TIBRVCOM_ENCODER_FAILED Datatype encoder failed.

0x80048028
TIBRVCOM_DECODER_FAILED Datatype decoder failed.

0x80048029
TIBRVCOM_INVALID_MSG The method received a message argument that is not a

0x8004802a well-formed message.
TIBRVCOM_INVALID_FIELD The program supplied an invalid field as an argument.

0x8004802b
TIBRVCOM_INVALID_INSTANCE The program supplied zero as the field instance number

0x8004802c (the first instance is number 1).
TIBRVCOM_CORRUPT_MSG The method detected a corrupt message argument.

0x8004802d
TIBRVCOM_ENCODING_MISMATCH The method attempted to add or update a field within a

0x8004802e message. However, the encoding in the new value does
not match the encoding of the message.
TIBRVCOM_TIMEOUT A timed dispatch call returned without dispatching an

0x80048032 event.
A send request call returned without receiving a reply
message.
A virtual circuit terminal is not yet ready for use.
TIBRVCOM_INTR Interrupted operation.

0x80048033
TIBRVCOM_INVALID_DISPATCHABLE The method received an event queue or queue group that

0x80048034 has been destroyed, or is otherwise unusable.
TIBRVCOM_INVALID_EVENT The method received an event that has been destroyed, or

0x8004803c is otherwise unusable.
TIBRVCOM_INVALID_CALLBACK The method received NULL instead of a callback method.

0x8004803d
TIBRVCOM_INVALID_QUEUE The method received a queue that has been destroyed, or

0x8004803e is otherwise unusable.

296
| Chapter 11 Errors
Constant
TIBRVCOM_INVALID_QUEUE_GROUP The method received a queue group that has been

0x8004803f destroyed, or is otherwise unusable.
TIBRVCOM_INVALID_TIME_INTERVAL The method received a negative timer interval.

0x80048040
TIBRVCOM_SOCKET_LIMIT The operation failed because of an operating system

0x80048043 socket limitation.
TIBRVCOM_OS_ERROR Tibrv.open encountered an operating system error.

0x80048044
TIBRVCOM_EOF End of file.

0x80048047
TIBRVCOM_INVALID_FILE 1. A certificate file or a ledger file is not recognizable as

0x80048048 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.
TIBRVCOM_FILE_NOT_FOUND Rendezvous software could not find the specified file.

0x80048049
TIBRVCOM_IO_FAILED Cannot write to ledger file.

0x8004804a
TIBRVCOM_NOT_FILE_OWNER The program cannot open the specified file because

0x80048050 another program owns it.
For example, ledger files are associated with
correspondent names.

Component Error Codes 297
|
Component Error Codes
TIBRVCOM component error codes are 32-bit integers, with hex representations
0x80040nnn. The type library defines these error code constants.
These constants correspond to string resources—when the constant
TIBRVCOM_name has the value 0x80040nnn, the resource IDS_E_name has the value
nnn.
Table 8 TIBRVCOM HRESULT Error Codes (Sheet 1 of 3)
Constant
Description
Hex Code
TIBRVCOM_TIBRV_NOT_OPEN Operation requires that Tibrv be open.
0x80040200
TIBRVCOM_INVALID_MSG_OBJECT TibrvMsg has no internal structure.

0x80040201
TIBRVCOM_BAD_POINTER_ARG Argument must be a pointer to existing storage.

0x80040202
TIBRVCOM_INVALID_ARRAY Arrays must be one-dimensional.

0x80040203
TIBRVCOM_INVALID_DATATYPE Datatype not supported for this operation.

0x80040204
TIBRVCOM_INVALID_QUEUE_OBJECT Queue object has no internal structure.

0x80040205
TIBRVCOM_INVALID_TRANSPORT_OBJECT Transport object has no internal structure.

0x80040206
TIBRVCOM_ALREADY_INITIALIZED Object is already created or initialized.

0x80040207
TIBRVCOM_CREATE_WINDOW_FAILED Unable to create hidden window for automatic

0x80040208 dispatch.
TIBRVCOM_INVALID_FIELD_ID Invalid field id—range is 0 to 65535.

0x80040209
TIBRVCOM_DATA_CONVERSION_RANGE Data out of range for conversion to target type.

0x8004020a

298
| Chapter 11 Errors
Constant
TIBRVCOM_NOT_CREATED Unable to create object.

0x8004020b
TIBRVCOM_OUT_OF_MEMORY Insufficient memory for operation.

0x8004020c
TIBRVCOM_INVALID_VALUE Invalid value of data argument.

0x8004020d
TIBRVCOM_NULL_NAME Null name parameter is illegal.

0x8004020e
TIBRVCOM_MSG_NOT_CREATED Unable to create message object.

0x8004020f
TIBRVCOM_NULL_SUBJECT Null subject is illegal.

0x80040210
TIBRVCOM_CONVERSION_NOT_SUPPORTED Data conversion between these types is not

0x80040211 supported.
TIBRVCOM_DATA_CONVERSION_FAILED Data conversion failed.

0x80040212
TIBRVCOM_CANNOT_RETRIEVE Cannot retrieve the requested information.

0x80040213
TIBRVCOM_INVALID_PROPERTY_REQUEST No property with that name exists.

0x80040214
TIBRVCOM_INVALID_PROPERTY_VALUE Property value data type is incorrect

0x80040215
TIBRVCOM_NOT_DISTRIBUTED_TRANSPORT Operation is valid only for distributed CM

0x80040216 transport.
TIBRVCOM_NOT_FOR_DISTRIBUTED_TRANSPORT Operation is not allowed for distributed CM

0x80040217 transport.
TIBRVCOM_EVENT_CALLBACK_ACTIVE Dispatching a queue from a callback is not

0x80040218 allowed

Component Error Codes 299
|
Constant
TIBRVCOM_OBJECT_NOT_INITIALIZED The object’s internal structure has not been

0x80040219 created (or has already been destroyed).
TIBRVCOM_UNABLE Object cannot complete the requested operation.

0x8004021a
TIBRVCOM_INVALID_CLOSURE Invalid closure argument.

0x8004021b

300
| Chapter 11 Errors
VB Error Codes
Programs can receive errors that seem related to Rendezvous software, but really
originate from the VB language implementation. While it is difficult to give
complete advice to application programmers regarding these errors, Table 9
summarizes some of the common errors in this group.
Table 9 VB Errors (Sheet 1 of 2)
Error Error Text String and Description

91 Object variable or With block variable not set
VB cannot apply a method because the variable does not contain an appropriate object.
This error can indicate that an object has not yet been assigned to the variable, or was
once present but has been set to Nothing.
This error can also stem from incorrect assignment syntax. Remember that you must use
set to assign an object; for example:
Right:
’in General (Global) Declarations
dim q as TibrvQueue
’in a Subroutine
set q = tibrv.getDefaultQueue
Wrong:
dim q as New TibrvQueue
’in a Subroutine
q = tibrv.getDefaultQueue
429 COM rejected a call to CreateObject().

Check spelling of object name.
Check that the component is registered.
Check memory usage.

VB Error Codes 301
|
Table 9 VB Errors (Sheet 2 of 2)
Error Error Text String and Description

438 Object doesn’t support this property or method
Check spelling of method name and its arguments.
Check that the component is registered.
This error also indicates incorrect assignment syntax. Remember that you must use set to
assign an object; for example:
Right:
dim q as TibrvQueue
’in a Subroutine
set q = tibrv.getDefaultQueue
Wrong:
dim q as TibrvQueue
’in a Subroutine
q = tibrv.getDefaultQueue

302
| Chapter 11 Errors

Index 303
|
Index
Numerics callback method

fault tolerance 207
64-bit integer 101 fault tolerance monitor 221
inbound message 120
CM 235
review ledger 261
A timer 131
certificate
accept, create virtual circuit 186 set daemon certificate 27
activate, fault tolerance 208 set user certificate 29, 30
add certified delivery 223
datatype conversion during 47 add listener 241
TibrvMsg 45 allow listener 242
TibrvQueueGroup 153 confirm 226
addField 48 connect to relay agent 243
addListener 241 destroy
advisory message, see TIBCO Rendezvous Concepts listener 229
allow listener 242 transport 249
automatic dispatch 20 disallow listener 250
disconnect from relay agent 251
expireMessages 252
get transport parameter
B correspondent name 255
ledger name 254
backward compatibility. See, release 5. relay agent 256
batch mode 180 request old 257
bytes sync ledger 258
create message from 52 time limit 253
get field as 59 transport 259
get size of message 61 label information, inbound message 235
ledger review 266
stop 273
listener 224
C create 227
destroy 229
C library files 16 remove
listener 263

304
| Index
send state 265 copy message 51
review ledger 266 correspondent, get name 255
send 267 create
reply 268 certified delivery listener 227
request 269 certified delivery transport 245
send state, remove 265 distributed queue member 279
set explicit confirm 237 event queue 136
set time limit event queue group 154
of individual message 85 fault tolerance member 196
of transport, default 271 fault tolerance monitor 213
stop review 273 inbox name 169
sync ledger 274 listener 112
transport 238 message 50
create 245 message copy 51
destroy 249 timer 124
character encoding 7 transport 166
checklist, programmer’s 13 embed license 168
clear references 37, 49 createAcceptVc() 186
close 19 createConnectVc() 187
closure createCopy(), message 51
CM listener 230 createFromByteArray, message 52
fault tolerance createInbox() 169
member 201 customer support xxiv
monitor 216
listener 115
timer 127
CM queue. See distributed queue D
cmSender 72
cmSequenceNumber 72 daemon TCP socket 166
cmTimeLimit 72, 85 data, validity of snapshot 36
compatibility. See, release 5. datatype
complete time, distributed queue conversion
get 282 VB to wire format 47
set 286 wire format to VB 58
confirm 226 Rendezvous 42
set explicit 237 snapshot reference 35
confirmMsg 226 deactivate, fault tolerance 209
connect subject, get 189 default queue 133
connect, create virtual circuit 187 description 172, 181
connectToRelayAgent 243
control, message storage 34
conversion matrix
VB to wire format 47
wire format to VB 58
convert message to string 88

Index 305
|
destroy environment
certified delivery listener 229 isOpen() 24
certified delivery transport 249 Tibrv 17
event queue 137 TibrvSdContext class 26
fault tolerance member 200 variables 16
fault tolerance monitor 215 error codes
listener 114 component 297
message 53 Rendezvous 293
queue group 155 VB 300
timer 126 error handling 290
transport 170 event queue
detach message 54 class 133
disallowListener 250 create 136
discard amount, get 140 destroy 137
disconnectFromRelayAgent 251 dispatch 138
dispatch get
automatic 20 count 139
queue 138 discard amount 140
timed 150 limit policy 141
queue group 156 max events 142
timed 160 name 143
distributed queue 275 priority 144
get complete time 282 limit policy constants 133
get worker task capacity 283, 285 poll 146
get worker weight 284 set
member, create 279 limit policy 147
set complete time 286 name 148
set scheduler task queue limits 272 priority 149
set worker task capacity 287 timed dispatch 150
set worker weight 288 validity 145
transport 276 event queue group 151
validity 157
expireMessages, certified delivery 252
E
embedded license 168 F
encoding
get from message 69 fault tolerance 193
get inbound default 62 action constants 208
get outbound 71 member 195
set inbound default 83 callback 207
set outbound 84 create 196
encoding, character 7 destroy 200
monitor 211

306
| Index
callback 221 monitor 216
create 213 listener 115
destroy 215 timer 127
field getCMTransport(), from CM listener 231
add 45, 48 getCmVersion() 23
class 93 getCompleteTime() 282
get 55, 63 getCount() 139
initialize 99 getDaemon() 171
name and identifier 38 getData(), from field object 95
remove 79 getDefaultInboundEncoding() 62
remove instance 81 getDefaultQueue() 21
update 89 getDefaultTimeLimit() 253
update from field 92 getDescription() 172
field search algorithm getDiscardAmount() 140
get 55 getField() 63
remove 79 getFieldByIndex() 65
update 90 getFieldInstance() 66
file, ledger 246 getFtVersion() 23
getGroupName()
fault tolerance member 202
fault tolerance monitor 217
G getHighOrderPart() 106
getId(), from field object 96
get 55, 68 getInstance() 68
description of transport 172 getInterval() 128
instance 68 getLedgerName() 254
property from message 72 getLimitPolicy() 141
version 23 getLowOrderPart() 105
get (field) getMaxEvents() 142
datatype conversion during 58 getMsgEncoding() 69
get field getName()
by index 60, 65 certified delivery transport 255
field instance 66 event queue 143
get() 55 from field object 97
getAsByteArray(), message field 59 getNetwork() 173
getAsHexString() 102 getNumFields() 70
getAsString() 103 getOutboundEncoding() 71
getAsUnsignedString() 104 getPriority() 144
getAutoDispatchQueueGroup() 20 getProcessTransport() 22
getByIndex() 60 getProperty() 72
getByteSize() 61
getClosure()
CM listener 230
fault tolerance
member 201

Index 307
|
getQueue() index, get field by 65
CM listener 232 initialize message field 99
fault tolerance event 203 instance 68
fault tolerance monitor 218 instance (field)
listener 116 remove 81
timer 129 instance field
getRelayAgent() 256 get 66
getReplySubject() 73 integer, 64-bit 101
getRequestOld() 257 internal machinery
getSendSubject() 74 start (open) 25
getService() 174 stop (close) 19
getSubject() interval, timer 128
CM listener 233 reset 132
listener 117 intra-process transport 22
getSyncLedger() 258 isDetached(), message 75
getTransport() isDistributed() 285
certified delivery transport 259 isOpen() 24
fault tolerance member 204 isValid()
fault tolerance monitor 219 CM listener 234
listener 118 CM transport 260
getType(), from field object 98 fault tolerance member 206
getVcConnectSubject() 189 fault tolerance monitor 220
getVersion() 23 listener 119
getWeight() 205 message 76
getWorkerTasks() 283 queue 145
getWorkerWeight() 284 queue group 157
group name timer 130
fault tolerance 202 transport 175
fault tolerance monitor 217
group, queue 151
H Latin-1 7
ledger
hexidecimal string, 64-bit integer as 102 file 247
high order part of 64-bit integer 106 name, get 254
review 266
stop 273
sync 258, 274
I library files 16
licensed transport 168
identifier, field 38
inbox, create name 169
index, get by 60

308
| Index
limit policy mark 77
constants 133 remove field 79
get 141 reply subject 73, 86
set 147 reset 82
listener 110 send 176
callback method 120 send subject 74, 87
certified delivery 224 set property 85
create 227 time limit, CM 72, 85
destroy 229 update 89, 92
create 112 validity 76
destroy 114 monitor, fault tolerance 211
get closure 115 callback 221
get queue 116
get subject 117
get transport 118
validity 119 N
locale 7
lost interval 214 name
low order part of 64-bit integer 105 certified delivery transport 247
get name 255
event queue 143, 148
fault tolerance group 202
M fault tolerance monitor 217
nested message, get 56
mark references 37, 77 network interface 166
member, fault tolerance 195 number of fields in a message 70
callback 207
message 40, 50, 75
add field 45, 48
byte size 61 O
callback method 120
CM 235 old messages, request certified delivery 257
create 50 onCmMsg 235
create copy 51 onFtAction 207
destroy 53 onFtMonitor 221
detach 54 onMsg 120
field (as a class) 93 onTimer 131
get 55 open 25
get encoding 69 ownership, message storage 34
get field 63
get property 72
ownership and control 34
references P
clear 49
PEM 29

Index 309
|
PKCS #12 30 queue group 151
poll add queue 153
event queue 146 automatic dispatch 20
queue group 158 create 154
prepare to activate, fault tolerance 208 destroy 155
pre-register certified delivery listener 241 dispatch 156
priority, of event queue 144 poll 158
set 149 remove queue 159
property timed dispatch 160
get from message 72 validity 157
set on message 85
R
Q
raw storage device, as ledger file 247
queue reference count 19, 25
add to group 153 reference datatypes 35
CM listener 232 references
create 136 clear 49
default 21 mark 77
destroy 137 relay agent
dispatch 138 connect to 243
fault tolerance event 203 disconnect from 251
get get from certified delivery transport 256
discard amount 140 release 5, interaction
event count 139 fields with same name 39, 66, 68
from listener 116 sequence numbers, certified delivery 236
from timer 129 release number, get 23
limit policy 141 remove
max events 142 field from message 79
name 143 queue from group 159
priority 144 removeInstance, from message 81
poll 146 removeListener, certified delivery 263
set removeSendState, certified delivery 265
limit policy 147 reply
name 148 send 177
priority 149 send certified 268
timed dispatch 150 reply subject
validity 145 get 73
set 86
request
send 178
send certified 269
request old, certified delivery 257

310
| Index
reset message 82 setSendSubject 87
resetInterval, timer 132 setTaskBacklogLimit... 272
reviewLedger 266 setUserCertWithKey() 29
callback method 261 setUserCertWithKeyBin() 30
setUserNameWithPassword() 32
setWeight, fault tolerance member 210
setWorkerTasks 287
S setWorkerWeight 288
shared library files 16
secure daemon 64-bit integer 101
set daemon certificate 27 snapshot, data 36
set user certificate 29, 30 stopReview 273
set user name 32 string
send 176, 176 64-bit integer as 103
certified delivery 267 character encoding 7
certified reply 268 convert message to 88
certified request 269 subject
reply 177 CM listener 233
request 178 listener 117
send state, remove 265 reply 73, 86
send subject send 74, 87
get 74 support, contacting xxiv
set 87 sync ledger, certified delivery 274
sender correspondent name, CM 72 get 258
sendReply 177
certified delivery 268
sendRequest() 178
certified delivery 269 T
sequence number, CM 72
release 5, interaction 236 task capacity of distributed queue 283, 285, 287
service, UDP or PGM 166 TCP port, transport daemon parameter 166
setBatchMode 180 technical support xxiv
setCompleteTime 286 TIBCO_HOME xxi
setDaemonCert() 27 Tibrv 18
setDefaultInboundEncoding 83 Tibrv.close 19
setDefaultTimeLimit, certified delivery 271 Tibrv.getAutoDispatchQueueGroup() 20
setDescription 181 Tibrv.getCmVersion() 23
setExplicitConfirm 237 Tibrv.getDefaultQueue() 21
setFromString, 64-bit integer 107 Tibrv.getFtVersion() 23
setLimitPolicy() 147 Tibrv.getProcessTransport() 22
setName(), event queue 148 Tibrv.getVersion() 23
setOutboundEncoding 84 Tibrv.isOpen() 24
setPriority(), event queue 149 Tibrv.open 25
setProperty 85 TibrvCmListener 224
setReplySubject 86 TibrvCmListener_onCmMsg 235

Index 311
|
TibrvCmListener.confirmMsg 226 TibrvFtMember 195
TibrvCmListener.create 227 TibrvFtMember_onFtAction 207
TibrvCmListener.destroy 229 TibrvFtMember.create 196
TibrvCmListener.getClosure() 230 TibrvFtMember.destroy 200
TibrvCmListener.getCmTransport() 231 TibrvFtMember.getClosure() 201
TibrvCmListener.getQueue() 232 TibrvFtMember.getGroupName() 202
TibrvCmListener.getSubject() 233 TibrvFtMember.getQueue() 203
TibrvCmListener.isValid() 234 TibrvFtMember.getTransport() 204
TibrvCmListener.setExplicitConfirm 237 TibrvFtMember.getWeight() 205
TibrvCmQueueTransport.setCompleteTime 286 TibrvFtMember.isValid() 206
TibrvCmQueueTransport.setWorkerTasks 287 TibrvFtMember.setWeight 210
TibrvCmQueueTransport.setWorkerWeight 288 TibrvFtMonitor 211
TibrvCmTransport 238 TibrvFtMonitor_onFtMonitor 221
TibrvCmTransport_onLedgerMsg 261 TibrvFtMonitor.create 213
TibrvCmTransport.addListener 241 TibrvFtMonitor.destroy 215
TibrvCmTransport.allowListener 242 TibrvFtMonitor.getClosure() 216
TibrvCmTransport.connectToRelayAgent 243 TibrvFtMonitor.getGroupName() 217
TibrvCmTransport.create 245 TibrvFtMonitor.getQueue() 218
TibrvCmTransport.createDistributedQueue 279 TibrvFtMonitor.getTransport() 219
TibrvCmTransport.destroy 249 TibrvFtMonitor.isValid() 220
TibrvCmTransport.disallowListener 250 TibrvInt64 101
TibrvCmTransport.disconnectFromRelayAgent 251 TibrvInt64.getAsHexString() 102
TibrvCmTransport.expireMessages 252 TibrvInt64.getAsString() 103
TibrvCmTransport.getCompleteTime() 282 TibrvInt64.getAsUnsignedString() 104
TibrvCmTransport.getDefaultTimeLimit() 253 TibrvInt64.getHighOrderPart() 106
TibrvCmTransport.getLedgerName() 254 TibrvInt64.getLowOrderPart() 105
TibrvCmTransport.getName() 255 TibrvInt64.setFromString 107
TibrvCmTransport.getRelayAgent() 256 TibrvListener 110
TibrvCmTransport.getRequestOld() 257 TibrvListener_onMsg 120
TibrvCmTransport.getSyncLedger() 258 TibrvListener.create 112
TibrvCmTransport.getTransport() 259 TibrvListener.destroy 114
TibrvCmTransport.getWorkerTasks() 283 TibrvListener.getClosure() 115
TibrvCmTransport.getWorkerWeight() 284 TibrvListener.getQueue() 116
TibrvCmTransport.isDistributed() 285 TibrvListener.getSubject() 117
TibrvCmTransport.isValid() 260 TibrvListener.getTransport() 118
TibrvCmTransport.removeListener 263 TibrvListener.isValid() 119
TibrvCmTransport.removeSendState 265 TibrvMsg 40
TibrvCmTransport.reviewLedger 266 TibrvMsg.add 45
TibrvCmTransport.send 267 TibrvMsg.addField 48
TibrvCmTransport.sendReply 268 TibrvMsg.clearReferences 49
TibrvCmTransport.sendRequest() 269 TibrvMsg.create 50
TibrvCmTransport.setDefaultTimeLimit 271 TibrvMsg.createCopy() 51
TibrvCmTransport.setTaskBacklogLimit... 272 TibrvMsg.createFromByteArray 52
TibrvCmTransport.stopReview 273 TibrvMsg.destroy 53
TibrvCmTransport.syncLedger 274 TibrvMsg.detach 54

312
| Index
TibrvMsg.get() 55 TibrvQueue.isValid() 145
TibrvMsg.getAsByteArray() 59 TibrvQueue.poll 146
TibrvMsg.getByIndex() 60 TibrvQueue.setLimitPolicy() 147
TibrvMsg.getByteSize() 61 TibrvQueue.setName() 148
TibrvMsg.getDefaultInboundEncoding() 62 TibrvQueue.setPriority 149
TibrvMsg.getField() 63 TibrvQueue.timedDispatch 150
TibrvMsg.getFieldByIndex() 65 TibrvQueueGroup 151
TibrvMsg.getFieldInstance() 66 TibrvQueueGroup.add 153
TibrvMsg.getInstance() 68 TibrvQueueGroup.create 154
TibrvMsg.getMsgEncoding() 69 TibrvQueueGroup.destroy 155
TibrvMsg.getNumFields() 70 TibrvQueueGroup.dispatch 156
TibrvMsg.getOutboundEncoding() 71 TibrvQueueGroup.isValid() 157
TibrvMsg.getProperty() 72 TibrvQueueGroup.poll 158
TibrvMsg.getReplySubject() 73 TibrvQueueGroup.remove 159
TibrvMsg.getSendSubject() 74 TibrvQueueGroup.timedDispatch 160
TibrvMsg.isDetached() 75 TibrvSdContext 26
TibrvMsg.isValid() 76 TibrvSdContext.setDaemonCert() 27
TibrvMsg.markReferences() 77 TibrvSdContext.setUserCertWithKey() 29
TibrvMsg.remove 79 TibrvSdContext.setUserCertWithKeyBin() 30
TibrvMsg.removeInstance 81 TibrvSdContext.setUserNameWithPassword() 32
TibrvMsg.reset 82 TibrvTimer 121
TibrvMsg.setDefaultInboundEncoding 83 TibrvTimer_onTimer 131
TibrvMsg.setOutboundEncoding 84 TibrvTimer.create 124
TibrvMsg.setProperty 85 TibrvTimer.destroy 126
TibrvMsg.setReplySubject 86 TibrvTimer.getClosure() 127
TibrvMsg.setSendSubject 87 TibrvTimer.getInterval() 128
TibrvMsg.toString() 88 TibrvTimer.getQueue() 129
TibrvMsg.update 89 TibrvTimer.isValid() 130
TibrvMsg.updateField 92 TibrvTimer.resetInterval 132
TibrvMsgField 93 TibrvTransport 164
TibrvMsgField.getData() 95 TibrvTransport.create 166
TibrvMsgField.getId() 96 TibrvTransport.createAcceptVc() 186
TibrvMsgField.getName() 97 TibrvTransport.createConnectVc() 187
TibrvMsgField.getType() 98 TibrvTransport.createInbox() 169
TibrvMsgField.initialize 99 TibrvTransport.createLicensed 168
TibrvQueue 133 TibrvTransport.destroy 170
TibrvQueue.create 136 TibrvTransport.getDaemon() 171
TibrvQueue.destroy 137 TibrvTransport.getDescription() 172
TibrvQueue.dispatch 138 TibrvTransport.getNetwork() 173
TibrvQueue.getCount() 139 TibrvTransport.getService() 174
TibrvQueue.getDiscardAmount() 140 TibrvTransport.getVcConnectSubject() 189
TibrvQueue.getLimitPolicy() 141 TibrvTransport.isValid() 175
TibrvQueue.getMaxEvents() 142 TibrvTransport.send 176
TibrvQueue.getName() 143 TibrvTransport.sendReply 177
TibrvQueue.getPriority() 144 TibrvTransport.sendRequest() 178

Index 313
|
TibrvTransport.setBatchMode 180 reply 177
TibrvTransport.setDescription 181 request 178
TibrvTransport.waitForVcConnection() 190 validity 175
time limit, CM 72, 85 virtual circuit 184
get default 253 create accept 186
set default 271 create connect 187
timedDispatch wait for connection 190
queue 150
queue group 160
timer
callback method 131 U
create 124
destroy 126 unicode 7
event object 121 unsigned string, 64-bit integer as 104
get closure 127 update 89
get interval 128 updateField 92
get queue 129 user name and password, set 32
reset interval 132
validity 130
toString(), message 88
translation, character encoding 7 V
transport
batch mode, set 180 valid
certified delivery 238 CM listener 234
create 245 CM transport 260
class 164 event queue 145
CM listener 231 event queue group 157
create 166 fault tolerance member 206
embed license 168 fault tolerance monitor 220
create inbox name 169 listener 119
description message 76
get 172 snapshot data 36
set 181 timer 130
destroy 170 transport 175
certified delivery 249 version number, get 23
distributed queue 276 virtual circuit
embed license 168 get connect subject 189
fault tolerance member 204 transport 184
get daemon (TCP socket) 171 wait for connection 190
get from certified delivery transport 259
get from listener 118
get network interface 173
get service 174 W
intra-process 22
send 176 waitForVcConnection() 190

314
| Index
weight, fault tolerance
get 205
set 210
withdraw from fault tolerance group 200
worker weight, distributed queue
get 284
set 288

TIB RV Com Reference

Uploaded by

Copyright:

Available Formats

TIB RV Com Reference

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TIB RV Com Reference

Uploaded by

Copyright:

Available Formats

TIBCO Rendezvous®

New or Modified Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

TIBCO Rendezvous COM Reference

Chapter 2 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3 Rendezvous Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

Chapter 5 Events and Queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

TIBCO Rendezvous COM Reference

Chapter 6 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163

Chapter 7 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Chapter 8 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

TIBCO Rendezvous COM Reference

Chapter 9 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

TIBCO Rendezvous COM Reference

Chapter 10 Distributed Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275

Chapter 11 Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

Figure 1 VB to Wire Format Datatype Conversion Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

New or Modified Sections

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

TIBCO Rendezvous® is a messaging infrastructure product.

• Manual Organization, page xviii

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

This section lists documentation resources you may find useful.

TIBCO Rendezvous Documentation

Legend PDF HTML

The following documents form the Rendezvous documentation set:

TIBCO Rendezvous COM Reference

• TIBCO Rendezvous C++ Reference

TIBCO Rendezvous COM Reference

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

TIBCO Rendezvous installs into a version-specific directory inside TIBCO_HOME.

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

TIBCO Rendezvous COM Reference

Table 1 General Typographical Conventions (Cont’d)

Table 2 Syntax Typographical Conventions

TIBCO Rendezvous COM Reference

Table 2 Syntax Typographical Conventions

TIBCO Rendezvous COM Reference

Connecting with TIBCO Resources

How to Join TIBCOmmunity

How to Access All TIBCO Documentation

How to Contact TIBCO Support

TIBCO Rendezvous COM Reference

This chapter presents concepts specific to the TIBCO Rendezvous® COM

• General Description, page 2

TIBCO Rendezvous COM Reference

TIBCO Rendezvous COM Reference

Object Safety in Scripting Environments