dt_thor_tdtget

Daylight v4.9
Release Date: 1 February 2008

Name

dt_thor_tdtget - retrieve a TDT from a database

Generic Prototype

dt_thor_tdtget(dt_Handle, dt_Handle, dt_String, dt_Boolean, dt_Boolean)
=> dt_Handle

C Prototype

#include "dt_thor.h"

dt_Handle dt_thor_tdtget(dt_Handle parent, dt_Handle datatype, dt_Integer len, dt_String identifier, dt_Boolean writable, dt_Boolean *isnew)

FORTRAN Prototype

include 'dt_f_thor.inc'

integer*4 dt_f_thor_tdtget(parent, datatype, identifier, writable, isnew)

integer*4 parent
integer*4 datatype
character*() identifier
logical writable
logical isnew

Description

Gets or creates a THOR datatree (TDT) object from the object 'parent', which must be a database or TDT. The TDT's root identifier will be the datatype/identifier represented by 'datatype' and 'identifier', with 'identifier' standardized according to the specifications for the datatype object 'datatype'. If 'parent' is a database, the datatype/identifier will be the root of a TDT; if 'parent' is a TDT, the datatype/identifier will be for a subtree.

The parameter 'writable' indicates whether modification of the TDT is permitted. If FALSE, the TDT is marked "read-only" and attempts to modify it or write it back to the database fail. If TRUE, the TDT is marked "writable" and modifications are allowed. If the database is opened read-only, 'writable' is ignored -- the TDT is always read-only.

If 'writable' is TRUE and the database is one in which record locking is enforced (see dt_thor_settdtlocking(3)), then this function also locks the TDT, unless another client already has the lock in which case this function fails (returns NULL_OB). Note that this is true even if the TDT was not in the database to begin with (see the 'isnew' parameter, described below).

A client that locks a TDT has exclusive write access to that TDT as long as the lock exists; no other client can modify or delete the TDT, or even get a writable TDT object (attempts to do so result in a "Record is locked" error message). The TDT remains locked until it is explicitly unlocked (see dt_thor_tdtput(3)), the database is closed, or the client disconnects from the THOR server. Deallocating the TDT object via dt_dealloc(3) does NOT remove the lock.

It is not possible to lock a subtree. That is, if locking is enforced but 'parent' is a TDT rather than a database, then no lock is set. You can only lock whole TDTs.

It is permissible to re-retrieve a TDT that is already locked. For example, one could use dt_thor_tdtget(3) from a database in which record-locking is enforced (thus locking the TDT), deallocate the TDT object, then use dt_thor_tdtget(3) again. The lock would remain in effect, whether the 'writable' parameter was TRUE or FALSE on the second invocation of dt_thor_tdtget(3).

The return parameter 'isnew', when TRUE, indicates that the TDT is brand new. In this case, the parent didn't contain the requested datatype/identifier, so a new one was created. If the return value is FALSE, the datatype/identifier was found and the TDT object returned represents existing data. Note that a newly-created TDT is not stored in the database until explicitly put there with dt_thor_tdtput(3).

The parameter 'writable' also controls whether a new TDT can be created:

     TDT found?  writable  isnew   Function returns
       NO         FALSE     FALSE     NULL_OB
       NO         TRUE      TRUE      New, writable TDT
       YES        FALSE     FALSE     Read-only TDT from DB
       YES        TRUE      FALSE     Writable TDT from DB

For root TDTs, if 'isnew' returns TRUE, the newly-created TDT will have no timestamp. This is effectively the same as a timestamp of 'eons ago', a date guaranteed to be older than any TDT in the database.

Return Value