dt_thor_tdtget

Daylight v4.9
Release Date: 1 February 2008

Name

dt_thor_tdtget_raw - retrieve a TDT from a database as a string

Generic Prototype

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

C Prototype

#include "dt_thor.h"

dt_Handle dt_thor_tdtget_raw(dt_Handle database, dt_Integer taglen, dt_String tag, dt_Integer idlen, dt_String identifier, dt_Boolean writable)

FORTRAN Prototype

include 'dt_f_thor.inc'

integer*4 dt_f_thor_tdtget_raw(database, tag, identifier, writable)

integer*4 database
character*() tag
character*() identifier
logical writable

Description

Fetches a TDT directly from the database, and returns it in lexical form as a string object. The parameter 'tag' is not checked for validity (i.e. if there is no such datatype, nothing will be found and no warning issued), and the identifier is not standardized (i.e. normalizations like unique-SMILES, removing punctuation and whitespace, converting to uppercase, etc. that might be applied by dt_thor_tdtget(3) are not used here). In other words, you must use the exact tag and identifier as they appear in the database.

The parameter 'writable' only has effect if the database is one in which record locking is enforced (see dt_thor_settdtlocking(3)). If record locking is enforced and 'writable' is TRUE, then this function also locks the TDT. Note that this is true even if the TDT was not in the database to begin with. 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), dt_thor_tdtput_raw(3)), the database is closed, or the client disconnects from the THOR server. Deallocating the string object via dt_dealloc(3) does NOT remove the lock.

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

Return Value