tsc_JobCustomEntities

Available in SC version 2.10 and higher.

This class provides methods to deal with Custom Entities in the SC database.

A Custom Entity is a fragment of XML data which can be added to the database, and later be found by name and read back.  Lists of custom entities can be obtained and filtered in various ways similarly to other entity types such as points.

An instance of tsc_JobCustomEntities may be obtained from the tsc_Database class for a given job.

Public methods

tsc_JobCustomEntities();
Constructs an empty instance.

tsc_CustomEntityList Snapshot (tsc_DatabaseCustomType& type);
Returns a list filled with a snapshot of all custom entities of the supplied type found in the database. Use this for iterating through custom entities in the job. The items in the list are in the sequence that the custom entities were added to the database, followed by those in any linked jobs.

tsc_CustomEntityList Snapshot (tsc_DatabaseCustomType& type, const char* key);
Obtains a snapshot of all custom entities of the indicated type, which match the supplied key case-sensitively. The items in the list are in the sequence that the custom entities were added to the database, followed by those in any linked jobs.  An empty string is a valid key.  If the search fails (no matching entities found) then the returned list is empty.  The list also contains deleted items; these can be removed by calling tsc_CustomEntityList::RemoveDeleted().

x_Code Append (tsc_DatabaseCustomType& type);
Appends a custom entity to the job, by calling the type's Serialize method and storing the resulting XML. The key of the record (the string by which it can be found later) must be present in the XML at the XML path given by the type. A return code of X_NULL indicates the record was successfully appended.

x_Code Replace (tsc_CustomEntity& victim, tsc_DatabaseCustomType& replacement);
Replaces the victim entity with the new entity supplied by the replacement and its Serialize method.  The type cannot be changed, and the value of the key in the supplied replacementXml must be equal to the original key. A return code of X_NULL indicates success.

x_Code Delete (tsc_CustomEntity& victim);
Deletes the custom entity. This is not a physical deletion, and the entity will still appear in snapshot lists with its Deleted flag set. A custom entity may be deleted and undeleted any number of times. A return code of X_NULL indicates a successful deletion. 

x_Code UnDelete (tsc_CustomEntity& victim);
Undeletes the custom entity, negating the effect of the Delete method. A return code of X_NULL indicates a successful deletion.

void ReadAt (int recordId, tsc_DatabaseCustomType& deSerializeInto);
Given the database record ID, reads the XML of the entity from the database and passes it to the type's DeSerialize method. The original type (including the version of the type used to write the record) is also passed to DeSerialize. After the Read has completed, the supplied deSerializeInto should have been updated with the record's contents, although what actually occurs is dependent on the type's overridden DeSerialize method.

tsc_Database Parent() const;
Returns a reference to the parent object - the database.