tibrvcmTransport_Create()

Function

Declaration

tibrv_status tibrvcmTransport_Create(
    tibrvcmTransport*    cmTransport,
    tibrvTransport       transport,
    const char*          cmName,
    tibrv_bool           requestOld,
    const char*          ledgerName,
    tibrv_bool           syncLedge);

Purpose

Create a transport for certified delivery.

Remarks

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


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

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

Destroying a transport with a file-based ledger always leaves the ledger file intact; it neither erases nor removes a ledger file.