Open topic with navigation

TIBCO Rendezvous® 8.7.0

# TibrvCmTransport::create()

Method

## Declaration

    TibrvStatus create(
        TibrvTransport* transport);
    TibrvStatus create(
        TibrvTransport* transport,
        const char* cmName,
        tibrv_bool  requestOld,
        const char* ledgerName = NULL,
        tibrv_bool  syncLedger = TIBRV_FALSE);

## Purpose

Create a transport for certified delivery.

## Remarks

This method creates a C certified delivery transport and stores its handle in the C++ object.

The new certified delivery transport must employ a valid transport for network communications.

The certified delivery transport remains valid until the program explicitly destroys it.

Parameter | Description
`transport` | The new TibrvCmTransport employs this transport object for network communications. Despite the declaration as a TibrvTransport, this object must be an instance of TibrvNetTransport. In particular, it cannot be the TibrvProcessTransport nor TibrvVcTransport. Destroying the TibrvCmTransport does not affect this TibrvTransport object.
`cmName` | Bind this reusable name to the new TibrvCmTransport, so the TibrvCmTransport represents a persistent correspondent with this name. If non-`NULL`, the name must conform to the syntax rules for Rendezvous subject names. It cannot begin with reserved tokens. It cannot be a non-reusable name generated by another call to TibrvCmTransport::create(). It cannot be the empty string. If omitted or `NULL`, then TibrvCmTransport::create() generates a unique, non-reusable name for the duration of the transport. For more information, see Name.
`requestOld` | This parameter indicates whether a persistent correspondent requires delivery of messages sent to a previous certified delivery transport with the same name, for which delivery was not confirmed. Its value affects the behavior of other CM sending transports. If this parameter is `TIBRV_TRUE` and `cmName` is non-`NULL`, then the new TibrvCmTransport requires certified senders to retain unacknowledged messages sent to this persistent correspondent. When the new TibrvCmTransport begins listening to the appropriate subjects, the senders can complete delivery. (It is an error to supply `true` when `cmName` is `NULL`.) If this parameter is `TIBRV_FALSE` (or omitted), then the new TibrvCmTransport does not require certified senders to retain unacknowledged messages. Certified senders may delete those messages from their ledgers.
`ledgerName` | If this argument is non-`NULL`, then the new TibrvCmTransport uses a file-based ledger. The argument must represent a valid file name. Actual locations corresponding to relative file names conform to operating system conventions. We strongly discourage using the empty string as a ledger file name. If omitted or `NULL`, then the new TibrvCmTransport uses a process-based ledger. For more information, see Ledger File.
`syncLedger` | If this argument is `TIBRV_TRUE`, then operations that update the ledger file do not return until the changes are written to the storage medium. If this argument is `TIBRV_FALSE` (or omitted), the operating system writes changes to the storage medium asynchronously.

## Method Forms

With only a transport, create a transient correspondent, with a unique, non-reusable name. (Supplying `NULL` as the `cmName` has the same effect.)

All other parameters are optional, with default values when omitted.

## Name

If `cmName` is `NULL`, then TibrvCmTransport::create() generates a unique, non-reusable name for the new certified delivery transport.

If `cmName` is non-`NULL`, then the new transport binds that name. A correspondent can persist beyond transport destruction only when it has both a reusable name and a file-based ledger.

For more information about the use of reusable names, see CM Correspondent Name in TIBCO Rendezvous Concepts, and Persistent Correspondents in TIBCO Rendezvous Concepts. For details of reusable name syntax, see Reusable Names in TIBCO Rendezvous Concepts.

## Ledger File

Every certified delivery transport stores the state of its certified communications in a ledger.

If `ledgerFile` is `NULL`, then the new transport stores its ledger exclusively in process-based storage. When you destroy the transport or the process terminates, all information in the ledger is lost.

If `ledgerFile` specifies a valid file name, then the new transport uses that file for ledger storage. If the transport is destroyed or the process terminates with incomplete certified communications, the ledger file records that state. When a new transport binds the same reusable name, it reads the ledger file and continues certified communications from the state stored in the file.

Even though a transport uses a ledger file, it may sometimes replicate parts of the ledger in process-based storage for efficiency; however, programmers cannot rely on this replication.

The `syncLedger` parameter determines whether writing to the ledger file is a synchronous operation:

| • | To specify synchronous writing, supply `TIBRV_TRUE`. Each time Rendezvous software writes a ledger item, the call does not return until the data is safely stored in the storage medium.

| • | To specify asynchronous writing (the default), supply `TIBRV_FALSE`. Certified delivery calls may return before the data is safely stored in the storage medium, which results in greater speed at the cost of certainty. The ledger file might not accurately reflect program state in cases of hardware or operating system kernel failure (but it is accurate in cases of sudden program failure). Despite this small risk, we strongly recommend this option for maximum performance.

A program that uses an asynchronous ledger file can explicitly synchronize it by calling TibrvCmTransport::syncLedger().

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

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2023. Cloud Software Group, Inc. All Rights Reserved.