You are here: Native API > Reference Manual > Runtime Function Descriptions > d_trrobegin

d_trrobegin

Begin a Read-Only Transaction

Prototype

int32_t d_trrobegin(
    DB_TASK *task,
    int32_t  dbn, 
    TXID    *txid);

Parameters

task (input) A pointer to a DB_TASK structure.
dbn (input) The database number.
txid (output) Transaction ID.

Description

Function d_trrobegin is called to mark the beginning of a Read-Only Transaction (a multi-version concurrency control implementation). After calling this function, and until d_trroend is called, it will appear as though no changes are being made to this database. Although changes are permitted by other users, this task will only see its own version of the database. It can be viewed as a snapshot of the database at that moment in time.

A read-only-transaction may not be started when a normal transaction is active, and vice-versa. Locks are not required or permitted during a read-only-transaction.

Read-only-transactions may be used to increase system throughput when readers and writers may contend for the same records. If Read-Only Transactions are used to read records, they will not prevent write locks (as required by normal transactions) from being granted, facilitating quicker transactions.

Read-Only Transactions should be short-lived, because the TFS is required to keep cached copies of pages that have been changed by other tasks, so that this task can still "see" its own version.

The txid parameter will be set by this function to the transaction ID following the last one that has been applied to the database. That is, all transactions up to, but not including txid will be found in the database files during this Read-Only Transaction. This information is used to create database backups using a Read-Only Transaction method.

Currency Changes

None.

Locking Requirements

None.

User's Guide

Read-Only-Transactions

Locking Rules

Required Headers

#include "rdm.h"

Libraries

Library Name Description
rdmerdm10 RDMe Runtime Library

See Library Naming Conventions section for full library name and a list of library dependencies.

Return Codes

Value Name Description
0 S_OKAY A normal return; everything worked successfully
-76 S_ROTACTIVE A read-only transaction is already active.
-78 S_HASWRITELOCKS A read-only-transaction cannot start because the user holds exclusive locks.

See Also

d_trabort, d_trend, d_trroend

Example

d_trrobegin(task, 0, &txID);
    ...   /* generate orders report */
d_trroend(task);

Copyright © 2011, Raima Inc. All rights reserved.