tsc_Database (custom records)

Available in SC version 2.10 and higher.

These methods are part of the tsc_Database class, and support custom database records.

An introduction to the subject of custom data can be found on the page Adding custom data to the job database.

Public methods

int AppendCustomRecord (tsc_DatabaseCustomType& customData);
This method adds a "lone" custom XML record to the end of the database.  This type of record is useful for logging events or to provide an audit trail, but because these records are not easily read, they are recommended as write-only, however they do appear in exported JXL format files. The RecordId is returned which does allow the record to be read back in.  If an error occurs during the append, -1 is returned.

Warning: Avoid storing the record ID persistently, since the user's database may be converted to XML and back again in various situations. In almost every such case, the ID of the records in the database will change, rendering any stored record IDs useless. The ID will remain valid while the job is open.

x_Code ReadCustomRecord (int recordId, tsc_DatabaseCustomType& deSerializeInto);
Reads a "lone" custom record, given the ID of the record and a custom type to deserialize into.  The database record must of the same type as the supplied type subclass (GUID and name match) or an error occurs and X_Type is returned.

int AddCustomSubRecord (tsc_Entity addTo, tsc_DatabaseCustomType& customData);
Adds a custom sub-record to the given tsc_Entity.  Supply the entity to which the custom data is to be added, and the required type of the custom data whose serialize function is used to create the XML.  Sub-records are kept in the same sequence in the database as they were added to the entity.

Warning: Avoid storing the record ID persistently, since the user's database may be converted to XML and back again in various situations. In almost every case, the ID of the records in the database will change, rendering any stored record IDs useless. The ID will remain valid while the job is open.

x_Code ReplaceCustomSubRecord (tsc_Entity replaceIn, int existingRecordId, tsc_DatabaseCustomType& replacement);
x_Code ReplaceCustomSubRecord (tsc_DatabaseCustomXml& toUpdate, tsc_DatabaseCustomType& updated);
These two methods allow a sub-record to be replaced.  The sub-record maintains it's sequence in the list of sub-records attached to the entity.  The first overload addresses the record to be replaced by entity and record ID, the second specifies the record to be replaced by supplying the old one.

In the first form, the replaceIn entity must be the original parent entity, recordId should be obtained from the original record (the one being replaced), and the type and xml are supplied as required.

The return value will be X_NULL for a successful replacement, or some x_Code indicating the problem.

x_Code RemoveCustomSubRecord (tsc_Entity deleteFrom, int existingRecordId);
x_Code RemoveCustomSubRecord (tsc_DatabaseCustomXml& remove);
These two methods are used to remove a sub-record from a database entity.  The first form requires the entity to which the record is attached, and the ID of the record.  The second simply requires the sub-record as it was read.