TIBCO Rendezvous®

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

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

New or Modified Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
TIBCO Rendezvous Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
How to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi

Chapter 1 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Programming Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Programming Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Include These Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Link These Library Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
32-Bit UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
64-Bit UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
IBM i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
IPM Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

tibrv_Close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIBCO Rendezvous C Reference

iv
| Contents
tibrv_IsIPM() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
tibrv_Open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
tibrv_SetCodePages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
tibrv_SetRVParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
tibrv_Version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
tibrvSecureDaemon_SetDaemonCert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
tibrvSecureDaemon_SetUserCertWithKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
tibrvSecureDaemon_SetUserCertWithKeyBin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
tibrvSecureDaemon_SetUserNameWithPassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3 Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Message Operations by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Message Operations in Alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Message Ownership and Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Validity of Data Extracted From Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Scalar Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Pointer Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Deleting Snapshot References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Multiple Subscription Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Field Names and Field Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Finding a Field Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Strings and Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
tibrvLocalData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
tibrvMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
tibrvMsgDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
tibrvMsgField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
tibrvMsg_AddField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Add Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Add Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Add Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Add String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Add Opaque Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Add XML Byte Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Add DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
tibrvMsg_ClearReferences() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
tibrvMsg_ConvertToString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
tibrvMsg_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
tibrvMsg_CreateCopy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

TIBCO Rendezvous C Reference

 Contents v
|
tibrvMsg_CreateFromBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
tibrvMsg_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
tibrvMsg_Detach() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
tibrvMsg_Expand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
tibrvMsg_GetAsBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
tibrvMsg_GetAsBytesCopy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
tibrvMsg_GetByteSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
tibrvMsg_GetClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
tibrvMsg_GetCurrentTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
tibrvMsg_GetEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
tibrvMsg_GetField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Get Scalar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Get Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Get Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Get String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Get Opaque Byte Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Get XML Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Get DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
tibrvMsg_GetFieldByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
tibrvMsg_GetFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
tibrvMsg_GetNumFields() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
tibrvMsg_GetReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
tibrvMsg_GetSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
tibrvMsg_MarkReferences() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
tibrvMsg_RemoveField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
tibrvMsg_RemoveFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
tibrvMsg_Reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
tibrvMsg_SetReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
tibrvMsg_SetSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
tibrvMsg_UpdateField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Update Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Update Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Update Nested Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Update String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Update Opaque Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Update XML Byte Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Update DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

TIBCO Rendezvous C Reference

vi
| Contents

Chapter 4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Operations by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Operations in Alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
tibrvEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
tibrvEventCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
tibrvEventOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
tibrvEventVectorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
tibrvEvent_CreateIO() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
tibrvEvent_CreateListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
tibrvEvent_CreateTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
tibrvEvent_CreateVectorListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
tibrvEvent_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
tibrvEvent_DestroyEx() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
tibrvEvent_GetIOSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
tibrvEvent_GetIOType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
tibrvEvent_GetListenerSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
tibrvEvent_GetListenerTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
tibrvEvent_GetTimerInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
tibrvEvent_GetType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
tibrvEvent_GetQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
tibrvEvent_ResetTimerInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
tibrvEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
tibrvIOType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Chapter 5 Event Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Operations by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Operations in Alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
tibrvQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
tibrvQueueHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
tibrvQueueLimitPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
tibrvQueueOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
tibrvQueue_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
tibrvQueue_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
tibrvQueue_Dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
tibrvQueue_GetCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
tibrvQueue_GetHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

TIBCO Rendezvous C Reference

 Contents vii
|
tibrvQueue_GetLimitPolicy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
tibrvQueue_GetName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
tibrvQueue_GetPriority() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
tibrvQueue_Poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
tibrvQueue_RemoveHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
tibrvQueue_SetHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
tibrvQueue_SetLimitPolicy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
tibrvQueue_SetName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
tibrvQueue_SetPriority() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
tibrvQueue_TimedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 6 Event Queue Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

tibrvQueueGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
tibrvQueueGroup_Add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
tibrvQueueGroup_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
tibrvQueueGroup_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
tibrvQueueGroup_Dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
tibrvQueueGroup_Poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
tibrvQueueGroup_Remove() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
tibrvQueueGroup_TimedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Chapter 7 Dispatcher Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199

tibrvDispatchable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
tibrvDispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
tibrvDispatcher_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
tibrvDispatcher_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
tibrvDispatcher_GetName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
tibrvDispatcher_SetName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Chapter 8 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207

tibrvTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
tibrvTransportBatchMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
tibrvTransport_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
tibrvTransport_CreateInbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
tibrvTransport_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
tibrvTransport_GetDaemon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

TIBCO Rendezvous C Reference

viii
| Contents
tibrvTransport_GetDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
tibrvTransport_GetNetwork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
tibrvTransport_GetService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
tibrvTransport_RequestReliability() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
tibrvTransport_Send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
tibrvTransport_Sendv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
tibrvTransport_SendReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
tibrvTransport_SendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
tibrvTransport_SetBatchMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
tibrvTransport_SetBatchSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
tibrvTransport_SetDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Chapter 9 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

tibrvTransport_CreateAcceptVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
tibrvTransport_CreateConnectVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
tibrvTransport_WaitForVcConnection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Chapter 10 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

tibrvft_Version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
tibrvftAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
tibrvftMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
tibrvftMemberCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
tibrvftMemberOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
tibrvftMember_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
tibrvftMember_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
tibrvftMember_GetGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
tibrvftMember_GetQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
tibrvftMember_GetTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
tibrvftMember_GetWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
tibrvftMember_SetWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
tibrvftMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
tibrvftMonitorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
tibrvftMonitorOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
tibrvftMonitor_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
tibrvftMonitor_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
tibrvftMonitor_GetGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

TIBCO Rendezvous C Reference

 Contents ix
|
tibrvftMonitor_GetQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
tibrvftMonitor_GetTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Chapter 11 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269

Operations by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Operations in Alphabetical Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
tibrvcm_Version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
tibrvcmEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
tibrvcmEventCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
tibrvcmEvent_ConfirmMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
tibrvcmEvent_CreateListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
tibrvcmEvent_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
tibrvcmEvent_GetListenerSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
tibrvcmEvent_GetListenerTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
tibrvcmEvent_GetQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
tibrvcmEvent_SetExplicitConfirm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
tibrvcmTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
tibrvcmTransportOnComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
tibrvcmTransport_AddListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
tibrvcmTransport_AllowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
tibrvcmTransport_ConnectToRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
tibrvcmTransport_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
tibrvcmTransport_Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
tibrvcmTransport_DisallowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
tibrvcmTransport_DisconnectFromRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
tibrvcmTransport_ExpireMessages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
tibrvcmTransport_GetDefaultCMTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
tibrvcmTransport_GetLedgerName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
tibrvcmTransport_GetName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
tibrvcmTransport_GetRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
tibrvcmTransport_GetRequestOld() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
tibrvcmTransport_GetSyncLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
tibrvcmTransport_GetTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
tibrvcmTransport_RemoveListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
tibrvcmTransport_RemoveSendState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
tibrvcmTransport_ReviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

TIBCO Rendezvous C Reference

x
| Contents
tibrvcmReviewCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
tibrvcmTransport_Send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
tibrvcmTransport_SendReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
tibrvcmTransport_SendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
tibrvcmTransport_SetDefaultCMTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
tibrvcmTransport_SetPublisherInactivityDiscardInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
tibrvcmTransport_SyncLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
tibrvMsg_GetCMSender() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
tibrvMsg_GetCMSequence() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
tibrvMsg_GetCMTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
tibrvMsg_SetCMTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Chapter 12 Distributed Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Operations in Alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Distributed Queue Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
tibrvcmTransport_CreateDistributedQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
tibrvcmTransport_GetCompleteTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
tibrvcmTransport_GetUnassignedMessageCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
tibrvcmTransport_GetWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
tibrvcmTransport_GetWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
tibrvcmTransport_SetCompleteTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
tibrvcmTransport_SetTaskBacklogLimit...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
tibrvcmTransport_SetWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
tibrvcmTransport_SetWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Chapter 13 Datatypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Wire Format Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
C Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Datatype Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
General Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Converting to Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Chapter 14 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

tibrv_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
tibrvStatus_GetText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Appendix A Custom Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

TIBCO Rendezvous C Reference

 Contents xi
|
Operations by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Operations in Alphabetical Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Adding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Extracting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Custom Datatype Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Add and Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
tibrvMsg_SetHandlers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
tibrvMsgDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
tibrvMsgData_ByteSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
tibrvMsgData_Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
tibrvMsgData_CopyBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
tibrvMsgData_Decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
tibrvMsgData_Encoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
tibrvMsgData_GetBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
tibrvMsgData_GetSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
tibrvMsgData_Malloc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
tibrvMsgData_SetSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Appendix B Perl 5 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387

Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Installing the Perl 5 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Using the Perl 5 Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Perl Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393

TIBCO Rendezvous C Reference

xii
| Contents

TIBCO Rendezvous C Reference

 Figures xiii
|

Figures

Figure 1 Extracting a Scalar Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Figure 2 Extracting a Pointer Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Figure 3 Updating a Pointer Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Figure 4 Updating a Submessage Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Figure 5 Mark and Clear References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Figure 6 Completion when Callback Functions are in Progress. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Figure 7 Completion when Callback Functions are Not in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Figure 8 I/O Event Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Figure 9 Listener Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Figure 10 Timer Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Figure 11 Grouping Messages into Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Figure 12 Vector Listener Callbacks in a Single Dispatch Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Figure 13 Vector Listener Callbacks in Multiple Dispatch Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Figure 14 Wire Format to C Datatype Conversion Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Figure 15 Writing Fields into a Message’s Wire Buffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Figure 16 tibrvMsgData_CopyBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Figure 17 Advancing the Wire Buffer Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Figure 18 tibrvMsgData_GetBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Figure 19 tibrvMsgData_GetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Figure 20 tibrvMsgData_SetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

TIBCO Rendezvous C Reference

xiv
| Figures

TIBCO Rendezvous C Reference

 Tables xv
|

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Table 3 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Table 4 Linker Flags for 32-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Table 5 Linker Flags for 64-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Table 6 Library Files for Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 7 Library Files for VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 8 Library Files for IBM i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 9 Selecting the Communications Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Table 10 Date and Time Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Table 11 Architecture of Message and Data Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

TIBCO Rendezvous C Reference

xvi
| Tables

TIBCO Rendezvous C Reference

 New or Modified Sections
| xvii

New or Modified Sections

IBM i. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
tibrvcmTransport_CreateDistributedQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
tibrvcmTransport_SetWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

TIBCO Rendezvous C Reference

xviii New or Modified Sections
|

TIBCO Rendezvous C Reference

 Preface xix
|

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 C programmers. It is part
of the documentation set for Rendezvous Software Release 8.4.0.

Topics

• Manual Organization, page xx

• Related Documentation, page xxi
• Typographical Conventions, page xxiii
• Connecting with TIBCO Resources, page xxvi

TIBCO Rendezvous C Reference

xx
| Manual Organization

Manual Organization

The organization of this book mirrors the underlying object structure of the
Rendezvous C API. Each chapter describes a group of closely related objects and
the functions that pertain to them.
Within each chapter, functions appear in alphabetical order.

TIBCO Rendezvous C Reference

 Preface xxi
|

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.

TIBCO Rendezvous C Reference

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

TIBCO Rendezvous C Reference

 Preface xxiii
|

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]

TIBCO Rendezvous C Reference

xxiv 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

TIBCO Rendezvous C Reference

 Preface xxv
|

Table 2 Syntax Typographical Conventions

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

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

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

TIBCO Rendezvous C Reference

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

TIBCO Rendezvous C Reference

 Programmer’s Checklist 1
|

Chapter 1 Programmer’s Checklist

This chapter presents important general information for programmers using

TIBCO Rendezvous® software.

Topics

• Programming Environment, page 2

• Programming Restrictions, page 3
• Include These Header Files, page 4
• Link These Library Files, page 5

TIBCO Rendezvous C Reference

2
| Chapter 1 Programmer’s Checklist

Programming Environment

When developing or deploying TIBCO Rendezvous® C programs, remember

these steps.

Code
• Include the appropriate Rendezvous C header files; see Include These Header
Files on page 4.
• Include the same header files whether the program communicates through a
Rendezvous daemon or using TIBCO Rendezvous® Server In-Process Module
(IPM).

Compile
• Compile programs with an ANSI-compliant C compiler.
• VMS requires programmers to define the compile command; see VMS on
page 10.

Link
• Link with the appropriate Rendezvous C library files; see Link These Library
Files on page 5.
• VMS requires programmers to define the link command; see VMS on page 10.

Run
• Be sure that the Rendezvous daemon can run on each application host
computer. The user’s path must contain a version appropriate for the
application host. For more information, see Rendezvous Daemon (rvd) on
page 41 in TIBCO Rendezvous Administration.
• Be sure that the Rendezvous daemon process (or the application program
process with IPM) can access the Rendezvous license ticket file, tibrv.tkt.
The user’s path must contain this file. For more information, see Licensing
Information on page 11 in TIBCO Rendezvous Administration.

TIBCO Rendezvous C Reference

 Programming Restrictions 3
|

Programming Restrictions

In general, it is illegal to call Rendezvous functions from inside signal handlers.

TIBCO Rendezvous C Reference

4
| Chapter 1 Programmer’s Checklist

Include These Header Files

Rendezvous C programs must include the appropriate header files from this list.

Table 3 Header Files

Header File Description

Communications, Events and Data
All programs must include this API header file.

tibrv/tibrv.h Include this header file for the Rendezvous C API.

Certified Message Delivery and Distributed Queue

tibrv/cm.h Include this header file for the Rendezvous certified

message delivery and distributed queue C API. Including
cm.h automatically includes tibrv.h too.

Fault Tolerance

tibrv/ft.h Include this header file for the Rendezvous fault tolerance
C API. Including ft.h automatically includes tibrv.h
too.

Secure Daemons and OpenSSL

Programs that connect to secure daemons (rvsd, rvsrd) must include this
header file.

tibrv/sd.h Include this header file for the Rendezvous secure daemon
C API.

TIBCO Rendezvous C Reference

 Link These Library Files 5
|

Link These Library Files

Rendezvous C programs must link the appropriate library files. Choose from the
appropriate table based on operating system platform:
• 32-Bit UNIX, page 5
• 64-Bit UNIX, page 6
• Microsoft Windows, page 7
• VMS, page 10
• IBM i, page 12

See Also IPM Library on page 14

TIBCO Rendezvous for z/OS Installation and Configuration

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

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

Linker Flag Description

Communications, Data and Event Manager
All programs must link this library.

-ltibrv Programs that connect to ordinary daemons (rvd, rvrd)

must link using this library flag.

Secure Daemon

-ltibrvsd Programs that connect to secure daemons (rvsd, rvsrd)

-lssl
must also link using these three flags.
-lcrypto

TIBCO Rendezvous C Reference

6
| Chapter 1 Programmer’s Checklist

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

Linker Flag Description

Certified Message Delivery, Fault Tolerance, and Distributed Queues
Programs may also link one or more of these libraries as needed.

-ltibrvcm Programs that use certified message delivery must link

using this library flag.
Programs that use distributed queues must link using this
library flag.

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

-ltibrvcmq Programs that use distributed queues must link using this
library flag.
In addition, distributed queue programs also use
communications, certified message delivery, and fault
tolerance libraries; they must link with appropriate flags
from those groups.

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

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

Linker Flag Description

Communications, Data and Event Manager
All programs must link this library.

-ltibrv64 Programs that connect to ordinary daemons (rvd, rvrd)

must link using this library flag.

Secure Daemon

-ltibrvsd64 Programs that connect to secure daemons (rvd, rvrd) must

link using this library flag.

TIBCO Rendezvous C Reference

 Link These Library Files 7
|

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

Linker Flag Description

Certified Message Delivery, Fault Tolerance, and Distributed Queues
Programs may also link one or more of these libraries as needed.

-ltibrvcm64 Programs that use certified message delivery must link

using this library flag.
Programs that use distributed queues must link using this
library flag.

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

-ltibrvcmq64 Programs that use distributed queues must link using this
library flag.
In addition, distributed queue programs also use
communications, certified message delivery, and fault
tolerance libraries; they must link with appropriate flags
from those groups.

Microsoft Windows
Release 8.4.0 supports the following combinations:
• 32-bit Windows (XP, Server 2003, Server 2008, Vista)
• 64-bit Windows (XP, Server 2003, Server 2008, Vista)

Both DLLs and static libraries are available. We recommend DLLs to ease forward
migration.

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

Library File Description

Communications, Data and Event Manager
All programs must link only one of these libraries.

tibrv.lib Rendezvous C library.

DLL (import library).

TIBCO Rendezvous C Reference

8
| Chapter 1 Programmer’s Checklist

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

Library File Description

libtibrv.lib Rendezvous C library.
Static library, for use with the /MT compiler option.

libtibrvmd.lib Rendezvous C library.

Static library, for use with the /MD compiler option.

Secure Daemon
Programs that connect to secure daemons (rvsd, rvsrd) must link only one of
these sets of libraries.

tibrvsd.lib Secure daemon additions.

libeay32.lib
ssleay32.lib DLL (import library).

libtibrvsd.lib Secure daemon additions.

libeay32.lib
ssleay32.lib Static library, for use with the /MT compiler option.

libtibrvsdmd.lib Secure daemon additions.

libeay32.lib
ssleay32.lib Static library, for use with the /MD compiler option.

Certified Message Delivery

Programs that use certified message delivery must link only one of these
libraries.
Programs that use distributed queues must link only one of these libraries.

tibrvcm.lib Rendezvous certified message delivery software.

DLL (import library).

libtibrvcm.lib Rendezvous certified message delivery software.

Static library, for use with the /MT compiler option.

libtibrvcmmd.lib Rendezvous certified message delivery software.

Static library, for use with the /MD compiler option.

TIBCO Rendezvous C Reference

 Link These Library Files 9
|

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

Library File Description

Fault Tolerance
Programs that use fault tolerance must link only one of these libraries.
Programs that use distributed queues must link only one of these libraries.

tibrvft.lib Rendezvous fault tolerance software.

DLL (import library).

libtibrvft.lib Rendezvous fault tolerance software.

Static library, for use with the /MT compiler option.

libtibrvftmd.lib Rendezvous fault tolerance software.

Static library, for use with the /MD compiler option.

Distributed Queue
Programs that use distributed queues must link only one of these libraries.
In addition, distributed queue programs also use certified message delivery,
and fault tolerance libraries; they must link appropriate libraries from those
groups.

tibrvcmq.lib Rendezvous distributed queue software.

DLL (import library).

libtibrvcmq.lib Rendezvous distributed queue software.

Static library, for use with the /MT compiler option.

libtibrvcmqmd.lib Rendezvous distributed queue software.

Static library, for use with the /MD compiler option.

TIBCO Rendezvous C Reference

10
| Chapter 1 Programmer’s Checklist

VMS
In VMS environments, both shared and static libraries are available. We
recommend shared libraries to ease forward migration.

Migrating to Release 8.x

Forward Migration
In general, applications linked with shareable images migrate forward to new
versions of TIBCO Rendezvous without any need to relink; they usually operate
smoothly with newer shareable images.
Exception: In Rendezvous release 8.0, we reorganized the Rendezvous shareable
image libraries on OpenVMS platforms, in order to resolve issues with third-party
libraries. As a result, you must relink applications linked with shareable image
libraries when you upgrade across this division (from 7.5.4 or earlier, to 8.0 or
later, on OpenVMS).

Older Shareable Libraries

Applications that link with sharable images usually cannot run with older
shareable libraries (from earlier Rendezvous releases). The reason is that new
releases can introduce new entry points, which are absent from older shareable
libraries.
This incompatibility can cause problems if you link an application against a
current shareable library, and then distribute it to other host computers where it
runs with older shareable libraries.

Compile
On VMS platforms, Rendezvous programmers must define the C-compile
command appropriately.
For the HP C compiler:
$ CC :== CC/FLOAT=IEEE/IEEE_MODE=UNDERFLOW_TO_ZERO -
/PREFIX=ALL/INCLUDE_DIRECTORY=("/tibrv/include",[])

Link
Rendezvous API libraries are multi-threaded, so VMS scheduler upcalls can yield
significant performance improvements:
$ LINK/THREADS_ENABLE=UPCALLS

TIBCO Rendezvous C Reference

 Link These Library Files 11
|

Library Files

Table 7 Library Files for VMS (Sheet 1 of 2)

Library File Description

Communications, Data and Event Manager
All programs must link only one of these libraries.

libtibrv.olb Rendezvous C library.

Static library.

libtibrvshr.exe Rendezvous C library.

VMS sharable image.

Secure Daemon
Programs that connect to secure daemons (rvsd, rvsrd) must link only one of
these sets of libraries.

libtibrvsd.olb Secure daemon additions.

libcrypto.olb
libssl.olb Static library.

libtibrvsdshr.exe Secure daemon additions.

libcryptoshr.exe
libsslshr.exe VMS sharable image.

Certified Message Delivery

Programs that use certified message delivery must link only one of these
libraries.
Programs that use distributed queues must link only one of these libraries.

libtibrvcm.olb Rendezvous certified message delivery software.

Static library.

libtibrvcmshr.exe Rendezvous certified message delivery software.

VMS sharable image.

TIBCO Rendezvous C Reference

12
| Chapter 1 Programmer’s Checklist

Table 7 Library Files for VMS (Sheet 2 of 2)

Library File Description

Fault Tolerance
Programs that use fault tolerance must link only one of these libraries.
Programs that use distributed queues must link only one of these libraries.

libtibrvft.olb Rendezvous fault tolerance software.

Static library.

libtibrvftshr.exe Rendezvous fault tolerance software.

VMS sharable image.

Distributed Queue
Programs that use distributed queues must link only one of these libraries.
In addition, distributed queue programs also use certified message delivery,
and fault tolerance libraries; they must link appropriate libraries from those
groups.

libtibrvcmq.olb Rendezvous distributed queue software.

Static library.

libtibrvcmqshr.exe Rendezvous distributed queue software.

VMS sharable image.

IBM i
This section contains information specific to IBM i platforms.

Compile & Link

In the following command lines, the slash character (/) is a literal; it does not
mean either or.

1. Add the Rendezvous installation library to the library search path:

ADDLIBLE(RV_installation_library)

2. Compile:

TIBCO Rendezvous C Reference

 Link These Library Files 13
|

CRTCMOD MODULE(module_library_name/module_name)
SRCFILE(source_library_name/source_file_name) SRCMBR(source_member)
LANGLVL(*EXTENDED) PFROPT(*STRDONLY) DEFINE(_MULTI_THREADED)

3. Link:
CRTPGM PGM(program_library/program_name)
MODULE(module_library_name/module_name)
BNDSRVPGM(optional_RV_libraries LIBTIBRV)

Library Files

Table 8 Library Files for IBM i

Library File Description

Communications, Data and Event Manager
All programs must link this library.

LIBTIBRV Rendezvous C library.

Certified Message Delivery

Programs that use certified message delivery must link this library.
Programs that use distributed queues must link this library.

LIBTIBRVCM Rendezvous certified message delivery software.

Fault Tolerance
Programs that use fault tolerance must link this library.
Programs that use distributed queues must link this library.

LIBTIBRVFT Rendezvous fault tolerance software.

Distributed Queue
Programs that use distributed queues must link this library.
In addition, distributed queue programs also use certified message delivery
and fault tolerance libraries; they must link those libraries.

LIBTIBRVC0 Rendezvous distributed queue software.

TIBCO Rendezvous C Reference

14
| Chapter 1 Programmer’s Checklist

IPM Library

Linking commands are identical whether a C program uses standard Rendezvous

communication library or the IPM library. To select between these two libraries,
modify the library path environment variable according to Table 9.

Table 9 Selecting the Communications Library

Library Instructions
Rendezvous Standard Ensure that the subdirectory TIBCO_HOME/lib appears before
Communications Library TIBCO_HOME/lib/ipm in your library path environment variable.
For static linking, you may reference the standard library by an
explicit pathname (TIBCO_HOME/lib/library_name).

Rendezvous IPM Ensure that the subdirectory TIBCO_HOME/lib/ipm appears before

Communications Library TIBCO_HOME/lib in your library path environment variable.
For static linking, you may (as an alternative) reference the standard
library by an explicit pathname (TIBCO_HOME/lib/ipm/library_name).

Existing Rendezvous applications linked against the standard shared library do

not require modifications in order to link instead against the IPM library.

TIBCO Rendezvous C Reference

 | 15

Chapter 2 Environment

This chapter describes the functions relating to the global internal machinery
upon which Rendezvous software depends.

Topics

Function Description Page

tibrv_Close() Stop and destroy Rendezvous 17
internal machinery.

tibrv_Open() Create and start Rendezvous 19

internal machinery.

tibrv_Version() Identify the Rendezvous API 24

release number.

Secure Daemon

tibrvSecureDaemon_SetDaemonCert() Register trust in a secure daemon. 25

tibrvSecureDaemon_SetUserCertWithKey() Register a (PEM) certificate with 27

private key for identification to
secure daemons.

tibrvSecureDaemon_SetUserCertWithKeyBin() Register a (PKCS #12) certificate 28

with private key for identification
to secure daemons.

tibrvSecureDaemon_SetUserNameWithPassword() Register a (PEM) certificate with 29

private key for identification to
secure daemons.

TIBCO Rendezvous C Reference

16
| Chapter 2 Environment

Function Description Page

IPM

tibrv_IsIPM() Test whether IPM is operating. 18

tibrv_OpenEx() Create and start Rendezvous 19

internal machinery.

tibrv_SetRVParameters() Set Rendezvous daemon 23

command line parameters for
IPM.

EBCDIC

tibrv_SetCodePages() Set code pages for automatic 21

string conversion on EBCDIC
platforms (namely, IBM i and
z/OS).

TIBCO Rendezvous C Reference

 tibrv_Close() 17
|

tibrv_Close()
Function

Declaration tibrv_status tibrv_Close(void);

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 and queues are unusable, so programs can no longer dispatch
events.
• All transports are unusable, so programs can no longer send outbound
messages.

tibrv_Close() frees storage associated with events, queues, queue groups,

transports and dispatcher threads. However, tibrv_Close() does not destroy
Rendezvous messages; the program must explicitly destroy messages to reclaim
their storage.
Programs can call tibrv_Close() in any thread.

Reference Count A reference count protects against interactions between programs and third-party
packages that call tibrv_Open() and tibrv_Close(). Each call to tibrv_Open()
increments an internal counter; each call to tibrv_Close() decrements that
counter. A call to tibrv_Open() actually creates internal machinery only when
the reference counter is zero; subsequent calls merely increment the counter, but
do not duplicate the machinery. A call to tibrv_Close() actually destroys the
internal machinery only when the call decrements the counter to zero; other calls
merely decrement the counter. In each program, the number of calls to
tibrv_Open() and tibrv_Close() must match.

See Also tibrv_Open() on page 19

TIBCO Rendezvous C Reference

18
| Chapter 2 Environment

tibrv_IsIPM()
Function

Declaration tibrv_bool tibrv_IsIPM(void);

Purpose Test whether IPM is operating.

Remarks You can use this call to determine whether an application program process has
linked the IPM library. You can test that your program dynamically links the
correct library. You can program different behavior depending on which library is
linked.
TIBRV_TRUE indicates that the program links the IPM library (from the lib/ipm/
subdirectory).
TIBRV_FALSE indicates that the program links the standard Rendezvous library
(from the lib/ directory).

TIBCO Rendezvous C Reference

 tibrv_Open() 19
|

tibrv_Open()
Function

Declaration tibrv_status tibrv_Open(void);

tibrv_status tibrv_OpenEx(
const char *pathname);

Purpose Create and 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,
queues, and transports are unusable. However, calls that manipulate messages do
not require this machinery, and programs may use them before calling
tibrv_Open().

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.

IPM Programs that use IPM can start the Rendezvous machinery either with
tibrv_Open or with tibrv_OpenEx. The extended call is available only with IPM.
When IPM is not available, the extended call fails with error status.

TIBCO Rendezvous C Reference

20
| Chapter 2 Environment

The extended call accepts a filepath name, which explicitly specifies a

configuration file. IPM reads parameter values from that file.

Parameter Description
pathname Programs that use IPM can supply a filepath name, which
explicitly specifies a configuration file. IPM reads parameter
values from that file.
For details, see Configuring IPM on page 248 in TIBCO
Rendezvous Concepts.
When IPM is not available, this version of the method fails with
error status.
Not supported for Visual Basic.

Example 1 IPM: Specifying a Configuration File

char* cfgfile = "/var/tmp/mycfgfile"
tibrv_OpenEx(cfgfile);

See Also tibrv_Close() on page 17

Configuring IPM on page 248 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrv_SetCodePages() 21
|

tibrv_SetCodePages()
Function

Declaration tibrv_status tibrv_SetCodePages(

char* host_codepage,
char* net_codepage);

Purpose Set code pages for automatic string conversion on EBCDIC platforms (namely,
IBM i and z/OS).

String Rendezvous software uses the operating system’s iconv() call to automatically
Conversion convert strings. This automatic conversion applies to strings within message
fields, field names, subject names, and other strings associated with messages
(even when they are not strictly inside a message). Conversion occurs only as
needed:
• Programs running in EBCDIC environments represent all strings using an
EBCDIC code page (called the host code page). Before inserting strings into a
message object, Rendezvous software converts those strings to an ASCII
character set (the network code page).
• Conversely, when extracting strings from a message object, Rendezvous
software converts those strings to the EBCDIC host code page before
presenting the strings to the program.

Remarks This call sets the host and network code pages for string conversions in EBCDIC
environments. On other operating system platforms, this call has no effect, and
returns without error.
Call this function when the system code pages differ from the Rendezvous default
code pages (see the table of Default Code Pages on page 22). Throughout an
enterprise, all sending and receiving programs must use the same code pages.
Both arguments are string names of code pages. To determine valid code page
names for your operating system, see documentation from the operating system
vendor.
Programs may call this function at most once. The call must precede the first call
to tibrv_Open().

(Sheet 1 of 2)

Parameter Description
host_codepage Set this code page as the native (EBCDIC) character encoding for the host
computer.

TIBCO Rendezvous C Reference

22
| Chapter 2 Environment

(Sheet 2 of 2)

Parameter Description
net_codepage Set this code page as the ASCII character set for the network.

Default Code To use a default code page, programs may supply NULL for either parameter.
Pages Using the default code pages in both parameter positions has the same effect as
not calling this function at all.

OS Platform Default Host Code Page Default Network Code Page

IBM i "00000" "00819"

This value instructs IBM i routines to

use the system-defined default code
page.

z/OS "IBM-1047" "ISO8859-1"

See Also Strings and Character Encodings on page 49

TIBCO Rendezvous C Reference

 tibrv_SetRVParameters() 23
|

tibrv_SetRVParameters()
Function

Declaration tibrv_status tibrv_SetRVParameters(

tibrv_u32 argc,
const char** argv );

Purpose Set Rendezvous daemon command line parameters for IPM.

Remarks The Rendezvous daemon process (rvd) accepts several command line parameters.
When IPM serves the role of the daemon, this function lets you supply those
parameters from within the application program.
This call is optional. When this call is present, it must precede the call to
tibrv_Open(). For interaction semantics, see Parameter Configuration—
Precedence and Interaction on page 249 in TIBCO Rendezvous Concepts.
This call is available only with IPM. When IPM is not available, this call fails with
error status.

Parameter Description
argc Supply the number of strings in the argument vector.

argv Supply an array of null-terminated strings. Each string is either a command

line parameter name (for example, -logfile) or its value.
For details about parameters, see rvd on page 42 in TIBCO Rendezvous
Administration

Example 2 IPM: Configuring Parameters In Program Code

const char* rvParams[] = {"-reliability", "3",
"-reuse-port", "30000"};
tibrv_SetRVParameters(sizeof(rvParams)/sizeof(char*), rvParams);
tibrv_Open();

See Also Configuring IPM on page 248 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

24
| Chapter 2 Environment

tibrv_Version()
Function

Declaration const char* tibrv_Version(void);

Purpose Identify the Rendezvous API release number.

TIBCO Rendezvous C Reference

 tibrvSecureDaemon_SetDaemonCert() 25
|

tibrvSecureDaemon_SetDaemonCert()
Function

Declaration tibrv_status tibrvSecureDaemon_SetDaemonCert(

const char* daemonName,
const char* daemonCert);

#define TIBRV_SECURE_DAEMON_ANY_NAME (NULL)

#define TIBRV_SECURE_DAEMON_ANY_CERT (NULL)

Purpose Register trust in a secure daemon.

Remarks When any program transport connects to a secure daemon, it verifies the
daemon’s identity using SSL protocols. Certificates registered using this function
identify trustworthy daemons. Programs divulge user names and passwords to
daemons that present registered certificates.

Parameter Description
daemonName Register a certificate for a secure daemon with this name. For
the syntax and semantics of this parameter, see Daemon
Name, below.

daemonCert Register this public certificate. The text of this certificate must
be in PEM encoding.
See also Certificate on page 26.

Daemon Name The daemon name is a three-part string of the form:

ssl:host:port_number

This string must be identical to the string you supply as the daemon argument to
the transport creation call; see tibrvTransport_Create() on page 211.
Colon characters (:) separate the three parts.
ssl indicates the protocol to use when attempting to connect to the daemon.
host indicates the host computer of the secure daemon. You can specify this host
either as a network IP address, or a hostname. Omitting this part specifies the
local host.
port_number specifies the port number where the secure daemon listens for SSL
connections.
(This syntax is similar to the syntax connecting to remote daemons, with the
addition of the prefix ssl.)

TIBCO Rendezvous C Reference

26
| Chapter 2 Environment

In place of this three-part string, you can also supply the constant
TIBRV_SECURE_DAEMON_ANY_NAME. This form lets you register a catch-all
certificate that applies to any secure daemon for which you have not explicitly
registered another certificate. For example, you might use this form when several
secure daemons share the same certificate.

Certificate For important details, see CA-Signed Certificates on page 177 in TIBCO
Rendezvous Administration.
In place of an actual certificate, you can also supply the constant
TIBRV_SECURE_DAEMON_ANY_CERT. The program accepts any certificate from the
named secure daemon. For example, you might use this form when testing a
secure daemon configuration, before generating any actual certificates.

Any Name and Notice that the constants TIBRV_SECURE_DAEMON_ANY_NAME and

Any Certificate TIBRV_SECURE_DAEMON_ANY_CERT each eliminate one of the two security checks
before transmitting sensitive identification data to a secure daemon. We strongly
discourage using both of these constants simultaneously, because that would
eliminate all security checks, leaving the program vulnerable to unauthorized
daemons.

TIBCO Rendezvous C Reference

 tibrvSecureDaemon_SetUserCertWithKey() 27
|

tibrvSecureDaemon_SetUserCertWithKey()
Function

Declaration tibrv_status tibrvSecureDaemon_SetUserCertWithKey(

const char* userCertWithKey,
const char* password);

Purpose Register a (PEM) certificate with private key for identification to secure daemons.

Remarks When any program transport connects to a secure daemon, the daemon verifies
the program’s identity using SSL protocols.
The Rendezvous API includes two functions that achieve similar effects:
• This call accepts a certificate in PEM text format.
• tibrvSecureDaemon_SetUserCertWithKeyBin() accepts a certificate in
PKCS #12 binary format.

Parameter Description
userCertWithKey Register this user certificate with private key. The text of
these certificates must be in PEM encoding.

password Use this password to decrypt the private key.

For important information about password security, see Security Factors on

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

Errors Error status code TIBRV_INVALID_FILE can indicate either disk I/O failure, or
invalid certificate data, or an incorrect password.

See Also tibrvSecureDaemon_SetUserCertWithKeyBin() on page 28

TIBCO Rendezvous C Reference

28
| Chapter 2 Environment

tibrvSecureDaemon_SetUserCertWithKeyBin()
Function

Declaration tibrv_status tibrvSecureDaemon_SetUserCertWithKeyBin(

const void* userCertWithKey,
tibrv_u32 userCertWithKey_size,
const char* password);

Purpose Register a (PKCS #12) certificate with private key for identification to secure
daemons.

Remarks When any program transport connects to a secure daemon, the daemon verifies
the program’s identity using SSL protocols.
The Rendezvous API includes two functions that achieve similar effects:
• This call accepts a certificate in PKCS #12 binary format.
• tibrvSecureDaemon_SetUserCertWithKey() accepts a certificate in PEM
text format.

Parameter Description
userCertWithKey Register this user certificate with private key. The binary data of this
certificate must be in PKCS #12 format.

userCertWithKey_size The length (in bytes) of the certificate data.

password Use this password to decrypt the private key.

For important information about password security, see Security Factors on

page 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). For important
details, see CA-Signed Certificates on page 177 in TIBCO Rendezvous
Administration.

Errors Error status code TIBRV_INVALID_FILE can indicate either disk I/O failure, or
invalid certificate data, or an incorrect password.

See Also tibrvSecureDaemon_SetUserCertWithKey() on page 27

www.rsasecurity.com/rsalabs/pkcs

TIBCO Rendezvous C Reference

 tibrvSecureDaemon_SetUserNameWithPassword() 29
|

tibrvSecureDaemon_SetUserNameWithPassword()
Function

Declaration tibrv_status tibrvSecureDaemon_SetUserNameWithPassword(

const char* userName,
const char* password);

Purpose Register a user name with password for identification to secure daemons.

Remarks When any program transport connects to a secure daemon, them daemon verifies
the program’s identity using SSL protocols.

Parameter Description
userName Register this user name for communicating with secure
daemons.

password Register this password for communicating with secure

daemons.

For important information about password security, see Security Factors on

page 177 in TIBCO Rendezvous Administration.

TIBCO Rendezvous C Reference

30
| Chapter 2 Environment

TIBCO Rendezvous C Reference

 | 31

Chapter 3 Messages

Messages are the central unit of information that Rendezvous programs

exchange.
This chapter describes messages and the functions that manipulate them.

Topics

• Message Operations by Functional Group, page 32

• Message Operations in Alphabetical Order, page 36
• Message Ownership and Control, page 40
• Validity of Data Extracted From Messages, page 41
• Field Names and Field Identifiers, page 46
• Strings and Character Encodings, page 49

TIBCO Rendezvous C Reference

32
| Chapter 3 Messages

Message Operations by Functional Group

(Sheet 1 of 4)

Function Description Page

Message Life Cycle

tibrvMsg_Create() Allocate storage and initialize it as a new 70

message.

tibrvMsg_CreateCopy() Copy a message. 71

tibrvMsg_Destroy() Destroy a message; free the storage that it 73

occupies.

tibrvMsg_Detach() Detach an inbound message from 74

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

tibrvMsg_Expand() Enlarge a message by allocating 75

additional storage.

tibrvMsg_Reset() Clear a message, preparing it for re-use. 111

Message Attributes

tibrvMsg_GetNumFields() Extract the number of fields in a message. 103

tibrvMsg_GetByteSize() Return the size of a message (in bytes). 78

tibrvMsg_ConvertToString() Format a message as a string. 69

Address Attributes

tibrvMsg_GetSendSubject() Extract the subject from a message. 105

tibrvMsg_SetSendSubject() Set the subject for a message. 113

tibrvMsg_GetReplySubject() Extract the reply subject from a message. 104

tibrvMsg_SetReplySubject() Set the reply subject for a message. 112

TIBCO Rendezvous C Reference

 Message Operations by Functional Group 33
|

(Sheet 2 of 4)

Function Description Page

Message Fields

tibrvMsg_AddField() Add a field to a message. 56

Add Scalar 59

Add Array 61

Add Nested Message 63

Add String 64

Add Opaque Byte Sequence 65

Add XML Byte Sequence 66

Add DateTime 67

tibrvMsg_GetField() Get a specified field from a message. 82

Get Scalar 86

Get Array 88

Get Nested Message 90

Get String 92

Get Opaque Byte Sequence 94

Get XML Byte Sequence 96

Get DateTime 98

tibrvMsg_GetFieldByIndex() Get a field from a message by an index. 100

tibrvMsg_GetFieldInstance() Get a specified instance of a field from a 101

message.

tibrvMsg_RemoveField() Remove a field from a message. 108

tibrvMsg_RemoveFieldInstance() Remove a specified instance of a field 110

from a message.

TIBCO Rendezvous C Reference

34
| Chapter 3 Messages

(Sheet 3 of 4)

Function Description Page

tibrvMsg_UpdateField() Update a field within a message. 114

Update Scalar 117

Update Array 119

Update Nested Message 121

Update String 122

Update Opaque Byte Sequence 123

Update XML Byte Sequence 124

Update DateTime 125

Archiving Messages as Byte Sequences

tibrvMsg_CreateFromBytes() Create a new message, and populate it 72

with data.

tibrvMsg_GetAsBytes() Extract the data from a message as a byte 76

sequence.

tibrvMsg_GetAsBytesCopy() Extract a copy of the data from a message 77

as a byte sequence.

Deleting Snapshot References

tibrvMsg_ClearReferences() Clear references in this message. 68

tibrvMsg_MarkReferences() Mark references in this message. 106

Dispatch Attributes

tibrvMsg_GetClosure() Extract the closure object corresponding to 79

a (dispatched) message object.

tibrvMsg_GetEvent() Extract the event associated with a 81

(dispatched) message object.

Utilities

tibrvMsg_GetCurrentTime() Get the current time. 80

TIBCO Rendezvous C Reference

 Message Operations by Functional Group 35
|

(Sheet 4 of 4)

Function Description Page

Types

tibrvLocalData This type is the union of all the datatypes 50

that a Rendezvous message can contain as
data in a message field.

tibrvMsg This type represents inbound or outbound 52

Rendezvous messages.

tibrvMsgDateTime Represents dates and times. 53

tibrvMsgField Fields hold data within messages. 55

Programs manipulate the content of field
structs using the public struct accessors of
this type.

Custom Datatypes

tibrvMsg_SetHandlers() Define a program-specific datatype, by 369

registering functions to transfer it between
local format and wire format, and convert
it to other datatypes.

TIBCO Rendezvous C Reference

36
| Chapter 3 Messages

Message Operations in Alphabetical Order

(Sheet 1 of 4)

Function Description Page

tibrvLocalData This type is the union of all the datatypes 50
that a Rendezvous message can contain as
data in a message field.

tibrvMsg This type represents inbound or outbound 52

Rendezvous messages.

tibrvMsgDateTime Represents dates and times. 53

tibrvMsgField Fields hold data within messages. 55

Programs manipulate the content of field
structs using the public struct accessors of
this type.

tibrvMsg_AddField() Add a field to a message. 56

Add Scalar 59

Add Array 61

Add Nested Message 63

Add String 64

Add Opaque Byte Sequence 65

Add XML Byte Sequence 66

Add DateTime 67

tibrvMsg_ClearReferences() Clear references in this message. 68

tibrvMsg_ConvertToString() Format a message as a string. 69

tibrvMsg_Create() Allocate storage and initialize it as a new 70

message.

TIBCO Rendezvous C Reference

 Message Operations in Alphabetical Order 37
|

(Sheet 2 of 4)

Function Description Page

tibrvMsg_CreateCopy() Copy a message. 71

tibrvMsg_CreateFromBytes() Create a new message, and populate it 72

with data.

tibrvMsg_Destroy() Destroy a message; free the storage that it 73

occupies.

tibrvMsg_Detach() Detach an inbound message from 74

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

tibrvMsg_Expand() Enlarge a message by allocating 75

additional storage.

tibrvMsg_GetAsBytes() Extract the data from a message as a byte 76

sequence.

tibrvMsg_GetAsBytesCopy() Extract a copy of the data from a message 77

as a byte sequence.

tibrvMsg_GetByteSize() Return the size of a message (in bytes). 78

tibrvMsg_GetClosure() Extract the closure object corresponding 79

to a (dispatched) message object.

tibrvMsg_GetCurrentTime() Get the current time. 80

tibrvMsg_GetEvent() Extract the event associated with a 81

(dispatched) message object.

TIBCO Rendezvous C Reference

38
| Chapter 3 Messages

(Sheet 3 of 4)

Function Description Page

tibrvMsg_GetField() Get a specified field from a message. 82

Get Scalar 86

Get Array 88

Get Nested Message 90

Get String 92

Get Opaque Byte Sequence 94

Get XML Byte Sequence 96

Get DateTime 98

tibrvMsg_GetFieldByIndex() Get a field from a message by an index. 100

tibrvMsg_GetFieldInstance() Get a specified instance of a field from a 101

message.

tibrvMsg_GetNumFields() Extract the number of fields in a message. 103

tibrvMsg_GetReplySubject() Extract the reply subject from a message. 104

tibrvMsg_MarkReferences() Mark references in this message. 106

tibrvMsg_GetSendSubject() Extract the subject from a message. 105

tibrvMsg_RemoveField() Remove a field from a message. 108

tibrvMsg_RemoveFieldInstance() Remove a specified instance of a field 110

from a message.

tibrvMsg_Reset() Clear a message, preparing it for re-use. 111

tibrvMsg_SetHandlers() Define a program-specific datatype, by 369

registering functions to transfer it between
local format and wire format, and convert
it to other datatypes.

tibrvMsg_SetReplySubject() Set the reply subject for a message. 112

tibrvMsg_SetSendSubject() Set the subject for a message. 113

TIBCO Rendezvous C Reference

 Message Operations in Alphabetical Order 39
|

(Sheet 4 of 4)

Function Description Page

tibrvMsg_UpdateField() Update a field within a message. 114

Update Scalar 117

Update Array 119

Update Nested Message 121

Update String 122

Update Opaque Byte Sequence 123

Update XML Byte Sequence 124

Update DateTime 125

TIBCO Rendezvous C Reference

40
| Chapter 3 Messages

Message Ownership and Control

When a C program creates a message, the program owns that message. The
program is responsible for destroying that message when it no longer needs the
storage. That is, every create message operation must be paired with a destroy
message operation.
In contrast, when Rendezvous software creates a message, then Rendezvous
software owns that message. This situation occurs only in the case of inbound
messages presented to a callback function; Rendezvous software destroys such
messages when the callback function returns, unless the program explicitly
detaches the message first. After a detach operation, the program owns the
message, and must explicitly destroy it to reclaim the storage.
Rendezvous software controls the storage in which all messages reside—even
messages that the program owns. Programs must not directly modify the storage
in which a message resides. Programs may change the contents of a message only
by using Rendezvous functions that add, remove or update fields.

TIBCO Rendezvous C Reference

 Validity of Data Extracted From Messages 41
|

Validity of Data Extracted From Messages

To extract data values from a message, programs use a set of get convenience
functions. All of these functions extract a snapshot of the message data—that is,
the data value as it exists at a particular time. If the program later modifies the
message by removing or updating the field, the snapshot remains unchanged.
Rendezvous messages implement snapshot semantics using two separate
strategies for scalar data and pointer data.

Scalar Snapshot
To extract the value of a scalar field, a program declares a scalar in
program-owned storage, and passes its address to the get function; the get
function copies a snapshot of the scalar field value from the message into
program storage.
The program can modify its snapshot at any time without affecting the original
message. The program can update or delete the message field at any time without
affecting the snapshot copy.

Figure 1 Extracting a Scalar Field

Message

1
Snapshot Copy of
Scalar Field Get Field
Scalar Value
Update Field

After deleting or updating the field,

Message 3
the snapshot copy of the scalar
value remains in program storage.
Updated Scalar Snapshot Copy of
Field Scalar Value

TIBCO Rendezvous C Reference

42
| Chapter 3 Messages

Pointer Snapshot
Pointer data is a broad category, which includes arrays, strings, opaque byte
sequences, XML data, and submessages.
To extract the value of a pointer field, a program declares a typed pointer in
program-owned storage, and passes its address to the get function; the get
function copies a pointer to the field value into the program’s pointer address. The
function does not copy data into program-owned storage; the data still resides in
storage associated with the message. Nonetheless, Rendezvous software protects
the integrity of snapshot pointer data from subsequent changes to the message
field.

Figure 2 Extracting a Pointer Field

This pointer remains valid until the message is

Message
destroyed. Moreover, the array to which it points is a
snapshot, which remains unchanged even if the
program subsequently updates or removes the field.

Pointer to
Array
Array
Value
Snapshot Array

(Schematic diagrams in this section illustrate the general principles of snapshot

semantics as they apply to pointer data of message fields. However, these
diagrams do not accurately reflect the storage allocation and geometry of
messages, nor do they reflect the underlying implementation of snapshots.)

Rendezvous Protects Pointer Snapshots from Changes to the Message

If the program removes the field from the message, then Rendezvous software
protects the integrity of the snapshot data by retaining it in storage associated
with the message; the program’s pointer to the snapshot data remains valid until
the message is destroyed, even though the data is no longer accessible through
the message.
If the program updates the message field (see Figure 3 on page 43), then
Rendezvous software protects the integrity of the snapshot data by retaining it in
storage associated with the message; the program’s pointer to the snapshot data
remains valid until the message is destroyed, and the program’s view of the
snapshot data remains unchanged—even though the get function would extract
updated data from the message.
These semantics apply to all pointer data—arrays, strings, opaque byte
sequences, XML data, and submessages.

TIBCO Rendezvous C Reference

 Validity of Data Extracted From Messages 43
|

Figure 3 Updating a Pointer Field

This pointer remains valid until the message is

Message
destroyed. Moreover, the snapshot of Array 1 remains
unchanged by updating the field. After updating the
field, subsequent Get calls bypass this snapshot.

Pointer to
Snapshot
Array Value
of Array 1
Snapshot Array 1

Copy of Array 2 Update Field Array 2

Updating the field copies Array 2 from the program into

the message, without disturbing Array 1 snapshot.
Subsequent Get calls extract this copy of Array 2.

Do Not Modify Pointer Snapshots

Programs must treat array, string, XML and opaque pointer data as read-only
snapshots, and must not modify the data to which those pointers refer. For
example, it is illegal for programs to change any element in a snapshot array; it is
illegal for programs to change any byte in snapshot strings, XML data or opaque
byte sequences.
Although Rendezvous software does not enforce this restriction, violating this
rule is dangerous, and can result in erroneous program behavior. Do not attempt
to modify the elements of an array snapshot, nor the bytes of a string, XML data
or opaque snapshot.
Figure 3 illustrates the correct way to modify the value of pointer data within a
message field. Instead of directly modifying storage associated with the message,
supply the new value through an update call, which replaces the whole value of
the field. (Even after updating or removing the field, it is still illegal to modify the
snapshot.)
Although superseded snapshot data remains in storage associated with the
message, it is not included when sending the message, nor when accessing
message fields.

TIBCO Rendezvous C Reference

44
| Chapter 3 Messages

Rendezvous Protects the Message from Changes to Submessage Snapshots

In contrast to other pointer data, programs may legally modify snapshot
submessages (since a submessage is also a message in its own right). Field
modification functions apply equally to ordinary messages and to submessage
snapshots extracted using get calls.
Moreover, modifying a snapshot submessage does not affect the original field in
the parent message. Field modification functions protect the integrity of the
parent message when updating or removing a field in a submessage snapshot, or
when adding a new field to the submessage snapshot.
Figure 4 illustrates this protection for parent messages. After updating a field in a
snapshot submessage, subsequent get calls extract a pristine copy of the
submessage from the field of the parent message, creating a second snapshot.
Meanwhile, the modified snapshot submessage remains in storage owned by the
parent message; it remains valid until the parent message is destroyed. (However,
if the program detaches the snapshot submessage, it remains valid until the
program explicitly destroys the submessage.)

Figure 4 Updating a Submessage Field

Updating a field in a snapshot submessage does not affect

Message
the field value of the parent message.
Subsequent calls to get the submessage from the parent
message bypass the updated snapshot, and instead
extract a new snapshot of the unchanged submessage.

Pointer to
Snapshot of Submsg 1
Snapshot Submsg 1
This pointer remains valid until the
Updated Field in message is destroyed.
Snapshot of Submsg 1
Subsequent calls to get the field from the
Pristine Copy of snapshot submessage extract this new value.
Submsg 1

Unchanged Field in
Copy of Submsg 1

TIBCO Rendezvous C Reference

 Validity of Data Extracted From Messages 45
|

Deleting Snapshot References

Ordinarily, snapshot references remain part of the message until the program
destroys the message. However, in rare situations snapshots can accumulate
within a program, causing unbounded memory growth.
For example, consider the result of a program that calls a function 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 functions 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 functions to control the
proliferation of references.

See Also tibrvMsg_MarkReferences() on page 106

Multiple Subscription Snapshots

Rendezvous software also protects the integrity of messages distributed to
multiple subscriptions. When a callback function modifies an inbound message
(whether detached or not), Rendezvous software still presents the original
message content to subsequent callback functions.

TIBCO Rendezvous C Reference

46
| Chapter 3 Messages

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.

Regular message functions specify fields using a field name. Extended functions
specify fields using a combination of a field name and a unique field identifier.
To compare the speed and space characteristics of these two options, see Search
Characteristics on page 47.

Rules and Restrictions

NULL is a legal field name only when the identifier is zero. It is illegal for a field to
have both a non-zero identifier and a NULL field name.
However, NULL is not the same as "" (the empty string). It is legal for a field to
have a non-zero identifier and the empty string as its field name.

Field Search Algorithm

The functions that get message fields (including functions that update or remove
fields, since these functions call get internally) all use this algorithm to find a field
within a message, as specified by a field identifier and a field name.
1. Extended functions begin here. Regular functions begin at step 3.
If the program supplied a non-zero field identifier, then search for the field
with that identifier. On failure, continue to step 2. (If the identifier is zero, skip
to step 3.)
2. If the identifier search (in step 1) fails, and the program supplied a non-NULL
field name, then search for a field with that name. On failure, or if the program
supplied NULL as the field name, return the status code TIBRV_NOT_FOUND. If
the name search succeeds, but the actual identifier in the field is non-NULL (so
it does not match the identifier supplied) then return the status code
TIBRV_ID_CONFLICT.

TIBCO Rendezvous C Reference

 Field Names and Field Identifiers 47
|

3. Regular functions begin here. Extended functions also begin here when the
program supplied zero as the identifier (supplying zero is equivalent to not
supplying a field identifier, so the behavior is equivalent to the corresponding
regular function).
Search for a field with the specified name—even if that name is NULL. On
failure, return the status code TIBRV_NOT_FOUND.

If a message contains several fields with the same name, searching by name finds
the first instance of the field with that name.

Adding a New Field

When a program uses an extended function to add a new field to a message, it can
attach a field name, a field identifier, or both. If the program supplies an identifier,
Rendezvous software checks that it is unique within the message; if the identifier
is already in use, the operation fails and returns the status code
TIBRV_ID_IN_USE.

Passing Field Name and Identifiers

The program can pass the field name and identifier to functions in either of two
ways:
• All extended functions accept two separate parameters, named fieldName
and fieldId.
• tibrvMsg_AddField() and tibrvMsg_UpdateField() do not have extended
functions. Instead, they accept a field parameter, which contains these two
items as members within a tibrvMsgField struct. (The convenience functions
that add and update fields do have extended functions.)

Search Characteristics
In general, an identifier search completes in constant time. In contrast, a name
search completes in linear time proportional to the number of fields in the
message. Name search is quite fast for messages with 16 fields or fewer; for
messages with more than 16 fields, identifier search is faster.

Space Characteristics
The smallest field name is a one-character string, which occupies three bytes in
Rendezvous wire format. That one ASCII character yields a name space of 127
possible field names; a larger range requires additional characters.

TIBCO Rendezvous C Reference

48
| Chapter 3 Messages

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
functions find a specific instance by name and number (they do not use field
identifiers):
• tibrvMsg_RemoveFieldInstance() on page 110.
• tibrvMsg_GetFieldInstance() on page 101.

TIBCO Rendezvous C Reference

 Strings and Character Encodings 49
|

Strings and Character Encodings

Rendezvous software uses strings in several roles:

• String data inside message fields
• Field names
• Subject names (and other associated strings that are not strictly inside the
message)
• Certified delivery correspondent names
• Group names (fault tolerance)

All these strings (both in C and in wire format) use the character encoding
appropriate to the ISO locale of the sender. For example, the United States is locale
en_US, and uses the Latin-1 character encoding (also called ISO 8859-1); Japan is
locale ja_JP, and uses the Shift-JIS character encoding.
When two programs exchange messages within the same locale, strings are
always correct. However, when a message sender and receiver use different
character encodings, the receiving program must convert between encodings as
needed. Rendezvous software does not convert automatically.

EBCDIC
For information about string encoding in EBCDIC environments, see
tibrv_SetCodePages() on page 21.

TIBCO Rendezvous C Reference

50
| Chapter 3 Messages

tibrvLocalData
Type

Declaration typedef union {

tibrvMsg msg;
char* str;
void* buf;
void* array;
tibrv_bool boolean;
tibrv_i8 i8;
tibrv_u8 u8;
tibrv_i16 i16;
tibrv_u16 u16;
tibrv_i32 i32;
tibrv_u32 u32;
tibrv_i64 i64;
tibrv_u64 u64;
tibrv_f32 f32;
tibrv_f64 f64;
tibrv_ipport16 ipport16;
tibrv_ipaddr32 ipaddr32;
tibrvMsgDateTime date;
} tibrvLocalData;

Purpose This type is the union of all the datatypes that a Rendezvous message can contain
as data in a message field.

(Sheet 1 of 2)

Accessor Description
msg Rendezvous message

str character string; NULL-terminated; encoding depends on ISO locale

buf opaque buffer, or XML data buffer (uncompressed)

Do not use this field to access data that requires memory alignment; it does not
necessarily preserve alignment. Instead, see Add Opaque Byte Sequence on
page 65, Get Opaque Byte Sequence on page 94, or Update Opaque Byte
Sequence on page 123.

array array (any valid element type)

boolean boolean

i8 8-bit integer

u8 8-bit unsigned integer

TIBCO Rendezvous C Reference

 tibrvLocalData 51
|

(Sheet 2 of 2)

Accessor Description
i16 16-bit integer

u16 16-bit unsigned integer

i32 32-bit integer

u32 32-bit unsigned integer

i64 64-bit integer

u64 64-bit unsigned integer

f32 32-bit floating point number

f64 64-bit floating point number

ipport16 2-byte IP port, in network byte order

ipaddr32 4-byte IP address, in network byte order

date Rendezvous date-time value; see tibrvMsgDateTime on page 53

See Also Wire Format Datatypes, page 348

C Datatypes, page 350
Datatype Conversion, page 352

TIBCO Rendezvous C Reference

52
| Chapter 3 Messages

tibrvMsg
Type

Declaration typedef void* tibrvMsg;

Purpose This type represents inbound or outbound Rendezvous messages.

Remarks Programs manipulate messages using the calls in this chapter.

TIBCO Rendezvous C Reference

 tibrvMsgDateTime 53
|

tibrvMsgDateTime
Type

Declaration typedef struct

{
tibrv_i64 sec;
tibrv_u32 nsec;
} tibrvMsgDateTime;

Purpose Represents dates and times.

Accessor Description
sec Signed 64-bit integer representing seconds.

nsec Unsigned 32-bit integer representing nanoseconds after the

seconds value. This value is always non-negative, between zero
and 999999999.
It modifies the date in whole seconds by specifying the number
of nanoseconds after that date. For example, the time 1/2 second
before midnight of December 31, 1969 is -1 seconds plus
500,000,000 nanoseconds.

Converting tibrvMsg_ConvertToString() prints times in UTC format (also known as Zulu

Dates to Strings time or GMT). The ISO-8601 standard requires appending a Z character in this
notation.
tibrvMsg_ConvertToString() uses Common Era numbering for years. This
system does not include a year zero. So for example, the time 1 second before
0001-01-01 00:00:00Z would print as -0001-12-31 23:59:59Z.

tibrvMsg_ConvertToString() uses a proleptic Gregorian calendar. That is,

when formatting dates earlier than the adoption of the Gregorian calendar, it
projects the Gregorian calendar backward beyond its actual invention and
adoption.

Representations Rendezvous software represents time values in two ways—one within C

programs, and a more compact wire format within messages. Table 10 on page 54
compares these two representations. In both representations, zero denotes the
epoch, 12:00 midnight, January 1st, 1970. Range limits denote the extreme value
on either side of that center. Bold type indicates the primary unit of measurement
for each representation.

TIBCO Rendezvous C Reference

54
| Chapter 3 Messages

Table 10 Date and Time Representations

Representation Details
Within C Seconds as a 64-bit signed integer, plus nanoseconds as a 32-bit unsigned
programs integer.
However, values are restricted to the range and granularity supported by
Rendezvous wire format. Forcing larger or finer values into this representation
produces an error.
Two constants bracket the available (restricted) range of values within
programs— TIBRVMSG_DATETIME_SEC_MAX and TIBRVMSG_DATETIME_SEC_MIN.

range in years 292,471,208,677

range in seconds 9,223,372,036,854,775,807

restricted range in seconds 549,755,813,887

restricted range in millisecs 549,755,813,887,000

Rendezvous Seconds as a 40-bit signed integer, plus microseconds as a 24-bit unsigned

wire format integer.

range in years 17,432

range in seconds 549,755,813,887

range in milliseconds 549,755,813,887,000

See Also Add DateTime, page 67

tibrvMsg_ConvertToString() on page 69
tibrvMsg_GetCurrentTime() on page 80
Get DateTime, page 98
Update DateTime, page 125

TIBCO Rendezvous C Reference

 tibrvMsgField 55
|

tibrvMsgField
Type

Declaration typedef struct

{
char* name;
tibrv_u32 size;
tibrv_u32 count;
tibrvLocalData data;
tibrv_u16 id;
tibrv_u8 type;
} tibrvMsgField;

Purpose Fields hold data within messages. Programs manipulate the content of field
structs using the public struct accessors of this type.

Accessor Description
name The field’s name. NULL signifies the empty string as the field name.
Field name strings use the ISO 8859-1 character encoding.

size The size of the field’s data (in bytes).

For array types, size reflects the size (in bytes) of one array element. For
TIBRVMSG_STRING, size reflects the number of bytes in the string (including the
NULL terminator, if present). For TIBRVMSG_OPAQUE and TIBRVMSG_XML, size
reflects the number of bytes of data.

count The number of values in an array field. For array types, count is the number of
array elements.
For example, when a field contains a array of ten 32-bit integers, its size is 4, and
its count is 10.
(For scalar types, strings, opaque byte sequences and XML data, count is 1. That is,
the field contains one string—not an array of characters; one opaque value—not an
array of bytes.)

data The field’s data value.

id The field’s identifier. Identifiers are optional, but must be unique within each
message.

type A Rendezvous datatype token denoting the type of the field’s data.

TIBCO Rendezvous C Reference

56
| Chapter 3 Messages

tibrvMsg_AddField()
Function

Declaration tibrv_status tibrvMsg_AddField(

tibrvMsg message,
tibrvMsgField* field);

Purpose Add a field to a message.

Remarks This function copies the data into the new message field. All related convenience
functions behave similarly.

Parameter Description
message Add the new field to this message.

field Add this field to the message.

Adding Fields to Earlier releases of Rendezvous software allowed programs to append fields to a
a Nested nested submessage under certain conditions. Starting with release 6, Rendezvous
Message software no longer supports this special case convenience. Instead, programs
must use this three-step process:
1. Extract the nested submessage, using tibrvMsg_getMsg().
2. Add the new fields to the extracted submessage, using type-specific
convenience functions or this function. The field is added to a snapshot copy
of the submessage, and modifies the copy rather than the original parent
message.
3. Store the modified submessage back into the field of the parent message,
using TibrvMsg_UpdateMsg().

Avoiding Whenever possible, we recommend storing arrays in message fields using one of
Common the Rendezvous array types. This strategy makes the most efficient use of storage
Mistakes space, processor time, and network bandwidth.
If you must store array elements as individual fields, be careful mapping array
indices to field identifiers. Zero-based arrays are common in C programs, but zero
has a special meaning as a field identifier—it represents the absence of an
identifier. Do not map the zeroth element of an array (myArray[0]) to a field with
identifier zero; it is impossible to retrieve such a field by its identifier (because it
does not have one).
It is illegal to add a field that has both a NULL field name, and a non-zero field
identifier.

TIBCO Rendezvous C Reference

 tibrvMsg_AddField() 57
|
Reserved Field
Name

The field name _data_ is reserved. Programs may not add fields with this name.
More generally, all fields that begin with the underbar character are reserved.

Field Name The constant TIBRVMSG_FIELDNAME_MAX (127) determines the longest possible
Length field name.

Convenience When the datatype of a field is determined during execution, use this general
Functions function. When you can determine the datatype of a field before compile-time, we
recommend using type-specific convenience functions instead of this general
function. Type-specific functions yield these advantages when adding fields:
• Code readability.
• Type checking.
• Accept constants and literals directly.

(Type-specific functions yield even further advantages when extracting or

updating fields.)
These categories of type-specific convenience functions add a new field:
• Add Scalar, page 59.
• Add Array, page 61.
• Add Nested Message, page 63.
• Add String, page 64.
• Add Opaque Byte Sequence, page 65.
• Add XML Byte Sequence, page 66.
• Add DateTime, page 67.

Extended Each convenience function has two forms.

Functions
• The usual form specifies the field to add using a field name.
• The extended form specifies the field to add using a field name and a field
identifier.

For example, the function tibrvMsg_AddI32() is paired with the extended form
tibrvMsg_AddI32Ex().

TIBCO Rendezvous C Reference

58
| Chapter 3 Messages

Field identifiers have type tibrv_u16. Zero is a special value that signifies no
field identifier. All non-zero field identifiers must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a non-zero field
identifier.
For more information, see Adding a New Field, page 47.

TIBCO Rendezvous C Reference

 Add Scalar 59
|

Add Scalar
Convenience Functions

Declaration tibrv_status
tibrvMsg_AddScalar_type(
tibrvMsg message,
const char* fieldName,
scalar_type value);

tibrv_status
tibrvMsg_AddScalar_typeEx(
tibrvMsg message,
const char* fieldName,
scalar_type value,
tibrv_i16 fieldId);

Purpose Add a field containing a scalar value.

Function Name Field Value Type Type Description

tibrvMsg_AddBool tibrv_bool boolean

tibrvMsg_AddF32 tibrv_f32 32-bit floating point

tibrvMsg_AddF64 tibrv_f64 64-bit floating point

tibrvMsg_AddI8 tibrv_i8 8-bit integer

tibrvMsg_AddI16 tibrv_i16 16-bit integer

tibrvMsg_AddI32 tibrv_i32 32-bit integer

tibrvMsg_AddI64 tibrv_i64 64-bit integer

tibrvMsg_AddU8 tibrv_u8 8-bit unsigned integer

tibrvMsg_AddU16 tibrv_u16 16-bit unsigned integer

tibrvMsg_AddU32 tibrv_u32 32-bit unsigned integer

tibrvMsg_AddU64 tibrv_u64 64-bit unsigned integer

tibrvMsg_AddIPAddr32 tibrv_ipaddr32 4-byte IP address

tibrvMsg_AddIPPort16 tibrv_ipport16 2-byte IP port

TIBCO Rendezvous C Reference

60
| Chapter 3 Messages

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field with this value (which may be a literal or
stored in a variable).
The convenience function must correspond to the
datatype of this value. We recommend casting the data to
match the convenience function.
The function copies the value into the new message field.

fieldId Create the new field with this identifier. Zero is a special
value that signifies no field identifier. All non-zero field
identifiers must be unique within each message.
It is illegal to add a field that has both a NULL field name,
and a non-zero field identifier.

TIBCO Rendezvous C Reference

 Add Array 61
|

Add Array
Convenience Functions

Declaration tibrv_status
tibrvMsg_Addelement_typeArray(
tibrvMsg message,
const char* fieldName,
const element_type* value,
tibrv_u32 numElements);

tibrv_status
tibrvMsg_Addelement_typeArrayEx(
tibrvMsg message,
const char* fieldName,
const element_type* value,
tibrv_u32 numElements,
tibrv_u16 fieldId);

Purpose Add a field containing an array value.

Function Name Element Type Type Description

tibrvMsg_AddF32Array tibrv_f32 32-bit floating point array

tibrvMsg_AddF64Array tibrv_f64 64-bit floating point array

tibrvMsg_AddI8Array tibrv_i8 8-bit integer array

tibrvMsg_AddI16Array tibrv_i16 16-bit integer array

tibrvMsg_AddI32Array tibrv_i32 32-bit integer array

tibrvMsg_AddI64Array tibrv_i64 64-bit integer array

tibrvMsg_AddU8Array tibrv_u8 8-bit unsigned integer array

tibrvMsg_AddU16Array tibrv_u16 16-bit unsigned integer array

tibrvMsg_AddU32Array tibrv_u32 32-bit unsigned integer array

tibrvMsg_AddU64Array tibrv_u64 64-bit unsigned integer array

tibrvMsg_AddMsgArray tibrv_Msg message array

tibrvMsg_AddStringArray char* string array

TIBCO Rendezvous C Reference

62
| Chapter 3 Messages

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains this array.

The convenience function must correspond to the
datatype of this value.
The function copies the array into the new message field.

numElements When adding an array type, the program supplies the

count of array elements in this parameter.

fieldId Create the new field with this identifier. Zero is a special
value that signifies no field identifier. All non-zero field
identifiers must be unique within each message.
It is illegal to add a field that has both a NULL field name,
and a non-zero field identifier.

TIBCO Rendezvous C Reference

 Add Nested Message 63
|

Add Nested Message

Convenience Function

Declaration tibrv_status tibrvMsg_AddMsg(

tibrvMsg message,
const char* fieldName,
tibrvMsg value);

tibrv_status tibrvMsg_AddMsgEx(
tibrvMsg message,
const char* fieldName,
tibrvMsg value,
tibrv_u16 fieldId);

Purpose Add a field containing a nested submessage.

Remarks This function adds only the data portion of the nested message (value); it does
not include any address information or certified delivery information.

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains this submessage.

The function copies the data into the new field.

fieldId Create the new field with this identifier. Zero is a special value
that signifies no field identifier. All non-zero field identifiers
must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a
non-zero field identifier.

TIBCO Rendezvous C Reference

64
| Chapter 3 Messages

Add String
Convenience Function

Declaration tibrv_status tibrvMsg_AddString(

tibrvMsg message,
const char* fieldName,
const char* value);

tibrv_status tibrvMsg_AddStringEx(
tibrvMsg message,
const char* fieldName,
const char* value,
tibrv_u16 fieldId);

Purpose Add a field containing a string.

Remarks The string cannot contain interior NULL bytes, because this function expects a
NULL-terminated string. To add a string with interior NULL bytes, use the generic
function tibrvMsg_AddField().

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains this string (which may be a
literal or stored in a variable).
The function copies the data into the new field.

fieldId Create the new field with this identifier. Zero is a special value
that signifies no field identifier. All non-zero field identifiers
must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a
non-zero field identifier.

TIBCO Rendezvous C Reference

 Add Opaque Byte Sequence 65
|

Add Opaque Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_AddOpaque(

tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size);

tibrv_status tibrvMsg_AddOpaqueEx(
tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size,
tibrv_u16 fieldId);

Purpose Add a field containing an opaque byte sequence.

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains this opaque buffer.

The function copies the data into the new message field.

size When adding an opaque buffer, the program supplies the size
(in bytes) of the data in this parameter.

fieldId Create the new field with this identifier. Zero is a special value
that signifies no field identifier. All non-zero field identifiers
must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a
non-zero field identifier.

TIBCO Rendezvous C Reference

66
| Chapter 3 Messages

Add XML Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_AddXml(

tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size);

tibrv_status tibrvMsg_AddXmlEx(
tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size,
tibrv_u16 fieldId);

Purpose Add a field containing XML data.

Remarks XML data is a byte sequence. Adding a field of type TIBRVMSG_XML compresses
the bytes. Extracting data from the field uncompresses it to obtain the original
byte sequence.

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains the XML data in this buffer.
The function copies the data into the new message field.

size When adding XML data, the program supplies the size (in
bytes) of the data in this parameter.

fieldId Create the new field with this identifier. Zero is a special value
that signifies no field identifier. All non-zero field identifiers
must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a
non-zero field identifier.

TIBCO Rendezvous C Reference

 Add DateTime 67
|

Add DateTime
Convenience Function

Declaration tibrv_status tibrvMsg_AddDateTime(

tibrvMsg message,
const char* fieldName,
const tibrvMsgDateTime* value);

tibrv_status tibrvMsg_AddDateTimeEx(
tibrvMsg message,
const char* fieldName,
const tibrvMsgDateTime* value,
tibrv_u16 fieldId);

Purpose Add a field containing a Rendezvous datetime value.

Parameter Description
message Add the new field to this message.

fieldName Create the new field with this name.

value Add a new field that contains this datetime value.

The function copies the data into the new message field.

fieldId Create the new field with this identifier. Zero is a special value that signifies no
field identifier. All non-zero field identifiers must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a non-zero field
identifier.

Example This example code fragment converts a time_t value to a datetime value, and
adds the datetime to a message field. Programs can adapt this example as
appropriate. (For corresponding code to extract a datetime value from a message
field, and convert it to a time_t value, see the example at Get DateTime, page 98.)
#include <limits.h>

tibrv_status
addAsTimeT(tibrvMsg msg,
const char * field,
time_t value)
{ tibrvMsgDateTime d;

d.nsec = 0;
d.sec = (tibrv_i64) value;
return tibrvMsg_AddDateTime(msg, field, &d); }

See Also tibrvMsgDateTime on page 53

TIBCO Rendezvous C Reference

68
| Chapter 3 Messages

tibrvMsg_ClearReferences()
Function

Declaration tibrv_status tibrvMsg_ClearReferences(

tibrvMsg message);

Purpose Clear references in this message.

Remarks This function clears references back to the most recent mark.
For a description and example, see tibrvMsg_MarkReferences() on page 106.

Parameter Description
message Clear references in this message.

See Also Validity of Data Extracted From Messages, page 41

Deleting Snapshot References, page 45
tibrvMsg_MarkReferences() on page 106

TIBCO Rendezvous C Reference

 tibrvMsg_ConvertToString() 69
|

tibrvMsg_ConvertToString()
Function

Declaration tibrv_status tibrvMsg_ConvertToString(

tibrvMsg message,
const char** string);

Purpose Format a message as a string.

Remarks Programs can use this function to obtain a string representation of the message for
printing.
For most datatypes, this function formats the full value of the field to the output
string; however, these two types are exceptions:
TIBRVMSG_OPAQUEThis function abbreviates the value of an opaque field; for
example, [472 opaque bytes].
TIBRVMSG_XML This function abbreviates the value of an XML field; for
example, [XML document: 472 bytes].
The size measures uncompressed data.

This function formats TIBRVMSG_IPADDR32 fields as four dot-separated

decimal integers.
This function formats TIBRVMSG_IPPORT16 fields as one decimal integer.
For printing tibrvMsgDateTime values, see Converting Dates to Strings on
page 53.

Parameter Description
message Format this message as a string.

string The program supplies a location in this parameter; the

function stores a pointer to the string in that location. The
function allocates storage for the string itself as part of the
message; the string pointer remains valid until the message is
destroyed. The program must not modify the string.

TIBCO Rendezvous C Reference

70
| Chapter 3 Messages

tibrvMsg_Create()
Function

Declaration tibrv_status tibrvMsg_Create(

tibrvMsg* message);

tibrv_status tibrvMsg_CreateEx(
tibrvMsg* message,
tibrv_u32 initialStorage);

Purpose Allocate storage and initialize it as a new message.

Remarks This function allocates storage for the new message. A program owns the
messages that it creates, and must destroy them to reclaim the storage. That is,
each call to this function must be paired with a call to tibrvMsg_Destroy() on
page 73.
Programs can add address information to the message using
tibrvMsg_SetSendSubject() on page 113, and tibrvMsg_SetReplySubject() on
page 112.

Message Size When adding data to a message would overflow the allocated space, the message
automatically expands by allocating additional storage. However, when creating
messages that contain many small fields, you can optimize program performance
by pre-allocating sufficient storage initially.

Parameter Description
message The function stores a pointer to the new message in this
location.

initialStorage Initial space (in bytes) to allocate for the message.

See Also tibrvMsg_Destroy() on page 73

tibrvMsg_Expand() on page 75
tibrvMsg_SetReplySubject() on page 112
tibrvMsg_SetSendSubject() on page 113

TIBCO Rendezvous C Reference

 tibrvMsg_CreateCopy() 71
|

tibrvMsg_CreateCopy()
Function

Declaration tibrv_status tibrvMsg_CreateCopy(

const tibrvMsg message
tibrvMsg* copy);

Purpose Copy a message.

Remarks The copy is completely independent of the original message. Pointer data in fields
are independent copies of the values.
This function copies only the data within the fields of the message. The copy does
not include any supplementary information—for example, address information or
certified delivery information. (Programs can explicitly add supplementary
information to the copy using functions such as tibrvMsg_SetSendSubject() on
page 113.)
This function allocates the storage for the copy. The duration of the copy is
independent of the original message.
A program owns the messages that it creates, and must destroy them to reclaim
the storage. That is, each call to this function must be paired with a call to
tibrvMsg_Destroy() on page 73.

Parameter Description
message Copy this message.

copy The function stores a pointer to the new copy in this location.

See Also tibrvMsg_Destroy() on page 73

tibrvMsg_SetReplySubject() on page 112
tibrvMsg_SetSendSubject() on page 113

TIBCO Rendezvous C Reference

72
| Chapter 3 Messages

tibrvMsg_CreateFromBytes()
Function

Declaration tibrv_status tibrvMsg_CreateFromBytes(

tibrvMsg* message,
const void* bytes);

Purpose Create a new message, and populate it with data.

Remarks This function allocates storage for the new message. The program owns the
message, and must destroy it to reclaim the storage. That is, each call to this
function must be paired with a call to tibrvMsg_Destroy() on page 73.
This function copies the bytes into the new message.
Programs can add address information to the message using
tibrvMsg_SetSendSubject() on page 113, and tibrvMsg_ConvertToString() on
page 69.

Parameter Description
message The program supplies a location for the new message. The
function creates a new message and stores a pointer to it in that
location.

bytes Fill the new message with this data. This data buffer represents
the message in Rendezvous wire format, as produced by
tibrvMsg_GetAsBytes() or tibrvMsg_GetAsBytesCopy().

See Also tibrvMsg_GetAsBytes() on page 76

tibrvMsg_GetAsBytesCopy() on page 77

TIBCO Rendezvous C Reference

 tibrvMsg_Destroy() 73
|

tibrvMsg_Destroy()
Function

Declaration tibrv_status tibrvMsg_Destroy(

tibrvMsg message);

Purpose Destroy a message; free the storage that it occupies.

Remarks A program owns all messages that it creates or detaches, and must destroy them
to reclaim the storage. That is, each call to tibrvMsg_Create() or
tibrvMsg_Detach() must be paired with a call to this function.

This function frees the storage associated with the message and its snapshot data.
In most operating environments it is illegal to access freed storage.
Destroying a message invalidates all pointer data (such as strings, arrays,
undetached submessages, byte sequences, or XML data) previously extracted
from any fields of the message.
However, destroying a parent message does not affect detached submessages of
the parent.
It is safe for a program to exit without first destroying all messages.

Do Not Destroy Messages that Rendezvous Software Owns

Rendezvous software owns all inbound messages (unless explicitly detached). It

automatically destroys its messages as the program exits the context of the
callback function. It is illegal for your program to destroy a message that it does
not own.

Parameter Description
message Destroy this message, freeing its storage.

See Also tibrvMsg_Create() on page 70

tibrvMsg_Detach() on page 74
tibrvEventCallback on page 133

TIBCO Rendezvous C Reference

74
| Chapter 3 Messages

tibrvMsg_Detach()
Function

Declaration tibrv_status tibrvMsg_Detach(

tibrvMsg message);

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
function; Rendezvous software destroys such messages when the callback
function returns, unless the program explicitly detaches the message. After a
detach operation, the program owns the message, and must explicitly destroy it to
reclaim the storage.
Programs can use this function to detach either an entire message, or a
submessage. After detaching a submessage, the program owns that submessage,
even after the destruction of the surrounding parent message.

Programs may modify messages only with functions that add, remove or update
fields. It is illegal to directly modify data storage in a message field. Detaching a
message does not change this restriction. For further information, see Do Not
Modify Pointer Snapshots on page 43, or more generally, Validity of Data
Extracted From Messages on page 41.

Parameter Description
message Detach this message.

See Also tibrvMsg_Destroy() on page 73

tibrvEventCallback on page 133
tibrvcmEventCallback on page 281

TIBCO Rendezvous C Reference

 tibrvMsg_Expand() 75
|

tibrvMsg_Expand()
Function

Declaration tibrv_status tibrvMsg_Expand(

tibrvMsg message,
tibrv_u32 additionalStorage);

Purpose Enlarge a message by allocating additional storage.

Remarks When adding data to a message would overflow the allocated space, the message
automatically expands by allocating additional storage. However, reallocation
(whether explicit or automatic) is a slow operation; to optimize program
performance, we recommend allocating sufficient storage initially, so that
reallocation is not required.
In most cases, the message expands in place (without copying). In some cases, this
function copies the message to a new location. In all cases, existing pointers to the
message, its fields, and its field values remain valid (even after copying).
If no space is available, this function returns the error code TIBRV_NO_MEMORY.

Parameter Description
message Expand this message.

additionalStorage Enlarge the message by this amount (in bytes) to

allocate for the message. If the message was oldSize
bytes before this call, it is oldSize + additionalStorage
when the function returns.

TIBCO Rendezvous C Reference

76
| Chapter 3 Messages

tibrvMsg_GetAsBytes()
Function

Declaration tibrv_status tibrvMsg_GetAsBytes(

tibrvMsg message,
const void** bytePtr);

Purpose Extract the data from a message as a byte sequence.

Remarks Return the data as a byte sequence, suitable for archiving in a file.
The storage for the byte sequence is associated with the message, and persists
until the message is destroyed. Programs must not modify the resulting byte
sequence, which remains part of the message object. To make a copy that your
program can modify, use tibrvMsg_GetAsBytesCopy() on page 77.
The byte data includes the message header and all message fields in Rendezvous
wire format. It does not include address information, such as the subject and reply
subject, nor certified delivery information.
The byte sequence can contain interior NULL bytes.

Parameter Description
message Extract the data bytes from this message.

bytePtr The program supplies a location. The function stores a pointer

to the byte sequence in that location.

See Also tibrvMsg_GetAsBytesCopy() on page 77

tibrvMsg_GetByteSize() on page 78
tibrvMsg_CreateFromBytes() on page 72

TIBCO Rendezvous C Reference

 tibrvMsg_GetAsBytesCopy() 77
|

tibrvMsg_GetAsBytesCopy()
Function

Declaration tibrv_status tibrvMsg_GetAsBytesCopy(

tibrvMsg message,
void* buf,
tibrv_u32 byteSize);

Purpose Extract a copy of the data from a message as a byte sequence.

Remarks Return the data as a byte sequence, suitable for archiving in a file.
This function copies the message data into a buffer, which the program owns and
may modify.
The byte data includes the message header and all message fields in Rendezvous
wire format. It does not include address information, such as the subject and reply
subject.
To allocate appropriate storage, programs determine the length of the byte
sequence using tibrvMsg_GetByteSize() on page 78.
The byte sequence can contain interior NULL bytes.

Parameter Description
message Extract the data from this message.

buf The program supplies a buffer. The function copies the byte
sequence into that buffer.

byteSize The size of the buffer.

See Also tibrvMsg_GetAsBytes() on page 76

tibrvMsg_GetByteSize() on page 78
tibrvMsg_CreateFromBytes() on page 72

TIBCO Rendezvous C Reference

78
| Chapter 3 Messages

tibrvMsg_GetByteSize()
Function

Declaration tibrv_status tibrvMsg_GetByteSize(

tibrvMsg message,
tibrv_u32* byteSize);

Purpose Return the size of a message (in bytes).

Remarks This measurement accounts for the actual space that the message occupies (in
wire format), including its header and its fields. It does not include storage that is
allocated but unused. It does not include address information, such as the subject
or reply subject.
Programs can use this function as part of these tasks:
• Measure the size of message before allocating space to store a copy—as with
tibrvMsg_GetAsBytesCopy().

• Assess throughput rates.

• Limit output rates (also called throttling).

Parameter Description
message Return the size of this message.

byteSize The program supplies a location. The function stores the

message size (in bytes) in that location.

See Also tibrvMsg_GetAsBytes() on page 76

tibrvMsg_GetAsBytesCopy() on page 77

TIBCO Rendezvous C Reference

 tibrvMsg_GetClosure() 79
|

tibrvMsg_GetClosure()
Function

Declaration tibrv_status tibrvMsg_GetClosure(

tibrvMsg message,
void** closure);

Purpose Extract the closure object corresponding to a (dispatched) message object.

Parameter Description
message Extract the closure corresponding to this message object.

closure The program supplies a location. The function stores the

closure object in that location.

Remarks Dispatch associates the message with a listener event. This call gets the closure
from that listener event.
This call is valid only for an inbound message that has already been dispatched to
a listener event. Error status TIBRV_INVALID_MSG indicates that the message is
not associated with a listener event.

See Also tibrvMsg_GetEvent() on page 81

tibrvEventVectorCallback on page 137

TIBCO Rendezvous C Reference

80
| Chapter 3 Messages

tibrvMsg_GetCurrentTime()
Function

Declaration tibrv_status tibrvMsg_GetCurrentTime(

tibrvMsgDateTime* dateTime);

tibrv_status tibrvMsg_GetCurrentTimeString(
char* local,
char* gmt);

Purpose Get the current time.

Remarks The first function produces a date-time object; for details, see tibrvMsgDateTime
on page 53.
The second function produces printable strings.
Both functions are thread-safe.

Parameter Description
dateTime The program supplies a location. The function stores the
current time in that location.

local If this argument is non-NULL, then it is the location of a string.

The function stores a string representing the current time (in
the local time zone) in that location.
If this argument is NULL, then the function leaves it unchanged.

gmt If this argument is non-NULL, then it is the location of a string.

The function uses tibrvMsg_ConvertToString() to produce
a string representing the current time (Zulu time), and stores
the string in that location. For details, see Converting Dates to
Strings on page 53.
If this argument is NULL, then the function leaves it unchanged.

See Also tibrvMsgDateTime on page 53

TIBCO Rendezvous C Reference

 tibrvMsg_GetEvent() 81
|

tibrvMsg_GetEvent()
Function

Declaration tibrv_status tibrvMsg_GetEvent(

tibrvMsg message,
tibrvEvent* event);

Purpose Extract the event associated with a (dispatched) message object.

Parameter Description
message Extract the event associated with this message object.

event The program supplies a location. The function stores the event
object in that location.

Remarks Dispatch associates the message with a listener event.

This call is valid only for an inbound message that has already been dispatched to
a listener event. Error status TIBRV_INVALID_MSG indicates that the message is
not associated with a listener event.

See Also tibrvMsg_GetClosure() on page 79

tibrvEventVectorCallback on page 137

TIBCO Rendezvous C Reference

82
| Chapter 3 Messages

tibrvMsg_GetField()
Function

Declaration tibrv_status tibrvMsg_GetField(

tibrvMsg message,
const char* fieldName,
tibrvMsgField* field);

tibrv_status tibrvMsg_GetFieldEx(
tibrvMsg message,
const char* fieldName,
tibrvMsgField* field,
tibrv_u16 fieldId);

Purpose Get a specified field from a message.

Remarks Programs specify the field to retrieve using the fieldName and fieldId
parameters. For details, see Field Names and Field Identifiers, page 46.
The function takes a snapshot of the field, and stores that information in the
field argument, overwriting the struct supplied as an argument.
The function copies scalar data into the program’s field struct. Pointer data (such
as strings, arrays, submessages, opaque byte sequences, or XML data) extracted
from the field remain valid until the message is destroyed; that is, even removing
the field or updating the field’s value does not invalidate pointer data.
Programs can use a related function to loop through all the fields of a message. To
retrieve each field by its integer index number, see tibrvMsg_GetFieldByIndex()
on page 100.

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

field The program supplies a pointer to a tibrvMsgField struct; the

function overwrites the contents of the struct with a snapshot
of the information from the message field.

fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

TIBCO Rendezvous C Reference

 tibrvMsg_GetField() 83
|

Field Search Algorithm

This function, and related functions that get message fields, all use this algorithm
to find a field within a message, as specified by a field identifier and a field name.
1. Extended functions begin here. Regular functions begin at step 3.
If the identifier is zero, skip to step 3.
If the program supplied a non-zero field identifier, then search for the field
with that identifier.
If the search succeeds, return the field.
On failure, continue to step 2.
2. If the identifier search (in step 1) fails, and the program supplied a non-NULL
field name, then search for a field with that name.
If the name search succeeds, and the identifier in the field is NULL, return the
field.
If the name search succeeds, but the actual identifier in the field is non-NULL
(so it does not match the identifier supplied) then return the status code
TIBRV_ID_CONFLICT.

If the name search fails, or if the program supplied NULL as the field name,
return the status code TIBRV_NOT_FOUND.
3. Regular functions begin here. Extended functions also begin here when the
program supplied zero as the identifier (supplying zero is equivalent to not
supplying a field identifier, so the behavior is equivalent to the corresponding
regular function).
Search for a field with the specified name—even if that name is NULL.
If the search succeeds, return the field.
On failure, return the status code TIBRV_NOT_FOUND.
If a message contains several fields with the same name, searching by name finds
the first instance of the field with that name.

Extracting Fields from a Nested Message

Earlier releases of Rendezvous software allowed programs to get fields from a

nested submessage by concatenating field names. Starting with release 6,
Rendezvous software no longer supports this special case convenience. Instead,
programs must separately extract the nested submessage using
tibrvMsg_GetMsg(), and then get the desired fields from the submessage.

TIBCO Rendezvous C Reference

84
| Chapter 3 Messages

Convenience Functions
In most situations, we recommend using type-specific convenience functions
instead of this general function. Type-specific functions yield these advantages
when extracting fields:
• Code readability.
• Type checking.
• Automatic type conversion.

However, we do recommend the general function in two specific situations:

• No convenience function exists.
• The program must extract the data exactly as it appears in the message,
without automatic type conversion. (Convenience functions always convert
extracted data to a specific type.)

These categories of type-specific convenience functions find a field and get its
data:
• Get Scalar, page 86.
• Get Array, page 88.
• Get Nested Message, page 90.
• Get String, page 92.
• Get Opaque Byte Sequence, page 94.
• Get XML Byte Sequence, page 96.
• Get DateTime, page 98.

Extended Functions
Each convenience function has two forms.
• The usual form specifies the field to get using a field name.
• The extended form specifies the field to get using a field name and a field
identifier.

For example, the function tibrvMsg_GetI32() is paired with the extended form
tibrvMsg_GetI32Ex().

The field identifier has type tibrv_u16. Zero is a special value that signifies no
field identifier. All non-zero field identifiers must be unique within each message.
For details, see Field Names and Field Identifiers, page 46.

TIBCO Rendezvous C Reference

 tibrvMsg_GetField() 85
|
See Also Field Names and Field Identifiers, page 46
Get Scalar, page 86
tibrvMsgField on page 55

TIBCO Rendezvous C Reference

86
| Chapter 3 Messages

Get Scalar
Convenience Functions

Declaration tibrv_status
tibrvMsg_Getscalar_type(
tibrvMsg message,
const char* fieldName,
scalar_type* value);

tibrv_status
tibrvMsg_Getscalar_typeEx(
tibrvMsg message,
const char* fieldName,
scalar_type* value,
tibrv_u16 fieldId);

Purpose Get the value of a field as a scalar value.

Remarks Each convenience function in this family retrieves a field and extracts its data. If
the field’s type (as it exists) does not match the type of the convenience function,
then the function attempts to convert the data (see Datatype Conversion on
page 352). If conversion is not possible, the function returns
TIBRV_CONVERSION_FAILED.

(Sheet 1 of 2)

Function Name Type Type Description

tibrvMsg_GetBool tibrv_bool boolean

tibrvMsg_GetF32 tibrv_f32 32-bit floating point

tibrvMsg_GetF64 tibrv_f64 64-bit floating point

tibrvMsg_GetI8 tibrv_i8 8-bit integer

tibrvMsg_GetI16 tibrv_i16 16-bit integer

tibrvMsg_GetI32 tibrv_i32 32-bit integer

tibrvMsg_GetI64 tibrv_i64 64-bit integer

tibrvMsg_GetU8 tibrv_u8 8-bit unsigned integer

tibrvMsg_GetU16 tibrv_u16 16-bit unsigned integer

tibrvMsg_GetU32 tibrv_u32 32-bit unsigned integer

tibrvMsg_GetU64 tibrv_u64 64-bit unsigned integer

TIBCO Rendezvous C Reference

 Get Scalar 87
|

(Sheet 2 of 2)

Function Name Type Type Description

tibrvMsg_GetIPAddr32 tibrv_ipaddr32 4-byte IP address

tibrvMsg_GetIPPort16 tibrv_ipport16 2-byte IP port

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

value When extracting a scalar type, the program supplies a location in

this parameter, and the function copies the scalar value of the
field to that location.

fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must be
unique within each message.

See Also Validity of Data Extracted From Messages, page 41

Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

88
| Chapter 3 Messages

Get Array
Convenience Functions

Declaration tibrv_status tibrvMsg_Getelement_typeArray(

tibrvMsg message,
const char* fieldName,
element_type** value,
tibrv_u32* numElementsAddr)

tibrv_status tibrvMsg_Getelement_typeArrayEx(
tibrvMsg message,
const char* fieldName,
element_type** value,
tibrv_u32* numElementsAddr,
tibrv_u16 fieldId);

Purpose Get the value of a field as an array.

Remarks Each convenience function in this family retrieves a field and extracts its data. If
the field’s type (as it exists) is does not match the type of the convenience
function, then the function attempts to convert the data (see Datatype Conversion
on page 352). If conversion is not possible, the function returns
TIBRV_CONVERSION_FAILED.

Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
These functions produce values that are read-only snapshots of the field data (see
Pointer Snapshot on page 42). Programs must not modify elements of the value
array.

(Sheet 1 of 2)

Function Name Element Type Type Description

tibrvMsg_GetF32Array tibrv_f32 32-bit floating point array

tibrvMsg_GetF64Array tibrv_i64 64-bit floating point array

tibrvMsg_GetI8Array tibrv_i8 8-bit integer array

tibrvMsg_GetI16Array tibrv_i16 16-bit integer array

tibrvMsg_GetI32Array tibrv_i32 32-bit integer array

tibrvMsg_GetI64Array tibrv_i64 64-bit integer array

tibrvMsg_GetU8Array tibrv_u8 8-bit unsigned integer array

TIBCO Rendezvous C Reference

 Get Array 89
|

(Sheet 2 of 2)

Function Name Element Type Type Description

tibrvMsg_GetU16Array tibrv_u16 16-bit unsigned integer array

tibrvMsg_GetU32Array tibrv_u32 32-bit unsigned integer array

tibrvMsg_GetU64Array tibrv_u64 64-bit unsigned integer array

tibrvMsg_GetMsgArray tibrv_Msg message array

tibrvMsg_GetStringArray char* string array

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

value When extracting an array type, the program supplies a

location in this parameter, and the function stores a
pointer to the array in that location.

numElementsAddr When extracting an array type, the program supplies a

location in this parameter, and the function stores the
number of array elements in that location.

fieldId Get the field with this identifier. Zero is a special value
that signifies no field identifier. All non-zero field
identifiers must be unique within each message.

See Also Validity of Data Extracted From Messages, page 41

Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

90
| Chapter 3 Messages

Get Nested Message

Convenience Function

Declaration tibrv_status tibrvMsg_GetMsg(

tibrvMsg message,
const char* fieldName,
tibrvMsg* subMessage);

tibrv_status tibrvMsg_GetMsgEx(
tibrvMsg message,
const char* fieldName,
tibrvMsg* subMessage,
tibrv_u16 fieldId);

Purpose Get the value of a field as a Rendezvous message.

Remarks Since it is not possible to convert any other datatype to a message, the field must
already contain a message. Otherwise, the function returns
TIBRV_CONVERSION_FAILED.

Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
After extracting a submessage, a program can detach it. A detached submessage
remains valid and unchanged even after the parent message is destroyed. The
program must explicitly destroy the detached submessage.
This function produces values that are modifiable snapshots of the field data.
Programs may modify the resulting submessage by adding, removing or
updating fields. However, these modifications do not change the field in the
original parent message; instead, they force Rendezvous software to make a copy
of the field (see Rendezvous Protects the Message from Changes to Submessage
Snapshots on page 44).

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

subMessage The program supplies a location in this parameter, and the

function stores a pointer to the submessage in that location.

fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

TIBCO Rendezvous C Reference

 Get Nested Message 91
|
See Also Validity of Data Extracted From Messages, page 41
Field Names and Field Identifiers, page 46
tibrvMsg_Detach() on page 74

TIBCO Rendezvous C Reference

92
| Chapter 3 Messages

Get String
Convenience Function

Declaration tibrv_status tibrvMsg_GetString(

tibrvMsg message,
const char* fieldName,
const char** value);

tibrv_status tibrvMsg_GetStringEx(
tibrvMsg message,
const char* fieldName,
const char** value,
tibrv_u16 fieldId);

Purpose Get the value of a field as a character string.

Remarks This convenience function retrieves a field and extracts its data, automatically
converting it to a string.
Programs can use this function to obtain a printable representation of field data.
For most datatypes, this function formats the full value of the field to the output
string; however, these two types are exceptions:
TIBRVMSG_OPAQUEThis function abbreviates the value of an opaque field; for
example, [472 opaque bytes].
TIBRVMSG_XML This function abbreviates the value of an XML field; for
example, [XML document: 472 bytes].
The size measures uncompressed data.

Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
This function produces values that are read-only snapshots of the field data (see
Pointer Snapshot on page 42). Programs must not modify the value string.

(Sheet 1 of 2)

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

value The program supplies a location in this parameter, and the

function stores a pointer to the field value in that location.

TIBCO Rendezvous C Reference

 Get String 93
|

(Sheet 2 of 2)

Parameter Description
fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

See Also Validity of Data Extracted From Messages, page 41

Field Names and Field Identifiers, page 46
Datatype Conversion, page 352

TIBCO Rendezvous C Reference

94
| Chapter 3 Messages

Get Opaque Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_GetOpaque(

tibrvMsg message,
const char* fieldName,
const void** value,
tibrv_u32* length);

tibrv_status tibrvMsg_GetOpaqueEx(
tibrvMsg message,
const char* fieldName,
const void** value,
tibrv_u32* length,
tibrv_u16 fieldId);

Purpose Get the value of a field as an opaque byte sequence.

Remarks This convenience function retrieves a field and extracts its data.
Since it is not possible to convert any other datatype to an opaque byte sequence,
the field must already contain an opaque byte sequence. Otherwise, the function
returns TIBRV_CONVERSION_FAILED.
Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
This function produces values that are read-only snapshots of the field data (see
Pointer Snapshot on page 42). Programs must not modify the value sequence.

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

length The program supplies a location in this parameter, and the

function stores the length of the opaque byte sequence in that
location.

value The program supplies a location in this parameter, and the

function stores a pointer to the field value in that location.

fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

TIBCO Rendezvous C Reference

 Get Opaque Byte Sequence 95
|
See Also Validity of Data Extracted From Messages, page 41
Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

96
| Chapter 3 Messages

Get XML Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_GetXml(

tibrvMsg message,
const char* fieldName,
const void** value,
tibrv_u32* length);

tibrv_status tibrvMsg_GetXmlEx(
tibrvMsg message,
const char* fieldName,
const void** value,
tibrv_u32* length,
tibrv_u16 fieldId);

Purpose Get the value of a field as an XML byte sequence.

Remarks This convenience function retrieves a field and extracts its data.
XML data is a byte sequence. Adding a field of type TIBRVMSG_XML compresses
the bytes. Extracting data from the field uncompresses it to obtain the original
byte sequence.
Since it is not possible to convert any other datatype to an XML byte sequence, the
field must already contain an XML byte sequence. Otherwise, the function returns
TIBRV_CONVERSION_FAILED.

Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
This function produces values that are read-only snapshots of the field data (see
Pointer Snapshot on page 42). Programs must not modify the value sequence.

(Sheet 1 of 2)

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

length The program supplies a location in this parameter, and the

function stores the length of the XML byte sequence in that
location.

value The program supplies a location in this parameter, and the

function stores a pointer to the field value in that location.

TIBCO Rendezvous C Reference

 Get XML Byte Sequence 97
|

(Sheet 2 of 2)

Parameter Description
fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

See Also Validity of Data Extracted From Messages, page 41

Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

98
| Chapter 3 Messages

Get DateTime
Convenience Function

Declaration tibrv_status tibrvMsg_GetDateTime(

tibrvMsg message,
const char* fieldName,
tibrvMsgDateTime* value);

tibrv_status tibrvMsg_GetDateTimeEx(
tibrvMsg message,
const char* fieldName,
tibrvMsgDateTime* value,
tibrv_u16 fieldId);

Purpose Get the value of a field as a Rendezvous datetime value.

Remarks This convenience function retrieves a field and extracts its data.
Since it is not possible to convert any other datatype to a datetime value, the field
must already contain a datetime. Otherwise, the function returns
TIBRV_CONVERSION_FAILED.

Pointer data extracted from the field remain valid until the message is destroyed;
that is, even removing the field or updating the field’s value does not invalidate
pointer data.
This function produces values that are read-only snapshots of the field data (see
Pointer Snapshot on page 42). Programs must not modify the datetime value.

Parameter Description
message Get the specified field of this message.

fieldName Get a field with this name.

value The program supplies a location in this parameter, and the

function stores a pointer to the field value in that location.

fieldId Get the field with this identifier. Zero is a special value that
signifies no field identifier. All non-zero field identifiers must
be unique within each message.

Example This example code extracts a datetime value from a message field, and converts it
to a time_t value. Programs can adapt this code as appropriate. (For
corresponding code to convert a time_t value to a datetime value, and add the
datetime to a message field, see the example at Add DateTime, page 67.)

TIBCO Rendezvous C Reference

 Get DateTime 99
|
#include <limits.h>

tibrv_status
getAsTimeT(tibrvMsg msg,
const char * field,
time_t * value)
{
tibrvMsgDateTime d;
tibrv_status err;

err = tibrvMsg_GetDateTime(msg, field, &d);

if( err != TIBRV_OK )
return err;

if( d.sec > INT_MAX || d.sec < INT_MIN )

return TIBRV_CONVERSION_FAILED;
*value = (time_t) d.sec;

return TIBRV_OK;
}

See Also Validity of Data Extracted From Messages, page 41

Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

100
| Chapter 3 Messages

tibrvMsg_GetFieldByIndex()
Function

Declaration tibrv_status tibrvMsg_GetFieldByIndex(

tibrvMsg message,
tibrvMsgField* field,
tibrv_u32 fieldIndex);

Purpose Get a field from a message by an index.

Remarks Programs can loop through all the fields of a message, to retrieve each field in
turn using an integer index.
The function copies scalar data into the program’s field struct. Pointer data
extracted from the field remain valid until the message is destroyed; that is, even
removing the field or updating the field’s value does not invalidate pointer data.
Add, remove and update calls can perturb the order of fields (which, in turn, affects
the results when a program gets a field by index).

Parameter Description
message Get the field from this message.

field The program supplies a pointer to a tibrvMsgField struct; the

function overwrites the contents of the struct, using
information from the message field.

fieldIndex Get the field with this index. Zero specifies the first field.

See Also tibrvMsg_GetField() on page 82

TIBCO Rendezvous C Reference

 tibrvMsg_GetFieldInstance() 101
|

tibrvMsg_GetFieldInstance()
Function

Declaration tibrv_status tibrvMsg_GetFieldInstance(

tibrvMsg message,
const char* fieldName,
tibrvMsgField* fieldAddr,
tibrv_u32 instance);

Purpose Get a specified instance of a field from a message.

Remarks When a message contains several field instances with the same field name,
retrieve a specific instance by number (for example, get the ith field named foo).
Programs can use this function in a loop that examines every field with a specified
name.
The argument 1 denotes the first instance of the named field.
The function copies scalar data into the program’s field struct. Pointer data
extracted from the field remain valid until the message is destroyed; that is, even
removing the field or updating the field’s value does not invalidate pointer data.
When the instance argument is greater than the actual number of instances of
the field in the message, this function returns the status code TIBRV_NOT_FOUND.

Release 5 Rendezvous 5 (and earlier) did not support array datatypes. Some older
Interaction programs circumvented this limitation by using several fields with the same
name to simulate arrays. This work-around is no longer necessary, since release 6
(and later) supports array datatypes within message fields. The function
tibrvMsg_GetFieldInstance() ensures backward compatibility, so new
programs can still receive and manipulate messages sent from older programs.
Nonetheless, we encourage programmers to use array types as appropriate, and
we discourage storing several fields with the same name in a message.

(Sheet 1 of 2)

Parameter Description
message Get the specified field instance of this message.

fieldName Get an instance of the field with this name.

NULL specifies the empty string as the field name.

fieldAddr The program supplies a pointer to a tibrvMsgField struct; the

function overwrites the contents of the struct, using
information from the message field.

TIBCO Rendezvous C Reference

102
| Chapter 3 Messages

(Sheet 2 of 2)

Parameter Description
instance Get this instance of the specified field name. The argument 1
denotes the first instance of the named field.

See Also tibrvMsg_GetField() on page 82

TIBCO Rendezvous C Reference

 tibrvMsg_GetNumFields() 103
|

tibrvMsg_GetNumFields()
Function

Declaration tibrv_status tibrvMsg_GetNumFields(

tibrvMsg message,
tibrv_u32* numFields);

Purpose Extract the number of fields in a message.

Remarks This call counts the immediate fields of the message; it does not descend into
submessages to count their fields recursively.

Parameter Description
message Extract the number of fields in this message.

numFields The program supplies a location in this parameter; the

function stores the number of fields in that location.

TIBCO Rendezvous C Reference

104
| Chapter 3 Messages

tibrvMsg_GetReplySubject()
Function

Declaration tibrv_status tibrvMsg_GetReplySubject(

tibrvMsg message,
const char** replySubject);

Purpose Extract the reply subject from a message.

Remarks The reply subject string is part of a message’s address information—it is not part
of the message itself.
Programs must not modify the storage in which this reply subject string resides.

Parameter Description
message Get the subject of this message.

replySubject The function stores a pointer to the reply subject string in

this location.
The function 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
function that determines the scope of an inbound message.
For more information, see Pointer Snapshot on page 42,
and Deleting Snapshot References on page 45.

See Also tibrvMsg_SetSendSubject() on page 113

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C Reference

 tibrvMsg_GetSendSubject() 105
|

tibrvMsg_GetSendSubject()
Function

Declaration tibrv_status tibrvMsg_GetSendSubject(

tibrvMsg message,
const char** subject);

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.
Programs must not modify the storage in which this subject string resides.

Parameter Description
message Get the subject of this message.

subject The function stores a pointer to the subject string in this location.
The function 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
function that determines the scope of an inbound message. For
more information, see Pointer Snapshot on page 42, and
Deleting Snapshot References on page 45.

See Also tibrvMsg_SetSendSubject() on page 113

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C Reference

106
| Chapter 3 Messages

tibrvMsg_MarkReferences()
Function

Declaration tibrv_status tibrvMsg_MarkReferences(

tibrvMsg message);

Purpose Mark references in this message.

Parameter Description
message Mark references in this message.

Remarks Extracting pointer data from a message field creates a snapshot of that data. The
snapshot remains associated with the message until the program destroys the
message. However, in rare situations snapshots can accumulate within a program,
causing unbounded memory growth. This function gives programs explicit
control over snapshot references; by clearing references, the program declares that
it no longer needs the references that arise as side effects of calls that get a message
field.
For example, consider a program fragment that repeatedly sends a template
message, getting and updating fields within a nested submessage before each
send call. Each call to extract the nested message produces a snapshot reference.
By surrounding the get operation with a mark and clear pair (with the clear call
occurring at any time after the get call), the program releases the reference, which
helps control memory usage.
void myTimerCB(
tibrvEvent myTimer,
tibrvMsg empty,
void* closure_msg_arg)
{
tibrvMsg msg = (tibrvMsg)closure_msg_arg;
tibrvMsg submsg;

tibrvMsg_MarkReferences(msg);
tibrvMsg_GetMsg(msg, "foo", &submsg);
...
tibrvMsg_ClearReferences(msg);
tibrvMsg_SetSendSubject(msg, some_subject);
tibrvTransport_Send(myTransport, msg);
}

TIBCO Rendezvous C Reference

 tibrvMsg_MarkReferences() 107
|

Every call to tibrvMsg_MarkReferences() must be paired with a call to

tibrvMsg_ClearReferences(). It is legal to mark references several times, as
long as the program eventually clears all the marks. To understand this idea, it is
helpful to think of get and mark as pushdown operations, and clear as a pop
operation. Figure 5 illustrates that each clear call deletes snapshots back to the
most recent mark.

Figure 5 Mark and Clear References

This pointer remains valid until the call that clears

references back to mark 1 (that is, the second clear call).

Mark 1
Pointer to
Array
Snapshot
Value
1
Snapshot 1
Mark 2
Pointer to
Array
Snapshot
Value
2
Snapshot 2

This pointer remains valid until the call that clears

references back to mark 2 (that is, the first clear call).

Unless a program explicitly marks and clears references, references persist until
the message is destroyed or reset.

See Also Validity of Data Extracted From Messages, page 41

Deleting Snapshot References, page 45
tibrvMsg_ClearReferences() on page 68

TIBCO Rendezvous C Reference

108
| Chapter 3 Messages

tibrvMsg_RemoveField()
Function

Declaration tibrv_status tibrvMsg_RemoveField(

tibrvMsg message,
const char* fieldName);

tibrv_status tibrvMsg_RemoveFieldEx(
tibrvMsg message,
const char* fieldName,
tibrv_u16 fieldId);

Purpose Remove a field from a message.

Remarks Pointer data (such as strings, arrays, submessages, opaque byte sequences or
XML data) previously extracted from the field remains valid even after removing
the field from the message.

Parameter Description
message Remove the specified field from this message.

fieldName Remove the field with this name.

fieldId Remove the field with this identifier. Zero is a special value
that signifies no field identifier.

Field Search This function uses this algorithm to find and remove a field within a message, as
Algorithm specified by a field identifier and a field name.
1. The extended function begins here. The regular function begins at step 3.
If the program supplied a non-zero field identifier, then search for the field
with that identifier. If the search succeeds, remove the field.
On failure, continue to step 2. (If the identifier is zero, skip to step 3.)
2. If the identifier search (in step 1) fails, and the program supplied a non-NULL
field name, then search for a field with that name.
If the program supplied NULL as the field name, return the status code
TIBRV_NOT_FOUND.

If the name search fails, return the status code TIBRV_NOT_FOUND.

If the name search succeeds, but the actual identifier in the field is non-NULL
(so it does not match the identifier supplied) then return the status code
TIBRV_ID_CONFLICT.

TIBCO Rendezvous C Reference

 tibrvMsg_RemoveField() 109
|

If the search succeeds, remove the field.

3. The regular function begins here. The extended function also begins here
when the program supplied zero as the identifier (supplying zero is equivalent
to not supplying a field identifier, so the behavior is equivalent to the regular
function).
Search for a field with the specified name—even if that name is NULL.
If the search succeeds, remove the field.
If the search fails, return the status code TIBRV_NOT_FOUND.

If a message contains several fields with the same name, searching by name
removes the first instance of the field with that name.

TIBCO Rendezvous C Reference

110
| Chapter 3 Messages

tibrvMsg_RemoveFieldInstance()
Function

Declaration tibrv_status tibrvMsg_RemoveFieldInstance(

tibrvMsg message,
const char* fieldName,
tibrv_u32 instance);

Purpose Remove a specified instance of a field from a message.

Remarks When a message contains several field instances with the same field name,
remove a specific instance by number (for example, remove the ith field named
foo). Programs can use this function 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 function returns TIBRV_NOT_FOUND.
Pointer data (such as strings, arrays, submessages, opaque byte sequences or
XML data) previously extracted from the field remains valid even after removing
the field from the message.

Parameter Description
message Remove the specified field from this message.

fieldName Remove the field with this name.

instance Remove this instance of the field. The argument 1 specifies the
first instance of the named field.

See Also tibrvMsg_RemoveField() on page 108

TIBCO Rendezvous C Reference

 tibrvMsg_Reset() 111
|

tibrvMsg_Reset()
Function

Declaration tibrv_status tibrvMsg_Reset(

tibrvMsg message);

Purpose Clear a message, preparing it for re-use.

Remarks This function is the equivalent of tibrvMsg_Destroy(), followed immediately by

tibrvMsg_Create()—except that the storage is not freed, but rather re-used.

When this function returns, the message has no fields; it is like a newly created
message. The message’s address information is also reset.
Pointer data (such as strings, arrays, submessages, opaque byte sequences or
XML data) previously extracted from fields of the old message are invalid.

Parameter Description
message Reset this message.

See Also tibrvMsg_Create() on page 70

tibrvMsg_Destroy() on page 73

TIBCO Rendezvous C Reference

112
| Chapter 3 Messages

tibrvMsg_SetReplySubject()
Function

Declaration tibrv_status tibrvMsg_SetReplySubject(

tibrvMsg message,
const char* replySubject);

Purpose Set the reply subject for a message.

Remarks Recipients of a message can use its reply subject as the address for return
messages.
Rendezvous routing daemons modify subjects and reply subjects to enable
transparent point-to-point communication across network boundaries. This
modification does not apply to subject names stored in message data fields; we
discourage storing point-to-point subject names in data fields.

Parameter Description
message Set the reply subject of this message.

replySubject Use this string as the new reply subject.

The function copies this string to the message.
The empty string is not a legal subject name.

Subject Name The constant TIBRV_SUBJECT_MAX determines the longest possible subject name.
Length

See Also tibrvMsg_GetReplySubject() on page 104

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C Reference

 tibrvMsg_SetSendSubject() 113
|

tibrvMsg_SetSendSubject()
Function

Declaration tibrv_status tibrvMsg_SetSendSubject(

tibrvMsg message,
const char* subject);

Purpose Set the subject for a message.

Remarks The subject of a message can describe its content, as well as its destination set.
Rendezvous routing daemons modify subjects and reply subjects to enable
transparent point-to-point communication across network boundaries. This
modification does not apply to subject names stored in message data fields; we
discourage storing point-to-point subject names in data fields.

Parameter Description
message Set the subject of this message.

subject Use this string as the new subject.

The function copies this string to the message.
The empty string is not a legal subject name.

Subject Name The constant TIBRV_SUBJECT_MAX determines the longest possible subject name.
Length

See Also tibrvMsg_GetSendSubject() on page 105

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

TIBCO Rendezvous C Reference

114
| Chapter 3 Messages

tibrvMsg_UpdateField()
Function

Declaration tibrv_status tibrvMsg_UpdateField(

tibrvMsg message,
tibrvMsgField* field);

Purpose Update a field within a message.

For most programs, we recommend type-specific convenience functions instead
of this generic function. However, translation engine programs can require
generic tibrvMsg_UpdateField(), and would use it in conjunction with generic
tibrvMsg_GetField(). In this paradigm, modify the field returned from
tibrvMsg_GetField() by replacing its field->value, and supply it as the field
argument to tibrvMsg_UpdateField().

Remarks This function locates a field within the message by matching the name and
identifier of field. Then it updates the message field using the field argument.
(Notice that the program may not supply a field object with a different field name,
field identifier, or datatype.)
If no existing field matches the specifications in the field argument, then this
function adds the field to the message. Update convenience functions also add the
field if it is not present.
The type of the existing field (within the message) and the type of the updating
field argument must be identical; otherwise, the function returns the error status
code TIBRV_INVALID_TYPE. However, when updating array or vector fields, the
count (number of elements) can change.
Pointer data (such as strings, arrays, submessages, opaque byte sequences or
XML data) previously extracted from the field remain valid and unchanged until
the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data.

Parameter Description
message Update this message.

field Update the existing message field using this field.

Field Search This function, and related functions that update message fields, all use this
Algorithm algorithm to find and update a field within a message, as specified by a field
identifier and a field name.
1. Extended functions begin here. Regular functions begin at step 3.
If the identifier is zero, skip to step 3.

TIBCO Rendezvous C Reference

 tibrvMsg_UpdateField() 115
|

If the program supplied a non-zero field identifier, then search for the field
with that identifier.
If the search succeeds, then update that field.
On failure, continue to step 2.
2. If the identifier search (in step 1) fails, and the program supplied a non-NULL
field name, then search for a field with that name.
If the program supplied NULL as the field name, return the status code
TIBRV_NOT_FOUND.

If the name search succeeds, but the actual identifier in the field is non-NULL
(so it does not match the identifier supplied) then return the status code
TIBRV_ID_CONFLICT.

If the search fails, add the field as specified (with name and identifier).
3. Regular functions begin here. Extended functions also begin here when the
program supplied zero as the identifier (supplying zero is equivalent to not
supplying a field identifier, so the behavior is equivalent to the corresponding
regular function).
Search for a field with the specified name—even if that name is NULL.
If the search fails, add the field as specified (with name and identifier).

If a message contains several fields with the same name, searching by name finds
the first instance of the field with that name.

Reserved Field Name

The field name _data_ is reserved. Programs may not add fields with this name.
(More generally, all fields that begin with the underbar character are reserved.)

Field Name The constant TIBRVMSG_FIELDNAME_MAX determines the longest possible field
Length name.

Convenience When the datatype of a field is determined during execution, use this general
Functions function. When you can determine the datatype of a field before compile-time, we
recommend using type-specific convenience functions instead of this general
function. Type-specific functions yield these advantages when updating fields:
• Code readability.
• Type checking.

TIBCO Rendezvous C Reference

116
| Chapter 3 Messages

These categories of type-specific convenience functions find a field and update its
data:
• Update Scalar, page 117.
• Update Array, page 119.
• Update Nested Message, page 121.
• Update String, page 122.
• Update Opaque Byte Sequence, page 123
• Update XML Byte Sequence, page 124
• Update DateTime, page 125

Extended Each convenience function has two forms.

Functions
• The usual form specifies the field to update using a field name.
• The extended form specifies the field to update using a field name and a field
identifier.

For example, the function tibrvMsg_UpdateI32() is paired with the extended

form tibrvMsg_UpdateI32Ex().
The field identifier has type tibrv_u16. Zero is a special value that signifies no
field identifier. All non-zero field identifiers must be unique within each message.
It is illegal to add a field that has both a NULL field name, and a non-zero field
identifier.
For details, see Field Names and Field Identifiers, page 46.

TIBCO Rendezvous C Reference

 Update Scalar 117
|

Update Scalar
Convenience Functions

Declaration tibrv_status tibrvMsg_Updatescalar_type(

tibrvMsg message,
const char* fieldName,
scalar_type value);

tibrv_status tibrvMsg_Updatescalar_typeEx(
tibrvMsg message,
const char* fieldName,
scalar_type value,
tibrv_u16 fieldId);

Purpose Update a field containing a scalar value.

Remarks Each convenience function in this family locates a field (by name or identifier)
and updates its data.
The type of the existing field (within the message) and the type of the updating
value must match.

(Sheet 1 of 2)

Function Name Value Type Type Description

tibrvMsg_UpdateBool tibrv_bool boolean scalar

tibrvMsg_UpdateI8 tibrv_i8 8-bit integer

tibrvMsg_UpdateU8 tibrv_u8 8-bit unsigned integer

tibrvMsg_UpdateI16 tibrv_i16 16-bit integer

tibrvMsg_UpdateU16 tibrv_u16 16-bit unsigned integer

tibrvMsg_UpdateI32 tibrv_i32 32-bit integer

tibrvMsg_UpdateU32 tibrv_u32 32-bit unsigned integer

tibrvMsg_UpdateI64 tibrv_i64 64-bit integer

tibrvMsg_UpdateU64 tibrv_u64 64-bit unsigned integer

tibrvMsg_UpdateF32 tibrv_f32 32-bit floating point

tibrvMsg_UpdateF64 tibrv_f64 64-bit floating point

TIBCO Rendezvous C Reference

118
| Chapter 3 Messages

(Sheet 2 of 2)

Function Name Value Type Type Description

tibrvMsg_UpdateIPAddr32 tibrv_ipaddr32 4-byte IP address

tibrvMsg_UpdateIPPort16 tibrv_ipport16 2-byte IP port

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value (which may be a literal
or stored in a variable).
The function copies the value into the new message field.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

 Update Array 119
|

Update Array
Convenience Functions

Declaration tibrv_status tibrvMsg_Updateelement_typeArray(

tibrvMsg message,
const char* fieldName,
const element_type* value,
tibrv_u32 numElements);

tibrv_status tibrvMsg_Updateelement_typeArrayEx(
tibrvMsg message,
const char* fieldName,
const element_type* value,
tibrv_u32 numElements,
tibrv_u16 fieldId);

Purpose Update a field containing an array value.

Remarks Each convenience function in this family locates a field (by name or identifier)
and updates its data.
The type of the existing field (within the message) and the type of the updating
value must match. The number of elements can change.

Pointer data previously extracted from the field remain valid and unchanged
until the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data. (See Pointer Snapshot on page 42.)

(Sheet 1 of 2)

Function Name Element Type Type Description

tibrvMsg_UpdateI8Array tibrv_i8 8-bit integer array

tibrvMsg_UpdateU8Array tibrv_u8 8-bit unsigned integer array

tibrvMsg_UpdateI16Array tibrv_i16 16-bit integer array

tibrvMsg_UpdateU16Array tibrv_u16 16-bit unsigned integer array

tibrvMsg_UpdateI32Array tibrv_i32 32-bit integer array

tibrvMsg_UpdateU32Array tibrv_u32 32-bit unsigned integer array

tibrvMsg_UpdateI64Array tibrv_i64 64-bit integer array

tibrvMsg_UpdateU64Array tibrv_u64 64-bit unsigned integer array

TIBCO Rendezvous C Reference

120
| Chapter 3 Messages

(Sheet 2 of 2)

Function Name Element Type Type Description

tibrvMsg_UpdateF32Array tibrv_f32 32-bit floating point array

tibrvMsg_UpdateF64Array tibrv_f64 64-bit floating point array

tibrvMsg_UpdateMsgArray tibrv_Msg message array

tibrvMsg_UpdateStringArray char* string array

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this array value.

The function copies the new array into the existing field.

numElements When updating an array type, the program supplies the count
of array elements in this parameter.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

 Update Nested Message 121
|

Update Nested Message

Convenience Function

Declaration tibrv_status tibrvMsg_UpdateMsg(

tibrvMsg message,
const char* fieldName,
tibrvMsg value);

tibrv_status tibrvMsg_UpdateMsgEx(
tibrvMsg message,
const char* fieldName,
tibrvMsg value,
tibrv_u16 fieldId);

Purpose Update a field containing a nested submessage.

Remarks This convenience function locates a field (by name or identifier) and updates its
data.
The type of the existing field (within the message) and the type of the updating
value must match. The message size (that is, its length in bytes) can change.

This function uses only the data portion of the nested message (value); it does not
include any address information or certified delivery information.

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value.

The function copies the new value into the field.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

122
| Chapter 3 Messages

Update String
Convenience Function

Declaration tibrv_status tibrvMsg_UpdateString(

tibrvMsg message,
const char* fieldName,
const char* value);

tibrv_status tibrvMsg_UpdateStringEx(
tibrvMsg message,
const char* fieldName,
const char* value,
tibrv_u16 fieldId);

Purpose Update a field containing a character string.

Remarks This convenience function locates a field (by name or identifier) and updates its
data.
The type of the existing field (within the message) and the type of the updating
value must match. The length of the string can change.

Pointer data previously extracted from the field remain valid and unchanged
until the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data. (See Pointer Snapshot on page 42.)

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value (which may be a literal
or stored in a variable).
The function copies the new value into the existing field.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

 Update Opaque Byte Sequence 123
|

Update Opaque Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_UpdateOpaque(

tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size);

tibrv_status tibrvMsg_UpdateOpaqueEx(
tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size,
tibrv_u16 fieldId);

Purpose Update a field containing an opaque byte sequence.

Remarks This convenience function locates a field (by name or identifier) and updates its
data.
The type of the existing field (within the message) and the type of the updating
value must match. The size can change.

Pointer data previously extracted from the field remain valid and unchanged
until the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data. (See Pointer Snapshot on page 42.)

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value.

The function copies the new value into the existing field.

size The program supplies the size of the new data in this
parameter.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

124
| Chapter 3 Messages

Update XML Byte Sequence

Convenience Function

Declaration tibrv_status tibrvMsg_UpdateXml(

tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size);

tibrv_status tibrvMsg_UpdateXmlEx(
tibrvMsg message,
const char* fieldName,
const void* value,
tibrv_u32 size,
tibrv_u16 fieldId);

Purpose Update a field containing an XML byte sequence.

Remarks This convenience function locates a field (by name or identifier) and updates its
data.
The type of the existing field (within the message) and the type of the updating
value must match. The size can change.

Pointer data previously extracted from the field remain valid and unchanged
until the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data. (See Pointer Snapshot on page 42.)
XML data is a byte sequence. Adding (or updating) a field of type
TIBRVMSG_XML compresses the bytes. Extracting data from the field
uncompresses it to obtain the original byte sequence.

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value.

The function copies the new value into the existing field.

size The program supplies the size of the new data in this parameter.

fieldId Update the field with this identifier. Zero is a special value that signifies no field
identifier. It is illegal to add a field that has both a NULL field name, and a non-zero
field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

 Update DateTime 125
|

Update DateTime
Convenience Function

Declaration tibrv_status tibrvMsg_UpdateDateTime(

tibrvMsg message,
const char* fieldName,
const tibrvMsgDateTime* value);

tibrv_status tibrvMsg_UpdateDateTimeEx(
tibrvMsg message,
const char* fieldName,
const tibrvMsgDateTime* value,
tibrv_u16 fieldId);

Purpose Update a field containing a datetime value.

Remarks This convenience function locates a field (by name or identifier) and updates its
data.
The type of the existing field (within the message) and the type of the updating
value must match.

Pointer data previously extracted from the field remain valid and unchanged
until the message is destroyed; that is, even updating the field’s value does not
invalidate pointer data. (See Pointer Snapshot on page 42.)

Parameter Description
message Update the specified field of this message.

fieldName Update a field with this name.

value Update the message field to this value.

The function copies the new value into the existing field.

fieldId Update the field with this identifier. Zero is a special value that
signifies no field identifier. It is illegal to add a field that has
both a NULL field name, and a non-zero field identifier.

See Also Field Names and Field Identifiers, page 46

TIBCO Rendezvous C Reference

126
| Chapter 3 Messages

TIBCO Rendezvous C Reference

 | 127

Chapter 4 Events

Programs can express interest in events of three kinds—inbound messages,

timers, and I/O conditions. When an event occurs, it triggers a program callback
function to process the event.
This chapter presents functions and types associated with event interest and
event processing.

Topics

• Operations by Functional Group, page 128

• Operations in Alphabetical Order, page 130

TIBCO Rendezvous C Reference

128
| Chapter 4 Events

Operations by Functional Group

(Sheet 1 of 2)

Function or Type Description Page

Event Interest: Create and Destroy

tibrvEvent_CreateListener() Listen for inbound messages. 140

tibrvEvent_CreateVectorListener() Listen for inbound messages, and receive 146

them in a vector.

tibrvEvent_CreateTimer() Start a timer. 143

tibrvEvent_CreateIO() Wait for specified I/O situations to occur. 138

tibrvEvent_Destroy() Destroy an event, canceling interest. 151

tibrvEvent_DestroyEx() Destroy an event, and run a completion 152

function when all of the destroyed event’s
callback functions are complete.

Event Accessors

tibrvEvent_GetIOSource() Extract the source (socket ID) from an I/O 153

event object.

tibrvEvent_GetIOType() Extract the I/O type from an I/O event object. 154

tibrvEvent_GetListenerSubject() Extract the subject from a listener event object. 155

tibrvEvent_GetListenerTransport() Extract the transport from a listener event 156

object.

tibrvEvent_GetTimerInterval() Extract the interval from a timer event object. 157

tibrvEvent_GetType() Extract the type of an event object. 158

tibrvEvent_GetQueue() Extract the queue of an event object. 159

tibrvEvent_ResetTimerInterval() Reset the interval of a timer event object. 160

TIBCO Rendezvous C Reference

 Operations by Functional Group 129
|

(Sheet 2 of 2)

Function or Type Description Page

Types Related to Events

tibrvEvent Each call to a Rendezvous event creation 132

function results in a new event object, which
represents your program’s interest in a class of
events. Rendezvous software uses the same
event object to signal each occurrence of such
an event.

tibrvEventCallback Programs define functions of this type to 133

process events.

tibrvEventVectorCallback Programs define functions of this type to 137

process message vector events.

tibrvEventOnComplete A program can destroy an event object even 134

when its callback function is running in one or
more threads. Multi-threaded programs can
define functions of this type to discover when
all callback functions in progress have
completed.

tibrvEventType Distinguish event objects as listeners, timers, 161

or I/O interest.

tibrvIOType Distinguish event interest in I/O conditions. 162

TIBCO Rendezvous C Reference

130
| Chapter 4 Events

Operations in Alphabetical Order

(Sheet 1 of 2)

Function or Type Description Page

tibrvEvent Each call to a Rendezvous event creation 132
function results in a new event object, which
represents your program’s interest in a class of
events. Rendezvous software uses the same
event object to signal each occurrence of such
an event.

tibrvEventCallback Programs define functions of this type to 133

process events.

tibrvEventOnComplete A program can destroy an event object even 134

when its callback function is running in one or
more threads. Multi-threaded programs can
define functions of this type to discover when
all callback functions in progress have
completed.

tibrvEventVectorCallback Programs define functions of this type to 137

process message vector events.

tibrvEvent_CreateIO() Wait for specified I/O situations to occur. 138

tibrvEvent_CreateListener() Listen for inbound messages. 140

tibrvEvent_CreateTimer() Start a timer. 143

tibrvEvent_CreateVectorListener() Listen for inbound messages, and receive 146

them in a vector.

tibrvEvent_Destroy() Destroy an event, canceling interest. 151

tibrvEvent_DestroyEx() Destroy an event, and run a completion 152

function when all of the destroyed event’s
callback functions are complete.

tibrvEvent_GetIOSource() Extract the source (socket ID) from an I/O 153

event object.

TIBCO Rendezvous C Reference

 Operations in Alphabetical Order 131
|

(Sheet 2 of 2)

Function or Type Description Page

tibrvEvent_GetIOType() Extract the I/O type from an I/O event object. 154

tibrvEvent_GetListenerSubject() Extract the subject from a listener event object. 155

tibrvEvent_GetListenerTransport() Extract the transport from a listener event 156

object.

tibrvEvent_GetTimerInterval() Extract the interval from a timer event object. 157

tibrvEvent_GetType() Extract the type of an event object. 158

tibrvEvent_GetQueue() Extract the queue of an event object. 159

tibrvEventType Distinguish event objects as listeners, timers, 161

or I/O interest.

tibrvIOType Distinguish event interest in I/O conditions. 162

TIBCO Rendezvous C Reference

132
| Chapter 4 Events

tibrvEvent
Type

Declaration typedef tibrvId tibrvEvent;

Purpose Event objects represent program interest in events, and event occurrences.

Remarks Each call to a Rendezvous event creation function results in a new event object,
which represents your program’s interest in a class of events. Rendezvous
software uses the same event object to signal each occurrence of such an event.
Programs use the event object as a token; they cannot view or modify the object,
except using accessor functions.
Programs must explicitly destroy each event object. Destroying an event object
cancels the program’s interest in that event, and frees its storage.

See Also tibrvEvent_Destroy() on page 151

Event Creation tibrvEvent_CreateIO() on page 138

Functions tibrvEvent_CreateListener() on page 140
tibrvEvent_CreateVectorListener() on page 146
tibrvEvent_CreateTimer() on page 143

Event Accessor tibrvEvent_GetIOSource() on page 153

Functions tibrvEvent_GetIOType() on page 154
tibrvEvent_GetListenerSubject() on page 155
tibrvEvent_GetListenerTransport() on page 156
tibrvEvent_GetTimerInterval() on page 157
tibrvEvent_GetType() on page 158
tibrvEvent_GetQueue() on page 159

TIBCO Rendezvous C Reference

 tibrvEventCallback 133
|

tibrvEventCallback
Function Type

Declaration typedef void (*tibrvEventCallback) (

tibrvEvent event,
tibrvMsg message,
void* closure);

Purpose Programs define functions of this type to process events.

Remarks A single callback function type spans listener, timer and I/O events.

Parameter Description
event This parameter receives the event object. This object is
identical to the object that the program created to express
event interest.

message When the event object is a listener, the callback receives the
inbound message in this parameter. If the inbound message is
empty, this parameter receives a message that has no fields.
When the event object is a timer or I/O event, this parameter
receives NULL.

closure This parameter receives the closure data, which the program
supplied in the call that created the event object.

See Also tibrvEvent_CreateIO() on page 138

tibrvEvent_CreateListener() on page 140
tibrvEvent_CreateTimer() on page 143

TIBCO Rendezvous C Reference

134
| Chapter 4 Events

tibrvEventOnComplete
Function Type

Declaration typedef void (*tibrvEventOnComplete) (

tibrvEvent destroyedEvent,
void* closure);

Purpose A program can destroy an event object even when its callback function is running
in one or more threads. Multi-threaded programs can define functions of this type
to discover when all callback functions in progress have completed.

Parameter Description
destroyedEvent This parameter receives the event object. This object is
identical to the object that the program created to express
event interest.
However, by the time this function runs, the event is
already destroyed; this function cannot use the event
object in Rendezvous calls.

closure This parameter receives the closure data, which the

program supplied in the call that created the event object.

Remarks This type of function is important in two situations:

• An event callback function calls tibrvEvent_DestroyEx() to destroy its
event, and the program must do additional processing after the rest of the
callback function has completed.
• Several threads dispatch an event (so the event callback function can be
running in several threads) and the program must do additional processing
after the callback function has completed in all threads.

Upon return from tibrvEvent_DestroyEx(), the destroyed event’s callback

function can no longer begin to run. However, in each thread where the callback
function is already in progress, that callback function does continue to run until
complete.
tibrvEvent_DestroyEx() accepts a completion function argument of type
tibrvEventOnComplete. Rendezvous software ensures that the completion
function runs when the last callback-in-progress has completed.

Timing and This completion function can run in two situations:

Context
• Figure 6 on page 136 illustrates a situation in which the program calls
tibrvEvent_DestroyEx() while callback functions of the destroyed event are

TIBCO Rendezvous C Reference

 tibrvEventOnComplete 135
|

in progress. When the last of those callback functions completes, Rendezvous

software runs the completion function immediately, in the same thread as the
callback function that completes last.
• Figure 7 on page 136 illustrates a situation in which the program calls
tibrvEvent_DestroyEx() when the destroyed event’s callback function is
not running in any thread. In this case, tibrvEvent_DestroyEx() calls the
completion function before returning.
Notice that in this situation, the completion function runs in the program
context, instead of the usual context of a callback function. In rare instances,
deadlock can occur, resulting from unintended interactions between mutex
operations in the program context before the destroy call, and mutex
operations in the program’s completion function code.
To protect against this type of deadlock, programmers can use a
straightforward thought-experiment as a preventive test. Expand the
completion function code immediately after the call to
tibrvEvent_DestroyEx()—as it would run when the destroyed event’s
callback function is not running in any thread. Trace mutex locking activity
within this context to determine whether the resulting code could violate
established rules for proper use of mutex locks.
...
mutex lock operations
...
tibrvEvent_DestroyEx()
expand completion function code here, and check for violations of mutex rules
...

Potential violations and conflicts usually become apparent during this

exercise. Remember, it is the programmer’s responsibility to prevent
deadlock.

TIBCO Rendezvous C Reference

136
| Chapter 4 Events

Figure 6 Completion when Callback Functions are in Progress

2. Destroy event. Event becomes invalid.

No more callback functions can begin running.

Event Valid

Callback Function Running

in Thread 1

Callback Function Running Completion Function Running

in Thread 2 in Thread 2

Callback Function Running 3. All callback functions are complete.

in Thread 3 The completion function runs
immediately after the last callback
function returns, in the dispatch
1. Several threads dispatch the event, thread of that callback function.
running its callback function.

Figure 7 Completion when Callback Functions are Not in Progress

1. Destroy event. Event becomes invalid.

Event Valid
No more callback functions can begin running.

Program Code Completion Function Running

Context in Destroy Thread

2. Notice that no callback functions are in progress when the

program destroys the event. So the completion function runs in
the destroy thread, immediately after the destroy function returns.

See Also tibrvEvent_CreateIO() on page 138

tibrvEvent_CreateListener() on page 140
tibrvEvent_CreateTimer() on page 143
tibrvEvent_DestroyEx() on page 152

TIBCO Rendezvous C Reference

 tibrvEventVectorCallback 137
|

tibrvEventVectorCallback
Function Type

Declaration typedef void (*tibrvEventVectorCallback) (

tibrvMsg messages[],
tibrv_u32 numMessages);

Purpose Programs define functions of this type to process message vector events.

Remarks In the simplest arrangement, your callback function processes the messages in the
array. When the callback function returns, the Rendezvous library deallocates the
array.
If your application requires a more complex processing arrangement, it can
detach individual messages, and pass them to other threads for processing. (If
your program detaches a message, then it must also explicitly destroy it.)
It is illegal to pass the message array to a different thread for processing, or to use
it as dynamically-allocated storage.
Notice that in contrast to tibrvEventCallback, this vector callback does not
receive the listener event and the closure object as arguments. You can use
tibrvMsg_GetEvent() and tibrvMsg_GetClosure() to get them from the
individual message objects.

Parameter Description
messages The callback receives an array of inbound messages in this
parameter.

numMessages This parameter receives the number of messages in the array.

See Also tibrvMsg_Detach() on page 74

tibrvMsg_GetClosure() on page 79
tibrvMsg_GetEvent() on page 81
tibrvEvent_CreateVectorListener() on page 146

TIBCO Rendezvous C Reference

138
| Chapter 4 Events

tibrvEvent_CreateIO()
Function

Declaration tibrv_status tibrvEvent_CreateIO(

tibrvEvent* event,
tibrvQueue queue,
tibrvEventCallback callback,
tibrv_i32 socketId,
tibrvIOType ioType,
const void* closure);

Purpose Wait for specified I/O situations to occur.

Parameter Description
event For each I/O occurrence, place this event object on the event
queue.
The program supplies a location, and the function stores the
new event object in that location.
The event object remains valid until the program explicitly
destroys it.

queue For each I/O occurrence, place the event on this event queue.

callback On dispatch, process the event with this callback function.

socketID Wait for I/O occurrences on this socket.

ioType Wait for I/O occurrences of this type.

See tibrvIOType on page 162.

closure Store this closure data in the event object.

Activation and This function creates an event object that describes an I/O situation, and activates
Dispatch the event—that is, it requests notification from the operating system when that
I/O situation occurs. When the situation occurs, Rendezvous software deactivates
the event, and places the event object on its event queue. Dispatch removes the
event object from the queue, and runs the callback function to process the event.
When the callback function returns, Rendezvous software automatically
reactivates the event. (To stop the cycle, destroy the event object; see
tibrvEvent_Destroy() on page 151.)

TIBCO Rendezvous C Reference

 tibrvEvent_CreateIO() 139
|

Figure 8 illustrates that Rendezvous software temporarily deactivates the I/O

event from the time it enters the queue until its callback function returns.
Consequently, an I/O object can cause at most one event at a time.

Figure 8 I/O Event Activation and Dispatch

1. Activate I/O event. 3. Dispatch event to its callback function.

Event Callback
I/O Event
Waiting in Function
Active
Queue Running

2. I/O event occurs.

4. When the callback function returns,
Deactivate event
reactivate I/O event for the next cycle.
and enter queue.

Event
I/O Event
Waiting in
Active
Queue

I/O event deactivated

Semantics of I/O The semantics of all I/O conditions depend on the underlying operating system
Events and event manager. Rendezvous software does not change those semantics.
I/O events trigger when the operating system reports that an I/O condition on a
monitored socket would succeed (that is, transfer at least one byte without
blocking). Nonetheless, Rendezvous software cannot guarantee that a subsequent
I/O call will not block.

See Also tibrvIOType on page 162

tibrvQueue on page 168

TIBCO Rendezvous C Reference

140
| Chapter 4 Events

tibrvEvent_CreateListener()
Function

Declaration tibrv_status tibrvEvent_CreateListener(

tibrvEvent* event,
tibrvQueue queue,
tibrvEventCallback callback,
tibrvTransport transport,
const char* subject,
const void* closure);

Purpose Listen for inbound messages.

Parameter Description
event For each inbound message, place this event on the event
queue.
The program supplies a location, and the function stores the
new event in that location.
The event object remains valid until the program explicitly
destroys it.

queue For each inbound message, place the event on this event
queue.

callback On dispatch, process the event with this callback function.

transport Listen for inbound messages on this transport.

subject Listen for inbound messages with subjects that match this
specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.

closure Store this closure data in the event object.

Activation and Inbound messages on the transport that match the subject trigger the event.
Dispatch
This function creates a listener event object, and activates the event—that is, it
begins listening for all inbound messages with matching subjects. When a
message arrives, Rendezvous software places the event object and message on its
event queue. Dispatch removes the event object from the queue, and runs the
callback function to process the message. (To stop receiving inbound messages on
the subject, destroy the event object; this action cancels all messages already
queued for the listener event; see also tibrvEvent_Destroy() on page 151.)

TIBCO Rendezvous C Reference

 tibrvEvent_CreateListener() 141
|

Figure 9 illustrates that Rendezvous software does not deactivate the listener
when it places new message events on the queue (in contrast to I/O events, which
are temporarily deactivated). Consequently, several messages can accumulate in
the queue while the callback function is processing.

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

When the callback function is I/O-bound, messages can arrive faster than the
callback function can process them, and the queue can grow unacceptably long. In
applications where a delay in processing messages is unacceptable, consider
dispatching from several threads to process messages concurrently.

Listening for Use this function to listen for advisory subjects. We recommend sending advisory
Advisory message events to the default queue.
Messages

TIBCO Rendezvous C Reference

142
| Chapter 4 Events

Inbox Listener To receive unicast (point-to-point) messages, listen to an inbox subject name. First
call tibrvTransport_CreateInbox() to create the unique inbox name; then call
tibrvEvent_CreateListener() to begin listening. Remember that other
programs have no information about an inbox until the listening program uses it
as a reply subject in an outbound message. See also, Inbox Names on page 115 in
TIBCO Rendezvous Concepts.

See Also tibrvEvent_GetListenerSubject() on page 155

tibrvTransport_CreateInbox() on page 214

TIBCO Rendezvous C Reference

 tibrvEvent_CreateTimer() 143
|

tibrvEvent_CreateTimer()
Function

Declaration tibrv_status tibrvEvent_CreateTimer(

tibrvEvent* event,
tibrvQueue queue,
tibrvEventCallback callback,
tibrv_f64 interval,
const void* closure);

Purpose Start a timer.

Parameter Description
event At each time interval, place this event on the event queue.
The program supplies a location, and the function stores the
new event object in that location.
The event object remains valid until the program explicitly
destroys it.

queue At each time interval, place the event on this event queue.

callback On dispatch, process the event with this callback function.

interval The timer triggers its callback function at this repeating

interval (in seconds).

closure Store this closure data in the event object.

Remarks All timers are repeating timers. To simulate a once-only timer, code the callback
function to destroy the timer.
This function creates a timer event 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 function to process the timer event. On dispatch Rendezvous software
also determines whether the next interval has already elapsed, and requeues the
timer event if appropriate. (To stop the cycle, destroy the event object; see
tibrvEvent_Destroy() on page 151.)
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.

TIBCO Rendezvous C Reference

144
| Chapter 4 Events

Figure 10 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 functions 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 10 Timer Activation and Dispatch

1. Activate timer.

Timer Timer Timer

Interval Interval Interval

2. Interval elapses. Event

Callback Function
Enter queue. Waiting in
Running
Queue
Event
3. Dispatch the event Callback Function
Waiting in
to its callback function. Running
Queue

4. Interval elapses. Event

Enter queue. Waiting in
Queue
5. Dispatch the event
to its callback function.

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

TIBCO Rendezvous C Reference

 tibrvEvent_CreateTimer() 145
|
Zero as Interval Many programmers traditionally implement user events as timers with interval
zero. Instead, we recommend implementing user events as messages on the
intra-process transport. For more information, see Intra-Process Transport and
User Events on page 114 in TIBCO Rendezvous Concepts.

See Also tibrvEvent_Destroy() on page 151

tibrvEvent_ResetTimerInterval() on page 160
Timer Event Semantics, page 96 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

146
| Chapter 4 Events

tibrvEvent_CreateVectorListener()
Function

Declaration tibrv_status tibrvEvent_CreateVectorListener(

tibrvEvent* event,
tibrvQueue queue,
tibrvEventVectorCallback callback,
tibrvTransport transport,
const char* subject,
const void* closure);

Purpose Listen for inbound messages, and receive them in a vector.

Parameter Description
event For each vector of inbound messages, place this event on the
event queue.
The program supplies a location, and the function stores the
new event in that location.
The event object remains valid until the program explicitly
destroys it.

queue For each vector of inbound messages, place the event on this
event queue.

callback On dispatch, process the event with this callback function.

transport Listen for inbound messages on this transport.

subject Listen for inbound messages with subjects that match this
specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.

closure Store this closure data in the event object.

Motivation The standard way of receiving messages—one at a time—has the advantage of

simplicity. However, if your application requires high throughput and low
latency, consider receiving data messages in a vector instead. Vector listeners can
boost performance for programs that receive a large number of messages by
reducing the overhead associated with message dispatch. Applications that
require high throughput (that is, many messages arriving rapidly) could benefit
from vector listeners.

TIBCO Rendezvous C Reference

 tibrvEvent_CreateVectorListener() 147
|

We do not recommend vector listeners for command messages, administrative

messages, advisory messages, nor any other out-of-band purpose.

Activation and This function creates a vector listener event object, and activates the event—that is,
Dispatch it begins listening for all inbound messages with matching subjects. Dispatch
removes a group of matching messages from the queue, and runs the callback
function to process the message vector.
To stop receiving inbound messages on the subject, destroy the event object; this
action cancels all messages already queued for the vector listener event; see also
tibrvEvent_Destroy() on page 151.

Interoperability Vector listeners and ordinary listeners can listen on the same queue.

Grouping When several vector listeners use the same queue, the dispatcher groups
Messages into messages into vectors with the following properties:
Vectors
• The sequence of messages in a vector reflect consecutive arrival in the queue.
• All messages in a vector share the same callback function (though they need
not match the same listener).

From these properties we can derive further inferences:

• If two vector listeners use the same callback function, then the dispatcher can
group messages on their subjects into the same vector.
• If two messages are adjacent in the queue, but require different callback
functions, then the dispatcher cannot group them into the same vector.

Example 3 Vector Listeners: Same Callback

Two vector listeners, F and P, listen on subjects FOO and PHU, respectively. Both F
and P designate the same queue, Q1, and the same callback function, C1, to
process their messages. In this situation, the dispatcher for Q1 can group
messages on subjects FOO and PHU into the same vector (as long as the messages
constitute a contiguous sequence within Q1).

Example 4 Vector Listeners: Different Callbacks

Extend the previous example by adding a third vector listener, B, which listens on
subject BAR. B designates the same queue, Q1, but uses a new callback function,
C2 to process its messages. In this situation, the dispatcher for Q1 must group
messages on subject BAR separately from messages on subjects FOO and PHU.

TIBCO Rendezvous C Reference

148
| Chapter 4 Events

Suppose the Q1 contains 49 messages with subjects FOO or PHU, then 1 message
with subject BAR, then 30 more messages with subjects FOO and s. Figure 11 shows
this message queue. The dispatcher produces at least three separate events.
Because messages 49 and 50 require different callbacks, the dispatcher must close
the vector of FOO and PHU messages at message 49, and start a new vector for
message 50 with subject BAR. When the dispatcher encounters message 51 with
subject FOO again, it closes the BAR vector after only one message, and starts a
third vector for FOO.

Figure 11 Grouping Messages into Vectors

Message Queue

FOO PHU FOO FOO BAR FOO PHU FOO

... ...
1 2 48 49 50 51 52 80

Event A Event B Event C

Example 5 Vector Listeners: Mixing Vector and Ordinary Listeners

Altering the previous example, suppose that B is an ordinary listener, instead of a
vector listener. B necessarily specifies a different callback function than F and P
(because ordinary listeners and vector listeners require different callback types
with different signatures).
The behavior of the dispatcher remains the same as in Example 4.

Dispatch Order Messages dispatch in the order that they arrive in the queue. However, the order
vs. in which callbacks process messages can differ from dispatch order. The following
Processing examples illustrate this possibility by contrasting three scenarios.
Order
Example 6 Vector Listeners: Deliberately Processing Out of Order
The simplest callback (from the programmer’s perspective) processes the
messages within a vector in order (that is, the order that dispatcher moves them
from the queue into the vector, which mirrors the order in which the messages
arrive in the queue). Nonetheless you could program a callback that processes
messages in reverse order, or any other order (though one would need a
convincing reason to do so).

TIBCO Rendezvous C Reference

 tibrvEvent_CreateVectorListener() 149
|

Example 7 Vector Listeners: Processing Message Vectors in a Single Dispatcher Thread

Figure 12 shows a closer look at the situation of Example 4, in which several
vector listeners all designate Q1 for their events. If a single thread dispatches Q1,
then the callbacks are guaranteed to run in sequence. If the callbacks process
messages in the order that they appear within the vectors, then message
processing order is identical to dispatch order, which is also identical to arrival
order. Figure 12 shows this effect.

Figure 12 Vector Listener Callbacks in a Single Dispatch Thread

Single Message Dispatch Thread

Msgs 1 - 49 Msgs 51 - 80

50 51
49

Example 8 Vector Listeners: Processing Message Vectors in Separate Threads

However, if several threads dispatch Q1 in parallel, then the callbacks can run
concurrently. In this situation, message processing order could differ dramatically
from arrival order. Figure 13 shows this possibility.

Figure 13 Vector Listener Callbacks in Multiple Dispatch Threads

Thread A

Msgs 1 - 49

Thread B 49

50 Thread C

Msgs 51 - 80

51

TIBCO Rendezvous C Reference

150
| Chapter 4 Events

Although message number 49 dispatches (in event A) before message 50 (in event
B), it is possible for the BAR callback (in thread B) to process message 50 before the
FOO callback (in thread A) processes message 49. Furthermore, it is even possible
for the FOO callback (in thread C) to process message 51 before the FOO callback (in
thread A) processes message 49.

Before developing a program that processes inbound message vectors in several

threads, consider carefully whether it is important (in the context of your
application’s semantics) to process messages in order of arrival.

See Also tibrvEventVectorCallback on page 137

TIBCO Rendezvous C Reference

 tibrvEvent_Destroy() 151
|

tibrvEvent_Destroy()
Function

Declaration tibrv_status tibrvEvent_Destroy(

tibrvEvent event);

Purpose Destroy an event, canceling interest.

Remarks Destroying an event object cancels interest in the specified event. Upon return
from tibrvEvent_Destroy(), the destroyed event is no longer dispatched.
It is legal for an event callback function to destroy its own event argument.
Destroying event interest invalidates the event object; passing the event object as
an argument to subsequent API calls produces an error.

Parameter Description
event Cancel interest in this event.

See Also tibrvEventOnComplete on page 134

tibrvEvent_CreateIO() on page 138
tibrvEvent_CreateListener() on page 140
tibrvEvent_CreateTimer() on page 143
tibrvEvent_DestroyEx() on page 152

TIBCO Rendezvous C Reference

152
| Chapter 4 Events

tibrvEvent_DestroyEx()
Function

Declaration tibrv_status tibrvEvent_DestroyEx(

tibrvEvent event,
tibrvEventOnComplete completionFunction);

Purpose Destroy an event, and run a completion function when all of the destroyed event’s
callback functions are complete.

Remarks Destroying an event object cancels interest in the specified event. Upon return
from tibrvEvent_DestroyEx(), the destroyed event’s callback function is no
longer dispatched.
It is legal for an event callback function to destroy its own event argument.
Although tibrvEvent_DestroyEx() prevents future dispatch calls from running
the destroyed event’s callback function, that callback function might be already
running in one or more threads that dispatch events from the same queue. In each
thread where the callback function is already in progress, that callback function
does continue to run until complete. Rendezvous software ensures that the
completion function runs when the last callback-in-progress has completed; for
important details, see tibrvEventOnComplete on page 134.
Destroying event interest invalidates the event object; passing the event object as
an argument to subsequent API calls produces an error.

Parameter Description
event Cancel interest in this event.

completionFunction Rendezvous software runs this function immediately

after all instances of the event’s callback function
have completed. If the event’s callback function is not
running when the event is destroyed, the destroy call
runs it before returning.
If this parameter is NULL, tibrvEvent_DestroyEx()
does not run a completion function; instead, its
behavior is the same as tibrvEvent_Destroy().

See Also tibrvEventOnComplete on page 134

tibrvEvent_CreateIO() on page 138
tibrvEvent_CreateListener() on page 140
tibrvEvent_Destroy() on page 151

TIBCO Rendezvous C Reference

 tibrvEvent_GetIOSource() 153
|

tibrvEvent_GetIOSource()
Function

Declaration tibrv_status tibrvEvent_GetIOSource(

tibrvEvent event,
tibrv_i32* source);

Purpose Extract the source (socket ID) from an I/O event object.

Parameter Description
event Extract the source from this I/O event object.

source The program supplies a location. The function stores the

source of the I/O event object in that location.

See Also tibrvEvent_CreateIO() on page 138

TIBCO Rendezvous C Reference

154
| Chapter 4 Events

tibrvEvent_GetIOType()
Function

Declaration tibrv_status tibrvEvent_GetIOType(

tibrvEvent event,
tibrvIOType* ioType);

Purpose Extract the I/O type from an I/O event object.

Parameter Description
event Extract the I/O type from this I/O event object.

ioType The program supplies a location. The function stores the I/O
type in that location.

See Also tibrvEvent_CreateIO() on page 138

tibrvIOType on page 162

TIBCO Rendezvous C Reference

 tibrvEvent_GetListenerSubject() 155
|

tibrvEvent_GetListenerSubject()
Function

Declaration tibrv_status tibrvEvent_GetListenerSubject(

tibrvEvent event,
const char** subject);

Purpose Extract the subject from a listener event object.

Parameter Description
event Extract the subject from this listener.

subject The program supplies a location. The function stores the

subject of the listener event object in that location.

See Also tibrvEvent_CreateListener() on page 140

TIBCO Rendezvous C Reference

156
| Chapter 4 Events

tibrvEvent_GetListenerTransport()
Function

Declaration tibrv_status tibrvEvent_GetListenerTransport(

tibrvEvent event,
tibrvTransport* transport);

Purpose Extract the transport from a listener event object.

Parameter Description
event Extract the transport from this listener.

transport The program supplies a location. The function stores the

transport of the listener event object in that location.

See Also tibrvEvent_CreateListener() on page 140

TIBCO Rendezvous C Reference

 tibrvEvent_GetTimerInterval() 157
|

tibrvEvent_GetTimerInterval()
Function

Declaration tibrv_status tibrvEvent_GetTimerInterval(

tibrvEvent event,
tibrv_f64* interval);

Purpose Extract the interval from a timer event object.

Parameter Description
event Extract the interval from this timer.

interval The program supplies a location. The function stores the

interval of the timer event object in that location.

See Also tibrvEvent_CreateTimer() on page 143

tibrvEvent_ResetTimerInterval() on page 160

TIBCO Rendezvous C Reference

158
| Chapter 4 Events

tibrvEvent_GetType()
Function

Declaration tibrv_status tibrvEvent_GetType(

tibrvEvent event,
tibrvEventType* type);

Purpose Extract the type of an event object.

Parameter Description
event Extract the event type from this event object.

type The program supplies a location. The function stores the event
object’s type in that location.

See Also tibrvEvent on page 132

tibrvEventType on page 161

TIBCO Rendezvous C Reference

 tibrvEvent_GetQueue() 159
|

tibrvEvent_GetQueue()
Function

Declaration tibrv_status tibrvEvent_GetQueue(

tibrvEvent event,
tibrvQueue* queue);

Purpose Extract the queue of an event object.

Parameter Description
event Extract the event queue from this event object.

queue The program supplies a location. The function stores the event
object’s queue in that location.

See Also tibrvEvent on page 132

tibrvQueue on page 168

TIBCO Rendezvous C Reference

160
| Chapter 4 Events

tibrvEvent_ResetTimerInterval()
Function

Declaration tibrv_status tibrvEvent_ResetTimerInterval(

tibrvEvent event,
tibrv_f64 newInterval);

Purpose Reset the interval of a timer event object.

Remarks The timer begins counting the new interval immediately.

Parameter Description
event Reset the interval of this timer.

newInterval The timer triggers its callback function at this new repeating
interval (in seconds).

Timer Express the timer interval (in seconds) as a 64-bit floating point number. This
Granularity representation allows microsecond granularity for intervals up to approximately
146 years. The actual granularity of intervals depends on hardware and operating
system constraints.

Limit of This function can affect a timer only before or during its interval—but not after its
Effectiveness interval has elapsed.
This function neither examines, changes nor removes an event that is already
waiting in a queue for dispatch. If the next event for the timer object is already in
the queue, then that event remains in the queue, representing the old interval. The
change takes effect with the subsequent interval. (To circumvent this limitation, a
program can destroy the old timer object and replace it with a new one.)

See Also tibrvEvent_CreateTimer() on page 143

tibrvEvent_GetTimerInterval() on page 157

TIBCO Rendezvous C Reference

 tibrvEventType 161
|

tibrvEventType
Type

Declaration typedef tibrv_u32 tibrvEventType;

Purpose Distinguish event objects as listeners, timers, or I/O interest.

Value Description
TIBRV_LISTEN_EVENT An event object with this type listens for inbound
messages.

TIBRV_TIMER_EVENT An event object with this type represents is a timer.

TIBRV_IO_EVENT An event object with this type expresses interest in

an I/O condition.

See Also tibrvEvent_GetType() on page 158

TIBCO Rendezvous C Reference

162
| Chapter 4 Events

tibrvIOType
Type

Declaration typedef enum {

TIBRV_IO_READ,
TIBRV_IO_WRITE,
TIBRV_IO_EXCEPTION } tibrvIOType;

Purpose Distinguish event interest in I/O conditions.

Value Description
TIBRV_IO_READ The socket is now readable.

TIBRV_IO_WRITE The socket is now write-available.

TIBRV_IO_EXCEPTION An exceptional condition occurred on the socket.

(For example, out-of-band data has arrived.)

See Also tibrvEvent_CreateIO() on page 138

tibrvEvent_GetIOType() on page 154

TIBCO Rendezvous C Reference

 | 163

Chapter 5 Event Queues

Event queues organize events awaiting dispatch. Programs dispatch events to run
callback functions.
This chapter presents functions and types associated with event queues.

Topics

• Operations by Functional Group, page 164

• Operations in Alphabetical Order, page 166

TIBCO Rendezvous C Reference

164
| Chapter 5 Event Queues

Operations by Functional Group

(Sheet 1 of 2)

Function Description Page

Queue Life Cycle

tibrvQueue Specify an event queue. 168

tibrvQueue_Create() Create an event queue. 172

tibrvQueue_Destroy() Destroy an event queue. 173

tibrvQueueOnComplete A program can destroy a queue object even when 171

callback functions from its events are running in
one or more threads. Multi-threaded programs
can define functions of this type to discover when
all event callback functions in progress have
completed.

Dispatch

tibrvQueue_Dispatch() Dispatch an event; if no event is ready, block. 174

tibrvQueue_Poll() Dispatch an event, if possible. 180

tibrvQueue_TimedDispatch() Dispatch an event, but if no event is ready to 187

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

Properties

tibrvQueueLimitPolicy Specify a strategy for resolving overflow of queue 170

limit.

tibrvQueue_GetCount() Extract the number of events in a queue. 175

tibrvQueue_GetLimitPolicy() Extract the limit properties of a queue. 177

tibrvQueue_GetName() Extract the name of a queue. 178

tibrvQueue_GetPriority() Extract the priority of a queue. 179

tibrvQueue_SetLimitPolicy() Set the limit properties of a queue. 183

TIBCO Rendezvous C Reference

 Operations by Functional Group 165
|

(Sheet 2 of 2)

Function Description Page

tibrvQueue_SetName() Set the name of a queue. 185

tibrvQueue_SetPriority() Set the priority of a queue. 186

External Event Manager Hook

tibrvQueueHook Asynchronously notify an external event manager 169

when a Rendezvous event is ready for dispatch.

tibrvQueue_GetHook() Extract an event queue hook function. 176

tibrvQueue_RemoveHook() Remove the event queue hook function from a 181

queue.

tibrvQueue_SetHook() Register an event queue hook function. 182

TIBCO Rendezvous C Reference

166
| Chapter 5 Event Queues

Operations in Alphabetical Order

(Sheet 1 of 2)

Function or Type Description Page

tibrvQueue Specify an event queue. 168

tibrvQueueHook Asynchronously notify an external event manager 169

when a Rendezvous event is ready for dispatch.

tibrvQueueLimitPolicy Specify a strategy for resolving overflow of queue 170

limit.

tibrvQueueOnComplete A program can destroy a queue object even when 171

callback functions from its events are running in one
or more threads. Multi-threaded programs can
define functions of this type to discover when all
event callback functions in progress have
completed.

tibrvQueue_Create() Create an event queue. 172

tibrvQueue_Destroy() Destroy an event queue. 173

tibrvQueue_Dispatch() Dispatch an event; if no event is ready, block. 174

tibrvQueue_GetCount() Extract the number of events in a queue. 175

tibrvQueue_GetHook() Extract an event queue hook function. 176

tibrvQueue_GetLimitPolicy() Extract the limit properties of a queue. 177

tibrvQueue_GetName() Extract the name of a queue. 178

tibrvQueue_GetPriority() Extract the priority of a queue. 179

tibrvQueue_Poll() Dispatch an event, if possible. 180

tibrvQueue_RemoveHook() Remove the event queue hook function from a 181

queue.

tibrvQueue_SetHook() Register an event queue hook function. 182

tibrvQueue_SetLimitPolicy() Set the limit properties of a queue. 183

TIBCO Rendezvous C Reference

 Operations in Alphabetical Order 167
|

(Sheet 2 of 2)

Function or Type Description Page

tibrvQueue_SetName() Set the name of a queue. 185

tibrvQueue_SetPriority() Set the priority of a queue. 186

tibrvQueue_TimedDispatch() Dispatch an event, but if no event is ready to 187

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

TIBCO Rendezvous C Reference

168
| Chapter 5 Event Queues

tibrvQueue
Type

Declaration typedef tibrvId tibrvQueue;

#define TIBRV_DEFAULT_QUEUE

Purpose Specify an event queue.

Default Queue The constant TIBRV_DEFAULT_QUEUE represents a pre-defined queue. Programs

that need only one event queue can use this default queue (instead of using
tibrvQueue_Create() to create one). The default queue has priority 1, can hold
an unlimited number of events, and never discards an event (since it never
exceeds an event limit).
Rendezvous software places all advisories pertaining to queue overflow on the
default queue.
Programs cannot destroy the default queue, except as a side effect of
tibrv_Close(). Programs cannot change the parameters of the default queue.

See Also tibrvQueue_Create() on page 172

TIBCO Rendezvous C Reference

 tibrvQueueHook 169
|

tibrvQueueHook
Function Type

Declaration typedef void (*tibrvQueueHook) (

tibrvQueue eventQueue,
void* closure);

Purpose Asynchronously notify an external event manager when a Rendezvous event is

ready for dispatch.

Motivation Some programs need to use existing event managers to dispatch Rendezvous
events. Some event managers repeatedly poll queues for events; others require
notification that an event is ready (for example, the Microsoft Windows event
manager operates this way). This hook function can inform an event manager
when an event enters a queue and is ready for dispatch.
You can think of this function as a wake-up call to the event manager. Once
awakened, the event manager dispatches Rendezvous events in its usual way, by
calling tibrvQueue_Dispatch() or tibrvQueue_TimedDispatch().

Remarks When coding hook functions, remember that hook functions can be called from
any thread. In general, hook functions run in the thread that enqueues the event;
that thread can be a program thread, or a Rendezvous internal thread.

Procedure To use this facility, follow these steps:

1. Code a queue hook function to post a message to the target event manager
when a message is received.
2. Arrange for the target event handler to call tibrvQueue_Dispatch().
3. Register the queue hook function, using tibrvQueue_SetHook().

Parameter Description
eventQueue This parameter receives the queue on which an event has
arrived.

closure This parameter receives closure data supplied by the program

when it registered this hook function.

See Also tibrvQueue_Dispatch() on page 174

tibrvQueue_GetHook() on page 176
tibrvQueue_RemoveHook() on page 181
tibrvQueue_SetHook() on page 182
tibrvQueue_TimedDispatch() on page 187

TIBCO Rendezvous C Reference

170
| Chapter 5 Event Queues

tibrvQueueLimitPolicy
Type

Declaration typedef enum {

TIBRVQUEUE_DISCARD_NONE,
TIBRVQUEUE_DISCARD_NEW,
TIBRVQUEUE_DISCARD_FIRST,
TIBRVQUEUE_DISCARD_LAST } tibrvQueueLimitPolicy;

Purpose Specify a strategy for resolving overflow of queue limit.

Value Description
TIBRVQUEUE_DISCARD_NONE Never discard events; use this policy when
a queue has no limit on the number of
events it can contain.

TIBRVQUEUE_DISCARD_FIRST Discard the first event in the queue (that is,

the oldest event in the queue, which would
otherwise be the next event to dispatch).

TIBRVQUEUE_DISCARD_LAST Discard the last event in the queue (that is,

the youngest event in the queue).

TIBRVQUEUE_DISCARD_NEW Discard the new event (which would

otherwise cause the queue to overflow its
maximum events limit).

See Also tibrvQueue_Create() on page 172

tibrvQueue_GetLimitPolicy() on page 177
tibrvQueue_SetLimitPolicy() on page 183
QUEUE.LIMIT_EXCEEDED on page 280 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvQueueOnComplete 171
|

tibrvQueueOnComplete
Function Type

Declaration typedef void (*tibrvQueueOnComplete) (

tibrvQueue destroyedQueue,
void* closure);

Purpose A program can destroy a queue object even when callback functions from its
events are running in one or more threads. Multi-threaded programs can define
functions of this type to discover when all event callback functions in progress
have completed.

Parameter Description
destroyedQueue This parameter receives the queue object.
However, by the time this function runs, the queue is
already destroyed; this function cannot use the queue
object in Rendezvous calls.

closure This parameter receives the closure data, which the

program supplied in the call that destroyed the queue
object.

Remarks This type of function is important when several threads dispatch from the same
queue, and the program must do additional processing after the callback
functions have completed in all threads.
Upon return from tibrvQueue_DestroyEx(), the destroyed queue can no longer
dispatch events. However, in each thread where an event callback function is
already in progress, that callback function does continue to run until complete.
tibrvQueue_DestroyEx() accepts a completion function argument of type
tibrvQueueOnComplete. Rendezvous software ensures that the completion
function runs when the last callback-in-progress has completed.

See Also tibrvQueue_Destroy() on page 173

TIBCO Rendezvous C Reference

172
| Chapter 5 Event Queues

tibrvQueue_Create()
Function

Declaration tibrv_status tibrvQueue_Create(

tibrvQueue* eventQueue);

Purpose Create an event queue.

Parameter Description
eventQueue The program supplies a location, and the function stores the
address of a new queue in that location.
The queue remains valid until the program explicitly destroys
it.

Remarks Upon creation, new queues use these default values.

Property Default Value Set Function

limitPolicy TIBRVQUEUE_DISCARD_NONE tibrvQueue_SetLimitPolicy() on page 183
maxEvents zero (unlimited)

discardAmount zero

name tibrvQueue tibrvQueue_SetName() on page 185

priority 1 tibrvQueue_SetPriority() on page 186

TIBCO Rendezvous C Reference

 tibrvQueue_Destroy() 173
|

tibrvQueue_Destroy()
Function

Declaration tibrv_status tibrvQueue_Destroy(

tibrvQueue eventQueue);

tibrv_status tibrvQueue_DestroyEx(
tibrvQueue eventQueue,
tibrvQueueOnComplete completionFn,
void* closure);

Purpose Destroy an event queue.

Remarks When a queue is destroyed, events that remain in the queue are discarded.
When a program destroys a queue, all events associated with the queue become
invalid. These invalid events still occupy storage until the program explicitly
destroys them, or until the program calls tibrv_Close().

Parameter Description
eventQueue Destroy this queue.

completionFn Rendezvous software runs this function immediately after

all event callback functions dispatched from the queue have
completed. If no event callback functions are running when
the queue is destroyed, the destroy call runs the completion
function before returning.
If this parameter is NULL, tibrvQueue_DestroyEx() does
not run a completion function; instead, its behavior is the
same as tibrvQueue_Destroy().

closure Pass this closure argument to the completion function.

See Also tibrvQueueOnComplete on page 171

TIBCO Rendezvous C Reference

174
| Chapter 5 Event Queues

tibrvQueue_Dispatch()
Macro

Declaration tibrv_status tibrvQueue_Dispatch(

tibrvQueue eventQueue);

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.

Parameter Description
eventQueue Dispatch an event from the head of this queue.

See Also tibrvQueue_Poll() on page 180

tibrvQueue_TimedDispatch() on page 187

TIBCO Rendezvous C Reference

 tibrvQueue_GetCount() 175
|

tibrvQueue_GetCount()
Function

Declaration tibrv_status tibrvQueue_GetCount(

tibrvQueue eventQueue,
tibrv_u32* numEvents);

Purpose Extract the number of events in a queue.

Parameter Description
eventQueue Extract the current event count of this queue.

numEvents The program supplies a location, and the function stores (a

snapshot of) the event count of the queue in that location.

TIBCO Rendezvous C Reference

176
| Chapter 5 Event Queues

tibrvQueue_GetHook()
Function

Declaration tibrv_status tibrvQueue_GetHook(

tibrvQueue eventQueue,
tibrvQueueHook* eventQueueHook);

Purpose Extract an event queue hook function.

Parameter Description
eventQueue Get the hook function from this queue.

eventQueueHook The program supplies a location. The function stores the

hook function in that location.

See Also tibrvQueueHook on page 169

tibrvQueue_RemoveHook() on page 181
tibrvQueue_SetHook() on page 182

TIBCO Rendezvous C Reference

 tibrvQueue_GetLimitPolicy() 177
|

tibrvQueue_GetLimitPolicy()
Function

Declaration tibrv_status tibrvQueue_GetLimitPolicy(

tibrvQueue eventQueue,
tibrvQueueLimitPolicy* policy,
tibrv_u32* maxEvents,
tibrv_u32* discardAmount);

Purpose Extract the limit properties of a queue.

Parameter Description
eventQueue Extract the limit information from this queue.

policy Each queue has a policy for discarding events when a new
event would cause the queue to exceed its maxEvents
limit. For an explanation of the policy values, see
tibrvQueueLimitPolicy on page 170.
The program supplies a location, and the function stores
the limit policy of the queue in that location.

maxEvents Programs can limit the number of events that a queue can
hold—either to curb queue growth, or implement a
specialized dispatch semantics.
Zero specifies an unlimited number of events.
The program supplies a location, and the function stores
the maximum event limit of the queue in that location.

discardAmount When the queue exceeds its maximum event limit, discard
a block of events. This property specifies the number of
events to discard.
The program supplies a location, and the function stores
the discard amount of the queue in that location.

See Also tibrvQueueLimitPolicy on page 170

tibrvQueue_Create() on page 172
tibrvQueue_SetLimitPolicy() on page 183
QUEUE.LIMIT_EXCEEDED on page 280 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

178
| Chapter 5 Event Queues

tibrvQueue_GetName()
Function

Declaration tibrv_status tibrvQueue_GetName(

tibrvQueue eventQueue,
const char** queueName);

Purpose Extract the name of a queue.

Remarks Queue names assist programmers and administrators in troubleshooting queues.

When Rendezvous software delivers an advisory message pertaining to a queue,
it includes the queue’s name; administrators can use queue names to identify
specific queues within a program.
The default name of every queue is tibrvQueue. We strongly recommend that
you relabel each queue with a distinct and informative name, for use in
debugging.

Parameter Description
eventQueue Extract the name of this queue.

queueName The program supplies a location, and the function places in

that location a string pointer to the queue name.
The program must not modify the string.

See Also tibrvQueue_Create() on page 172

tibrvQueue_SetName() on page 185

TIBCO Rendezvous C Reference

 tibrvQueue_GetPriority() 179
|

tibrvQueue_GetPriority()
Function

Declaration tibrv_status tibrvQueue_GetPriority(

tibrvQueue eventQueue,
tibrv_u32* priority);

Purpose Extract the priority of a queue.

Remarks Each queue has a single priority value, which controls its dispatch precedence
within queue groups. Higher values dispatch before lower values; queues with
equal priority values dispatch in round-robin fashion.

Parameter Description
eventQueue Extract the priority of this queue.

priority The program supplies a location, and the function copies the
priority of the queue into that location.

See Also tibrvQueue_Create() on page 172

tibrvQueue_SetPriority() on page 186

TIBCO Rendezvous C Reference

180
| Chapter 5 Event Queues

tibrvQueue_Poll()
Macro

Declaration tibrv_status tibrvQueue_Poll(

tibrvQueue eventQueue);

Purpose Dispatch an event, if possible.

Remarks If the queue is not empty, then this call dispatches the event at the head of the
queue, and then returns. If the queue is empty, then this call returns immediately.
When the call dispatches an event, it returns the status code TIBRV_OK. When the
call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.

Parameter Description
eventQueue Dispatch an event from the head of this queue.

See Also tibrvQueue_Dispatch() on page 174

tibrvQueue_TimedDispatch() on page 187

TIBCO Rendezvous C Reference

 tibrvQueue_RemoveHook() 181
|

tibrvQueue_RemoveHook()
Function

Declaration tibrv_status tibrvQueue_RemoveHook(

tibrvQueue eventQueue);

Purpose Remove the event queue hook function from a queue.

Parameter Description
eventQueue Remove the hook function from this queue.

See Also tibrvQueueHook on page 169

tibrvQueue_GetHook() on page 176
tibrvQueue_SetHook() on page 182

TIBCO Rendezvous C Reference

182
| Chapter 5 Event Queues

tibrvQueue_SetHook()
Function

Declaration tibrv_status tibrvQueue_SetHook(

tibrvQueue eventQueue,
tibrvQueueHook eventQueueHook,
void* closure);

Purpose Register an event queue hook function.

Parameter Description
eventQueue Attach the hook function to this queue.

eventQueueHook Call this hook function whenever an event arrives on the

queue.

closure Pass this closure data to the hook function.

See Also tibrvQueueHook on page 169

tibrvQueue_GetHook() on page 176
tibrvQueue_RemoveHook() on page 181

TIBCO Rendezvous C Reference

 tibrvQueue_SetLimitPolicy() 183
|

tibrvQueue_SetLimitPolicy()
Function

Declaration tibrv_status tibrvQueue_SetLimitPolicy(

tibrvQueue eventQueue,
tibrvQueueLimitPolicy policy,
tibrv_u32 maxEvents,
tibrv_u32 discardAmount);

Purpose Set the limit properties of a queue.

Remarks This function simultaneously sets three related properties, which together
describe the behavior of a queue in overflow situations. Each call must explicitly
specify all three properties.

(Sheet 1 of 2)

Parameter Description
eventQueue Set the limit properties of this queue.

policy Each queue has a policy for discarding events when a new
event would cause the queue to exceed its maxEvents
limit. Choose from the values of tibrvQueueLimitPolicy on
page 170.
When maxEvents is zero (unlimited), the policy must be
TIBRVQUEUE_DISCARD_NONE.

The program supplies a value, and the function sets the

limit policy of the queue to that value.

maxEvents Programs can limit the number of events that a queue can
hold—either to curb queue growth, or implement a
specialized dispatch semantics.
Zero specifies an unlimited number of events; in this case,
the policy must be TIBRVQUEUE_DISCARD_NONE.
The program supplies a value, and the function sets the
maximum event limit of the queue to that value.

TIBCO Rendezvous C Reference

184
| Chapter 5 Event Queues

(Sheet 2 of 2)

Parameter Description
discardAmount When the queue exceeds its maximum event limit, discard
a block of events. This property specifies the number of
events to discard.
When discardAmount is zero, the policy must be
TIBRVQUEUE_DISCARD_NONE.

The program supplies a value, and the function sets the

discard amount of the queue to that value.

See Also tibrvQueue_GetLimitPolicy() on page 177

QUEUE.LIMIT_EXCEEDED on page 280 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvQueue_SetName() 185
|

tibrvQueue_SetName()
Function

Declaration tibrv_status tibrvQueue_SetName(

tibrvQueue eventQueue,
const char* queueName);

Purpose Set the name of a queue.

Remarks Queue names assist programmers and administrators in troubleshooting queues.

When Rendezvous software delivers an advisory message pertaining to a queue,
it includes the queue’s name; administrators can use queue names to identify
specific queues within a program.
The default name of every queue is tibrvQueue. We strongly recommend that
you relabel each queue with a distinct and informative name, for use in
debugging.

Parameter Description
eventQueue Set the name of this queue.

queueName Replace the name of the queue with this new name.
It is illegal to supply NULL as the new queue name.

See Also tibrvQueue_GetName() on page 178

TIBCO Rendezvous C Reference

186
| Chapter 5 Event Queues

tibrvQueue_SetPriority()
Function

Declaration tibrv_status tibrvQueue_SetPriority(

tibrvQueue eventQueue,
tibrv_u32 priority);

Purpose Set the priority of a queue.

Remarks Each queue has a single priority value, which controls its dispatch precedence
within queue groups. Higher values dispatch before lower values; queues with
equal priority values dispatch in round-robin fashion.
Changing the priority of a queue affects its position in all the queue groups that
contain it.

Parameter Description
eventQueue Set the priority of this queue.

priority Replace the priority of the queue with this new value.
The priority is a non-negative integer. Priority zero signifies
the last queue to dispatch.

See Also tibrvQueue_GetPriority() on page 179

tibrvQueueGroup_Dispatch() on page 194

TIBCO Rendezvous C Reference

 tibrvQueue_TimedDispatch() 187
|

tibrvQueue_TimedDispatch()
Function

Declaration tibrv_status tibrvQueue_TimedDispatch(

tibrvQueue eventQueue,
tibrv_f64 timeout);

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

Remarks If an event is already in the queue, this call dispatches it, and returns immediately.
If the queue is empty, this call waits for an event to arrive. If an event arrives
before the waiting time elapses, then it dispatches the event and returns. If the
waiting time elapses first, then the call returns without dispatching an event.
When the call dispatches an event, it returns the status code TIBRV_OK. When the
call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.

Parameter Description
eventQueue Dispatch the next event from this queue.

timeout Maximum time (in seconds) that this call can block while
waiting for an event to arrive in the queue.
TIBRV_NO_WAIT (zero) indicates no blocking (immediate
timeout).
TIBRV_WAIT_FOREVER (-1) indicates no timeout.

See Also tibrvQueue_Dispatch() on page 174

tibrvQueue_Poll() on page 180

TIBCO Rendezvous C Reference

188
| Chapter 5 Event Queues

TIBCO Rendezvous C Reference

 | 189

Chapter 6 Event Queue Groups

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.

Topics in Alphabetical Order

Function or Type Description Page

tibrvQueueGroup Specify an event queue group. 190

tibrvQueueGroup_Add() Add an event queue to a queue group. 191

tibrvQueueGroup_Create() Create an event queue group. 192

tibrvQueueGroup_Destroy() Destroy an event queue group. 193

tibrvQueueGroup_Dispatch() Dispatch an event from a queue group; if no event 194

is ready, block.

tibrvQueueGroup_Poll() Dispatch an event from a queue group, if possible. 195

tibrvQueueGroup_Remove() Remove an event queue from a queue group. 196

tibrvQueueGroup_TimedDispatch() Dispatch an event, but if no event is ready to 197

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

TIBCO Rendezvous C Reference

190
| Chapter 6 Event Queue Groups

tibrvQueueGroup
Type

Declaration typedef tibrvId tibrvQueueGroup;

Purpose Specify an event queue group.

See Also tibrvQueueGroup_Create() on page 192

TIBCO Rendezvous C Reference

 tibrvQueueGroup_Add() 191
|

tibrvQueueGroup_Add()
Function

Declaration tibrv_status tibrvQueueGroup_Add(

tibrvQueueGroup eventQueueGroup,
tibrvQueue eventQueue);

Purpose Add an event queue to a queue group.

Remarks If the queue is already in the group, adding it again has no effect, and the call
returns TIBRV_OK.
If either the queue or the group is invalid, this function returns an error status.

Parameter Description
eventQueueGroup Add an event queue to this queue group.

eventQueue Add this event queue to a queue group.

See Also tibrvQueue on page 168

tibrvQueueGroup_Remove() on page 196

TIBCO Rendezvous C Reference

192
| Chapter 6 Event Queue Groups

tibrvQueueGroup_Create()
Function

Declaration tibrv_status tibrvQueueGroup_Create(

tibrvQueueGroup* eventQueueGroup);

Purpose Create an event queue group.

Parameter Description
eventQueueGroup The program supplies a location, and the function stores
the address of a new queue group in that location.
The queue group remains valid until the program
explicitly destroys it.

See Also tibrvQueueGroup_Destroy() on page 193

TIBCO Rendezvous C Reference

 tibrvQueueGroup_Destroy() 193
|

tibrvQueueGroup_Destroy()
Function

Declaration tibrv_status tibrvQueueGroup_Destroy(

tibrvQueueGroup eventQueueGroup);

Purpose Destroy an event queue group.

Remarks The individual queues in the group continue to exist, even though the group has
been destroyed.

Parameter Description
eventQueueGroup Destroy this event queue group.

See Also tibrvQueueGroup_Create() on page 192

TIBCO Rendezvous C Reference

194
| Chapter 6 Event Queue Groups

tibrvQueueGroup_Dispatch()
Macro

Declaration tibrv_status tibrvQueueGroup_Dispatch(

tibrvQueueGroup eventQueueGroup);

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.

Parameter Description
eventQueueGroup Dispatch the next event from a queue in this group.

See Also tibrvQueueGroup_Poll() on page 195

tibrvQueueGroup_TimedDispatch() on page 197

TIBCO Rendezvous C Reference

 tibrvQueueGroup_Poll() 195
|

tibrvQueueGroup_Poll()
Macro

Declaration tibrv_status tibrvQueueGroup_Poll(

tibrvQueueGroup eventQueueGroup);

Purpose Dispatch an event from a queue group, if possible.

Remarks If any queue in the group contains an event, then this call searches the queues in
priority order, dispatches an event from the first non-empty queue that it finds,
and then returns. If all the queues are empty, then this call returns immediately.
When searching the group for a non-empty queue, this call searches according to
the priority values of the queues. If two or more queues have identical priorities,
subsequent dispatch and poll calls rotate through them in round-robin fashion.
When the call dispatches an event, it returns the status code TIBRV_OK. When the
call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.

Parameter Description
eventQueueGroup Dispatch the next event from a queue in this group.

See Also tibrvQueueGroup_Dispatch() on page 194

tibrvQueueGroup_TimedDispatch() on page 197

TIBCO Rendezvous C Reference

196
| Chapter 6 Event Queue Groups

tibrvQueueGroup_Remove()
Function

Declaration tibrv_status tibrvQueueGroup_Remove(

tibrvQueueGroup eventQueueGroup,
tibrvQueue eventQueue);

Purpose Remove an event queue from a queue group.

Remarks If the queue is not in the group, this call returns the status code
TIBRV_INVALID_QUEUE.

Parameter Description
eventQueueGroup Remove an event queue from this queue group.

eventQueue Remove this event queue from a queue group.

See Also tibrvQueue on page 168

tibrvQueueGroup_Add() on page 191

TIBCO Rendezvous C Reference

 tibrvQueueGroup_TimedDispatch() 197
|

tibrvQueueGroup_TimedDispatch()
Function

Declaration tibrv_status tibrvQueueGroup_TimedDispatch(

tibrvQueueGroup eventQueueGroup,
tibrv_f64 timeout);

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

Remarks If any queue in the group contains an event, then this call searches the queues in
priority order, dispatches an event from the first non-empty queue that it finds,
and then returns. If the queue is empty, this call waits for an event to arrive in any
queue. If an event arrives before the waiting time elapses, then the call searches
the queues, dispatches the event, and returns. If the waiting time elapses first,
then the call returns without dispatching an event.
When searching the group for a non-empty queue, this call searches according to
the priority values of the queues. If two or more queues have identical priorities,
subsequent dispatch calls rotate through them in round-robin fashion.
When the call dispatches an event, it returns the status code TIBRV_OK. When the
call does not dispatch an event, it returns the status code TIBRV_TIMEOUT.

Parameter Description
eventQueueGroup Dispatch the next event from a queue in this group.

timeout Maximum time (in seconds) that this call can block
while waiting for an event to arrive in the queue group.
TIBRV_NO_WAIT (zero) indicates no blocking (immediate
timeout).
TIBRV_WAIT_FOREVER (-1) indicates no timeout.

See Also tibrvQueue_TimedDispatch() on page 187

tibrvQueueGroup_Dispatch() on page 194
tibrvQueueGroup_Poll() on page 195

TIBCO Rendezvous C Reference

198
| Chapter 6 Event Queue Groups

TIBCO Rendezvous C Reference

 | 199

Chapter 7 Dispatcher Thread

Every program must dispatch events. This chapter describes functions that
conveniently create dispatcher threads. Programmers can use this convenience
facility, or arrange for event dispatch in other ways.

Topics in Alphabetical Order

Function or Type Description Page

tibrvDispatchable Specify an event queue or queue group. 200

tibrvDispatcher Specify a dispatcher thread. 201

tibrvDispatcher_Create() Create a dispatcher thread. 202

tibrvDispatcher_Destroy() Destroy a dispatcher thread. 204

tibrvDispatcher_GetName() Extract the name of a dispatcher thread. 205

tibrvDispatcher_SetName() Set the name of a dispatcher thread. 206

TIBCO Rendezvous C Reference

200
| Chapter 7 Dispatcher Thread

tibrvDispatchable
Type

Declaration typedef tibrvId tibrvdispatchable;

Purpose Specify an event queue or queue group.

Remarks This type can refer to either kind of dispatchable object—an event queue or a
queue group.

See Also tibrvDispatcher_Create() on page 202

TIBCO Rendezvous C Reference

 tibrvDispatcher 201
|

tibrvDispatcher
Type

Declaration typedef tibrvId tibrvdispatcher;

Purpose Specify a dispatcher thread.

See Also tibrvDispatcher_Create() on page 202

TIBCO Rendezvous C Reference

202
| Chapter 7 Dispatcher Thread

tibrvDispatcher_Create()
Function

Declaration tibrv_status tibrvDispatcher_Create(

tibrvDispatcher* dispatcher,
tibrvDispatchable dispatchable);

tibrv_status tibrvDispatcher_CreateEx(
tibrvDispatcher* dispatcher,
tibrvDispatchable dispatchable,
tibrv_f64 idleTimeout);

Purpose Create a dispatcher thread.

Remarks A dispatcher thread repeatedly dispatches a queue or queue group.

Inside the thread, a loop calls tibrvQueue_TimedDispatch() or
tibrvQueueGroup_TimedDispatch() (as appropriate to the dispatchable
argument).
The simple form of this function creates a dispatcher thread that loops
indefinitely. The extended function creates a thread that passes the idleTimeout
argument to the timed dispatch call; if the timed dispatch call returns without
dispatching an event (after waiting for idleTimeout seconds), then the thread
exits by calling tibrvDispatcher_Destroy().

Parameter Description
dispatcher The program supplies a location, and the function stores the
address of the new dispatcher thread in that location.

dispatchable The new thread dispatches this object, which can be either a
queue or a queue group.

idleTimeout When this time period (in seconds) elapses without

dispatching an event, the thread exits.
The special value TIBRV_WAIT_FOREVER instructs the
dispatcher to loop indefinitely; the thread does not exit until
the program explicitly destroys it.
The special value TIBRV_NO_WAIT instructs the dispatcher to
poll until no events are ready to dispatch, then exit.

Stack Size On UNIX platforms that use the POSIX thread package (pthread), this call sets
the stacksize attribute of the dispatcher thread to the larger of two candidate
values—either the default stack size of the operating system, or 64 kilobytes.

TIBCO Rendezvous C Reference

 tibrvDispatcher_Create() 203
|

For programs that require a larger stack size, we recommend that you code a
custom dispatcher thread.

See Also tibrvQueue_TimedDispatch() on page 187

tibrvQueueGroup_TimedDispatch() on page 197
tibrvDispatchable on page 200
tibrvDispatcher_Destroy() on page 204
tibrvDispatcher_SetName() on page 206
DISPATCHER.THREAD_EXITED on page 274 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

204
| Chapter 7 Dispatcher Thread

tibrvDispatcher_Destroy()
Function

Declaration tibrv_status tibrvDispatcher_Destroy(

tibrvDispatcher dispatcher);

Purpose Destroy a dispatcher thread.

Parameter Description
dispatcher Destroy and exit this dispatcher thread.
We do not recommend destroying a dispatcher thread within
the same thread (for example, from within a listener callback
running within that thread). Although it is legal to do so, we
discourage this practice, because some operating systems do
not properly free internal resources associated with the thread
(which can result in memory growth).

See Also DISPATCHER.THREAD_EXITED on page 274 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvDispatcher_GetName() 205
|

tibrvDispatcher_GetName()
Function

Declaration tibrv_status tibrvDispatcher_GetName(

tibrvDispatcher dispatcher,
const char** dispatchName);

Purpose Extract the name of a dispatcher thread.

Parameter Description
dispatcher Get the name of this thread.

dispatchName The program supplies a location, and the function stores the
name of the dispatcher thread in that location.

TIBCO Rendezvous C Reference

206
| Chapter 7 Dispatcher Thread

tibrvDispatcher_SetName()
Function

Declaration tibrv_status tibrvDispatcher_SetName(

tibrvDispatcher dispatcher,
const char* dispatchName);

Purpose Set the name of a dispatcher thread.

Parameter Description
dispatcher Set the name of this thread.

dispatchName Use this name as the name of the dispatcher thread.

TIBCO Rendezvous C Reference

 | 207

Chapter 8 Transport

Transports manage network connections and send outbound messages.

Topics in Alphabetical Order

Function or Type Description Page

tibrvTransport A transport object represents a delivery 209
mechanism for messages.

tibrvTransportBatchMode Specify the batch mode of a transport. 210

tibrvTransport_Create() Create a network transport. 211

tibrvTransport_CreateInbox() Create a unique inbox subject name. 214

tibrvTransport_Destroy() Destroy a transport. 216

tibrvTransport_GetDaemon() Extract the daemon parameter from a 217

transport.

tibrvTransport_GetDescription() Extract the program description parameter 218

from a transport.

tibrvTransport_GetNetwork() Extract the network parameter from a 219

transport.

tibrvTransport_GetService() Extract the service parameter from a 220

transport.

tibrvTransport_RequestReliability() Request reliability interval (message 221

retention time) for a service.

tibrvTransport_Send() Send a message. 223

tibrvTransport_SendReply() Send a reply message. 225

tibrvTransport_SendRequest() Send a request message and wait for a reply. 226

TIBCO Rendezvous C Reference

208
| Chapter 8 Transport

Function or Type Description Page

tibrvTransport_SetBatchMode() Set the batch mode parameter of a transport. 228

tibrvTransport_SetBatchSize() Enable outbound batching of data from IPM, 229

and set the batch size (in bytes).

tibrvTransport_SetDescription() Set the program description parameter of a 230

transport.

TIBCO Rendezvous C Reference

 tibrvTransport 209
|

tibrvTransport
Type

Declaration typedef tibrvId tibrvTransport;

Purpose A transport object represents a delivery mechanism for messages.

Remarks A transport describes a carrier mechanism for messages—whether across a

network, among processes on a single computer, or within a process.
A transport also defines the delivery scope of a message—that is, the set of possible
destinations for the messages it sends.
Programs must explicitly destroy each transport object. Destroying a transport
object invalidates subsequent send calls on that transport, invalidates any
listeners using that transport, and frees its storage.

Intra-Process Each process has exactly one intra-process transport; the call tibrv_Open()
Transport automatically creates it, and arranges the constant TIBRV_PROCESS_TRANSPORT to
refer to it. Programs must not destroy the intra-process transport.

See Also tibrvTransport_Create() on page 211

tibrvTransport_Destroy() on page 216
tibrvTransport_Send() on page 223
Transport on page 99 in TIBCO Rendezvous Concepts
Intra-Process Transport and User Events, page 114 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

210
| Chapter 8 Transport

tibrvTransportBatchMode
Type

Declaration typedef enum {

TIBRV_TRANSPORT_DEFAULT_BATCH,
TIBRV_TRANSPORT_TIMER_BATCH
} tibrvTransportBatchMode;

Purpose Specify the batch mode of a transport.

Value Description
TIBRV_TRANSPORT_DEFAULT_B Default batch behavior. The transport transmits outbound
ATCH messages to rvd as soon as possible.
This value is the initial default for all transports.

TIBRV_TRANSPORT_TIMER_BAT Timer batch behavior. The transport accumulates outbound

CH messages, and transmits them to rvd in batches—either
when its buffer is full, or when a timer interval expires.
(Programs cannot adjust the timer interval.)

See Also tibrvTransport_SetBatchMode() on page 228

Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvTransport_Create() 211
|

tibrvTransport_Create()
Function

Declaration tibrv_status tibrvTransport_Create(

tibrvTransport* transport,
const char* service,
const char* network,
const char* daemon);

tibrv_status tibrvTransport_CreateLicensed(
tibrvTransport* transport,
const char* service,
const char* network,
const char* daemon,
const char* licenseTicket);

Purpose Create a network transport.

Remarks These calls create only network transports. The call tibrv_Open() automatically
creates the intra-process transport; programs cannot create additional
intra-process transports.

(Sheet 1 of 2)

Parameter Description
transport The program supplies a location, and the function stores the new transport in
that location.
The transport remains valid until the program explicitly destroys it.

service 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 over more than one service, a program must create more than
one transport—one transport for each service.
You can specify the service in several ways. For details, see Service Parameter
on page 103 in TIBCO Rendezvous Concepts.
NULL specifies the default rendezvous service.

TIBCO Rendezvous C Reference

212
| Chapter 8 Transport

(Sheet 2 of 2)

Parameter Description
network Every network transport communicates with other transports over a single
network interface. On computers with more than one network interface, the
network parameter instructs the Rendezvous daemon to use a particular
network for all outbound messages from this transport.
To communicate over more than one network, programs must create more than
one transport.
You can specify the network in several ways. For details, see Network
Parameter on page 107 in TIBCO Rendezvous Concepts.
NULL specifies the primary network interface for the host computer.

daemon The daemon parameter instructs tibrvTransport_Create() 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 tibrvSecureDaemon_SetDaemonCert() on page 25.
See also, Secure Daemon on page 111 in TIBCO Rendezvous Concepts.
null specifies the default—find the local daemon on TCP socket 7500. (This
default is not valid when the local daemon is a secure daemon.)

licenseTicket Embed this special license ticket in the transport object. When a licensed
transport connects to rvd, it presents this special ticket to validate its
connection (rvd uses the longest-running ticket available, which can be either
this special ticket, or a ticket from the ticket file, tibrv.tkt)
Ordinary license tickets are not valid for this parameter; see also, Embedded
License on page 213.

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.
Daemon
If a Rendezvous daemon process with a corresponding daemon parameter is
already running, tibrvTransport_Create() connects to it.

TIBCO Rendezvous C Reference

 tibrvTransport_Create() 213
|

If an appropriate Rendezvous local daemon is not running,

tibrvTransport_Create() tries to start it. However,
tibrvTransport_Create() does not attempt to start a remote daemon when none
is running.
If tibrvTransport_Create() cannot connect to the Rendezvous daemon, it
returns the status code TIBRV_DAEMON_NOT_CONNECTED, and does not create a
transport object.
The first time a program successfully connects to the Rendezvous daemon
process, rvd starts the clock ticking for temporary license tickets. (See Licensing
Information on page 11 in TIBCO Rendezvous Administration.)

Description As a debugging aid, we recommend setting a unique description string for each
String transport. Use a string that distinguishes both the application and the role of the
transport within it. See tibrvTransport_SetDescription() on page 230.

Destroying Programs must explicitly destroy each transport object. Destroying a transport
Transports object invalidates subsequent send calls on that transport, invalidates any
listeners using that transport, and frees its storage. See tibrvTransport_Destroy()
on page 216.
Attempting to use a destroyed transport in any way is an error.

Embedded Specially-licensed third-party developers can use the second form of this
License function. 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_Destroy() on page 216

TIBCO Rendezvous C Reference

214
| Chapter 8 Transport

tibrvTransport_CreateInbox()
Function

Declaration tibrv_status tibrvTransport_CreateInbox(

tibrvTransport transport,
char* subjectString,
tibrv_u32 subjectLimit);

Purpose Create a unique inbox subject name.

This function is the only legal way for programs to create inbox subject names.

Remarks This function creates inbox names that are unique throughout the transport scope.
• For network transports, inbox subject names are unique across all processes
within the local router domain—that is, anywhere that direct multicast contact
is possible. The inbox name is not necessarily unique outside of the local
router domain.
• For the intra-process transport, inbox names are unique across all threads of
the process.

This function 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 tibrvEvent_CreateListener(). The inbox
name is only valid for use with the same transport that created it. When calling
tibrvEvent_CreateListener(), 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.
Programs can overwrite or free the subjectString storage at any time.
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.

(Sheet 1 of 2)

Parameter Description
transport Create an inbox on this transport.

TIBCO Rendezvous C Reference

 tibrvTransport_CreateInbox() 215
|

(Sheet 2 of 2)

Parameter Description
subjectString The program supplies a string buffer, and the function
stores the new inbox subject string in that buffer.

subjectLimit The number of bytes that the program has allocated to

receive the new inbox subject string.

See Also tibrvEvent_CreateListener() on page 140

TIBCO Rendezvous C Reference

216
| Chapter 8 Transport

tibrvTransport_Destroy()
Function

Declaration tibrv_status tibrvTransport_Destroy(

tibrvTransport transport);

Purpose Destroy a transport.

Remarks Programs must explicitly destroy each transport object.

Destroying a transport achieves these effects:
• The transport flushes all outbound data to the Rendezvous daemon.
This effect is especially important, and neither exiting the program nor calling
tibrv_Close() is sufficient to flush outbound data.

• The transport invalidates all its listeners.

• Subsequent calls that use the destroyed transport return an error status.
• Storage for the transport object is freed.

It is illegal to destroy the intra-process transport (TIBRV_PROCESS_TRANSPORT);

attempting to destroy it produces the status code TIBRV_NOT_PERMITTED.

Parameter Description
transport Destroy this transport.

See Also tibrvTransport on page 209

tibrvTransport_Create() on page 211

TIBCO Rendezvous C Reference

 tibrvTransport_GetDaemon() 217
|

tibrvTransport_GetDaemon()
Function

Declaration tibrv_status tibrvTransport_GetDaemon(

tibrvTransport transport,
const char** daemonString);

Purpose Extract the daemon parameter from a transport.

Remarks This function returns the daemon parameter as a NULL-terminated string.

Parameter Description
transport Extract the effective daemon parameter from this transport.
It is an error to supply the intra-process transport or virtual
circuit transport to this function.

daemonString The program supplies a location, and the function places in

that location a string pointer to the daemon information.
The program must not modify nor free the string.

See Also tibrvTransport on page 209

tibrvTransport_Create() on page 211

TIBCO Rendezvous C Reference

218
| Chapter 8 Transport

tibrvTransport_GetDescription()
Function

Declaration tibrv_status tibrvTransport_GetDescription(

tibrvTransport transport,
const char** description);

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.
This function returns the description parameter as a NULL-terminated string.

Parameter Description
transport Extract the description parameter from this transport.
It is an error to supply the intra-process transport or virtual
circuit transport to this function.

description The program supplies a location, and the function places in

that location a string pointer to the description.
The program must not modify nor free the string.

See Also tibrvTransport on page 209

tibrvTransport_SetDescription() on page 230

TIBCO Rendezvous C Reference

 tibrvTransport_GetNetwork() 219
|

tibrvTransport_GetNetwork()
Function

Declaration tibrv_status tibrvTransport_GetNetwork(

tibrvTransport transport,
const char** networkString);

Purpose Extract the network parameter from a transport.

Remarks This function returns the network parameter as a NULL-terminated string.

Parameter Description
transport Extract the network parameter from this transport.
It is an error to supply the intra-process transport or
virtual circuit transport to this function.

networkString The program supplies a location, and the function places

in that location a string pointer to the network parameter.
The program must not modify the string.

See Also tibrvTransport on page 209

tibrvTransport_Create() on page 211

TIBCO Rendezvous C Reference

220
| Chapter 8 Transport

tibrvTransport_GetService()
Function

Declaration tibrv_status tibrvTransport_GetService(

tibrvTransport transport,
const char** serviceString);

Purpose Extract the service parameter from a transport.

Remarks This function returns the service parameter as a NULL-terminated string.

Parameter Description
transport Extract the service parameter from this transport.
It is an error to supply the intra-process transport or
virtual circuit transport to this function.

serviceString The program supplies a location, and the function places

in that location a string pointer to the service information.
The program must not modify the string.

See Also tibrvTransport on page 209

tibrvTransport_Create() on page 211

TIBCO Rendezvous C Reference

 tibrvTransport_RequestReliability() 221
|

tibrvTransport_RequestReliability()
Function

Declaration tibrv_status tibrvTransport_RequestReliability(

tibrvTransport transport,
tibrv_f64 reliability);

Purpose Request reliability interval (message retention time) for a service.

Parameter Description
transport Request reliability on the service of this transport.

reliability Request this reliability interval (in seconds).

This value must be greater than zero.

Remarks This call lets application programs shorten the reliability interval of the specific
service associated with a transport object. Successful calls change the daemon’s
reliability interval for all transports within the application process that use the
same service.
Programs can request reliability only from daemons of release 8.2 or later.
An application can request a shorter retention time than the value that governs
the daemon as a whole (either the factory default or the daemons -reliability
parameter). The daemon’s governing value silently overrides calls that request a
longer retention time.

Maximum Value Client transport objects that connect to the same daemon could specify different
Rule reliability intervals on the same service—whether by requesting a reliability
value, or by using the daemon’s effective value. In this situation, the daemon
selects the largest potential value from among all the transports on that service,
and uses that maximum value as the effective reliability interval for the service
(that is, for all the transports on the service). This method of resolution favors the
more stringent reliability requirements. (Contrast this rule with the Lower Value
Rule that applies between two daemons.)

Recomputing the Whenever a transport connects, requests reliability, or disconnects from the
Reliability daemon, the daemon recalculates the reliability interval for the corresponding
service, by selecting the largest value of all transports communicating on that
service.

TIBCO Rendezvous C Reference

222
| Chapter 8 Transport

When recomputing the reliability interval would result in a shorter retention time,
the daemon delays using the new value until after an interval equivalent to the
older (longer) retention time. This delay ensures that the daemon retains message
data at least as long as the effective reliability interval at the time the message is
sent.

See Also tibrvTransport on page 209

Reliability and Message Retention Time on page 35 in TIBCO Rendezvous
Administration
Lower Value Rule on page 36 in TIBCO Rendezvous Administration
Changing the Reliability Interval within an Application Program on page 37 in
TIBCO Rendezvous Administration
Reliable Message Delivery on page 58 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvTransport_Send() 223
|

tibrvTransport_Send()
Function

Declaration tibrv_status tibrvTransport_Send(

tibrvTransport transport,
tibrvMsg message);

Purpose Send a message.

Parameter Description
transport Send the message on this transport.

message Send this message.

See Also tibrvMsg on page 52

tibrvMsg_Create() on page 70
tibrvTransport on page 209

TIBCO Rendezvous C Reference

224
| Chapter 8 Transport

tibrvTransport_Sendv()
Function

Declaration tibrv_status tibrvTransport_Sendv(

tibrvTransport transport,
tibrvMsg* messageVector,
tibrv_u32 length);

Purpose Send a vector of messages.

Remarks This function sends a group of messages with one call. In most applications this
call is more efficient than a series of send calls on individual messages.

messageVector is an an array of tibrvMsg objects. To avoid array out-of-bounds

errors, be careful to pass an appropriate length (that is, a length that is no larger
than the number of tibrvMsg objects in the array).

Parameter Description
transport Send the messages on this transport.

messageVector Send these messages.

length Number of messages in the vector.

See Also tibrvMsg on page 52

tibrvMsg_Create() on page 70
tibrvTransport on page 209
tibrvTransport_Send() on page 223

TIBCO Rendezvous C Reference

 tibrvTransport_SendReply() 225
|

tibrvTransport_SendReply()
Function

Declaration tibrv_status tibrvTransport_SendReply(

tibrvTransport transport,
tibrvMsg replyMessage,
tibrvMsg requestMessage);

Purpose Send a reply message.

Remarks This function 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 function overwrites any existing send subject of the reply message with the
reply subject of the request message.

Parameter Description
transport Send the reply on this transport.

replyMessage Send this outbound reply message.

requestMessage Send a reply to this inbound request message; extract its

reply subject to use as the subject of the outbound reply
message.

Give special attention to the order of the arguments to this function. 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_Create() on page 70

tibrvTransport on page 209

TIBCO Rendezvous C Reference

226
| Chapter 8 Transport

tibrvTransport_SendRequest()
Function

Declaration tibrv_status tibrvTransport_SendRequest(

tibrvTransport transport,
tibrvMsg message,
tibrvMsg* reply,
tibrv_f64 timeout);

Purpose Send a request message and wait for a reply.

Blocking can Stall Event Dispatch

This call blocks all other activity on its program thread. If appropriate,
programmers must ensure that other threads continue dispatching events on its
queues.

Parameter Description
transport Send the message and receive the reply on this transport.

message Send this outbound message.

reply The program supplies a location, and the function stores the
inbound reply in that location.
The program need not create the reply message, nor allocate
space for it. However, the program must destroy the reply
message, even though it did not create it.

timeout Maximum time (in seconds) that this call can block while
waiting for a reply.
TIBRV_WAIT_FOREVER (-1) indicates no timeout (wait without
limit for a reply).

Remarks The status code TIBRV_TIMEOUT indicates that the specified time expired before
receiving a reply.
Programs that receive and process the request message cannot determine that the
sender has blocked until a reply arrives.
The request message must have a valid destination subject; see
tibrvMsg_SetSendSubject() on page 113.

TIBCO Rendezvous C Reference

 tibrvTransport_SendRequest() 227
|
Operation This function operates in several synchronous steps:
1. Create an inbox name, and an event that listens to it. Overwrite any existing
reply subject of message with the inbox name.
2. Send the outbound message.
3. Block until the listener receives a reply; if the time limit expires before a reply
arrives, return the status code TIBRV_TIMEOUT. (The reply circumvents the
event queue mechanism, so it is not necessary to explicitly call dispatch
methods in the program.)
4. Store the reply in the location specified by the reply parameter.
5. Return.

See Also tibrvMsg_Create() on page 70

tibrvTransport on page 209

TIBCO Rendezvous C Reference

228
| Chapter 8 Transport

tibrvTransport_SetBatchMode()
Function

Declaration tibrv_status tibrvTransport_SetBatchMode(

tibrvTransport transport,
tibrvTransportBatchMode mode);

Purpose Set the batch mode parameter of a transport.

Remarks This type of batching is available only with the standard (daemon-based)
Rendezvous library. It is not available with the IPM library.
The batch mode determines when the transport transmits outbound message data
to rvd:
• As soon as possible (the initial default for all transports)
• Either when its buffer is full, or when a timer interval expires—either event
triggers transmission to the daemon

Parameter Description
transport Set the batch mode parameter of this transport.

mode Use this value as the new batch mode.

See Also tibrvTransport on page 209

tibrvTransportBatchMode on page 210
Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvTransport_SetBatchSize() 229
|

tibrvTransport_SetBatchSize()

Declaration tibrv_status tibrvTransport_SetBatchSize(

tibrvTransport transport,
tibrv_u32 numBytes);

Purpose Enable outbound batching of data from IPM, and set the batch size (in bytes).

Remarks This type of batching is available only with the IPM library. It is not available with
the standard (daemon-based) Rendezvous library.
When the batch size is greater than zero, IPM transfers data to the network in
batches. This option can increase throughput, at the cost of higher latency.
When the batch size is zero, IPM transfers data to the network immediately, for
lowest latency.
If you do not explicitly set the batch size using this call, then the default behavior
disables outbound batching.

Contraindications
These conditions characterize situations in which we do not recommend batching:
• Data latency is not acceptable.
• Batch behavior does not produce measurable improvements in the
performance of your application.

Parameter Description
transport Enable (or disable) batching for this transport.

numBytes Set the batch size (in bytes).

Zero is a special value, which diables batching for the transport.

TIBCO Rendezvous C Reference

230
| Chapter 8 Transport

tibrvTransport_SetDescription()
Function

Declaration tibrv_status tibrvTransport_SetDescription(

tibrvTransport transport,
const char* description);

Purpose Set the program description parameter of a transport.

Remarks The description identifies your program to Rendezvous components. Browser

administration interfaces display the description string.
As a debugging aid, we recommend setting a unique description string for each
transport. Use a string that distinguishes both the application and the role of the
transport within it.

Parameter Description
transport Set the description parameter of this transport.
It is an error to supply the intra-process transport or virtual
circuit transport to this function.

description Use this string as the new program description.

The function copies this string.

See Also tibrvTransport on page 209

tibrvTransport_GetDescription() on page 218

TIBCO Rendezvous C Reference

 | 231

Chapter 9 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 in Alphabetical Order

Function or Type Description Page

tibrvTransport_CreateAcceptVc() Create a virtual circuit accept object. 232

tibrvTransport_CreateConnectVc() Create a virtual circuit connect object. 235

tibrvTransport_WaitForVcConnection() Test the connection status of a virtual 237

circuit.

TIBCO Rendezvous C Reference

232
| Chapter 9 Virtual Circuits

tibrvTransport_CreateAcceptVc()
Function

Declaration tibrv_status tibrvTransport_CreateAcceptVc(

tibrvTransport* vcTransport,
const char** connectSubject,
tibrvTransport transport);

Purpose Create a virtual circuit accept object.

Remarks A virtual circuit transport can fill the same roles as an ordinary transport.
Programs can supply them as arguments to calls that create inbox names, send
messages, create listeners and other events.

Parameter Description
vcTransport The program supplies a location, and the function stores the new virtual circuit
accept transport in that location.

connectSubject The program supplies a location, and the function stores the connect subject of
the new virtual circuit accept transport in that location.
After this call returns, the program must send a message to another program,
inviting it to establish a virtual circuit. Furthermore, the reply subject of that
invitation message must be this connect subject. To complete the virtual circuit,
the second program must extract this subject from the invitation, and supply it
to tibrvTransport_CreateConnectVc().

transport The virtual circuit uses this ordinary transport for communications.
Programs may use this transport for other purposes.
It is illegal to supply a virtual circuit transport object for this parameter (that is,
you cannot nest a virtual circuit within another virtual circuit).

Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The transport presents the VC.CONNECTED advisory.
• 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.

TIBCO Rendezvous C Reference

 tibrvTransport_CreateAcceptVc() 233
|

2. Call tibrvTransport_WaitForVcConnection() with zero as the timeout

parameter.

For an explanation, see Testing the New Connection on page 123 in TIBCO
Rendezvous Concepts.

Broken The following conditions can close a virtual circuit connection:

Connection
• Contact is broken between the object and its terminal.
• The virtual circuit loses data in either direction (see DATALOSS on page 272
in TIBCO Rendezvous Concepts).
• The partner program destroys its terminal object (or that terminal becomes
invalid).
• The program destroys the object.
• The program destroys the object’s ordinary transport.

Destroying VC Programs must explicitly destroy each virtual circuit transport object. Destroying
Transports 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.
See tibrvTransport_Destroy() on page 216.
Destroying a virtual circuit transport does not affect the ordinary transport that
the terminal employs.

Direct Because virtual circuits rely on point-to-point messages between the two
Communication terminals, they can use direct communication to good advantage. To do so, both
terminals must use network transports that enable direct communication.
For an overview, see Direct Communication on page 116 in TIBCO Rendezvous
Concepts.
For programming details, see Specifying Direct Communication on page 105 in
TIBCO Rendezvous Concepts.

Disabled Although virtual circuit transport objects have the same data type as transport
Functions objects, some transport functions are disabled for virtual circuit objects.

Transport Functions
Legal Calls for tibrvTransport_CreateInbox()
tibrvTransport_Destroy()
Virtual Circuit
tibrvTransport_Send()
Transports
tibrvTransport_SendReply()
tibrvTransport_SendRequest()

TIBCO Rendezvous C Reference

234
| Chapter 9 Virtual Circuits

Transport Functions
Disabled Calls for tibrvTransport_GetDaemon()
Virtual Circuit tibrvTransport_GetDescription()
Transports tibrvTransport_GetNetwork()
tibrvTransport_GetService()
tibrvTransport_SetBatchMode()
tibrvTransport_SetDescription()

See Also tibrvTransport_Destroy() on page 216

tibrvTransport_CreateConnectVc() on page 235
tibrvTransport_WaitForVcConnection() on page 237
VC.CONNECTED on page 288 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 289 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvTransport_CreateConnectVc() 235
|

tibrvTransport_CreateConnectVc()
Function

Declaration tibrv_status tibrvTransport_CreateConnectVc(

tibrvTransport* vcTransport,
const char* connectSubject,
tibrvTransport transport);

Purpose Create a virtual circuit connect object.

Remarks A virtual circuit transport can fill the same roles as an ordinary transport.
Programs can supply them as arguments to calls that create inbox names, send
messages, create listeners and other events.

Parameter Description
vcTransport The program supplies a location, and the function stores the new virtual circuit
connect transport in that location.

connectSubject The connect transport uses this connect subject to establish a virtual circuit
with an accept transport in another program.
The program must receive this connect subject from the accepting program.
The call to tibrvTransport_CreateAcceptVc() creates this subject.

transport The virtual circuit uses this ordinary transport for communications.
Programs may use this transport for other purposes.
It is illegal to supply a virtual circuit transport object for this parameter (that is,
you cannot nest a virtual circuit within another virtual circuit).

Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The transport presents the VC.CONNECTED advisory.
• 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 zero as the timeout
parameter.

TIBCO Rendezvous C Reference

236
| Chapter 9 Virtual Circuits

For an explanation, see Testing the New Connection on page 123 in TIBCO
Rendezvous Concepts.

Broken The following conditions can close a virtual circuit connection:

Connection
• Contact is broken between the object and its terminal.
• The virtual circuit loses data in either direction (see DATALOSS on page 272
in TIBCO Rendezvous Concepts).
• The partner program destroys its terminal object (or that terminal becomes
invalid).
• The program destroys the object.
• The program destroys the object’s ordinary transport.

Destroying VC Programs must explicitly destroy each virtual circuit transport object. Destroying
Transports 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.
See tibrvTransport_Destroy() on page 216.
Destroying a virtual circuit transport does not affect the ordinary transport that
the terminal employs.

Direct Because virtual circuits rely on point-to-point messages between the two
Communication terminals, they can use direct communication to good advantage. To do so, both
terminals must use network transports that enable direct communication.
For an overview, see Direct Communication on page 116 in TIBCO Rendezvous
Concepts.
For programming details, see Specifying Direct Communication on page 105 in
TIBCO Rendezvous Concepts.

See Also tibrvTransport_Destroy() on page 216

tibrvTransport_CreateAcceptVc() on page 232
tibrvTransport_WaitForVcConnection() on page 237
VC.CONNECTED on page 288 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 289 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvTransport_WaitForVcConnection() 237
|

tibrvTransport_WaitForVcConnection()
Function

Declaration tibrv_status tibrvTransport_WaitForVcConnection(

tibrvTransport vcTransport,
tibrv_f64 timeout);

Purpose Test the connection status of a virtual circuit.

Remarks This function produces the same information as the virtual circuit advisory
messages—but it produces it synchronously (while advisories are asynchronous).
Programs can use this function 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 function to wait
until the connection completes.

Parameter Description
vcTransport Wait until this virtual circuit transport object has established a connection with
its opposite terminal. You may supply either an accept terminal or a connect
terminal as an argument.

timeout This parameter determines the behavior of the call:

• For a quick test of current connection status, supply zero. The call returns
immediately, without blocking.
• To wait for a new terminal to establish a connection, supply a reasonable
positive value. The call returns either when the connection is complete, or
when this time limit elapses.
• To wait indefinitely for a usable connection, supply -1. The call returns
when the connection is complete. If the connection was already complete
and is now broken, the call returns immediately.

(Sheet 1 of 2)

Status Description
TIBRV_OK The connection is complete (ready to use).

TIBRV_TIMEOUT The connection is not yet complete, but the non-negative time limit
for waiting has expired.

TIBCO Rendezvous C Reference

238
| Chapter 9 Virtual Circuits

(Sheet 2 of 2)

Status Description
TIBRV_VC_NOT_CONNECTED The connection was formerly complete, but is now irreparably
broken.

See Also tibrvTransport_CreateAcceptVc() on page 232

tibrvTransport_CreateConnectVc() on page 235
Testing the New Connection on page 123 in TIBCO Rendezvous Concepts
VC.CONNECTED on page 288 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 289 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 | 239

Chapter 10 Fault Tolerance

Rendezvous fault tolerance software coordinates a group of redundant processes

into a fault-tolerant distributed system. Some processes actively fulfill the tasks of
the application, while other processes wait in readiness. When one of the active
processes fails, another process rapidly assumes active duty.

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

Topics in Alphabetical Order

(Sheet 1 of 3)

Function or Type Description Page

tibrvft_Version() Identify the fault tolerance API release number. 242

tibrvftAction Instruct fault tolerance callback functions to react to 243

changing circumstances.

tibrvftMember Member objects represent program membership in a 244

fault tolerance group.

TIBCO Rendezvous C Reference

240
| Chapter 10 Fault Tolerance

(Sheet 2 of 3)

Function or Type Description Page

tibrvftMemberCallback Process fault tolerance events for a group member. 245

tibrvftMemberOnComplete A program can destroy a member object even when 247

its callback function is running in one or more
threads. Multi-threaded programs can define
functions of this type to discover when all callback
functions in progress have completed.

tibrvftMember_Create() Create a member of a fault tolerance group. 249

tibrvftMember_Destroy() Destroy a member of a fault tolerance group. 252

tibrvftMember_GetGroupName() Extract the group name of a fault tolerance member. 254

tibrvftMember_GetQueue() Extract the event queue of a fault tolerance member. 255

tibrvftMember_GetTransport() Extract the transport of a fault tolerance member. 256

tibrvftMember_GetWeight() Extract the weight of a fault tolerance member. 257

tibrvftMember_SetWeight() Change the weight of a fault tolerance member 258

within its group.

Monitors

tibrvftMonitor Monitor objects express interest in fault tolerance 259

events.

tibrvftMonitorCallback Process fault tolerance events for a monitor. 260

tibrvftMonitorOnComplete A program can destroy a monitor object even when 261

its callback function is running in one or more
threads. Multi-threaded programs can define
functions of this type to discover when all callback
functions in progress have completed.

tibrvftMonitor_Create() Monitor a fault tolerance group. 263

tibrvftMonitor_Destroy() Stop monitoring a fault tolerance group, and free 265

associated resources.

tibrvftMonitor_GetGroupName() Extract the group name of a fault tolerance monitor. 266

tibrvftMonitor_GetQueue() Extract the event queue of a fault tolerance monitor. 267

TIBCO Rendezvous C Reference

 Fault Tolerance 241
|

(Sheet 3 of 3)

Function or Type Description Page

tibrvftMonitor_GetTransport() Extract the transport of a fault tolerance monitor. 268

TIBCO Rendezvous C Reference

242
| Chapter 10 Fault Tolerance

tibrvft_Version()
Function

Declaration const char* tibrvft_Version(void);

Purpose Identify the fault tolerance API release number.

TIBCO Rendezvous C Reference

 tibrvftAction 243
|

tibrvftAction
Type

Declaration typedef enum

{
TIBRVFT_PREPARE_TO_ACTIVATE = 1,
TIBRVFT_ACTIVATE = 2,
TIBRVFT_DEACTIVATE = 3

} tibrvftAction;

Purpose Instruct fault tolerance callback functions to react to changing circumstances.

Remarks Each token of this enumerated type designates a command to a fault tolerance
callback function. The program’s callback function 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).

Token Description
TIBRVFT_PREPARE_TO_ACTIVATE Prepare to activate (hint).
Rendezvous fault tolerance software passes this token to the
callback function to instruct the program to make itself ready
to activate on short notice—so that if the callback function
subsequently receives the instruction to activate, it can do so
without delay.
This token is a hint, indicating that the program might soon
receive an instruction to activate. It does not guarantee that an
activate instruction will follow, nor that any minimum time
will elapse before an activate instruction follows.

TIBRVFT_ACTIVATE Activate immediately.

Rendezvous fault tolerance software passes this token to the
callback function to instruct the program to activate.

TIBRVFT_DEACTIVATE Deactivate immediately.

Rendezvous fault tolerance software passes this token to the
callback function to instruct the program to deactivate.

See Also tibrvftMemberCallback on page 245

tibrvftMember_Create() on page 249

TIBCO Rendezvous C Reference

244
| Chapter 10 Fault Tolerance

tibrvftMember
Type

Declaration typedef tibrvId tibrvftMember;

Purpose Member objects represent program membership in a fault tolerance group.

See Also tibrvftMember_Create() on page 249

TIBCO Rendezvous C Reference

 tibrvftMemberCallback 245
|

tibrvftMemberCallback
Function Type

Declaration typedef void (*tibrvftMemberCallback) (

tibrvftMember member,
const char* groupName,
tibrvftAction action,
void* closure);

Purpose Process fault tolerance events for a group member.

Remarks Each member program of a fault tolerance group must define a function of this
type. Programs register a member callback function with each call to
tibrvftMember_Create().

Rendezvous fault tolerance software queues a member action event in three

situations. In each case, it passes a different action argument, instructing the
callback function to activate, deactivate, or prepare to activate the program.
• When the number of active members drops below the active goal, the fault
tolerance callback function (in the ranking inactive member process) receives
the token TIBRVFT_ACTIVATE; the callback function must respond by
assuming the duties of an active member.
• When the number of active members exceeds the active goal, the fault
tolerance callback function (in any active member that is outranked by
another active member) receives the action token TIBRVFT_DEACTIVATE; the
callback function 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 function (in the ranking inactive member)
receives the action token TIBRVFT_PREPARE_TO_ACTIVATE; the callback
function 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 function subsequently receives the
TIBRVFT_ACTIVATE token, it will be ready to activate without delay.

For additional information see Fault Tolerance Callback Actions on page 216 in
TIBCO Rendezvous Concepts.

(Sheet 1 of 2)

Parameter Description
member This parameter receives the member object.

TIBCO Rendezvous C Reference

246
| Chapter 10 Fault Tolerance

(Sheet 2 of 2)

Parameter Description
groupName This parameter receives a string denoting the name of the fault
tolerance group.

action This parameter receives a value of the enumerated type

tibrvftAction, which instructs the callback function to
activate, deactivate or prepare to activate.

closure This parameter receives the closure data, which the program
supplied in the call that created the member object.

See Also tibrvftAction on page 243

tibrvftMember_Create() on page 249

TIBCO Rendezvous C Reference

 tibrvftMemberOnComplete 247
|

tibrvftMemberOnComplete
Function Type

Declaration typedef void (*tibrvftMemberOnComplete) (

tibrvftMember destroyedMember,
void* closure);

Purpose A program can destroy a member object even when its callback function is
running in one or more threads. Multi-threaded programs can define functions of
this type to discover when all callback functions in progress have completed.

Parameter Description
destroyedMember This parameter receives the member event object. This
object is identical to the object that the program created
to join the fault tolerance group.
However, by the time this function runs, the member is
already destroyed; this function cannot use the member
object in Rendezvous calls.

closure This parameter receives the closure data, which the

program supplied in the call that created the member
object.

Remarks This type of function is important in two situations:

• Internal fault tolerance callback functions run in several threads (because
several threads dispatch the member’s event queue), and the program must
do additional processing after these callback functions have completed in all
threads.
• A member callback function calls tibrvftMember_DestroyEx() to withdraw
from a fault tolerance group, and the program must do additional processing
after the rest of the callback function has completed.

Upon return from tibrvftMember_DestroyEx(), the destroyed member’s

callback function can no longer begin to run (this is also true of internal callback
functions). However, in each thread where a callback function is already in
progress, that callback function does continue to run until complete.
tibrvftMember_DestroyEx() accepts a completion function argument of type
tibrvftMemberOnComplete. Rendezvous software ensures that the completion
function runs when the last callback-in-progress has completed.

Timing and This information in completely analogous to tibrvEventOnComplete on page 134.

Context See that section for important details.

TIBCO Rendezvous C Reference

248
| Chapter 10 Fault Tolerance

See Also tibrvftMember_Create() on page 249

tibrvftMember_DestroyEx(), see tibrvftMember_Destroy() on page 252

TIBCO Rendezvous C Reference

 tibrvftMember_Create() 249
|

tibrvftMember_Create()
Function

Declaration tibrv_status tibrvftMember_Create(

tibrvftMember* member,
tibrvQueue queue,
tibrvftMemberCallback callback,
tibrvTransport transport,
const char* groupName,
tibrv_u16 weight,
tibrv_u16 activeGoal,
tibrv_f64 heartbeatInterval,
tibrv_f64 preparationInterval,
tibrv_f64 activationInterval,
void* closure);

Purpose Create a member of a fault tolerance group.

Remarks Upon creating a member object, the program becomes a member of the group.
A program 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 program to maintain more
than one membership in any one fault tolerance group. The function
tibrvftMember_Create() does not guard against this illegal situation, and
results are unpredictable.
All arguments are required except for preparationInterval (which may be
zero) and closure (which may be NULL).

(Sheet 1 of 3)

Parameter Description
member This member object denotes membership in a fault tolerance group.
The program supplies a location, and the function stores the new
member object in that location.
The member object remains valid until the program explicitly destroys it.

queue Place fault tolerance events for this member on this event queue.

callback On dispatch, process the event with this callback function.

transport Use this transport for fault tolerance internal protocol messages (such as
heartbeat messages).

TIBCO Rendezvous C Reference

250
| Chapter 10 Fault Tolerance

(Sheet 2 of 3)

Parameter Description
groupName Join the fault tolerant group with this name.
The group name must conform to the syntax required for Rendezvous
subject names. For details, see Subject Names on page 61 in TIBCO
Rendezvous Concepts.

weight Weight represents the ability of this member to fulfill its purpose, relative
to other members of the same fault tolerance group. Rendezvous fault
tolerance software uses relative weight values to select which members
to activate; members with higher weight take precedence over members
with lower weight.
Acceptable values range from 1 to 65535. Zero is a special, reserved
value; Rendezvous fault tolerance software assigns zero weight to
processes with resource errors, so they only activate when no other
members are available.
For more information, see Rank and Weight on page 206 in TIBCO
Rendezvous Concepts.

activeGoal Rendezvous fault tolerance software sends callback instructions to

maintain this number of active members.
Acceptable values range from 1 to 65535.

heartbeatInterval When this member is active, it sends heartbeat messages at this interval
(in seconds).
The interval must be positive. To determine the correct value, see Step 4:
Choose the Intervals on page 237 in TIBCO Rendezvous Concepts.

preparationInterval When the heartbeat signal from one or more active members has been
silent for this interval (in seconds), Rendezvous fault tolerance software
issues an early warning hint (TIBRVFT_PREPARE_TO_ACTIVATE) to the
ranking inactive member. This warning lets the inactive member prepare
to activate, for example, by connecting to a database server, or allocating
memory.
The interval must be non-negative. Zero is a special value, indicating
that the member does not need advance warning to activate;
Rendezvous fault tolerance software never issues a
TIBRVFT_PREPARE_TO_ACTIVATE hint when this value is zero. To
determine the correct value, see Step 4: Choose the Intervals on page 237
in TIBCO Rendezvous Concepts.

TIBCO Rendezvous C Reference

 tibrvftMember_Create() 251
|

(Sheet 3 of 3)

Parameter Description
activationInterval When the heartbeat signal from one or more active members has been
silent for this interval (in seconds), Rendezvous fault tolerance software
considers the silent member to be lost, and issues the instruction to
activate (TIBRVFT_ACTIVATE) to the ranking inactive member.
When a new member joins a group, Rendezvous fault tolerance software
identifies the new member to existing members (if any), and then waits
for this interval to receive identification from them in return. If, at the
end of this interval, it determines that too few members are active, it
issues the activate instruction (TIBRVFT_ACTIVATE) to the new member.
Then interval must be positive. To determine the correct value, see Step
4: Choose the Intervals on page 237 in TIBCO Rendezvous Concepts.

closure Store this closure data on the member object.

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.

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 tibrvftAction on page 243

tibrvftMemberCallback on page 245
tibrvftMember_Destroy() on page 252
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

TIBCO Rendezvous C Reference

252
| Chapter 10 Fault Tolerance

tibrvftMember_Destroy()
Function

Declaration tibrv_status tibrvftMember_Destroy(

tibrvftMember member);

tibrv_status tibrvftMember_DestroyEx(
tibrvftMember member,
tibrvftMemberOnComplete completionFunction);

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

Parameter Description
member Destroy this member object, and cancel
membership in its fault tolerance group.

completionFunction Rendezvous software runs this function

immediately after all instances of the member’s
callback function (and internal callback functions)
have completed. If callback functions are not
running when the event is destroyed, the destroy
call runs it before returning.
If this parameter is NULL,
tibrvftMember_DestroyEx() does not run a
completion function; instead, its behavior is the
same as tibrvftMember_Destroy().
See tibrvftMemberOnComplete on page 247.

TIBCO Rendezvous C Reference

 tibrvftMember_Destroy() 253
|
Extended Although tibrvftMember_DestroyEx() prevents future dispatch calls from
Function running the destroyed member’s callback function, that callback function might
be already running in one or more threads that dispatch events from the same
queue. In each thread where the callback function is already in progress, that
callback function does continue to run until complete. Rendezvous software
ensures that the completion function runs when the last callback-in-progress has
completed; for important details, see tibrvEventOnComplete on page 134.

See Also tibrvftMember_Create() on page 249

tibrvftMemberOnComplete on page 247

TIBCO Rendezvous C Reference

254
| Chapter 10 Fault Tolerance

tibrvftMember_GetGroupName()
Function

Declaration tibrv_status tibrvftMember_GetGroupName(

tibrvftMember member,
const char** groupName);

Purpose Extract the group name of a fault tolerance member.

Parameter Description
member Extract the group name from this member object.

groupName The program supplies a location, and the function stores the
group name in that location.

TIBCO Rendezvous C Reference

 tibrvftMember_GetQueue() 255
|

tibrvftMember_GetQueue()
Function

Declaration tibrv_status tibrvftMember_GetQueue(

tibrvftMember member,
tibrvQueue* queue);

Purpose Extract the event queue of a fault tolerance member.

Parameter Description
member Extract the event queue from this member object.

queue The program supplies a location, and the function stores the
queue in that location.

TIBCO Rendezvous C Reference

256
| Chapter 10 Fault Tolerance

tibrvftMember_GetTransport()
Function

Declaration tibrv_status tibrvftMember_GetTransport(

tibrvftMember member,
tibrvTransport* transport);

Purpose Extract the transport of a fault tolerance member.

Parameter Description
member Extract the transport from this member object.

transport The program supplies a location, and the function stores the
transport in that location.

TIBCO Rendezvous C Reference

 tibrvftMember_GetWeight() 257
|

tibrvftMember_GetWeight()
Function

Declaration tibrv_status tibrvftMember_GetWeight(

tibrvftMember member,
tibrv_u16* weight);

Purpose Extract the weight of a fault tolerance member.

Parameter Description
member Extract the weight from this member object.

weight The program supplies a location, and the function stores the
weight in that location.

TIBCO Rendezvous C Reference

258
| Chapter 10 Fault Tolerance

tibrvftMember_SetWeight()
Function

Declaration tibrv_status tibrvftMember_SetWeight(

tibrvftMember member,
tibrv_u16 weight);

Purpose Change the weight of a fault tolerance member within its group.

Remarks Weight summarizes the relative suitability of a member for its task, relative to
other members of the same fault tolerance group. That suitability is a combination
of computer speed and load factors, network bandwidth, computer and network
reliability, and other factors. Programs may reset their weight when any of these
factors change, overriding the previous assigned weight.
You can use relative weights to indicate priority among group members.
Zero is a special value; Rendezvous fault tolerance software assigns zero weight
to processes with resource errors, so they only activate when no other members
are available. Programs must always assign weights greater than zero.
When Rendezvous fault tolerance software requests a resource but receives an
error (for example, the member process cannot allocate memory, or start a timer),
it attempts to send the member process a DISABLING_MEMBER advisory message,
and sets the member’s weight to zero, effectively disabling the member. Weight
zero implies that this member is active only as a last resort—when no other
members outrank it. (However, if the disabled member process does become
active, it might not operate correctly.)

Parameter Description
member Set the weight of this member object.

weight The new weight value. See weight on page 250.

See Also Adjusting Member Weights, page 227 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvftMonitor 259
|

tibrvftMonitor
Type

Declaration typedef tibrvId tibrvftMonitor;

Purpose Monitor objects express interest in fault tolerance events.

See Also tibrvftMonitor_Create() on page 263

TIBCO Rendezvous C Reference

260
| Chapter 10 Fault Tolerance

tibrvftMonitorCallback
Function Type

Declaration typedef void (*tibrvftMonitorCallback) (

tibrvftMonitor monitor,
const char* groupName,
tibrv_u32 numActiveMembers,
void* closure);

Purpose Process fault tolerance events for a monitor.

Remarks A program must define a function of this type as a prerequisite for monitoring a
fault tolerance group. Programs register a monitor callback function with each
call to tibrvftMonitor_Create() on page 263.
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 function.

Parameter Description
monitor This parameter receives the monitor object.

groupName This parameter receives a string denoting the name of

the fault tolerance group.

numActiveMembers This parameter receives the number of group

members now active.

closure This parameter receives the closure data, which the

program supplied in the call that created the monitor
object.

See Also tibrvftMonitor_Create() on page 263

TIBCO Rendezvous C Reference

 tibrvftMonitorOnComplete 261
|

tibrvftMonitorOnComplete
Function Type

Declaration typedef void (*tibrvftMonitorOnComplete) (

tibrvftMember destroyedMonitor,
void* closure);

Purpose A program can destroy a monitor object even when its callback function is
running in one or more threads. Multi-threaded programs can define functions of
this type to discover when all callback functions in progress have completed.

Parameter Description
destroyedMonitor This parameter receives the monitor event object. This
object is identical to the object that the program
created to monitor the fault tolerance group.
However, by the time this function runs, the monitor
is already destroyed; this function cannot use the
monitor object in Rendezvous calls.

closure This parameter receives the closure data, which the

program supplied in the call that created the monitor
object.

Remarks This type of function is important in two situations:

• Internal fault tolerance callback functions run in several threads (because
several threads dispatch the monitor’s event queue), and the program must
do additional processing after these callback functions have completed in all
threads.
• A monitor callback function calls tibrvftMonitor_DestroyEx() to
withdraw from a fault tolerance group, and the program must do additional
processing after the rest of the callback function has completed.

Upon return from tibrvftMonitor_DestroyEx(), the destroyed monitor’s

callback function can no longer begin to run (this is also true of internal callback
functions). However, in each thread where a callback function is already in
progress, that callback function does continue to run until complete.
tibrvftMonitor_DestroyEx() accepts a completion function argument of type
tibrvftMonitorOnComplete. Rendezvous software ensures that the completion
function runs when the last callback-in-progress has completed.

Timing and This information in completely analogous to tibrvEventOnComplete on page 134.

Context See that section for important details.

TIBCO Rendezvous C Reference

262
| Chapter 10 Fault Tolerance

See Also tibrvftMonitor_Create() on page 263

tibrvftMonitor_Destroy() on page 265

TIBCO Rendezvous C Reference

 tibrvftMonitor_Create() 263
|

tibrvftMonitor_Create()
Function

Declaration tibrv_status tibrvftMonitor_Create(

tibrvftMonitor* monitor,
tibrvQueue queue,
tibrvftMonitorCallback callback,
tibrvTransport transport,
const char* groupName,
tibrv_f64 lostInterval,
void* closure);

Purpose Monitor a fault tolerance group.

Remarks 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 function receives the number of active members as an
argument.
The group need not have any members at the time of this function call.

(Sheet 1 of 2)

Parameter Description
monitor This monitor object denotes a passive monitor of a fault
tolerance group.
The program supplies a location, and the function stores the
new monitor object in that location.
The monitor object remains valid until the program
explicitly destroys it.

queue Place events for this monitor on this event queue.

callback On dispatch, process the event with this callback function.

transport Listen on this transport for fault tolerance internal protocol

messages (such as heartbeat messages).

TIBCO Rendezvous C Reference

264
| Chapter 10 Fault Tolerance

(Sheet 2 of 2)

Parameter Description
groupName Monitor the fault tolerant group with this name.
The group name must conform to the syntax required for
Rendezvous subject names. For details, see Subject Names
on page 61 in TIBCO Rendezvous Concepts.
See also, Group Name on page 264.

lostInterval When the heartbeat signal from an active member has been
silent for this interval (in seconds), Rendezvous fault
tolerance software considers that member lost, and queues a
monitor event.
The interval must be positive. To determine the correct
value, see Step 4: Choose the Intervals on page 237 in TIBCO
Rendezvous Concepts.
See also, Lost Interval on page 264.

closure Store this closure data on 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 tibrvftMonitorCallback on page 260

tibrvftMonitor_Destroy() on page 265

TIBCO Rendezvous C Reference

 tibrvftMonitor_Destroy() 265
|

tibrvftMonitor_Destroy()
Function

Declaration tibrv_status tibrvftMonitor_Destroy(

tibrvftMonitor monitor);

tibrv_status tibrvftMonitor_DestroyEx(
tibrvftMonitor monitor,
tibrvftMonitorOnComplete completionFunction);

Purpose Stop monitoring a fault tolerance group, and free associated resources.

Parameter Description
monitor Destroy this monitor object.

completionFunction Rendezvous software runs this function

immediately after all instances of the monitor’s
callback function (and internal callback functions)
have completed. If callback functions are not
running when the monitor is destroyed, the destroy
call runs it before returning.
If this parameter is NULL,
tibrvftMonitor_DestroyEx() does not run a
completion function; instead, its behavior is the
same as tibrvftMonitor_Destroy().
See tibrvftMonitorOnComplete on page 261.

Extended Although tibrvftMonitor_DestroyEx() prevents future dispatch calls from

Function running the destroyed monitor’s callback function, a callback function might be
already running in one or more threads that dispatch events from the same queue.
In each thread where the callback function is already in progress, that callback
function does continue to run until complete. Rendezvous software ensures that
the completion function runs when the last callback-in-progress has completed;
for important details, see tibrvftMonitorOnComplete on page 261.

TIBCO Rendezvous C Reference

266
| Chapter 10 Fault Tolerance

tibrvftMonitor_GetGroupName()
Function

Declaration tibrv_status tibrvftMonitor_GetGroupName(

tibrvftMonitor monitor,
const char** groupName);

Purpose Extract the group name of a fault tolerance monitor.

Parameter Description
monitor Extract the group name from this monitor object.

groupName The program supplies a location, and the function stores the
group name in that location.

TIBCO Rendezvous C Reference

 tibrvftMonitor_GetQueue() 267
|

tibrvftMonitor_GetQueue()
Function

Declaration tibrv_status tibrvftMonitor_GetQueue(

tibrvftMonitor monitor,
tibrvQueue* queue);

Purpose Extract the event queue of a fault tolerance monitor.

Parameter Description
monitor Extract the event queue from this monitor object.

queue The program supplies a location, and the function stores the
queue in that location.

TIBCO Rendezvous C Reference

268
| Chapter 10 Fault Tolerance

tibrvftMonitor_GetTransport()
Function

Declaration tibrv_status tibrvftMonitor_GetTransport(

tibrvftMonitor monitor,
tibrvTransport* transport);

Purpose Extract the transport of a fault tolerance monitor.

Parameter Description
monitor Extract the transport from this monitor object.

transport The program supplies a location, and the function stores the
transport in that location.

TIBCO Rendezvous C Reference

 | 269

Chapter 11 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
page 403 in TIBCO Rendezvous Administration.
Some programs require certified delivery to one of n listeners. See Distributed
Queue on page 183 in TIBCO Rendezvous Concepts.

Topics

• Operations by Functional Group, page 270

• Operations in Alphabetical Order, page 275

TIBCO Rendezvous C Reference

270
| Chapter 11 Certified Message Delivery

Operations by Functional Group

(Sheet 1 of 5)

Function Description Page

Listening for Messages

tibrvcmEvent_CreateListener() Listen for messages that match 284

the subject, and request certified
delivery when available.

tibrvcmEventCallback Programs define functions of this 281

type to process inbound certified
or labeled messages.

tibrvcmEvent_Destroy() Destroy a certified delivery 286

listener.

Sending Messages

tibrvcmTransport_Send() Send a labeled message. 319

tibrvcmTransport_SendReply() Send a labeled reply message. 320

tibrvcmTransport_SendRequest() Send a labeled request message 321

and wait for a reply.

Confirmation of Certified Messages

tibrvcmEvent_SetExplicitConfirm() Override automatic confirmation 291

of delivery for this listener.

tibrvcmEvent_ConfirmMsg() Explicitly confirm delivery of a 283

certified message.

Registration

tibrvcmTransport_AddListener() Pre-register an anticipated 294

listener.

tibrvcmTransport_AllowListener() Invite the named receiver to 295

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

TIBCO Rendezvous C Reference

 Operations by Functional Group 271
|

(Sheet 2 of 5)

Function Description Page

tibrvcmTransport_DisallowListener() Cancel certified delivery to all 303
listeners at a specific
correspondent. Deny subsequent
certified delivery registration
requests from those listeners.

tibrvcmTransport_RemoveListener() Unregister a specific listener at a 313

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

Relay Agents

tibrvcmTransport_ConnectToRelayAgent() Connect a certified delivery 296

transport to its designated relay
agent.

tibrvcmTransport_DisconnectFromRelayAgent() Disconnect a certified delivery 304

transport from its relay agent.

Ledger

tibrvcmTransport_RemoveSendState() Reclaim ledger space from 315

obsolete subjects.

tibrvcmTransport_ReviewLedger() Query the ledger for stored items 316

related to a subject name.

tibrvcmReviewCallback Programs define functions of this 317

type to process ledger review
summary messages.

tibrvcmTransport_SyncLedger() Synchronize the ledger to it its 325

storage medium.

Listener Attributes

tibrvcmEvent_GetListenerSubject() Extract the subject from a certified 288

delivery listener event object.

tibrvcmEvent_GetListenerTransport() Extract the certified delivery 289

transport from a certified delivery
listener event object.

TIBCO Rendezvous C Reference

272
| Chapter 11 Certified Message Delivery

(Sheet 3 of 5)

Function Description Page

tibrvcmEvent_GetQueue() Extract the queue of a certified 290
delivery listener object.

tibrvcmEvent_SetExplicitConfirm() Override automatic confirmation 291

of delivery for this listener.

Transport Life Cycles

tibrvcmTransport_Create() Create a transport for certified 298

delivery.

tibrvcmTransport_Destroy() Destroy a certified delivery 302

transport.

tibrvcmTransportOnComplete Destroying a CM or CMQ 293

transport involves cleanup
operations that can sometimes be
lengthy. Programs can define
functions of this type to discover
when the cleanup has completed.

Transport Attributes

tibrvcmTransport_GetLedgerName() Extract the ledger name of a 307

certified delivery transport.

tibrvcmTransport_GetName() Extract the correspondent name 308

of a certified delivery transport.

tibrvcmTransport_GetRelayAgent() Extract the name of the relay 309

agent used by a certified delivery
transport.

tibrvcmTransport_GetRequestOld() Extract the request old messages 310

flag of a certified delivery
transport.

tibrvcmTransport_GetSyncLedger() Extract the sync ledger flag of a 311

certified delivery transport.

tibrvcmTransport_GetTransport() Extract the transport employed by 312

a certified delivery transport.

TIBCO Rendezvous C Reference

 Operations by Functional Group 273
|

(Sheet 4 of 5)

Function Description Page

tibrvcmTransport_SetDefaultCMTimeLimit() Set the default message time limit 323
for all outbound certified
messages from a transport.

Message Attributes

tibrvMsg_GetCMSender() Extract the correspondent name 326

of the sender from a certified
message.

tibrvMsg_GetCMSequence() Extract the sequence number 327

from a certified message.

tibrvMsg_GetCMTimeLimit() Extract the message time limit 329

from a certified message.

tibrvMsg_SetCMTimeLimit() Set the message time limit of a 330

certified message.

tibrvcmTransport_SetPublisherInactivityDisca Set a time limit after which a 324

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

Types Related to Certified Delivery

tibrvcmEvent A certified delivery event object 280

listens for labeled messages and
certified messages.

tibrvcmTransport A certified delivery transport 292

object implements the CM
delivery protocol for messages.

tibrvcmEventCallback Programs define functions of this 281

type to process inbound certified
or labeled messages.

tibrvcmReviewCallback Programs define functions of this 317

type to process ledger review
summary messages.

TIBCO Rendezvous C Reference

274
| Chapter 11 Certified Message Delivery

(Sheet 5 of 5)

Function Description Page

Library Version

tibrvcm_Version() Identify the CM API release 279

number.

TIBCO Rendezvous C Reference

 Operations in Alphabetical Order 275
|

Operations in Alphabetical Order

(Sheet 1 of 4)

Function Description Page

tibrvcm_Version() Identify the CM API release 279
number.

Events (Certified Delivery Listeners)

tibrvcmEvent A certified delivery event object 280

listens for labeled messages and
certified messages.

tibrvcmEventCallback Programs define functions of this 281

type to process inbound certified
or labeled messages.

tibrvcmEvent_ConfirmMsg() Explicitly confirm delivery of a 283

certified message.

tibrvcmEvent_CreateListener() Listen for messages that match 284

the subject, and request certified
delivery when available.

tibrvcmEvent_Destroy() Destroy a certified delivery 286

listener.

tibrvcmEvent_GetListenerSubject() Extract the subject from a certified 288

delivery listener event object.

tibrvcmEvent_GetListenerTransport() Extract the certified delivery 289

transport from a certified delivery
listener event object.

tibrvcmEvent_GetQueue() Extract the queue of a certified 290

delivery listener object.

tibrvcmEvent_SetExplicitConfirm() Override automatic confirmation 291

of delivery for this listener.

TIBCO Rendezvous C Reference

276
| Chapter 11 Certified Message Delivery

(Sheet 2 of 4)

Function Description Page

Certified Delivery Transports

tibrvcmTransport A certified delivery transport 292

object implements the CM
delivery protocol for messages.

tibrvcmTransportOnComplete Destroying a CM or CMQ 293

transport involves cleanup
operations that can sometimes be
lengthy. Programs can define
functions of this type to discover
when the cleanup has completed.

tibrvcmTransport_AddListener() Pre-register an anticipated 294

listener.

tibrvcmTransport_AllowListener() Invite the named receiver to 295

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

tibrvcmTransport_ConnectToRelayAgent() Connect a certified delivery 296

transport to its designated relay
agent.

tibrvcmTransport_Create() Create a transport for certified 298

delivery.

tibrvcmTransport_Destroy() Destroy a certified delivery 302

transport.

tibrvcmTransport_DisallowListener() Cancel certified delivery to all 303

listeners at a specific
correspondent. Deny subsequent
certified delivery registration
requests from those listeners.

tibrvcmTransport_DisconnectFromRelayAgent() Disconnect a certified delivery 304

transport from its relay agent.

tibrvcmTransport_ExpireMessages() Mark specified outbound CM 305

messages as expired.

TIBCO Rendezvous C Reference

 Operations in Alphabetical Order 277
|

(Sheet 3 of 4)

Function Description Page

tibrvcmTransport_GetLedgerName() Extract the ledger name of a 307
certified delivery transport.

tibrvcmTransport_GetName() Extract the correspondent name 308

of a certified delivery transport.

tibrvcmTransport_GetRelayAgent() Extract the name of the relay 309

agent used by a certified delivery
transport.

tibrvcmTransport_GetRequestOld() Extract the request old messages 310

flag of a certified delivery
transport.

tibrvcmTransport_GetSyncLedger() Extract the sync ledger flag of a 311

certified delivery transport.

tibrvcmTransport_GetTransport() Extract the transport employed 312

by a certified delivery transport.

tibrvcmTransport_RemoveSendState() Reclaim ledger space from 315

obsolete subjects.

tibrvcmTransport_ReviewLedger() Query the ledger for stored items 316

related to a subject name.

tibrvcmReviewCallback Programs define functions of this 317

type to process ledger review
summary messages.

tibrvcmTransport_Send() Send a labeled message. 319

tibrvcmTransport_SendReply() Send a labeled reply message. 320

tibrvcmTransport_SendRequest() Send a labeled request message 321

and wait for a reply.

tibrvcmTransport_SetDefaultCMTimeLimit() Set the default message time limit 323

for all outbound certified
messages from a transport.

TIBCO Rendezvous C Reference

278
| Chapter 11 Certified Message Delivery

(Sheet 4 of 4)

Function Description Page

tibrvcmTransport_SetPublisherInactivityDisca Set a time limit after which a 324
rdInterval() listening CM transport can
discard state for inactive CM
senders.

tibrvcmTransport_SyncLedger() Synchronize the ledger to it its 325

storage medium.

Certified Messages

tibrvMsg_GetCMSender() Extract the correspondent name 326

of the sender from a certified
message.

tibrvMsg_GetCMSequence() Extract the sequence number 327

from a certified message.

tibrvMsg_GetCMTimeLimit() Extract the message time limit 329

from a certified message.

tibrvMsg_SetCMTimeLimit() Set the message time limit of a 330

certified message.

TIBCO Rendezvous C Reference

 tibrvcm_Version() 279
|

tibrvcm_Version()
Function

Declaration const char* tibrvcm_Version(void);

Purpose Identify the CM API release number.

TIBCO Rendezvous C Reference

280
| Chapter 11 Certified Message Delivery

tibrvcmEvent
Type

Declaration typedef tibrvId tibrvcmEvent;

Purpose A certified delivery event object listens for labeled messages and certified
messages.

Remarks Each call to the event creation function tibrvcmEvent_CreateListener()

results in a new certified delivery event object, which represents your program’s
listening interest in a stream of labeled messages and certified messages.
Rendezvous software uses the same event object to signal each occurrence of such
an event.
Programs use the event object as a token; they cannot view or modify the object,
except using accessor functions.
Programs must explicitly destroy each certified delivery event object using
tibrvcmEvent_Destroy(). Destroying 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.

See Also tibrvcmEvent_CreateListener() on page 284

tibrvcmEvent_Destroy() on page 286
tibrvcmEvent_GetListenerSubject() on page 288
tibrvcmEvent_GetListenerTransport() on page 289
tibrvcmEvent_GetQueue() on page 290
tibrvcmEvent_SetExplicitConfirm() on page 291
tibrvcmEvent_ConfirmMsg() on page 283

TIBCO Rendezvous C Reference

 tibrvcmEventCallback 281
|

tibrvcmEventCallback
Function Type

Declaration typedef void (*tibrvcmEventCallback) (

tibrvcmEvent cmListener,
tibrvMsg message,
void* closure);

Purpose Programs define functions of this type to process inbound certified or labeled
messages.

Remarks This callback function must also be able to process uncertified and unlabeled
messages.

Parameter Description
cmListener This parameter receives the listener object. This object is
identical to the certified listener object that the program
created to begin listening.

message The callback receives the inbound message in this parameter.

If the inbound message is empty, this parameter receives a
message that has no fields.

closure This parameter receives the closure data, which the program
supplied in the call that created the event object.

CM Label CM callback functions can use CM label information to discriminate these

Information situations:
• If tibrvMsg_GetCMSender() returns status code TIBRV_NOT_FOUND, then the
message uses the reliable protocol (that is, it was sent from an ordinary
transport).
• If tibrvMsg_GetCMSender() returns TIBRV_OK, then the message uses the
certified delivery protocol (that is, it is a labeled message, sent from a CM
transport).
Once the CM callback function determines that the message uses the certified
delivery protocol, it can discriminate further:
— If tibrvMsg_GetCMSequence() returns status code TIBRV_NOT_FOUND,
then the listener is not registered for certified delivery from the sender.
— If tibrvMsg_GetCMSequence() returns TIBRV_OK, then a certified delivery
agreement is in effect for this subject with the sender.

TIBCO Rendezvous C Reference

282
| Chapter 11 Certified Message Delivery

See Also tibrvcmEvent_CreateListener() on page 284

tibrvMsg_GetCMSender() on page 326
tibrvMsg_GetCMSequence() on page 327
tibrvMsg_GetCMTimeLimit() on page 329

TIBCO Rendezvous C Reference

 tibrvcmEvent_ConfirmMsg() 283
|

tibrvcmEvent_ConfirmMsg()
Function

Declaration tibrv_status tibrvcmEvent_ConfirmMsg(

tibrvcmEvent cmListener,
tibrvMsg message);

Purpose Explicitly confirm delivery of a certified message.

Remarks Use this function only in programs that override automatic confirmation (see
tibrvcmEvent_SetExplicitConfirm() on page 291). The default behavior of
certified listeners is to automatically confirm delivery when the callback function
returns.

Parameter Description
cmListener Confirm receipt by this listener.

message Confirm receipt of this message.

Unregistered When a CM listener receives a labeled message, its behavior depends on context:
Message
• If a CM listener is registered for certified delivery, it presents the
supplementary information to the callback function. 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 function, but omits the sequence
number. In this case, the receiving program cannot confirm delivery;
tibrvcmEvent_ConfirmMsg() returns the status code
TIBRV_NOT_PERMITTED.

Notice that the first labeled message that a program receives on a subject
might not be certified; that is, the sender has not registered a certified delivery
agreement with the listener. If appropriate, the certified delivery library
automatically requests that the sender register the listener for certified
delivery. (See Discovery and Registration for Certified Delivery on page 154 in
TIBCO Rendezvous Concepts.)
A labeled but uncertified message can also result when the sender explicitly
disallows or removes the listener.

See Also tibrvcmEvent on page 280

tibrvcmEvent_SetExplicitConfirm() on page 291

TIBCO Rendezvous C Reference

284
| Chapter 11 Certified Message Delivery

tibrvcmEvent_CreateListener()
Function

Declaration tibrv_status tibrvcmEvent_CreateListener(

tibrvcmEvent* cmListener,
tibrvQueue queue,
tibrvcmEventCallback callback,
tibrvcmTransport cmTransport,
const char* subject,
const void* closure);

Purpose Listen for messages that match the subject, and request certified delivery when
available.

Parameter Description
cmListener For each inbound message, place this listener event on the
event queue.
The program supplies a location, and the function stores the
new listener object in that location.
The event object remains valid until the program explicitly
destroys it.

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

callback On dispatch, process the event with this callback function.

cmTransport Listen for inbound messages on this certified delivery

transport.

subject Listen for inbound messages with subjects that match this
specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.

closure Store this closure data in the event object.

Activation and Details of listener event semantics are identical to those for ordinary listeners; see
Dispatch Activation and Dispatch on page 140.

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

TIBCO Rendezvous C Reference

 tibrvcmEvent_CreateListener() 285
|
See Also tibrvcmEvent on page 280
tibrvcmTransport_Destroy() on page 302
tibrvEvent_GetListenerSubject() on page 155
tibrvTransport_CreateInbox() on page 214

TIBCO Rendezvous C Reference

286
| Chapter 11 Certified Message Delivery

tibrvcmEvent_Destroy()
Function

Declaration tibrv_status tibrvcmEvent_Destroy(

tibrvcmEvent cmListener,
tibrv_bool cancelAgreements);

tibrv_status tibrvcmEvent_DestroyEx(
tibrvcmEvent cmListener,
tibrv_bool cancelAgreements,
tibrvEventOnComplete completionFunction);

Purpose Destroy a certified delivery listener.

Parameter Description
cmListener Destroy this listener.

cancelAgreements TIBRVCM_CANCEL cancels all certified delivery

agreements of this listener; certified senders delete
from their ledgers all messages sent to this listener.
TIBRVCM_PERSIST leaves all certified delivery
agreements in effect, so certified senders continue to
store messages.

completionFunction Rendezvous software runs this function immediately

after all instances of the event’s callback function
have completed. If the event’s callback function is not
running when the event is destroyed, the destroy call
runs it before returning.
If this parameter is NULL,
tibrvcmEvent_DestroyEx() does not run a
completion function; instead, its behavior is the same
as tibrvcmEvent_Destroy().
See tibrvEventOnComplete on page 134.

Remarks Destroying event interest invalidates the event object; passing the event object as
an argument to subsequent API calls produces an error.

Canceling When destroying a listener, a program can either cancel its certified delivery
Agreements agreements with senders, or let those agreements persist (so a successor listener
can receive the messages covered by those agreements).

TIBCO Rendezvous C Reference

 tibrvcmEvent_Destroy() 287
|

When canceling agreements, each (previously) certified sender transport receives

a REGISTRATION.CLOSED advisory. Successor listeners cannot receive old
messages.

Extended Although tibrvcmEvent_Destroy() and tibrvcmEvent_DestroyEx() prevent

Function future dispatch calls from running the destroyed event’s callback function, that
callback function might be already running in one or more threads that dispatch
events from the same queue. In each thread where the callback function is already
in progress, that callback function does continue to run until complete.
tibrvcmEvent_DestroyEx() ensures that its completionFunction runs when
the last callback-in-progress has completed; for important details, see
tibrvEventOnComplete on page 134.

See Also tibrvcmEvent on page 280

TIBCO Rendezvous C Reference

288
| Chapter 11 Certified Message Delivery

tibrvcmEvent_GetListenerSubject()
Function

Declaration tibrv_status tibrvcmEvent_GetListenerSubject(

tibrvcmEvent cmListener,
const char** subject);

Purpose Extract the subject from a certified delivery listener event object.

Parameter Description
cmListener Extract the subject from this listener.

subject The program supplies a location. The function stores the

subject of the listener event object in that location.

See Also tibrvcmEvent on page 280

TIBCO Rendezvous C Reference

 tibrvcmEvent_GetListenerTransport() 289
|

tibrvcmEvent_GetListenerTransport()
Function

Declaration tibrv_status tibrvcmEvent_GetListenerTransport(

tibrvcmEvent cmListener,
tibrvcmTransport* transport);

Purpose Extract the certified delivery transport from a certified delivery listener event
object.

Parameter Description
cmListener Extract the transport from this listener.

transport The program supplies a location. The function stores the

certified delivery transport of the listener event object in that
location.

See Also tibrvcmEvent on page 280

tibrvcmTransport on page 292

TIBCO Rendezvous C Reference

290
| Chapter 11 Certified Message Delivery

tibrvcmEvent_GetQueue()
Function

Declaration tibrv_status tibrvcmEvent_GetQueue(

tibrvcmEvent cmListener,
tibrvQueue* queue);

Purpose Extract the queue of a certified delivery listener object.

Parameter Description
cmListener Extract the event queue from this event object.

queue The program supplies a location. The function stores the event
object’s queue in that location.

See Also tibrvcmEvent on page 280

tibrvQueue on page 168

TIBCO Rendezvous C Reference

 tibrvcmEvent_SetExplicitConfirm() 291
|

tibrvcmEvent_SetExplicitConfirm()
Function

Declaration tibrv_status tibrvcmEvent_SetExplicitConfirm(

tibrvcmEvent cmListener)

Purpose Override automatic confirmation of delivery for this listener.

Remarks The default behavior of certified listeners is to automatically confirm delivery

when the callback function returns (see tibrvcmEventCallback on page 281). 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
tibrvcmEvent_ConfirmMsg().

Consider overriding automatic confirmation when the processing of inbound

messages involves activity that is asynchronous with respect to the message
callback method; for example, computations in other threads or additional
network communications.
No method exists to restore the default behavior, reversing the effect of this
function.

Parameter Description
cmListener Override automatic confirmation for this listener.

See Also tibrvcmEvent on page 280

tibrvcmEventCallback on page 281
tibrvcmEvent_ConfirmMsg() on page 283

TIBCO Rendezvous C Reference

292
| Chapter 11 Certified Message Delivery

tibrvcmTransport
Type

Declaration typedef tibrvId tibrvcmTransport;

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 the 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, invalidates any certified listeners using that transport
(while preserving the certified delivery agreements of those listeners), and frees
the transport’s storage.

See Also tibrvcmTransport_Create() on page 298

tibrvcmTransport_Destroy() on page 302
tibrvcmTransport_Send() on page 319

TIBCO Rendezvous C Reference

 tibrvcmTransportOnComplete 293
|

tibrvcmTransportOnComplete
Function Type

Declaration typedef void (*tibrvcmTransportOnComplete) (

tibrvcmTransport destroyedTransport,
void* closure);

Purpose Destroying a CM or CMQ transport involves cleanup operations that can

sometimes be lengthy. Programs can define functions of this type to discover
when the cleanup has completed.

Remarks After calling the extended destroy function, programs must not destroy the
transport’s listeners, nor any queue nor dispatcher that pertains to the transport,
until after this callback signals that cleanup has completed.

Parameter Description
destroyedTransport This parameter receives the transport object.
However, by the time this function runs, the transport is already
destroyed; this function cannot use the transport object in Rendezvous
calls.

closure This parameter receives the closure data, which the program supplied to
tibrvcmTransport_DestroyEx().

See Also tibrvcmTransport_Destroy() on page 302

TIBCO Rendezvous C Reference

294
| Chapter 11 Certified Message Delivery

tibrvcmTransport_AddListener()
Function

Declaration tibrv_status tibrvcmTransport_AddListener(

tibrvcmTransport cmTransport,
const char* cmName,
const char* subject);

Purpose Pre-register an anticipated listener.

Remarks Some sending programs can anticipate requests for certified delivery—even
before the listening programs actually register. In such situations, the sender can
pre-register listeners, so Rendezvous software begins storing outbound messages
in the sender’s ledger; when the listener requests certified delivery, it receives the
backlogged messages.
If the correspondent with this cmName already receives certified delivery of this
subject from this sender transport, then tibrvcmTransport_AddListener()
has no effect.
If the correspondent with this cmName is disallowed,
tibrvcmTransport_AddListener() returns the status code
TIBRV_NOT_PERMITTED. You can call tibrvcmTransport_AllowListener() to
supersede the effect of a prior call to tibrvcmTransport_DisallowListener();
then call tibrvcmTransport_AddListener() again.
It is not sufficient for a sender to use this function to anticipate listeners; the
anticipated listening programs must also require old messages when creating
certified delivery transports.

Parameter Description
cmTransport Instruct this transport to pre-register the named listeners.

cmName Anticipate a listener from a correspondent with this reusable

name.

subject Anticipate a listener for this subject. Wildcard subjects are

illegal.

See Also Name, page 300

tibrvcmTransport_AllowListener() on page 295
tibrvcmTransport_DisallowListener() on page 303
tibrvcmTransport_RemoveListener() on page 313
Anticipating a Listener, page 161 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvcmTransport_AllowListener() 295
|

tibrvcmTransport_AllowListener()
Function

Declaration tibrv_status tibrvcmTransport_AllowListener(

tibrvcmTransport cmTransport,
const char* cmName);

Purpose Invite the named receiver to reinstate certified delivery for its listeners,
superseding the effect of any previous disallow calls.

Remarks Upon receiving the invitation to reinstate certified delivery, Rendezvous software
at the listening program automatically sends new registration requests. The
sending program accepts these requests, restoring certified delivery.

Parameter Description
cmTransport Instruct this transport to allow the named listeners.

cmName Accept requests for certified delivery to listeners at the

transport with this correspondent name.

See Also Name, page 300

tibrvcmTransport_DisallowListener() on page 303
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

296
| Chapter 11 Certified Message Delivery

tibrvcmTransport_ConnectToRelayAgent()
Function

Declaration tibrv_status tibrvcmTransport_ConnectToRelayAgent(

tibrvcmTransport cmTransport);

Purpose Connect a certified delivery transport to its designated relay agent.

Parameter Description
cmTransport Connect this transport to its relay agent.

Remarks Programs may specify a relay agent when creating a CM transport.

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

TIBCO Rendezvous C Reference

 tibrvcmTransport_ConnectToRelayAgent() 297
|

If the transport is already connected to its relay agent, then this function returns
TIBRV_OK, and does not trigger a RELAY.CONNECTED advisory.

tibrvcmTransport_Create() automatically connects a transport to its

designated relay agent upon creation.

Errors The error code TIBRV_ARG_CONFLICT can indicate that the transport does not
have a relay agent.

See Also tibrvcmTransport_Create() on page 298

tibrvcmTransport_DisconnectFromRelayAgent() on page 304
Relay Agent, page 170 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

298
| Chapter 11 Certified Message Delivery

tibrvcmTransport_Create()
Function

Declaration tibrv_status tibrvcmTransport_Create(

tibrvcmTransport* cmTransport,
tibrvTransport transport,
const char* cmName,
tibrv_bool requestOld,
const char* ledgerName,
tibrv_bool syncLedger,
const char* relayAgent);

Purpose Create a transport for certified delivery.

Remarks The new certified delivery transport must employ a valid transport for network
communications.

(Sheet 1 of 3)

Parameter Description
cmTransport The program supplies a location, and the function stores the
new certified delivery transport in that location.
The certified delivery transport remains valid until the
program explicitly destroys it.

transport The new cmTransport employs this transport object for

network communications.
Destroying the cmTransport does not affect this
tibrvTransport.

It is illegal to supply a virtual circuit transport object for this

parameter.

TIBCO Rendezvous C Reference

 tibrvcmTransport_Create() 299
|

(Sheet 2 of 3)

Parameter Description
cmName Bind this reusable name to the new cmTransport, so the
cmTransport represents a persistent correspondent with this
name.
If non-NULL, the name must conform to the syntax rules for
Rendezvous subject names. It cannot begin with reserved
tokens. It cannot be a non-reusable name generated by another
call to tibrvcmTransport_Create(). It cannot be the empty
string.
If this argument is NULL, then tibrvcmTransport_Create()
generates a unique, non-reusable name for the duration of the
transport.
For more information, see Name on page 300.

requestOld This parameter indicates whether a persistent correspondent

requires delivery of messages sent to a previous certified
delivery transport with the same name, for which delivery
was not confirmed. Its value affects the behavior of other CM
sending transports.
If this parameter is TIBRV_TRUE and cmName is non-NULL, then
the new cmTransport requires certified senders to retain
unacknowledged messages sent to this persistent
correspondent. When the new cmTransport begins listening
to the appropriate subjects, the senders can complete delivery.
(It is an error to supply TIBRV_TRUE when cmName is NULL.)
If this parameter is TIBRV_FALSE, then the new cmTransport
does not require certified senders to retain unacknowledged
messages. Certified senders may delete those messages from
their ledgers.

ledgerName If this argument is non-NULL, then the new cmTransport 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 this argument is NULL, then the new cmTransport uses a
process-based ledger.
For more information, see Ledger File on page 300.

TIBCO Rendezvous C Reference

300
| Chapter 11 Certified Message Delivery

(Sheet 3 of 3)

Parameter Description
syncLedger If this argument is TIBRV_TRUE, then operations that update
the ledger file do not return until the changes are written to the
storage medium.
If this argument is TIBRV_FALSE, the operating system writes
changes to the storage medium asynchronously.

relayAgent Designate the rvrad process with this name as the new
transport’s relay agent.
NULL specifies that the new cmTransport 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.
We strongly discourage using the empty string as a relay agent
name.
For more information, see Relay Agent on page 300.

Name If name is NULL, then tibrvcmTransport_Create() generates a unique,

non-reusable name for the new certified delivery transport.
If name 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 296.

Ledger File Every certified delivery transport stores the state of its certified communications
in a ledger.

TIBCO Rendezvous C Reference

 tibrvcmTransport_Create() 301
|

If ledgerFile is NULL, then the new transport stores its ledger exclusively in
process-based storage. When you destroy the transport or the process terminates,
all information in the ledger is lost.
If ledgerFile specifies a valid file name, then the new transport uses that file for
ledger storage. If the transport is destroyed or the process terminates with
incomplete certified communications, the ledger file records that state. When a
new transport binds the same reusable name, it reads the ledger file and continues
certified communications from the state stored in the file.
Even though a transport uses a ledger file, it may sometimes replicate parts of the
ledger in process-based storage for efficiency; however, programmers cannot rely
on this replication.
The syncLedger parameter determines whether writing to the ledger file is a
synchronous operation:
• To specify synchronous writing, supply TIBRV_TRUE. Each time Rendezvous
software writes a ledger item, the call does not return until the data is safely
stored in the storage medium.
• To specify asynchronous writing, supply TIBRV_FALSE. CM 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 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 325.

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 302

tibrvcmTransport_ConnectToRelayAgent() on page 296

TIBCO Rendezvous C Reference

302
| Chapter 11 Certified Message Delivery

tibrvcmTransport_Destroy()
Function

Declaration tibrv_status tibrvcmTransport_Destroy(

tibrvcmTransport cmTransport);

tibrv_status tibrvcmTransport_DestroyEx(
tibrvcmTransport cmTransport,
tibrvcmTransportOnComplete completionFunction,
void* closure);

Purpose Destroy a certified delivery transport.

Parameter Description
cmTransport Destroy this transport.

completionFunction Rendezvous software runs this function immediately

after all queued tasks are complete.
Do not destroy the transport’s listeners until after this
callback signals that cleanup has completed.
See tibrvcmTransportOnComplete on page 293.

closure Pass this closure data to the completion function.

Remarks Destroying a certified delivery transport with a file-based ledger always leaves
the ledger file intact; it neither erases nor removes a ledger file.
This function automatically disconnects the transport from its relay agent before
destroying the object; see tibrvcmTransport_DisconnectFromRelayAgent().

Distributed To destroy a distributed queue transport, call tibrvcmTransport_DestroyEx().

Queue With the ordinary destroy call, the distributed queue can lose reliable
(non-certified) task messages before they are processed. The distributed queue
needs the listeners, queues and dispatchers (associated with the transport) to
remain operational—programs must wait until after the transport has been
completely destroyed before destroying these associated objects.

See Also tibrvcmTransportOnComplete on page 293

tibrvcmTransport_Create() on page 298
tibrvcmTransport_DisconnectFromRelayAgent() on page 304
tibrvcmTransport_CreateDistributedQueue() on page 334

TIBCO Rendezvous C Reference

 tibrvcmTransport_DisallowListener() 303
|

tibrvcmTransport_DisallowListener()
Function

Declaration tibrv_status tibrvcmTransport_DisallowListener(

tibrvcmTransport cmTransport,
const char* cmName);

Purpose Cancel certified delivery to all listeners at a specific correspondent. Deny

subsequent certified delivery registration requests from those listeners.

Remarks Disallowed listeners still receive subsequent messages from this sender, but
delivery is not certified. In other words:
• The first labeled message causes the listener to initiate registration.
Registration fails, and the listener discards that labeled message.
• The listener receives a REGISTRATION.NOT_CERTIFIED advisory, informing it
that the sender has canceled certified delivery of all subjects.
• If the sender’s ledger contains messages sent to the disallowed listener (for
which this listener has not confirmed delivery), then Rendezvous software
removes those ledger items, and does not attempt to redeliver those messages.
• Rendezvous software presents subsequent messages (from the canceling
sender) to the listener without a sequence number, to indicate that delivery is
not certified.

Senders can promptly revoke the acceptance of certified delivery by calling

tibrvcmTransport_DisallowListener() within the callback function that
processes the REGISTRATION.REQUEST advisory.
This function 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 295.

Parameter Description
cmTransport Instruct this transport to disallow the named listeners.

cmName Cancel certified delivery to listeners of the transport with this

name.

See Also Name, page 300

tibrvcmTransport_AllowListener() on page 295
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

304
| Chapter 11 Certified Message Delivery

tibrvcmTransport_DisconnectFromRelayAgent()
Function

Declaration tibrv_status tibrvcmTransport_DisconnectFromRelayAgent(

tibrvcmTransport cmTransport);

Purpose Disconnect a certified delivery transport from its relay agent.

Parameter Description
cmTransport Disconnect this transport from its relay agent.

Remarks Disconnect calls are non-blocking; they immediately return control to the
program, and asynchronously proceed with these clean-up tasks:
• If the client transport is a CM listener, the relay agent attempts to synchronize
its listening state with the transport (to assure that the relay agent adequately
represents the listening interest of the client).
• The transport stops communicating with the relay agent.
• The transport stores subsequent outbound events—including data messages
and protocol state changes. If the transport is a certified sender, it cancels its
request for delivery confirmation of outstanding unconfirmed messages. (See
also, Requesting Confirmation on page 157 in TIBCO Rendezvous Concepts.)
• The relay agent stores subsequent inbound events for the transport—
including data messages and protocol state changes.
• A transport that explicitly disconnects without terminating receives a
RELAY.DISCONNECTED advisory, informing it that is safe to sever the physical
network connection. (Terminating transports never receive this advisory;
instead, it is safe to sever the connection when the destroy call returns.)

tibrvcmTransport_Destroy() automatically disconnects a CM transport from

its relay agent before termination.

Errors The error code TIBRV_ARG_CONFLICT can indicate that the transport does not
have a relay agent.

See Also tibrvcmTransport_ConnectToRelayAgent() on page 296

tibrvcmTransport_Destroy() on page 302
Relay Agent, page 170 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvcmTransport_ExpireMessages() 305
|

tibrvcmTransport_ExpireMessages()
Function

Declaration tibrv_status tibrvcmTransport_ExpireMessages(

tibrvcmTransport cmTransport,
const char* subject,
tibrv_u64 sequenceNumber);

Purpose Mark specified outbound CM messages as expired.

Remarks This call checks the ledger for messages that match both the subject and sequence
number criteria, and immediately marks them as expired.
Once a message has expired, the CM transport no longer attempts to redeliver it
to registered listeners.
Rendezvous software presents each expired message to the sender in a
DELIVERY.FAILED advisory. Each advisory includes all the fields of an expired
message. (This call can cause many messages to expire simultaneously.)

Use with extreme caution. This call exempts the expired messages from certified
delivery semantics. It is appropriate only in very few situations.
For example, consider an application program in which an improperly formed
CM message causes registered listeners to exit unexpectedly. When the listeners
restart, the sender attempts to redeliver the offending message, which again
causes the listeners to exit. To break this cycle, the sender can expire the offending
message (along with all prior messages bearing the same subject).

Parameter Description
cmTransport Mark messages as expired in the ledger for this CM
transport.

subject Mark messages with this subject.

Wildcards subjects are permitted, but must exactly reflect
the send subject of the message. For example, if the
program sends to A.* then you may expire messages with
subject A.* (however, A.> does not resolve to match A.*).

sequenceNumber Mark messages with sequence numbers less than or equal

to this value.

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

TIBCO Rendezvous C Reference

306
| Chapter 11 Certified Message Delivery

tibrvcmTransport_GetDefaultCMTimeLimit()
Function

Declaration tibrv_status tibrvcmTransport_GetDefaultCMTimeLimit(

tibrvcmTransport cmTransport,
tibrv_f64* timeLimit);

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_SetCMTimeLimit() on page 330). 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 function); if this default is not set for the transport (nor for
the message), the default time limit is zero (no time limit).
Time limits represent the minimum time that certified delivery is in effect.

Parameter Description
cmTransport Set the default message time limit of this transport.

timeLimit The program supplies a location, and the function stores the
default time limit (in whole seconds) in that location.

See Also tibrvcmTransport_SetDefaultCMTimeLimit() on page 323

tibrvMsg_SetCMTimeLimit() on page 330

TIBCO Rendezvous C Reference

 tibrvcmTransport_GetLedgerName() 307
|

tibrvcmTransport_GetLedgerName()
Function

Declaration tibrv_status tibrvcmTransport_GetLedgerName(

tibrvcmTransport cmTransport,
const char** ledgerName);

Purpose Extract the ledger name of a certified delivery transport.

Parameter Description
cmTransport Extract the ledger name from this certified delivery transport
object.

ledgerName The program supplies a location, and the function stores the
ledger name in that location.

Errors The error code TIBRV_ARG_CONFLICT can indicate that the transport does not
have a ledger file.

See Also Ledger File, page 300

tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

308
| Chapter 11 Certified Message Delivery

tibrvcmTransport_GetName()
Function

Declaration tibrv_status tibrvcmTransport_GetName(

tibrvcmTransport cmTransport,
const char** cmName);

Purpose Extract the correspondent name of a certified delivery transport.

Parameter Description
cmTransport Extract the name from this certified delivery transport object.

cmName The program supplies a location, and the function stores the
correspondent name in that location.

See Also Name, page 300

tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

 tibrvcmTransport_GetRelayAgent() 309
|

tibrvcmTransport_GetRelayAgent()
Function

Declaration tibrv_status tibrvcmTransport_GetRelayAgent(

tibrvcmTransport cmTransport,
const char** relayAgent);

Purpose Extract the name of the relay agent used by a certified delivery transport.

Parameter Description
cmTransport Extract the relay agent from this certified delivery transport
object.

relayAgent The program supplies a location, and the function stores the
name of the relay agent in that location.

Errors The error code TIBRV_ARG_CONFLICT can indicate that the transport does not
have a relay agent.

See Also Relay Agent, page 300

tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

310
| Chapter 11 Certified Message Delivery

tibrvcmTransport_GetRequestOld()
Function

Declaration tibrv_status tibrvcmTransport_GetRequestOld(

tibrvcmTransport cmTransport,
tibrv_bool* requestOld);

Purpose Extract the request old messages flag of a certified delivery transport.

Parameter Description
cmTransport Extract the request old messages flag from this certified
delivery transport object.

requestOld The program supplies a location, and the function stores the
request old messages flag in that location.

See Also requestOld on page 299

tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

 tibrvcmTransport_GetSyncLedger() 311
|

tibrvcmTransport_GetSyncLedger()
Function

Declaration tibrv_status tibrvcmTransport_GetSyncLedger(

tibrvcmTransport cmTransport,
tibrv_bool* syncLedger);

Purpose Extract the sync ledger flag of a certified delivery transport.

Parameter Description
cmTransport Extract the sync ledger flag from this certified delivery
transport object.

syncLedger The program supplies a location, and the function stores the
sync ledger flag in that location.

Errors The error code TIBRV_ARG_CONFLICT can indicate that the transport does not
have a ledger file.

See Also Ledger File, page 300

tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

312
| Chapter 11 Certified Message Delivery

tibrvcmTransport_GetTransport()
Function

Declaration tibrv_status tibrvcmTransport_GetTransport(

tibrvcmTransport cmTransport,
tibrvTransport* transport);

Purpose Extract the transport employed by a certified delivery transport.

Parameter Description
cmTransport Extract the transport from this certified delivery transport
object.

transport The program supplies a location, and the function stores the
transport in that location.

See Also tibrvcmTransport_Create() on page 298

TIBCO Rendezvous C Reference

 tibrvcmTransport_RemoveListener() 313
|

tibrvcmTransport_RemoveListener()
Function

Declaration tibrv_status tibrvcmTransport_RemoveListener(

tibrvcmTransport cmTransport,
const char* cmName,
const char* subject);

Purpose Unregister a specific listener at a specific correspondent, and free associated

storage in the sender’s ledger.

Remarks This function 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 function 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 function, 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
function 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 cmTransport, then
tibrvcmTransport_RemoveListener() returns the status code
TIBRV_INVALID_SUBJECT.

Parameter Description
cmTransport Instruct this transport to unregister the specified listeners.

cmName Cancel certified delivery of the subject to listeners of this

correspondent.

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

Wildcard subjects are illegal.

TIBCO Rendezvous C Reference

314
| Chapter 11 Certified Message Delivery

See Also Name, page 300

tibrvcmTransport_AddListener() on page 294
tibrvcmTransport_DisallowListener() on page 303
Canceling Certified Delivery, page 162 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvcmTransport_RemoveSendState() 315
|

tibrvcmTransport_RemoveSendState()
Function

Declaration tibrv_status tibrvcmTransport_RemoveSendState(

tibrvcmTransport cmTransport,
const char* subject);

Purpose Reclaim ledger space from obsolete subjects.

Background In some programs subject names are useful only for a limited time; after that time,
they are never used again. For example, consider a server program that sends
certified reply messages to client inbox names; it only sends one reply message to
each inbox, and after delivery is confirmed and complete, that inbox name is
obsolete. Nonetheless, a record for that inbox name remains in the server’s ledger.
As such obsolete records accumulate, the ledger size grows. To counteract this
growth, programs can use this function 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.

Remarks

Do not use this function to clear subjects that are still in use.
As a side-effect, this function 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.

Parameter Description
cmTransport Remove send state from the ledger of this certified delivery
transport.

subject Remove send state for this obsolete subject.

See Also tibrvcmTransport_ReviewLedger() on page 316

tibrvcmTransport_Send() on page 319
DELIVERY.COMPLETE on page 296 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

316
| Chapter 11 Certified Message Delivery

tibrvcmTransport_ReviewLedger()
Function

Declaration tibrv_status tibrvcmTransport_ReviewLedger(

tibrvcmTransport cmTransport,
tibrvcmReviewCallback callback,
const char* subject,
const void* closure);

Purpose Query the ledger for stored items related to a subject name.

Remarks The callback function 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 function
separately for each matching subject—once for FOO.BAR, once for FOO.BAZ, and
once for FOO.BOX.
However, if the callback function returns non-NULL, then
tibrvcmTransport_ReviewLedger() returns immediately.

If the ledger does not contain any matching items,

tibrvcmTransport_ReviewLedger() returns normally without calling the
callback function.
For information about the content and format of the callback messages, see
tibrvcmReviewCallback on page 317.

Parameter Description
cmTransport Review the ledger of this transport.

callback This function receives the review messages.

subject Query for items related to this subject name.

If this subject contains wildcard characters ("*" or ">"), then
review all items with matching subject names. The callback
function receives a separate message for each matching subject
in the ledger.

closure Pass this closure data to the callback function.

See Also tibrvcmReviewCallback on page 317

TIBCO Rendezvous C Reference

 tibrvcmReviewCallback 317
|

tibrvcmReviewCallback
Function Type

Declaration typedef void* (*tibrvcmReviewCallback) (

tibrvcmTransport cmTransport,
const char* subject,
tibrvMsg message,
void* closure);

Purpose Programs define functions of this type to process ledger review summary
messages.

Remarks tibrvcmTransport_ReviewLedger() calls this callback function once for each

matching subject stored in the ledger.
To continue reviewing the ledger, return NULL from this callback function. To stop
reviewing the ledger, return non-NULL from this callback function;
tibrvcmTransport_ReviewLedger() cancels the review and returns
immediately.

Parameter Description
cmTransport This parameter receives the transport.

subject This parameter receives the subject for this ledger item.

message This parameter receives a summary message describing the

delivery status of messages in the ledger. The table below
describes the fields of the summary message.

closure This parameter receives closure data which the program

supplied to tibrvcmTransport_ReviewLedger().

Message Fields This callback function receives ledger summary messages with these fields.

(Sheet 1 of 2)

Field Name Description

subject The subject that this message summarizes.
This field has datatype TIBRVMSG_STRING.

seqno_last_sent The sequence number of the most recent message sent with this
subject name.
This field has datatype TIBRVMSG_U64.

TIBCO Rendezvous C Reference

318
| Chapter 11 Certified Message Delivery

(Sheet 2 of 2)

Field Name Description

total_msgs The total number of messages stored at this subject name.
This field has datatype TIBRVMSG_U32.

total_size The total storage (in bytes) occupied by all messages with this
subject name.
If the ledger contains several messages with this subject name,
then this field sums the storage space over all of them.
This field has datatype TIBRVMSG_U64.

listener Each summary message can contain one or more fields named
listener. Each listener field contains a nested submessage with
details about a single registered listener.
This field has datatype TIBRVMSG_MSG.

listener.name Within each listener submessage, the name field contains the
name of the listener transport.
This field has datatype TIBRVMSG_STRING.

listener.last_confirmed Within each listener submessage, the last_confirmed field

contains the sequence number of the last message for which the
listener confirmed delivery.
This field has datatype TIBRVMSG_U64.

See Also tibrvcmTransport_ReviewLedger() on page 316

TIBCO Rendezvous C Reference

 tibrvcmTransport_Send() 319
|

tibrvcmTransport_Send()
Function

Declaration tibrv_status tibrvcmTransport_Send(

tibrvcmTransport cmTransport,
tibrvMsg message);

Purpose Send a labeled message.

Remarks This function 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_SetCMTimeLimit() on page 330. If a time limit is not already set for the
outbound message, this function sets it to the transport’s default time limit (see
tibrvcmTransport_SetDefaultCMTimeLimit() on page 323); if that default is not
set for the transport, the default time limit is zero (no time limit).

Parameter Description
cmTransport Send a message using this certified delivery transport.

message Send this message.

Wildcard subjects are illegal.

See Also tibrvcmTransport_SendReply() on page 320

tibrvcmTransport_SendRequest() on page 321
tibrvcmTransport_SetDefaultCMTimeLimit() on page 323
tibrvMsg_SetCMTimeLimit() on page 330

TIBCO Rendezvous C Reference

320
| Chapter 11 Certified Message Delivery

tibrvcmTransport_SendReply()
Function

Declaration tibrv_status tibrvcmTransport_SendReply(

tibrvcmTransport cmTransport,
tibrvMsg replyMessage,
tibrvMsg requestMessage);

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 function can send a labeled reply to an ordinary message.
This function automatically registers the requesting CM transport, so the reply
message is certified.

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

Parameter Description
cmTransport Send a message using this certified delivery transport.

replyMessage Send this outbound reply message.

requestMessage Send a reply to this inbound request message; extract its

reply subject to use as the subject of the outbound reply
message.
If this message has a wildcard reply subject, the function
produces an error.

See Also tibrvcmTransport_Send() on page 319

tibrvcmTransport_SendRequest() on page 321

TIBCO Rendezvous C Reference

 tibrvcmTransport_SendRequest() 321
|

tibrvcmTransport_SendRequest()
Function

Declaration tibrv_status
tibrvcmTransport_SendRequest(
tibrvcmTransport cmTransport,
tibrvMsg message);
tibrvMsg* reply,
tibrv_f64 timeout);

Purpose Send a labeled request message and wait for a reply.

Blocking can Stall Event Dispatch

This call blocks all other activity on its program thread. If appropriate,
programmers must ensure that other threads continue dispatching events on its
queues.

Parameter Description
cmTransport Send a message using this certified delivery transport.

message Send this request message.

Wildcard subjects are illegal.

reply The program supplies a location, and the function stores the
inbound reply in that location.
The program need not create the reply message, nor allocate
space for it. However, the program must destroy the reply
message, even though it did not create it.

timeout Maximum time (in seconds) that this call can block while
waiting for a reply.
TIBRV_WAIT_FOREVER (-1) indicates no timeout (wait without
limit for a reply).

Remarks Programs that receive and process the request message cannot determine that the
sender has blocked until a reply arrives.
The sender and receiver must already have a certified delivery agreement,
otherwise the request is not certified.

TIBCO Rendezvous C Reference

322
| Chapter 11 Certified Message Delivery

The request message must have a valid destination subject; see

tibrvMsg_SetSendSubject() on page 113.
A certified request does not necessarily imply a certified reply; the replying
program determines the type of reply message that it sends.

Operation This function operates in several synchronous steps:

1. Create a tibrvcmEvent that listens for messages on the reply subject of
message.

2. Label and send the outbound message.

3. Block until the listener receives a reply; if the time limit expires before a reply
arrives, return the status code TIBRV_TIMEOUT. (The reply event uses a private
queue that is not accessible to the program.)
4. Store the reply in the location specified by the reply parameter.
5. Return.

See Also tibrvcmTransport_Send() on page 319

tibrvcmTransport_SendReply() on page 320

TIBCO Rendezvous C Reference

 tibrvcmTransport_SetDefaultCMTimeLimit() 323
|

tibrvcmTransport_SetDefaultCMTimeLimit()
Function

Declaration tibrv_status tibrvcmTransport_SetDefaultCMTimeLimit(

tibrvcmTransport cmTransport,
tibrv_f64 timeLimit);

Purpose Set the default message time limit for all outbound certified messages from a
transport.

Remarks Every labeled message has a time limit, after which the sender no longer certifies
delivery.
Sending programs can explicitly set the time limit on a message (see
tibrvMsg_SetCMTimeLimit() on page 330). If a time limit is not already set for the
outbound message, this function sets it to the transport’s default time limit (set
with this function); if this default is not set for the transport, the default time limit
is zero (no time limit).
Time limits represent the minimum time that certified delivery is in effect.

Parameter Description
cmTransport Set the default message time limit of this transport.

timeLimit Use this time limit (in whole seconds). The time limit must be
non-negative.

See Also tibrvcmTransport_GetDefaultCMTimeLimit() on page 306

tibrvMsg_SetCMTimeLimit() on page 330

TIBCO Rendezvous C Reference

324
| Chapter 11 Certified Message Delivery

tibrvcmTransport_SetPublisherInactivityDiscardInterval()
Function

Declaration tibrv_status
tibrvcmTransport_SetPublisherInactivityDiscardInterval(
tibrvcmTransport cmTransport,
tibrv_i32 timeout);

Purpose Set a time limit after which a listening CM transport can discard state for inactive
CM senders.

Remarks The timeout value limits the time that can elapse during which such a sender does
not send a message. When the elapsed time exceeds this limit, the listening
transport declares the sender inactive, and discards internal state corresponding
to the sender.

We discourage programmers from using this call except to solve a very specific
problem, in which a long-running CM listener program accumulates state for a
large number of obsolete CM senders with non-reusable names.
Before using this call, review every subject for which the CM transport has a
listener; ensure that only CM senders with non-reusable names send to those
subjects. (If senders with reusable names send messages to such subjects, the
listening transport can discard their state, and incorrect behavior can result.)

Parameter Description
cmTransport Set the inactivity discard interval of this transport.

timeout Use this time limit (in whole seconds). The time limit must be
non-negative.

TIBCO Rendezvous C Reference

 tibrvcmTransport_SyncLedger() 325
|

tibrvcmTransport_SyncLedger()
Function

Declaration tibrv_status tibrvcmTransport_SyncLedger(

tibrvcmTransport cmTransport);

Purpose Synchronize the ledger to it its storage medium.

Remarks When this function returns, the transport’s current state is safely stored in the
ledger file.
Transports that use synchronous ledger files need not call this function, since the
current state is automatically written to the file system before returning.
Transports that use process-based ledger storage need not call this function, since
they have no ledger file.

Parameter Description
cmTransport Synchronize the ledger file of this certified delivery transport
object.

Errors The error code TIBRV_INVALID_ARG can indicate that the transport does not have
a ledger file.

See Also Ledger File, page 300

tibrvcmTransport_Create() on page 298
tibrvcmTransport_GetSyncLedger() on page 311

TIBCO Rendezvous C Reference

326
| Chapter 11 Certified Message Delivery

tibrvMsg_GetCMSender()
Function

Declaration tibrv_status tibrvMsg_GetCMSender(

tibrvMsg message,
const char** name);

Purpose Extract the correspondent name of the sender from a certified message.

Parameter Description
message Extract the sender name from this message.

name The program supplies a location. The function stores the name in
that location.

Status This function returns a status code that discriminates between labeled messages
and other messages.
• If the message is from a CM sender, then tibrvMsg_GetCMSender() returns
the status code TIBRV_OK and yields a valid CM correspondent name.
• If the message is not from a CM sender, then tibrvMsg_GetCMSender()
returns the status code TIBRV_NOT_FOUND.

See Also tibrvcmTransport_Create() on page 298

tibrvcmTransport_GetName() on page 308

TIBCO Rendezvous C Reference

 tibrvMsg_GetCMSequence() 327
|

tibrvMsg_GetCMSequence()
Function

Declaration tibrv_status tibrvMsg_GetCMSequence(

tibrvMsg message,
tibrv_u64* sequenceNumber);

Purpose Extract the sequence number from a certified message.

Remarks Rendezvous certified delivery sending functions automatically generate positive

sequence numbers for outbound labeled messages.

Parameter Description
message Extract the sequence number from this message.

sequenceNumber The program supplies a location. The function stores the

sequence number in that location.

Status This function returns a status code that discriminates between certified messages
(with a certified delivery agreement) and other messages.
• If the message is from a CM sender, and the CM listener is registered for
certified delivery with that sender, then tibrvMsg_GetCMSequence() returns
the status code TIBRV_OK and yields a valid sequence number.
• If the message is from a CM sender, but the listener is not registered for
certified delivery, then tibrvMsg_GetCMSequence() in the context of a
tibrvcmEventCallback function returns the status code TIBRV_NOT_FOUND.
(In any other context, it returns the actual sequence number stored on the
message.)
Notice that the first labeled message that a program receives on a subject
might not be certified; that is, the sender has not registered a certified delivery
agreement with the listener. If appropriate, the certified delivery library
automatically requests that the sender register the listener for certified
delivery. (See Discovery and Registration for Certified Delivery on page 154 in
TIBCO Rendezvous Concepts.)
A labeled but uncertified message can also result when the sender explicitly
disallows or removes the listener.
• If the message is not from a CM sender, then tibrvMsg_GetCMSequence() (in
any context) returns the status code TIBRV_NOT_FOUND.

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.

TIBCO Rendezvous C Reference

328
| Chapter 11 Certified Message Delivery

When 32-bit senders overflow the sequence number, behavior is undefined.

When 64-bit senders send sequence numbers greater than 32 bits, 32-bit receivers
detect malformed label information, and process the message as an ordinary
reliable message (uncertified and unlabeled).

See Also tibrvcmTransport_Send() on page 319

TIBCO Rendezvous C Reference

 tibrvMsg_GetCMTimeLimit() 329
|

tibrvMsg_GetCMTimeLimit()
Function

Declaration tibrv_status tibrvMsg_GetCMTimeLimit(

tibrvMsg message,
tibrv_f64* timeLimit);

Purpose Extract the message time limit from a certified message.

Remarks Programs can explicitly set the message time limit (see
tibrvMsg_SetCMTimeLimit() on page 330).
Zero is a special value, indicating no time limit.
If a time limit is not set for a message, this function returns the status code
TIBRV_NOT_FOUND. This situation can occur only for unsent outbound messages,
and for inbound unlabeled messages.
Time limits represent the minimum time that certified delivery is in effect.
This value represents the total time limit of the message, not the time remaining.

Parameter Description
message Extract the time limit from this message.

timeLimit The program supplies a location. The function stores the time
limit in that location.

See Also tibrvcmTransport_Send() on page 319

tibrvMsg_SetCMTimeLimit() on page 330

TIBCO Rendezvous C Reference

330
| Chapter 11 Certified Message Delivery

tibrvMsg_SetCMTimeLimit()
Function

Declaration tibrv_status tibrvMsg_SetCMTimeLimit(

tibrvMsg message,
tibrv_f64 timeLimit);

Purpose Set the message time limit of a certified message.

Remarks Every labeled message has a time limit, after which the sender no longer certifies
delivery.
Sending programs can explicitly set the message time limit using this function. If
a time limit is not already set for the outbound message,
tibrvcmTransport_Send() sets it to the transport’s default time limit (see
tibrvcmTransport_SetDefaultCMTimeLimit() on page 323); if that default is not
set for the transport, the default time limit is zero (no time limit).
Time limits represent the minimum time that certified delivery is in effect.
It is meaningless for receiving programs to call this function.

Parameter Description
message Set the time limit of this message.

timeLimit Use this time limit (in whole seconds) for the message. The
time limit must be non-negative.

See Also tibrvcmTransport_GetDefaultCMTimeLimit() on page 306

tibrvcmTransport_SetDefaultCMTimeLimit() on page 323
tibrvMsg_GetCMTimeLimit() on page 329

TIBCO Rendezvous C Reference

 | 331

Chapter 12 Distributed Queues

Programs can use distributed queues for one of n certified delivery to a group of
worker processes.

Topics

• Operations in Alphabetical Order, page 332

• Distributed Queue Overview, page 333

TIBCO Rendezvous C Reference

332
| Chapter 12 Distributed Queues

Operations in Alphabetical Order

Function Description Page

tibrvcmTransport_CreateDistributedQueue() Create a distributed queue 334
member.

tibrvcmTransport_GetCompleteTime() Extract the worker complete time 339

limit of a distributed queue
transport.

tibrvcmTransport_GetUnassignedMessageCount() Extract the number of unassigned 340

task messages from a distributed
queue transport.

tibrvcmTransport_GetWorkerWeight() Extract the worker weight of a 341

distributed queue transport.

tibrvcmTransport_GetWorkerTasks() Extract the worker task capacity 342

of a distributed queue transport.

tibrvcmTransport_SetCompleteTime() Set the worker complete time 343

limit of a distributed queue
transport.

tibrvcmTransport_SetTaskBacklogLimit...() Set the scheduler task queue 344

limits of a distributed queue
transport.

tibrvcmTransport_SetWorkerWeight() Set the worker weight of a 345

distributed queue transport.

tibrvcmTransport_SetWorkerTasks() Set the worker task capacity of a 346

distributed queue transport.

TIBCO Rendezvous C Reference

 Distributed Queue Overview 333
|

Distributed Queue Overview

A distributed queue is a group of cooperating transport objects, each in a separate

process. From the outside, a distributed queue appears as though a single
transport object; inside, the group members act in concert to process inbound task
messages. Ordinary transports and CM transports can send task messages to the
group; notice that the senders are not group members, and do not do anything
special to send messages to a group; rather, they send messages to ordinary
subject names. Inside the group, the member acting as scheduler assigns each task
message to exactly one of the other members (which act as workers); only that
worker processes the task message. Each member uses CM listener objects to
receive task messages.
Distributed queues depend upon the certified delivery methods and the fault
tolerance methods.

We do not recommend sending messages across network boundaries to a

distributed queue, nor distributing queue members across network boundaries.
However, when crossing network boundaries in either of these ways, you must
configure the Rendezvous routing daemons to exchange _RVCM and _RVCMQ
administrative messages. For details, see Distributed Queues on page 411 in
TIBCO Rendezvous Administration.

See Also Distributed Queue, page 183 in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

334
| Chapter 12 Distributed Queues

tibrvcmTransport_CreateDistributedQueue()
Function

Declaration tibrv_status tibrvcmTransport_CreateDistributedQueue(

tibrvcmTransport* cmTransport,
tibrvTransport transport,
const char* cmName);

tibrv_status tibrvcmTransport_CreateDistributedQueueEx(
tibrvcmTransport* cmTransport,
tibrvTransport transport,
const char* cmName,
tibrv_u32 workerWeight,
tibrv_u32 workerTasks,
tibrv_u16 schedulerWeight,
tibrv_f64 schedulerHeartbeat,
tibrv_f64 schedulerActivation);

Purpose Create a distributed queue member.

Remarks The new distributed queue transport must employ a valid transport for network
communications.
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.
To destroy a distributed queue transport, call tibrvcmTransport_Destroy().

(Sheet 1 of 4)

Parameter Description
cmTransport The program supplies a location, and the function stores the new
distributed queue transport in that location.
The distributed queue transport remains valid until the program
explicitly destroys it.

transport The new distributed cmTransport employs this transport object for
network communications.
Destroying the distributed cmTransport does not affect this transport.
The program must explicitly call tibrvTransport_Destroy() to
destroy this tibrvTransport when it is no longer needed.

TIBCO Rendezvous C Reference

 tibrvcmTransport_CreateDistributedQueue() 335
|

(Sheet 2 of 4)

Parameter Description
cmName Bind this reusable name to the new distributed cmTransport, so the
distributed queue transport 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

Rendezvous Concepts.

workerWeight When the scheduler receives a task, it assigns the task to the available
worker with the greatest worker weight.
A worker is considered available unless either of these conditions are
true:
• The pending tasks assigned to the worker member exceed its task
capacity.
• The worker is also the scheduler. (The scheduler assigns tasks to its
own worker role only when no other workers are available.)
Programs can set this parameter using the extended function. The brief
form supplies the default value, TIBRVCM_DEFAULT_WORKER_WEIGHT (1).

TIBCO Rendezvous C Reference

336
| Chapter 12 Distributed Queues

(Sheet 3 of 4)

Parameter Description
workerTasks Task capacity is the maximum number of tasks that a worker can accept.
When the number of accepted tasks reaches this maximum, the worker
cannot accept additional tasks until it completes one or more of them.
When the scheduler receives a task, it assigns the task to the worker with
the greatest worker weight—unless the pending tasks assigned to that
worker exceed its task capacity. When the preferred worker has too
many tasks, the scheduler assigns the new inbound task to the worker
with the next greatest worker weight.
Programs can set this parameter using the extended function. The value
must be a non-negative integer. The brief form supplies the default
value, TIBRVCM_DEFAULT_WORKER_TASKS (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.

schedulerWeight Weight represents the ability of this member to fulfill the role of
scheduler, relative to other members with the same name. Cooperating
distributed queue transports use relative scheduler weight values to
elect one transport as the scheduler; members with higher scheduler
weight take precedence.
Programs can set this parameter using the extended function. Acceptable
values range from 0 to 65535. Zero is a special value, indicating that the
member can never be the scheduler. The brief form supplies the default
value, TIBRVCM_DEFAULT_SCHEDULER_WEIGHT (1).
For more information, see Rank and Weight on page 206 in TIBCO
Rendezvous Concepts.

TIBCO Rendezvous C Reference

 tibrvcmTransport_CreateDistributedQueue() 337
|

(Sheet 4 of 4)

Parameter Description
schedulerHeartbeat The scheduler sends heartbeat messages at this interval (in seconds).
All members with the same name must specify the same value for this
parameter. The value must be strictly positive. To determine the correct
value, see Step 4: Choose the Intervals on page 237 in TIBCO Rendezvous
Concepts.
Programs can set this parameter using the extended function. The brief
form supplies the default value, TIBRVCM_DEFAULT_SCHEDULER_HB
(1.0).

schedulerActivation When the heartbeat signal from the scheduler has been silent for this
interval (in seconds), the member with the greatest scheduler weight
takes its place as the new scheduler.
All members with the same name must specify the same value for this
parameter. The value must be strictly positive. To determine the correct
value, see Step 4: Choose the Intervals on page 237 in TIBCO Rendezvous
Concepts.
Programs can set this parameter using the extended function. The brief
form supplies the default value, TIBRVCM_DEFAULT_SCHEDULER_ACTIVE
(3.5).

Constant Value
TIBRVCM_DEFAULT_COMPLETE_TIME 0

TIBRVCM_DEFAULT_WORKER_WEIGHT 1

TIBRVCM_DEFAULT_WORKER_TASKS 1

TIBRVCM_DEFAULT_SCHEDULER_WEIGHT 1

TIBRVCM_DEFAULT_SCHEDULER_HB 1.0

TIBRVCM_DEFAULT_SCHEDULER_ACTIVE 3.5

Relationship to Although distributed queue members are a specialized type of CM transport,

CM their behavior is quite different. Distributed queue transports do not support any
functions related to sending messages (for a complete list, see the table of disabled
functions, below).

TIBCO Rendezvous C Reference

338
| Chapter 12 Distributed Queues

Scheduler recovery and task rescheduling are available only when the task
message is a certified message (that is, a certified delivery agreement is in effect
between the task sender and the distributed queue transport scheduler).

Disabled Functions
tibrvcmTransport_AddListener()
tibrvcmTransport_AllowListener()
tibrvcmTransport_ConnectToRelayAgent()
tibrvcmTransport_DisallowListener()
tibrvcmTransport_DisconnectFromRelayAgent()
tibrvcmTransport_GetDefaultCMTimeLimit()
tibrvcmTransport_GetLedgerName()
tibrvcmTransport_GetRelayAgent()
tibrvcmTransport_GetRequestOld()
tibrvcmTransport_GetSyncLedger()
tibrvcmTransport_RemoveListener()
tibrvcmTransport_RemoveSendState()
tibrvcmTransport_ReviewLedger()
tibrvcmTransport_Send()
tibrvcmTransport_SendReply()
tibrvcmTransport_SendRequest()
tibrvcmTransport_SetDefaultCMTimeLimit()
tibrvcmTransport_SyncLedger()

See Also tibrvcmTransport_Destroy() on page 302

Distributed Queue, page 183, in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

 tibrvcmTransport_GetCompleteTime() 339
|

tibrvcmTransport_GetCompleteTime()
Function

Declaration tibrv_status tibrvcmTransport_GetCompleteTime(

tibrvcmTransport cmTransport,
tibrv_f64* completeTime);

Purpose Extract the worker complete time limit of a distributed queue transport.

Remarks The complete time parameter of the scheduler affects the reassignment of tasks.

Parameter Description
cmTransport Get the complete time of this distributed queue transport.

completeTime The program supplies a location, and the function stores the
worker complete time in that location.

See Also tibrvcmTransport_SetCompleteTime() on page 343

Distributed Queue, page 183, in TIBCO Rendezvous Concepts
Complete Time, page 191, in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

340
| Chapter 12 Distributed Queues

tibrvcmTransport_GetUnassignedMessageCount()
Function

Declaration tibrv_status tibrvcmTransport_GetUnassignedMessageCount(

tibrvcmTransport cmTransport,
tibrv_u32* msgCount);

Purpose Extract the number of unassigned task messages from a distributed queue
transport.

Remarks An unassigned task message is a message received by the scheduler, but not yet
assigned to any worker in the distributed queue.
This call produces a valid count only within a scheduler process. Within a worker
process, this call always produces zero.

Parameter Description
cmTransport Extract the number of unassigned task messages from this
distributed queue transport.

msgCount The program supplies a location, and the function stores the
unassigned task count in that location.

TIBCO Rendezvous C Reference

 tibrvcmTransport_GetWorkerWeight() 341
|

tibrvcmTransport_GetWorkerWeight()
Function

Declaration tibrv_status tibrvcmTransport_GetWorkerWeight(

tibrvcmTransport cmTransport,
tibrv_u32* workerWeight);

Purpose Extract the worker weight of a distributed queue transport.

Parameter Description
cmTransport Get the worker weight of this distributed queue transport.

workerWeight The program supplies a location, and the function stores the
worker weight in that location.

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

tibrvcmTransport_CreateDistributedQueue() on page 334
tibrvcmTransport_SetWorkerWeight() on page 345

TIBCO Rendezvous C Reference

342
| Chapter 12 Distributed Queues

tibrvcmTransport_GetWorkerTasks()
Function

Declaration tibrv_status tibrvcmTransport_GetWorkerTasks(

tibrvcmTransport cmTransport,
tibrv_u32* workerTasks);

Purpose Extract the worker task capacity of a distributed queue transport.

Parameter Description
cmTransport Get the task capacity of this distributed queue transport.

workerTasks The program supplies a location, and the function stores the
task capacity in that location.

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

tibrvcmTransport_CreateDistributedQueue() on page 334
tibrvcmTransport_SetWorkerTasks() on page 346

TIBCO Rendezvous C Reference

 tibrvcmTransport_SetCompleteTime() 343
|

tibrvcmTransport_SetCompleteTime()
Function

Declaration tibrv_status tibrvcmTransport_SetCompleteTime(

tibrvcmTransport cmTransport,
tibrv_f64 completeTime);

Purpose Set the worker complete time limit of a distributed queue transport.

Remarks The complete time parameter of the scheduler affects the reassignment of tasks:
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 function.

Parameter Description
cmTransport Set the complete time of this distributed queue transport.

completeTime Use this complete time (in seconds). The time must be
non-negative.

See Also tibrvcmTransport_GetCompleteTime() on page 339

Distributed Queue, page 183, in TIBCO Rendezvous Concepts
Complete Time, page 191, in TIBCO Rendezvous Concepts

TIBCO Rendezvous C Reference

344
| Chapter 12 Distributed Queues

tibrvcmTransport_SetTaskBacklogLimit...()
Function

Declaration tibrv_status tibrvcmTransport_SetTaskBacklogLimitInBytes(

tibrvcmTransport cmTransport,
tibrv_u32 limitBySizeInBytes);

tibrv_status tibrvcmTransport_SetTaskBacklogLimitInMessages(
tibrvcmTransport cmTransport,
tibrv_u32 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 functions 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 TIBRV_NOT_PERMITTED.

Parameter Description
cmTransport Set the size limit of the task queue of this distributed
queue transport.

limitBySizeInBytes Use this size limit (in bytes).

Zero is a special value, indicating no size limit.

limitByMessages 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

TIBCO Rendezvous C Reference

 tibrvcmTransport_SetWorkerWeight() 345
|

tibrvcmTransport_SetWorkerWeight()
Function

Declaration tibrv_status tibrvcmTransport_SetWorkerWeight(

tibrvcmTransport cmTransport,
tibrv_u32 workerWeight);

Purpose Set the worker weight of a distributed queue transport.

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

Parameter Description
cmTransport Set the worker weight of this distributed queue transport.

workerWeight Use this worker weight.

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

tibrvcmTransport_CreateDistributedQueue() on page 334
tibrvcmTransport_GetWorkerWeight() on page 341

TIBCO Rendezvous C Reference

346
| Chapter 12 Distributed Queues

tibrvcmTransport_SetWorkerTasks()
Function

Declaration tibrv_status tibrvcmTransport_SetWorkerTasks(

tibrvcmTransport cmTransport,
tibrv_u32 workerTasks);

Purpose Set the worker task capacity of a distributed queue transport.

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.

Parameter Description
cmTransport Set the task capacity of this distributed queue transport.

workerTasks Use this task capacity. Value must be a non-negative integer.

Zero is a special value, indicating that this distributed queue
member is a dedicated scheduler (that is, it never accepts
tasks).

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

tibrvcmTransport_CreateDistributedQueue() on page 334
tibrvcmTransport_GetWorkerTasks() on page 342

TIBCO Rendezvous C Reference

 | 347

Chapter 13 Datatypes

Rendezvous wire format datatypes are a standard, platform-independent

convention for types and sizes. A parallel set of C datatypes represents data
within programs.
This chapter summarizes the two sets of datatypes, and the conversions among
the various types.

Topics

• Wire Format Datatypes, page 348

• C Datatypes, page 350
• Datatype Conversion, page 352

See Also
Appendix A, Custom Datatypes, on page 361

TIBCO Rendezvous C Reference

348
| Chapter 13 Datatypes

Wire Format Datatypes

(Sheet 1 of 2)

Wire Format Type Type Description Notes

Special Types

TIBRVMSG_MSG Rendezvous message

TIBRVMSG_DATETIME Rendezvous datetime

TIBRVMSG_OPAQUE opaque byte sequence

TIBRVMSG_STRING ISO 8859-1 character string NULL-terminated.

(also called Latin-1)

TIBRVMSG_XML XML data (byte sequence)

Scalar Types

TIBRVMSG_BOOL boolean TIBRV_FALSE, TIBRV_TRUE

TIBRVMSG_I8 8-bit integer

TIBRVMSG_I16 16-bit integer

TIBRVMSG_I32 32-bit integer

TIBRVMSG_I64 64-bit integer

TIBRVMSG_U8 8-bit unsigned integer

TIBRVMSG_U16 16-bit unsigned integer

TIBRVMSG_U32 32-bit unsigned integer

TIBRVMSG_U64 64-bit unsigned integer

TIBRVMSG_F32 32-bit floating point

TIBRVMSG_F64 64-bit floating point

TIBCO Rendezvous C Reference

 Wire Format Datatypes 349
|

(Sheet 2 of 2)

Wire Format Type Type Description Notes

TIBRVMSG_IPADDR32 4-byte IP address Network byte order.
String representation is four-part
dot-delimited notation.

TIBRVMSG_IPPORT16 2-byte IP port Network byte order.

String representation is a 16-bit
decimal integer.

Array Types

TIBRVMSG_I8ARRAY 8-bit integer array The count property of the field

reflects the number of elements in the
TIBRVMSG_I16ARRAY 16-bit integer array array.
TIBRVMSG_I32ARRAY 32-bit integer array

TIBRVMSG_I64ARRAY 64-bit integer array

TIBRVMSG_U8ARRAY 8-bit unsigned integer array

TIBRVMSG_U16ARRAY 16-bit unsigned integer array

TIBRVMSG_U32ARRAY 32-bit unsigned integer array

TIBRVMSG_U64ARRAY 64-bit unsigned integer array

TIBRVMSG_F32ARRAY 32-bit floating point array

TIBRVMSG_F64ARRAY 64-bit floating point array

TIBRVMSG_MESSAGEARRAY message array

TIBRVMSG_STRINGARRAY string array

Custom Types

TIBRVMSG_USER_FIRST First code available for For more information, see

custom datatypes. Appendix A, Custom Datatypes, on
page 361.
TIBRVMSG_USER_LAST Last code available for
custom datatypes.

TIBCO Rendezvous C Reference

350
| Chapter 13 Datatypes

C Datatypes

(Sheet 1 of 2)

C Type Type Description Notes

tibrv_bool boolean TIBRV_FALSE, TIBRV_TRUE

tibrv_f32 32-bit floating point

tibrv_f64 64-bit floating point

tibrv_i8 8-bit integer

tibrv_i16 16-bit integer

tibrv_i32 32-bit integer

tibrv_i64 64-bit integer

tibrv_u8 8-bit unsigned integer

tibrv_u16 16-bit unsigned integer

tibrv_u32 32-bit unsigned integer

tibrv_u64 64-bit unsigned integer

tibrv_ipaddr32 4-byte IP address Stored in network byte order.

String representation is four-part
dot-delimited notation.

tibrv_ipport16 2-byte IP port Stored in network byte order.

String representation is a decimal
integer (all 16-bits).

tibrvMsgDateTime Rendezvous datetime struct See tibrvMsgDateTime on page 53.

tibrv_f32* 32-bit floating point array

tibrv_f64* 64-bit floating point array

tibrv_i8* 8-bit integer array

TIBCO Rendezvous C Reference

 C Datatypes 351
|

(Sheet 2 of 2)

C Type Type Description Notes

tibrv_i16* 16-bit integer array

tibrv_i32* 32-bit integer array

tibrv_i64* 64-bit integer array

tibrv_u8* 8-bit unsigned integer array

tibrv_u16* 16-bit unsigned integer array

tibrv_u32* 32-bit unsigned integer array

tibrv_u64* 64-bit unsigned integer array

tibrvMsg Rendezvous message See tibrvMsg on page 52.

char* character string ISO 8859-1 (Latin-1) character encoding

void* opaque byte sequence

TIBCO Rendezvous C Reference

352
| Chapter 13 Datatypes

Datatype Conversion

Rendezvous software converts datatypes in two situations:

• As it translates a message to wire format (when sending a message).
• As it extracts data from a message field.

Convenience functions that extract a field from a Rendezvous message

automatically decode the field’s data to a homologous C type. Figure 14 on
page 354 specifies the homologous decodings as well as conversions to other
types. See also, tibrvMsg_GetField() on page 82.
Convenience functions that add a field to a Rendezvous message or update an
existing field severely restrict type encoding. These functions encode only to
homologous types (the solid dots along the diagonal of Figure 14 indicate pairs of
homologous types).

General Rules
These general rules govern most conversions.

Supported
• All wire format types decode to the homologous C datatypes (in get calls), and
all C datatypes encode to the homologous wire format types (in add and update
calls).
• All wire format numeric scalar types convert to all C numeric scalar types.
• All wire format numeric array types convert to all C numeric array types.

Caution
• Converting a wire format opaque or XML byte sequence to a C character
string creates a printable string, but the string does not capture any of the data
bytes (it captures only the number of bytes).
• Converting a wire format signed integer to a C unsigned integer discards the
sign.
• Converting a wire format numeric type to a C numeric type with fewer bits
risks loss of precision.
• Converting wire format floating point numbers to C integer types discards the
fractional part.

TIBCO Rendezvous C Reference

 Datatype Conversion 353
|

• Converting large (out-of-range) wire format floating point numbers to C

integers results in the maximum integer of the C target size.

Not Supported
• Array types do not convert to scalar types.
• Scalar types do not convert to array types.
• C types do not convert to non-homologous wire format types (when adding
or updating a field).

Converting to Boolean
• When converting a string to a boolean, all strings in which the first character is
either t or T map to boolean true. All other strings map to boolean false.
• When converting a numeric value to a boolean, zero maps to boolean false.
All non-zero numeric values map to boolean true.

TIBCO Rendezvous C Reference

354
| Chapter 13 Datatypes

Figure 14 Wire Format to C Datatype Conversion Matrix

C Destination Type

Get

tibrvMsgDateTime
tibrv_ipaddr32
tibrv_ipport16

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

tibrv_i16[]
tibrv_i32[]
tibrv_i64[]

tibrvMsg[]
tibrv_bool

tibrv_u16
tibrv_u32
tibrv_u64

tibrv_u8[]
tibrv_f32
tibrv_f64

tibrvMsg
tibrv_i16
tibrv_i32
tibrv_i64

tibrv_i8[]
tibrv_u8
tibrv_i8

char*[]
char*
void*
TIBRVMSG_BOOL S S S S S S S S S S S
TIBRVMSG_F32 S N N N N N N N N N S
TIBRVMSG_F64 S N N N N N N N N N S
TIBRVMSG_I8 S N N N N N N N N N S
TIBRVMSG_I16 S N N N N N N N N N S
TIBRVMSG_I32 S N N N N N N N N N S
TIBRVMSG_I64 S N N N N N N N N N S
TIBRVMSG_U8 S N N N N N N N N N S
TIBRVMSG_U16 S N N N N N N N N N S
TIBRVMSG_U32 S N N N N N N N N N S
TIBRVMSG_U64 S N N N N N N N N N S
tibrvMsg Source Type

TIBRVMSG_IPADDR32 N S
TIBRVMSG_IPPORT16 N N N S
TIBRVMSG_DATETIME C
TIBRVMSG_F32ARRAY N N N N N N N N N S
TIBRVMSG_F64ARRAY N N N N N N N N N S
TIBRVMSG_I8ARRAY N N N N N N N N N S
TIBRVMSG_I16ARRAY N N N N N N N N N S
TIBRVMSG_I32ARRAY N N N N N N N N N S
TIBRVMSG_I64ARRAY N N N N N N N N N S
TIBRVMSG_U8ARRAY N N N N N N N N N S
TIBRVMSG_U16ARRAY N N N N N N N N N S
TIBRVMSG_U32ARRAY N N N N N N N N N S
TIBRVMSG_U64ARRAY N N N N N N N N N S
TIBRVMSG_MSG S
TIBRVMSG_OPAQUE C
TIBRVMSG_STRING P P P P P P P P P P P P P
TIBRVMSG_XML C
TIBRVMSG_MSGARRAY
TIBRVMSG_STRINGARRAY

Key
Homologous types; conversion always supported; no loss of information
S Supported conversion; always supported
N Numeric conversion; loss of information is possible (without warning)
P Parsed conversion; supported only when sensible and syntactically correct
C Caution; supported, but results sometimes can be misleading
Unsupported conversion

TIBCO Rendezvous C Reference

 | 355

Chapter 14 Status

Most Rendezvous functions return a status code, indicating either normal return
status or a range of error conditions.
Programs must check the status after every Rendezvous function call, and take
appropriate action.

Topics

Function Description Page

Status Codes

tibrv_status Enumerated return codes from 356

Rendezvous functions.

tibrvStatus_GetText() Return the descriptive string 360

corresponding to a status code.

TIBCO Rendezvous C Reference

356
| Chapter 14 Status

tibrv_status
Type

Purpose Enumerated return codes from Rendezvous functions.

(Sheet 1 of 4)

Constant Description
TIBRV_OK The function returned without error.

TIBRV_INIT_FAILURE Cannot create the network transport.

TIBRV_INVALID_TRANSPORT The transport has been destroyed, or is otherwise unusable.

TIBRV_INVALID_ARG An argument is invalid. Check arguments other than

messages, subject names, transports, events, queues and queue
groups (which have separate status codes).

TIBRV_NOT_INITIALIZED The function cannot run because the Rendezvous environment

is not initialized (open).

TIBRV_ARG_CONFLICT Two arguments that require a specific relation are in conflict.

For example, the upper end of a numeric range is less than the
lower end.

TIBRV_SERVICE_NOT_FOUND tibrvTransport_Create() cannot match the service name

using getservbyname().

TIBRV_NETWORK_NOT_FOUND tibrvTransport_Create() cannot match the network name

using getnetbyname().

TIBRV_DAEMON_NOT_FOUND tibrvTransport_Create() cannot match the daemon port

number.

TIBRV_NO_MEMORY The function could not allocate dynamic storage.

TIBRV_INVALID_SUBJECT The function received a subject name with incorrect syntax.

TIBRV_DAEMON_NOT_CONNECTED The Rendezvous daemon process (rvd) exited, or was never

started. This status indicates that the program cannot start the
daemon and connect to it.

TIBRV_VERSION_MISMATCH The library, header files and Rendezvous daemon are

incompatible.

TIBCO Rendezvous C Reference

 tibrv_status 357
|

(Sheet 2 of 4)

Constant Description
TIBRV_SUBJECT_COLLISION It is illegal to create two certified listener events on the same
CM transport with overlapping subjects.

TIBRV_VC_NOT_CONNECTED A virtual circuit terminal was once complete, but is now

irreparably broken.

TIBRV_NOT_PERMITTED The program attempted an illegal operation.

For example:
• Cannot create ledger file.
• Cannot confirm an uncertified message (that is, it has no
sequence number).

TIBRV_INVALID_NAME The field name is too long; see Field Name Length on page 57.

TIBRV_INVALID_TYPE 1. The field type is not registered.

2. Cannot update field to a type that differs from the existing
field’s type.

TIBRV_INVALID_SIZE The explicit size in the field does not match its explicit type.

TIBRV_INVALID_COUNT The explicit field count does not match its explicit type.

TIBRV_NOT_FOUND The function could not find the specified field in the message.

TIBRV_ID_IN_USE Cannot add this field because its identifier is already present
in the message; identifiers must be unique.

TIBRV_ID_CONFLICT After field search by identifier fails, search by name succeeds,

but the actual identifier in the field is non-NULL (so it does not
match the identifier supplied).

TIBRV_CONVERSION_FAILED The function found the specified field, but could not convert it
to the desired datatype.

TIBRV_RESERVED_HANDLER The datatype handler number is reserved for Rendezvous

internal datatype handlers.

TIBRV_ENCODER_FAILED The program’s datatype encoder failed.

TIBRV_DECODER_FAILED The program’s datatype decoder failed.

TIBCO Rendezvous C Reference

358
| Chapter 14 Status

(Sheet 3 of 4)

Constant Description
TIBRV_INVALID_MSG The function received a message argument that is not a
well-formed message; for example, NULL.

TIBRV_INVALID_FIELD The program supplied an invalid field as an argument.

TIBRV_INVALID_INSTANCE The program supplied zero as the field instance number (the
first instance is number 1).

TIBRV_CORRUPT_MSG The function detected a corrupt message argument.

The most common cause is that the program corrupted storage
by accessing the message in two threads simultaneously
(without proper locking).

TIBRV_TIMEOUT A timed dispatch call returned without dispatching an event.

A send request call returned without receiving a reply
message.
A virtual circuit terminal is not yet ready for use.

TIBRV_INTR Interrupted operation.

TIBRV_INVALID_DISPATCHABLE The function received an event queue or queue group that has
been destroyed, or is otherwise unusable.

TIBRV_INVALID_DISPATCHER The function received a dispatcher that is invalid or has been

destroyed.

TIBRV_INVALID_EVENT The function received an event that has been destroyed, or is

otherwise unusable.

TIBRV_INVALID_CALLBACK The function received NULL instead of a callback function.

TIBRV_INVALID_QUEUE The function received a queue that has been destroyed, or is

otherwise unusable.

TIBRV_INVALID_QUEUE_GROUP The function received a queue group that has been destroyed,
or is otherwise unusable.

TIBRV_INVALID_TIME_INTERVAL The function received a negative timer interval.

TIBRV_INVALID_IO_SOURCE The function received an invalid I/O source (for this operating
system).

TIBCO Rendezvous C Reference

 tibrv_status 359
|

(Sheet 4 of 4)

Constant Description
TIBRV_INVALID_IO_CONDITION The function received an invalid I/O condition (for this
operating system).

TIBRV_SOCKET_LIMIT The operation failed because of an operating system socket

limitation.

TIBRV_OS_ERROR tibrv_Open() encountered an operating system error.

TIBRV_INSUFFICIENT_BUFFER The function received a buffer argument that is too small to

contain the result.

TIBRV_EOF End of file.

TIBRV_INVALID_FILE 1. Ledger file is not recognizable as such.

2. tibrvSecureDaemon_SetUserCertWithKey() or
tibrvSecureDaemon_SetUserCertWithKeyBin() could not
complete a certificate file operation; this status code can
indicate either disk I/O failure, or invalid certificate data, or
an incorrect password.

TIBRV_FILE_NOT_FOUND Rendezvous software could not find the specified file.

TIBRV_NOT_FILE_OWNER The program cannot open the specified file because another
program owns it.
For example, ledger files are associated with correspondent
names.

TIBRV_IO_FAILED Cannot write to ledger file.

TIBRV_IPM_ONLY The call is not available because IPM is not operating (that is,
the call is available only when IPM is operating).

TIBCO Rendezvous C Reference

360
| Chapter 14 Status

tibrvStatus_GetText()
Function

Declaration const char* tibrvStatus_GetText(

tibrv_status status);

Purpose Return the descriptive string corresponding to a status code.

Remarks Status strings use the ISO 8859-1 character encoding.

Parameter Description
status Return the string for this status code.

See Also tibrv_status on page 356

TIBCO Rendezvous C Reference

 | 361

Appendix A Custom Datatypes

Rendezvous programs can manipulate custom datatypes by defining and

registering functions to translate them. This appendix describes the required
functions and the tools you can use to implement them.
For most programs, the standard set of datatypes is sufficient. If your program
does not require custom datatypes, you may skip this appendix.

Topics

• Operations by Functional Group, page 362

• Operations in Alphabetical Order, page 363
• Architecture Overview, page 364
• Custom Datatype Checklist, page 367
• Convenience Functions, page 368

TIBCO Rendezvous C Reference

362
| Appendix A Custom Datatypes

Operations by Functional Group

Function or Type Description Page

Handlers

tibrvMsg_SetHandlers() Define a program-specific datatype, by registering 369

functions to transfer it between local format and wire
format, and convert it to other datatypes.

tibrvMsgData_Converter Convert a message field to another local datatype. 373

tibrvMsgData_Decoder Decode a wire format field to a local datatype. 377

tibrvMsgData_Encoder Encode a local format field to wire format. 378

Storage Type

tibrvMsgDataType Enumerate the types of low-level data references. 370

Utility Functions

tibrvMsgData_ByteSize() Calculate the wire buffer size of data from its C size. 372

tibrvMsgData_CopyBytes() Copy data into the wire buffer of a message for an encoder. 375

tibrvMsgData_GetBytes() Get data pointer and size from a wire buffer for a decoder. 380

tibrvMsgData_GetSize() Get the data size from a wire buffer for a decoder. 382

tibrvMsgData_Malloc() Allocate process storage for decoders and converters. 384

tibrvMsgData_SetSize() Write the size of data into a wire buffer for an encoder. 385

TIBCO Rendezvous C Reference

 Operations in Alphabetical Order 363
|

Operations in Alphabetical Order

Function or Type Description Page

tibrvMsg_SetHandlers() Define a program-specific datatype, by registering 369
functions to transfer it between local format and wire
format, and convert it to other datatypes.

tibrvMsgDataType Enumerate the types of low-level data references. 370

tibrvMsgData_ByteSize() Calculate the wire buffer size of data from its C size. 372

tibrvMsgData_Converter Convert a message field to another local datatype. 373

tibrvMsgData_CopyBytes() Copy data into the wire buffer of a message for an encoder. 375

tibrvMsgData_Decoder Decode a wire format field to a local datatype. 377

tibrvMsgData_Encoder Encode a local format field to wire format. 378

tibrvMsgData_GetBytes() Get data pointer and size from a wire buffer for a decoder. 380

tibrvMsgData_GetSize() Get the data size from a wire buffer for a decoder. 382

tibrvMsgData_Malloc() Allocate process storage for decoders and converters. 384

tibrvMsgData_SetSize() Write the size of data into a wire buffer for an encoder. 385

TIBCO Rendezvous C Reference

364
| Appendix A Custom Datatypes

Architecture Overview

Table 11 explains the stratification of data, field and message operations into four
layers.

Table 11 Architecture of Message and Data Manipulation

Layer Description
4. Convenience Functions Type-specific functions manipulate message field data. This
layer contains three functions per datatype—add, get and
update. For example, see Add String on page 64. All
convenience functions call the corresponding generic functions
of layer 3 for their main functionality.
When defining a custom datatype, a program can implement
these three functions (optional).

3. Generic Field Functions Field functions add, get or update a message field. This layer
consists of only three functions: tibrvMsg_AddField(),
tibrvMsg_GetField(), tibrvMsg_UpdateField(). Field
functions call the datatype handler functions of layer 2
whenever data enters or leaves a message.

2. Datatype Handler Functions Type-specific handler functions translate data between C format
and Rendezvous wire format, and convert it to other datatypes.
This layer contains three functions per datatype:
• encoder, of type tibrvMsgData_Encoder
• decoder, of type tibrvMsgData_Decoder
• converter, of type tibrvMsgData_Converter

To define a custom datatype, a program must implement these

functions.

1. Utility Functions Utility functions ease and standardize the implementation of

datatype handler functions in layer 2. For example,
tibrvMsgData_CopyBytes().

At the top of the table, programs call functions in layer 4 (and sometimes layer 3)
to move data in and out of messages. The remaining lower layers are generally
invisible to most programs. That is, most programs do not call functions below
layers 3.

TIBCO Rendezvous C Reference

 Architecture Overview 365
|

However, a program that defines custom datatypes must implement the three
functions in layer 2. Nevertheless, the program never calls layer 2 functions
directly. Instead the program can define optional convenience functions at layer 4,
and call them to move the custom datatype in and out of messages.

Adding Data
This narrative illustrates the interaction of functions at all four layers as they
cooperate to add data to a message. The narrative for updating data within a
message is parallel.
A program begins by calling a layer 4 convenience function to add data. The
convenience function creates a field object (tibrvMsgField) that contains the
data, the field name and identifier, a datatype token, and the element count (for
arrays only). Then the convenience function calls the layer 3 field function
tibrvMsg_AddField() to add that field to the message.

Among its other tasks, tibrvMsg_AddField() must write the field into wire
buffer storage within the message object; to accomplish this step, it calls the layer
2 encoder function specific to the datatype.
The encoder transforms the data into its wire format, using layer 1 utility
functions to copy that data into the message’s wire buffer.
Each write operation updates the message’s wire buffer pointer to the location
where the next write will begin.

Figure 15 Writing Fields into a Message’s Wire Buffer

Field m Field m+1

name type size data name type size data

Layer 3 writes Layer 2 encoder writes

For types with implicit fixed size,
these bytes. these bytes. Layer 1
omit this part.
functions assist.

Extracting Data
This narrative illustrates the interaction of functions at all four layers as they
cooperate to get data from a message.

TIBCO Rendezvous C Reference

366
| Appendix A Custom Datatypes

A program begins by calling a layer 4 convenience function to get data. The

convenience function calls the layer 3 field function tibrvMsg_GetField() to
find the field in the message.
Among its other tasks, tibrvMsg_GetField() must read the data from the
message’s wire buffer; to accomplish this step, it calls the layer 2 decoder function
for the datatype (as specified in the message field).
The decoder uses layer 1 utility functions to extract that data from the message’s
wire buffer, and transforms the data into its C format.
Returning to layer 3, tibrvMsg_GetField() receives the data from the decoder,
packaged in the data part of a field object (tibrvMsgField).
Returning to layer 4, the convenience function receives the field object from
tibrvMsg_GetField(). The next task is to convert the data from its actual
datatype to the target datatype (notice that the program, in effect, explicitly
requested a target datatype by calling a particular type-specific convenience
function). When the actual data does not already match the target datatype, the
convenience function calls down into layer 2, to the converter function associated
with the actual datatype.
If legal, the converter transforms the actual data to the target type, and modifies
the field object accordingly.
Returning once again to layer 4, the convenience function extracts the modified
data from the field object, and passes it back to the calling program.

TIBCO Rendezvous C Reference

 Custom Datatype Checklist 367
|

Custom Datatype Checklist

We recommend modeling your custom datatype implementation on our example

code; see the file examples/usertypes.c.

To define a custom datatype, a program must do these steps:

1. Define the C representation of the new type. This representation is often a C
struct.
2. Assign a code number to represent the new type. The new type must be in the
range [TIBRVMSG_USER_FIRST, TIBRVMSG_USER_LAST]. All other
codes are reserved.
3. Define an encoder function to transfer the new type from a field object into a
message’s wire buffer. See tibrvMsgData_Encoder on page 378.
4. Define a decoder function to transfer the new type from a message’s wire
buffer into t field object. See tibrvMsgData_Decoder on page 377.
5. Define a converter function to convert the new type to other datatypes. See
tibrvMsgData_Converter on page 373.
6. Register the encoder, decoder and converter functions. See
tibrvMsg_SetHandlers() on page 369.
7. Optional: define convenience functions to add, get and update message fields
with data of the new type. See Convenience Functions on page 368.

TIBCO Rendezvous C Reference

368
| Appendix A Custom Datatypes

Convenience Functions

When defining custom datatypes, programs have the option to also define
convenience functions for the new type. In general, layer 4 convenience functions
rely on layer 3 generic field functions to do most of their work, packing or
unpacking the field structure as appropriate. You can choose to implement up to
three convenience functions:
• Get a value of the custom datatype from a message.
• Add a value of the custom datatype to a message.
• Update an existing field in a message with a new value of the custom datatype.

Get
The get function must fulfill these responsibilities:
• Call tibrvMsg_GetField() to find the field in the message.
• Check that tibrvMsg_GetField() did not return an error code.
• Check that the type of the field matches the target datatype of the
convenience function.
— If the conversion is illegal, return an error code.
— If it matches, then return, passing back the data directly.
— Otherwise, convert the data to the target datatype. Pass back the converted
data. (In most cases, converter functions associated with the actual
datatype are unable to convert it to a custom type, so either the convenience
function must convert it, or declare the conversion illegal.)

Add and Update

The add and update functions must fulfill these responsibilities:
• Validate the integrity of the data.
• Create a field object (tibrvMsgField) on the stack, and set all six of its parts to
describe the data.
• Store it in the message:
— Add calls tibrvMsg_AddField() to add the field object to the message.
— Update calls tibrvMsg_UpdateField() to update an existing field in the
message with the data from the new field object.

TIBCO Rendezvous C Reference

 tibrvMsg_SetHandlers() 369
|

tibrvMsg_SetHandlers()
Function

Declaration tibrv_status tibrvMsg_SetHandlers(

tibrv_u8 type,
tibrvMsgData_Encoder encoder,
tibrvMsgData_Decoder decoder,
tibrvMsgData_Converter converter);

Purpose Define a program-specific datatype, by registering functions to transfer it between

local format and wire format, and convert it to other datatypes.

Remarks Programs that define custom data handler functions must register them before
any message operations involving the custom datatype.
The program’s data handler functions must properly address byte order and
endian issues.

Parameter Description
type Use this number as a unique identifier for the new datatype.
The type identifier must be in the range
[TIBRVMSG_USER_FIRST, TIBRVMSG_USER_LAST]; all
other identifiers are reserved.

encoder This function translates a local format instance of the datatype

into wire format. See tibrvMsgData_Encoder on page 378.
NULL indicates that the program cannot add or update fields of
this datatype.

decoder This function translates wire format to a local format instance

of the datatype. See tibrvMsgData_Decoder on page 377.
NULL indicates that the program cannot get fields of this
datatype.

converter This function translates a field of this datatype to other

datatypes. See tibrvMsgData_Converter on page 373.
NULL indicates that the program cannot force conversion to
another datatype during get and update calls.

See Also tibrvMsgData_Converter on page 373

tibrvMsgData_Decoder on page 377
tibrvMsgData_Encoder on page 378

TIBCO Rendezvous C Reference

370
| Appendix A Custom Datatypes

tibrvMsgDataType
Type

Declaration typedef enum {

tibrvMsgData_Primitive,
tibrvMsgData_MallocBlock,
tibrvMsgData_SubMessage,
tibrvMsgData_WireReference
} tibrvMsgDataType;

Purpose Enumerate the types of low-level data references.

Remarks This enumeration specifies the four low-level types of data reference that can be
extracted from a message field. Decoders and converters create references to the
data that they extract, and must inform the message of the type each time they
create a reference. Internal functions use this type information to properly
maintain references to the extracted data.

Value Description
tibrvMsgData_Primitive Extract primitive types by copying the data into the destination
field struct.
The predefined set of primitive types is tibrv_bool, tibrv_f32,
tibrv_f64, tibrv_i8, tibrv_i16, tibrv_i32, tibrv_i64, tibrv_u8,
tibrv_u16, tibrv_u32, tibrv_u64, tibrv_ipaddr32, tibrv_ipport16,
tibrvMsgDateTime.

tibrvMsgData_MallocBlock Extract this type by allocating a block of storage associated with

the message. To allocate the block, programs must call
tibrvMsgData_Malloc() rather than malloc.

The predefined set of malloc block types includes all arrays. On

EBCDIC architectures, it also includes EBCDIC strings.

tibrvMsgData_SubMessage Extract this type by creating a new tibrvMsg object for the
decoded data.
The only submessage type is tibrvMsg.

tibrvMsgData_WireReference Extract this type by copying a pointer into the destination field
struct; the pointer refers to a location within the wire buffer of
the message.
The predefined set of wire reference types includes character
strings, opaque byte sequences, and XML data.

See Also Wire Format Datatypes, page 348

TIBCO Rendezvous C Reference

 tibrvMsgDataType 371
|

C Datatypes, page 350

tibrvMsgData_Converter on page 373
tibrvMsgData_Decoder on page 377
tibrvMsgData_Malloc() on page 384

TIBCO Rendezvous C Reference

372
| Appendix A Custom Datatypes

tibrvMsgData_ByteSize()
Function

Declaration tibrv_u32 tibrvMsgData_ByteSize(

tibrv_u32 content_size);

Purpose Calculate the wire buffer size of data from its C size.

Remarks Encoders call this layer 1 function to preview the wire size of the data as
tibrvMsgData_CopyBytes() would write it into the message (that is, including
extra bytes for size information). Encoders test this wire size against the available
space in the message.

Parameter Description
content_size The encoder supplies the C size (in bytes) of data.

See Also tibrvMsgData_Encoder on page 378

tibrvMsgData_SetSize() on page 385

TIBCO Rendezvous C Reference

 tibrvMsgData_Converter 373
|

tibrvMsgData_Converter
Function Type

Declaration typedef tibrv_status (*tibrvMsgData_Converter)(

tibrvMsgField* field,
tibrv_u8 destination_type,
tibrvMsgDataType* converted_type);

Purpose Convert a message field to another local datatype.

Remarks Programs define converters for custom datatypes. Layer 2 converter functions
augment the Wire Format to C Datatype Conversion Matrix on page 354.
Each converter function receives a message field, and replaces information within
it.
Each converter must fulfill these responsibilities:
• For disallowed conversions, return the status code
TIBRV_CONVERSION_FAILED.

• Convert the field’s data to the destination_type, and store the new data
back into the field.
• Set the field’s size part to reflect the new size of the converted data.
• Set the field’s count part to reflect the new element count of the converted
data.
• Set the field’s type part to reflect the destination_type.
• Store the low-level type of the new reference in *converted_type.

If your converter implementation allocates process storage, it must call

tibrvMsgData_Malloc() rather than malloc.

Parameter Description
field This parameter receives the location of a message
field. The converter function modifies that field to
effect the conversion.

TIBCO Rendezvous C Reference

374
| Appendix A Custom Datatypes

Parameter Description
destination_type This parameter receives the type identifier
representing the datatype of the resulting field. This
parameter instructs the converter function to convert
the field to this datatype.
The parameter can be any of the predefined
datatypes listed in Wire Format Datatypes on
page 348, as well as any custom datatypes that the
program defines.

converted_type This parameter receives a location. The converter

function must store the low-level type of the new
data reference in that location.

See Also tibrvMsgField on page 55

tibrvMsgDataType on page 370
tibrvMsgData_GetBytes() on page 380
tibrvMsgData_GetSize() on page 382

TIBCO Rendezvous C Reference

 tibrvMsgData_CopyBytes() 375
|

tibrvMsgData_CopyBytes()
Function

Declaration tibrv_status tibrvMsgData_CopyBytes(

char** buffer,
const void* src,
tibrv_u32 size);

Purpose Copy data into the wire buffer of a message for an encoder.

Remarks This layer 1 function does these steps (see Figure 16 on page 376):
1. Compute the wire size of the data from the size parameter.
2. Write the wire size into the wire buffer, and advance *buffer. (Now *buffer
points to the end of the size information, which will be the start of the data.)
3. Copy size bytes from src into the wire buffer, and advance *buffer again.
Now *buffer points to the end of the copied data.
4. Return.

Parameter Description
buffer The encoder supplies the location of an address within the wire
buffer of a destination message. This function copies the source
data into the destination message, starting at that address.
Before returning, this function advances *buffer to the end of
the data that it copied.

src Copy the data from this source buffer.

size Number of bytes to copy.

TIBCO Rendezvous C Reference

376
| Appendix A Custom Datatypes

Figure 16 tibrvMsgData_CopyBytes

Before
*buffer

src F o r e s t 0
size 7

After
*buffer

src F o r e s t 0
size 7

7 F o r e s t 0

See Also tibrvMsgData_ByteSize() on page 372

tibrvMsgData_Encoder on page 378

TIBCO Rendezvous C Reference

 tibrvMsgData_Decoder 377
|

tibrvMsgData_Decoder
Function Type

Declaration typedef tibrv_status (*tibrvMsgData_Decoder)(

char** wire_buffer,
tibrvMsgField* field,
tibrvMsgDataType* decoded_type);

Purpose Decode a wire format field to a local datatype.

Remarks Programs define decoders for custom datatypes. Layer 2 decoder functions
augment the Wire Format to C Datatype Conversion Matrix on page 354.
Each decoder must fulfill these responsibilities:
• Set the size, count and data parts of the destination field struct. (The layer 3
function sets the name, id and type.)
• Advance *wire_buffer to the end the source data (in the message).
tibrvMsgData_GetBytes() automatically advances this buffer pointer.

• Store the low-level type of the new data reference in *decoded_type.

• Check consistency, and properly address byte order and endian issues.

If your decoder implementation allocates process storage, it must call

tibrvMsgData_Malloc() rather than malloc.

Parameter Description
wire_buffer This parameter receives the location of an address within the
wire buffer of the source message. The source data starts at
that address.

field This parameter receives the location of a destination field

object. The decoder function must set the parts of this field
with the source data, its size and count.

decoded_type This parameter receives a location. The decoder function

must store the low-level type of the new data reference in
that location.

See Also tibrvMsgField on page 55

tibrvMsgDataType on page 370
tibrvMsgData_GetBytes() on page 380

TIBCO Rendezvous C Reference

378
| Appendix A Custom Datatypes

tibrvMsgData_Encoder
Function Type

Declaration typedef tibrv_status (*tibrvMsgData_Encoder)(

char** wire_buffer,
tibrv_u32 mem_available,
tibrvMsgField* field);

Purpose Encode a local format field to wire format.

Remarks Programs define encoders for custom datatypes. Layer 2 encoder functions
translate custom datatypes into Rendezvous wire format.
Each encoder must fulfill these responsibilities:
• Check that the field contains valid data of the appropriate type.
• Check that the data will fit in the available space; if not, return the error status
TIBRV_NO_MEMORY.

The encoder can use tibrvMsgData_ByteSize() to compute the wire size of

the data.
• Write the data into wire buffer of the message. Do not overwrite space that is
not available.
• Advance *wire_buffer to the end of the destination data (in the message).
tibrvMsgData_CopyBytes() automatically advances this buffer pointer.
• Check consistency, and properly address byte order and endian issues.

If your encoder implementation allocates process storage, it must call

tibrvMsgData_Malloc() rather than malloc.

Parameter Description
wire_buffer This parameter receives the location of an address within
the wire buffer of the destination message. The encoder
must write the wire-format encoded data to this
destination.
We strongly recommend using
tibrvMsgData_CopyBytes() to transfer the data.

mem_available This parameter receives the size of the available storage in

the message’s wire buffer.

TIBCO Rendezvous C Reference

 tibrvMsgData_Encoder 379
|

Parameter Description
field This parameter receives a field object, with self-describing
data in local format. This source field determines the data
to place into the destination wire_buffer.

Figure 17 Advancing the Wire Buffer Pointer

available space

Field m-1 Field m Field m+1

name type size data

After writing the name After writing the size and

and type, layer 3 data, layer 2 must
advances the wire buffer advance the wire buffer
pointer to this location. pointer to this location.

See Also tibrvMsgField on page 55

tibrvMsgData_ByteSize() on page 372
tibrvMsgData_CopyBytes() on page 375

TIBCO Rendezvous C Reference

380
| Appendix A Custom Datatypes

tibrvMsgData_GetBytes()
Function

Declaration tibrv_status tibrvMsgData_GetBytes(

char** buffer,
const void** src,
tibrv_u32* size);

Purpose Get data pointer and size from a wire buffer for a decoder.

Remarks This layer 1 function helps decoders extract data from a message’s wire buffer. It
does these steps (see Figure 18 on page 381):
1. Read the size information from the wire buffer (starting at the position
*buffer) and store it in the size parameter.

2. Store the start position of the actual data in the src parameter.
3. Advance *buffer to point to the end of the actual data.
4. Return.
After tibrvMsgData_GetBytes() returns, the decoder can obtain the data by
copying *size bytes from the location *src.

Parameter Description
buffer The decoder supplies the location of an address within the wire
buffer of a source message. After reading the size information,
this function advances *buffer to point to the location at the
end of the data.

src The decoder supplies the location of a buffer pointer. This

function stores the address of the actual data in that pointer.

size The decoder supplies a location. This function stores the size of
the actual data in that location.

TIBCO Rendezvous C Reference

 tibrvMsgData_GetBytes() 381
|

Figure 18 tibrvMsgData_GetBytes

Before
*buffer

*src

size

7 F o r e s t 0

After
*buffer

*src

size 7

7 F o r e s t 0

See Also tibrvMsgData_Decoder on page 377

TIBCO Rendezvous C Reference

382
| Appendix A Custom Datatypes

tibrvMsgData_GetSize()
Function

Declaration tibrv_status tibrvMsgData_GetSize(

char** buffer,
tibrv_u32* size);

Purpose Get the data size from a wire buffer for a decoder.

Remarks This layer 1 function helps decoders extract data from a message’s wire buffer. It
does only part of the work that tibrvMsgData_GetBytes() does (see Figure 19
on page 383):
1. Read the size information from the wire buffer (starting at the position
*buffer) and store it in the size parameter.

2. Advance *buffer to point to the end of the size information, which is the start
of the actual data.
3. Return.
After tibrvMsgData_GetSize() returns, the decoder can obtain the data by
copying *size bytes from the location *buffer. We recommend using the more
complete function tibrvMsgData_GetBytes(); this function gives programmers
finer control over pointer advancement (along with the responsibility to advance
that pointer appropriately).

Parameter Description
buffer The decoder supplies the address of the wire buffer within the
message. The function advances *buffer to point to the location
at the end of the size (which is the beginning of the data).

size The decoder supplies a location. This function stores the size of
the actual data in that location.

TIBCO Rendezvous C Reference

 tibrvMsgData_GetSize() 383
|

Figure 19 tibrvMsgData_GetSize

Before
*buffer

size

7 F o r e s t 0

After
*buffer

size 7

7 F o r e s t 0

See Also tibrvMsgData_Decoder on page 377

tibrvMsgData_GetBytes() on page 380

TIBCO Rendezvous C Reference

384
| Appendix A Custom Datatypes

tibrvMsgData_Malloc()
Function

Declaration void* tibrvMsgData_Malloc(

tibrv_u32 size);

Purpose Allocate process storage for decoders and converters.

Remarks Decoders and converters must use this layer 1 function to allocate storage for
extracted data. Do not use ordinary malloc.
The function returns a pointer to the storage. The storage remains associated with
the message, and persists until the message is destroyed. Programmers need not
free this storage; instead, the message automatically frees the storage at the
appropriate time.
Decoders and converters that allocate storage using this function must pass back
the type tibrvMsgData_MallocBlock.

Parameter Description
size Allocate a storage block of this size (in bytes).

See Also tibrvMsgDataType on page 370

tibrvMsgData_Converter on page 373
tibrvMsgData_Decoder on page 377
tibrvMsgData_Encoder on page 378

TIBCO Rendezvous C Reference

 tibrvMsgData_SetSize() 385
|

tibrvMsgData_SetSize()
Function

Declaration tibrv_status tibrvMsgData_SetSize(

char** buffer,
tibrv_u32 size);

Purpose Write the size of data into a wire buffer for an encoder.

Remarks This layer 1 function helps encoders write size information to a message’s wire
buffer. It does only part of the work that tibrvMsgData_CopyBytes() does (see
Figure 20 on page 386):
1. Write the size information into the wire buffer, starting at the position
*buffer.

2. Advance *buffer to point to the end of the size information, which will
become the start of the actual data.
3. Return.

After tibrvMsgData_SetSize() returns, the encoder can continue by writing the

data starting at the (advanced) position *buffer. We recommend using the more
complete function tibrvMsgData_CopyBytes() to write the size and data with
one call; when finer control is required, programmers can use this function
instead, with corresponding responsibility.
When using this function, the encoder must first use tibrvMsgData_ByteSize()
to measure the wire size from the data length.

Parameter Description
buffer The encoder supplies the address of a location within the
message’s wire buffer. This function writes the size into the
destination message, and advances this buffer pointer.

size Size to copy into the wire buffer.

TIBCO Rendezvous C Reference

386
| Appendix A Custom Datatypes

Figure 20 tibrvMsgData_SetSize

Before
*buffer

After
*buffer

See Also tibrvMsgData_ByteSize() on page 372

tibrvMsgData_CopyBytes() on page 375
tibrvMsgData_Encoder on page 378

TIBCO Rendezvous C Reference

 | 387

Appendix B Perl 5 Interface

Perl programs can directly call Rendezvous API functions using a Perl 5 loadable
module called Tibrv, which extends the Perl language.
To simplify Perl prototyping of Rendezvous applications in C, Rv presents Perl
programs with an interface that is identical to the C Rendezvous API.

Topics

• Features and Benefits, page 388

• Installing the Perl 5 Interface, page 389
• Using the Perl 5 Interface, page 390
• Perl Example Programs, page 391

TIBCO Rendezvous C Reference

388
| Appendix B Perl 5 Interface

Features and Benefits

Tibrv presents the C API. All API details (for example, function names,
parameter lists, types, return codes) are the same as for C programs, so Perl
programmers can use it to:
• Prototype Rendezvous applications in Perl for later translation into C.
• Write Rendezvous applications in Perl for short-term use.

System administrators often choose Perl for data organization tasks. Combining
Perl with Rendezvous software yields a powerful tool for:
• Gathering and organizing information about the operation of distributed
systems.
• Administering physically distant computers across a network.

TIBCO Rendezvous C Reference

 Installing the Perl 5 Interface 389
|

Installing the Perl 5 Interface

For installation instructions, see the Rendezvous Perl README file:

rv_installation_dir/src/perl/README

TIBCO Rendezvous C Reference

390
| Appendix B Perl 5 Interface

Using the Perl 5 Interface

Be sure that the library path variable is set properly; for instructions, see the
README file.

Place this module reference near the top of each Perl program file that calls
Rendezvous API functions:
use Tibrv;

If the program uses Rendezvous fault tolerance features, add this module
reference:
use TibrvFt;

If the program uses Rendezvous certified message delivery features or distributed

queues, add this module reference:
use TibrvCm;

TIBCO Rendezvous C Reference

 Perl Example Programs 391
|

Perl Example Programs

The Rendezvous example directory (/src/examples/perl/) contains Perl

example programs.

TIBCO Rendezvous C Reference

392
| Appendix B Perl 5 Interface

TIBCO Rendezvous C Reference

 Index 393
|

Index

A callback function 133

certified delivery 281
accept, create virtual circuit 232 destroy complete
action, fault tolerance 243 CM transport 293
activate, fault tolerance 243 event 134
add fault tolerance 247
event queue to a queue group 191 monitor 261
listener, certified delivery 294 queue 171
message field 56 fault tolerance 245
array 61 monitor 260
datetime 67 ledger review, certified delivery 317
extended functions 57 message vector 137
nested message 63 certificate
opaque bytes 65 set daemon certificate 25
scalar 59 set user certificate 27, 28
string 64 certified delivery
XML 66 add listener 294
advisory message, see TIBCO Rendezvous Concepts allow listener 295
allow listener 295 confirm 283, 291
array connect to relay agent 296
add 61 destroy complete, transport 293
get 88 destroy listener 286
update 119 destroy transport 302
disallow listener 303
disconnect from relay agent 304
event 280
B expire messages 305
get
backward compatibility. See, release 5. ledger name 307
batch mode 228 message time limit 329
batch mode (type) 210 name from transport 308
relay agent 309
request old 310
sender name from message 326
C sequence number from message 327
sync ledger 311
C datatypes 350 transport 312

TIBCO Rendezvous C Reference

394
| Index
transport time limit 306 create
listener, create 284 certified delivery listener 284
remove listener 313 dispatcher thread 202
remove send state 315 distributed queue 334
review ledger 316 fault tolerance member 249
send 319 fault tolerance monitor 263
reply 320 I/O interest 138
request 321 inbox 214
set listener 140
message time limit 330 message 70
transport time limit 323 queue group 192
sync ledger 325 queue, event 172
transport 292 timer 143
create 298 transport 211
character encoding, See enconding certified delivery 298
checklist, programmer’s 2 virtual circuit accept 232
clear references 68 virtual circuit connect 235
close, environment 17 with embedded license 213
closure vector listener 146
get from message 79 current time, get 80
code pages 21 custom datatypes 361
compatibility. See, release 5. custom event manager hook 169
complete time customer support xxvi
get 339
set 343
complete, destroy
CM transport 293 D
event 134
fault tolerance member 247 daemon 217
fault tolerance monitor 261 data
queue 171 message field accessors 55
confirm, certified delivery 283, 291 union type 50
connect to relay agent 296 validity of snapshot 41
connect, create virtual circuit 235 datatypes 347
control, message storage 40 C 350
conversion, datatype 352 conversion 352
convert message to string 69 custom 361
converter 373 register handlers 369
copy message 71 low-level reference 370
correspondent, get name 308 wire format 348
count datetime, type definition 53
events in a queue 175 deactivate, fault tolerance 243
field, array items or string length 55 decoder 377
fields in a message 103 default event queue 168
delete field. See, remove.

TIBCO Rendezvous C Reference

 Index 395
|
description 218, 230 event
destroy callback function 133
certified delivery transport 302 certified delivery callback function 281
completion callback function 134 certified delivery, type 280
dispatcher thread 204 destroy 151
event 151 extended 152
extended 152 destroy complete, callback function 134
fault tolerance member 252 discard 177, 183
fault tolerance monitor 265 dispatch 174
message 73 get from message 81
queue 173 message vector callback function 137
queue group 193 poll queue 180
transport 216 queue 163
detach message 74 queue, get from event 159
disallow listener 303 certified delivery 290
discard events 177, 183 timed dispatch 187
disconnect from relay agent, certified delivery 304 type 132
dispatch type token 161
queue 174 get 158
queue group 194 event driver 19
dispatchable, type 200 event queue hook function
dispatcher thread 201 get 176
create 202 remove 181
destroy 204 set 182
distributed queue event queue, default 168
create 334 expand message, reallocate storage 75
get complete time 339 expire messages, certified delivery 305
get worker tasks 342 extended functions
get worker weight 341 add 57
set complete time 343 get 84
set scheduler task queue limits 344 update 116
set worker tasks 346 extract. See get.
set worker weight 345

E
EBCDIC 21
embedded license 213
encoder 378
encoding 49
error codes 356

TIBCO Rendezvous C Reference

396
| Index

F nested message 121

opaque bytes 123
fault tolerance scalar 117
action token 243 string 122
create member 249 XML 124
create monitor 263 fields, number in a message 103
destroy member 252 format message as string 69
destroy monitor 265 free message storage 73
group name 254, 266
join 249
member callback function 245
member destroy complete callback 247 G
monitor callback function 260
monitor destroy complete callback 261 get
queue 255, 267 byte size of message 78
transport 256, 268 certified delivery
weight 257 ledger name 307
set 258 name 308
withdraw 252 relay agent 309
field request old 310
add to message 56 sync ledger 311
array 61 transport 312
datetime 67 closure from message 79
nested message 63 complete time of distributed queue 339
opaque bytes 65 current time 80
scalar 59 daemon from transport 217
string 64 description from transport 218
XML 66 dispatcher thread name 205
get 82 event from message 81
array 88 event queue hook function 176
datetime 98 extended functions 84
nested message 90 I/O source from event 153
opaque bytes 94 I/O type from event 154
scalar 86 interval from timer 157
string 92 message field 82
XML 96 array 88
get by index 100 datetime 98
get instance from message 101 nested message 90
names and identifiers 46 opaque bytes 94
remove 108 scalar 86
remove instance 110 string 92
type definition 55
update in message 114
array 119
datetime 125

TIBCO Rendezvous C Reference

 Index 397
|
XML 96 instance, get field 101
message field by index 100 interval
message field instance 101 get from timer 157
network from transport 219 reset timer 160
queue from event 159 intra-process transport 209
certified delivery 290 IPM
queue from fault tolerance member 255 batch size 229
queue from fault tolerance monitor 267 checklist 2
reply subject 104 library 14
send subject 105 test for 18
service from transport 220 tibrv_Open() 19
subject from listener 155
transport from fault tolerance member 256
transport from fault tolerance monitor 268
transport from listener 156 J
certified delivery 288, 289
type of event 158 join, create fault tolerance member 249
weight from fault tolerance member 257
get group name
fault tolerance member 254
fault tolerance monitor 266 L
get unassigned task count 340
group of event queues 190 Latin-1
ledger
file, tibrvcmTransport_Create() parameter 300
name, get from certified delivery transport 307
H review 316
library files 5
handlers, set custom datatype 369 licensed transport 213
header files 4 limit, queue 177, 183
hook, event queue 169 linking 5
listener
create 140
certified delivery 284
I destroy
certified delivery 286
I/O subject, get 155
create event interest 138 transport, get 156
source, get 153 certified delivery 288, 289
type 162 vector, create 146
type, get 154 listener, distributed queue. See, worker.
IBM i 12 local data 50
ID, field identifier 46, 55 loop, get field by index
inbox, create 214 lost interval 264
include 4

TIBCO Rendezvous C Reference

398
| Index

M mark 106
remove field 108
malloc message storage for custom datatype 384 remove field instance 110
mark references 106 reply subject
maximum events, queue 177, 183 get 104
member, fault tolerance 244 set 112
callback function 245 reset 111
create 249 send subject
destroy 252 set 113
group name 254 send subject, get 105
queue 255 size 78
transport 256 type definition 52
weight 257 update field 114
set 258 array 119
message datetime 125
add field 56 nested message 121
array 61 opaque bytes 123
datetime 67 scalar 117
nested message 63 string 122
opaque bytes 65 XML 124
scalar 59 message field, type definition 55
string 64 monitor, fault tolerance 259
XML 66 callback 260
copy 71 create 263
create 70 destroy 265
create from data bytes 72 group name 266
destroy 73 queue 267
detach 74 transport 268
expand 75
format as string 69
get data as a byte sequence 77
get data as a byte string 76 N
get field 82
array 88 name
datetime 98 certified delivery, get sender from message 326
nested message 90 dispatcher thread 205, 206
opaque bytes 94 get from certified delivery transport 308
scalar 86 of a certified delivery transport 300
string 92 of a queue 178, 185
XML 96 name, of a field 55
get field by index 100 nested message, add field to message 63
get field instance 101 network 219
ownership and control 40 new. See, create.
references number of fields in a message 103
clear 68

TIBCO Rendezvous C Reference

 Index 399
|

O queue group
add 191
open, environment 19 create 192
overflow, queue 170, 177, 183 destroy 193
ownership, message storage 40 dispatch 194
poll 195
remove 196
timed dispatch 197
P type 190
queue, default 168
PEM 27
PKCS #12 28
policy
queue limit 170, 177, 183 R
poll
queue 180 raw storage device, as ledger file 300
queue group 195 reallocate 75
prepare-to-activate, fault tolerance 243 references
priority, queue 179, 186 clear 68
process transport 209 mark 106
programming environment 2 register custom datatype 369
relay agent
connect to 296
disconnect from 304
Q get from certified delivery transport 309
release 5, interaction
queue CM sequence numbers
count 175 several fields with same name
create 172 reliability, request 221
destroy 173 remove
destroy complete, callback function 171 event queue from a queue group 196
discard 177, 183 event queue hook function 181
dispatch 174 field from message 108, 108
fault tolerance member 255 field instance from message 110
fault tolerance monitor 267 listener, certified delivery 313
get from event 159 send state, certified delivery 315
certified delivery 290 reply subject
hook 169 get 104
limit policy 170, 177, 183 set 112
maximum events 177, 183 reply, send 225
name 178, 185 certified delivery 320
poll 180 request old messages, get from certified delivery
priority 179, 186 transport 310
timed dispatch 187 request reliability 221
type 168

TIBCO Rendezvous C Reference

400
| Index
request, send 226 set
certified delivery 321 batch mode of transport 228
reset code pages 21
message 111 complete time of distributed queue 343
timer interval 160 description of transport 230
return codes 356 dispatcher thread name 206
review ledger 316 event queue hook function 182
callback function 317 reply subject 112
secure daemon certificate 25
send subject 113
timer interval 160
S user certificate 27, 28
user name with password 29
scalar weight of fault tolerance member 258
add 59 set batch size, IPM 229
get 86 size
update 117 field 55
secure daemon message 78
set daemon certificate 25 snapshot, data 41
set user certificate 27, 28 source, get from I/O event 153
set user name 29 start 19
send 223 status codes 356
certified delivery 319 string encoding
reply 320 EBCDIC 21
request 321 string encoding, See encoding
reply 225 string, format message as 69
request 226 subject
send subject get from listener 155
get 105 maximum length of name 112, 113
set 113 reply
send vector 224 get 104
sequence number, certified delivery 327 set 112
service, get from transport 220 send
get 105
set 113
support, contacting xxvi
sync ledger
certified delivery 325
get from certified delivery transport 311

TIBCO Rendezvous C Reference

 Index 401
|

T tibrvcmTransport_GetWorkerTasks() 342
tibrvcmTransport_GetWorkerWeight() 341
task capacity tibrvcmTransport_RemoveListener() 313
get 342 tibrvcmTransport_RemoveSendState() 315
set 346 tibrvcmTransport_ReviewLedger() 316
technical support xxvi tibrvcmTransport_Send() 319
thread, create dispatcher 202 tibrvcmTransport_SendReply() 320
TIBCO_HOME xxiii tibrvcmTransport_SendRequest() 321
tibrv_Close() 17 tibrvcmTransport_SetCompleteTime() 343
TIBRV_DEFAULT_QUEUE 168 tibrvcmTransport_SetDefaultCMTimeLimit() 323
tibrv_IsIPM() 18 tibrvcmTransport_SetPublisherInactivityDiscardInter
tibrv_Open() 19 val() 324
tibrv_SetCodePages() 21 tibrvcmTransport_SetTaskBacklogLimitInBytes() 344
tibrv_status (type) 356 tibrvcmTransport_SetTaskBacklogLimitInMessages()
tibrv_Version() 24, 243, 243 344
tibrvcm_Version() 279 tibrvcmTransport_SetWorkerTasks() 346
tibrvcmEvent (type) 280 tibrvcmTransport_SetWorkerWeight() 345
tibrvcmEvent_ConfirmMsg() 283 tibrvcmTransport_SyncLedger() 325
tibrvcmEvent_CreateListener() 284 tibrvcmTransportOnComplete (function type) 293
tibrvcmEvent_Destroy 286 tibrvDispatchable (type) 200
tibrvcmEvent_GetListenerTransport() 288, 289 tibrvDispatcher (type) 201
tibrvcmEvent_GetQueue() 290 tibrvDispatcher_Create() 202
tibrvcmEvent_SetExplicitConfirm() 291 tibrvDispatcher_Destroy() 204
tibrvcmEventCallback (type) 281 tibrvDispatcher_GetName() 205
tibrvcmReviewCallback 317 tibrvDispatcher_SetName() 206
tibrvcmTransport (type) 292 tibrvEvent (type) 132
tibrvcmTransport_AddListener() 294 tibrvEvent_CreateIO() 138
tibrvcmTransport_AllowListener() 295 tibrvEvent_CreateListener() 140
tibrvcmTransport_ConnectToRelayAgent() 296 tibrvEvent_CreateTimer() 143
tibrvcmTransport_Create() 298 tibrvEvent_CreateVectorListener() 146
tibrvcmTransport_CreateDistributedQueue() 334 tibrvEvent_Destroy() 151
tibrvcmTransport_Destroy() 302 tibrvEvent_DestroyEx() 152
tibrvcmTransport_DisallowListener() 303 tibrvEvent_GetIOSource() 153
tibrvcmTransport_DisconnectFromRelayAgent 304 tibrvEvent_GetIOType() 154
tibrvcmTransport_ExpireMessages() 305 tibrvEvent_GetListenerSubject() 155
tibrvcmTransport_GetCompleteTime() 339 tibrvEvent_GetListenerTransport() 156
tibrvcmTransport_GetDefaultCMTimeLimit() 306 tibrvEvent_GetQueue() 159
tibrvcmTransport_GetLedgerName() 307 tibrvEvent_GetTimerInterval() 157
tibrvcmTransport_GetName() 308 tibrvEvent_GetType() 158
tibrvcmTransport_GetRelayAgent() 309 tibrvEvent_ResetTimerInterval() 160
tibrvcmTransport_GetRequestOld() 310 tibrvEventCallback (type) 133
tibrvcmTransport_GetSyncLedger() 311 tibrvEventOnComplete (type) 134
tibrvcmTransport_GetTransport() 312 tibrvEventType 161
tibrvcmTransport_GetUnassignedMessageCount() 34 tibrvEventVectorCallback (type) 137
0 TIBRVFT_ACTIVATE 243

TIBCO Rendezvous C Reference

402
| Index
TIBRVFT_DEACTIVATE 243 tibrvMsg_Get convenience functions
TIBRVFT_PREPARE_TO_ACTIVATE 243 array 88
tibrvft_Version() 242 datetime 98
tibrvftAction 243 nested message 90
tibrvftMember (type) 244 opaque bytes 94
tibrvftMember_Create() 249 scalar 86
tibrvftMember_Destroy() 252 string 92
tibrvftMember_GetGroupName() 254 XML 96
tibrvftMember_GetQueue() 255 tibrvMsg_GetAsBytes() 76
tibrvftMember_GetTransport() 256 tibrvMsg_GetAsBytesCopy() 77
tibrvftMember_GetWeight() 257 tibrvMsg_GetByIndex() 100
tibrvftMember_SetWeight() 258 tibrvMsg_GetByteSize() 78
tibrvftMemberCallback 245 tibrvMsg_GetClosure() 79
tibrvftMemberOnComplete (function type) 247 tibrvMsg_GetCMSender() 326
tibrvftMonitor (type) 259 tibrvMsg_GetCMSequence() 327
tibrvftMonitor_Create() 263 tibrvMsg_GetCMTimeLimit() 329
tibrvftMonitor_Destroy() 265 tibrvMsg_GetCurrentTime() 80
tibrvftMonitor_GetGroupName() 266 tibrvMsg_GetEvent() 81
tibrvftMonitor_GetQueue() 267 tibrvMsg_GetField() 82
tibrvftMonitor_GetTransport() 268 tibrvMsg_GetInstance() 101
tibrvftMonitorCallback 260 tibrvMsg_GetNumFields() 103
tibrvftMonitorOnComplete (function type) 261 tibrvMsg_GetReplySubject() 104
tibrvIOType 162 tibrvMsg_GetSendSubject() 105
tibrvLocalData, union type 50 tibrvMsg_MarkReferences() 106
tibrvMsg (type) 52 tibrvMsg_RemoveField() 108
tibrvMsg_Add convenience functions tibrvMsg_RemoveFieldInstance() 110
array 61 tibrvMsg_Reset() 111
datetime 67 tibrvMsg_SetCMTimeLimit() 330
nested message 63 tibrvMsg_SetHandlers() 369
opaque bytes 65 tibrvMsg_SetReplySubject() 112
scalar 59 tibrvMsg_SetSendSubject() 113
string 64 tibrvMsg_Update convenience functions
XML 66 array 119
tibrvMsg_AddField() 56 datetime 125
tibrvMsg_ClearReferences() 68 nested message 121
tibrvMsg_ConvertToString() 69 opaque bytes 123
tibrvMsg_Create() 70 scalar 117
tibrvMsg_CreateCopy() 71 string 122
tibrvMsg_CreateFromBytes() 72 XML 124
tibrvMsg_Destroy() 73 tibrvMsg_UpdateField() 114
tibrvMsg_Detach() 74 tibrvMsgData_ByteSize() 372
tibrvMsg_Expand() 75 tibrvMsgData_Converter() 373
tibrvMsgData_CopyBytes() 375
tibrvMsgData_Decoder() 377
tibrvMsgData_Encoder() 378

TIBCO Rendezvous C Reference

 Index 403
|
tibrvMsgData_GetBytes() 380 tibrvTransport_Destroy() 216
tibrvMsgData_GetSize() 382 tibrvTransport_GetDaemon() 217
tibrvMsgData_Malloc() 384 tibrvTransport_GetDescription() 218
tibrvMsgData_SetSize() 385 tibrvTransport_GetNetwork() 219
tibrvMsgDataType 370 tibrvTransport_GetService() 220
tibrvMsgDateTime (type) 53 tibrvTransport_RequestReliability() 221
tibrvMsgField (type) 55 tibrvTransport_Send() 223
tibrvQueue (type) 168 tibrvTransport_SendReply() 225
tibrvQueue_Create() 172 tibrvTransport_SendRequest() 226
tibrvQueue_Destroy() 173 tibrvTransport_Sendv() 224
tibrvQueue_Dispatch() 174 tibrvTransport_SetBatchMode() 228
tibrvQueue_GetCount() 175 tibrvTransport_SetBatchSize 229
tibrvQueue_GetHook() 176 tibrvTransport_SetDescription() 230
tibrvQueue_GetLimitPolicy() 177 tibrvTransport_WaitForVcConnection() 237
tibrvQueue_GetName() 178 tibrvTransportBatchMode (type) 210
tibrvQueue_GetPriority() 179 time limit, certified delivery 306, 323, 329, 330
tibrvQueue_Poll() 180 time, get 80
tibrvQueue_RemoveHook() 181 timed dispatch
tibrvQueue_SetHook() 182 queue 187
tibrvQueue_SetLimitPolicy() 183 queue group 197
tibrvQueue_SetName() 185 timer
tibrvQueue_SetPriority() 186 create 143
tibrvQueue_TimedDispatch() 187 get interval 157
tibrvQueueGroup (type) 190 reset interval 160
tibrvQueueGroup_Add() 191 transport 209
tibrvQueueGroup_Create() 192 batch mode 210
tibrvQueueGroup_Destroy() 193 batch mode, set 228
tibrvQueueGroup_Dispatch() 194 certified delivery 292
tibrvQueueGroup_Poll() 195 create 211
tibrvQueueGroup_Remove() 196 licensed 213
tibrvQueueGroup_TimedDispatch() 197 daemon, get 217
tibrvQueueHook (function type) 169 description, get 218
tibrvQueueLimitPolicy 170 description, set 230
tibrvQueueOnComplete (type) 171 destroy 216
tibrvSecureDaemon_SetDaemonCert() 25 certified delivery 302
tibrvSecureDaemon_SetUserCertWithKey() 27 fault tolerance member 256
tibrvSecureDaemon_SetUserCertWithKeyBin() 28 fault tolerance monitor 268
tibrvSecureDaemon_SetUserNameWithPassword() 29 get from certified delivery transport 312
tibrvStatus_GetText() 360 get from listener 156
tibrvTransport (type) 209 certified delivery 288, 289
tibrvTransport_Create() 211 network, get 219
tibrvTransport_CreateAcceptVc() 232 request reliability 221
tibrvTransport_CreateConnectVc() 235 send 223
tibrvTransport_CreateInbox() 214 reply 225
tibrvTransport_CreateLicensed() 213

TIBCO Rendezvous C Reference

404
| Index
request 226 W
send vector 224
service, get 220 wait, for virtual circuit connection 237
virtual circuit weight
create accept 232 fault tolerance member 257
create connect 235 set 258
wait for connection 237 wire format datatypes 348
type 347 withdraw, destroy fault tolerance member 252
C 350 worker task capacity of distributed queue 342, 346
datetime 53 worker weight of distributed queue 341, 345
get from event 158
get from I/O event 154
message 52
of a field 55 X
of events 161
of I/O conditions 162 XML
wire format 348 add 66
get 96
update 124

U
unassigned tasks 340
update
extended functions 116
message field 114
array 119
datetime 125
nested message 121
opaque bytes 123
scalar 117
string 122
XML 124
user datatypes 361
user name and password, set 29

V
validity, data 41
vector listener, create 146
version 24, 242, 243, 243, 279
virtual circuit, wait for connection 237

TIBCO Rendezvous C Reference