Name

Generic Prototype

C Prototype

dt_Integer dt_thor_tdtput(dt_Handle tdt, dt_Boolean how)

FORTRAN Prototype

integer*4 dt_f_thor_tdtput(tdt, how)

integer*4 tdt
integer*4 how

Description

The parameter 'how' controls what is to be done with existing data in the database. Its meaning depends on whether record locking is in effect for the database (see dt_settdtlocking(3)).

When no record locking is in effect, the parameter 'how' determines how new data and existing data are handled. It can take one of three values:

DX_THOR_WRITE

The TDT replaces the existing data in the database (no merging). If the timestamp in 'tdt' is older than the timestamp of the TDT it is replacing, then the write fails and the database is unchanged. If the timestamp in 'tdt' is the same as or newer than the one being replaced, and the write takes place.

The object 'tdt' is written to the database, overwriting existing data even if the existing data in the database is newer. This option should be used with caution.

The TDT in the database is retrieved, and its data are merged with data in the object 'tdt'. If the TDT contains other identifiers (subtrees) and these identifiers are found as separate (non-SMILES) TDTs in the database, they are "subsumed" by this TDT. That is, they are merged into this TDT and the separate TDTs are removed from the database. Finally, the contents of 'tdt' (which now is merged with existing data from the database) replace the existing TDT in the database.

The object 'tdt' is merged with existing data in the database as described for DX_THOR_MERGE above. The "transformations" described below are also applied. The TDT is NOT stored in the database. In other words, except for the actual timestamp dataitem, the TDT will be revised exactly as it would be if actually written, but no write operation takes place.

DX_THOR_WRITE_KEEPLOCK

Write the record to the database (as described for DX_THOR_WRITE, above), but keep the record locked for exclusive access. This has the effect of writing the record but not "committing" it -- the "rollback" operation below can restore the original record. Furthermore, the modifications to the record are only visible to the client that holds the lock; all other clients will see the original record until the changes are "committed" via an unlock operation. If the record was not locked to begin with, a lock is created.

Merge the record with existing data in the database (as described for DX_THOR_WRITE_MERGE, above), but keep the record locked for exclusive access. This operation may also have the effect of locking other "subsumed" records in the database as they are incorporated into the TDT being stored. As with DX_THOR_WRITE_KEEPLOCK, above, the record is not "committed", and modifications are only visible to the client that holds the lock. If the record was not locked to begin with, a lock is created.

Like DX_THOR_OVERWRITE, but keeps the record locked, as described for DX_THOR_WRITE_KEEPLOCK, above.

Unlock the record and "commit" it to the database. The TDT object's current contents are ignored (except for the "root" identifier itself) -- only changes made with a prior "write" operation take effect. The TDTs timestamp is set to reflect the time of the unlock operation. Once the record is unlocked, the "rollback" operation is no longer possible. If the record was not locked, no action is taken. If other records were subsumed by this one, they are also unlocked and committed to the database.

Undo all changes that were made to the record and written to the database since the lock was set, and keep the record locked. A "rollback" allows you to undo changes if problems are detected after the record is modified, but before it is unlocked. The record is restored to the exact state (including the original timestamp) that it was when the record was locked (see dt_thor_tdtget(3)). If the record was not locked, the operation fails and no action is taken. If other records were "subsumed" by this one and thus locked, they are returned to their original state and unlocked. Note that the TDT object itself is not altered by the rollback -- you can "undo the rollback" by writing the TDT object to the database again.

1. If the root identifier is not a SMILES and there are no SMILES subtrees, but a SMILES can be found somewhere in the datatree (as defined by the USMILES or ASMILES normalizations), create a new root identifier with that SMILES.

2. If TDT's root id is not a SMILES but there is SMILES subtree, "demote" the non-SMILES root identifier and its dataitems to a subtree, and "promote" the SMILES subtree to the root of the TDT.

3. For each datafield marked with the USMILES or ASMILES normalization, confirm that its unique SMILES is the same as the root SMILES of the datatree.

4. If a $ISM is identical to the root $SMI (i.e. it has no isotopic or isomeric information), merge its data with the root identifier and discard the $ISM subtree.

5. Do a "unique sort" of the datatree to eliminate all redundancy. This combines subtrees with the same identifier, and tosses out identical dataitems within a subtree.

6. If the root is not $SMI, issue an error message if there are any subtrees.

7. Delete all timestamp ("TS<>") dataitems, and add a new one with the current time. (All times are Coordinated Universal Time, also known as "GMT". Local time is never used.)

Return Value

Related Topics