tsc_Database

A tsc_Database instance is a member of an open tsc_Job.  The members of tsc_Job deal with the job as a whole - opening, closing, creating, etc - the metadata - while the tsc_Database class deals with the content of the job.

This content is an internal representation of the same information found in (e.g.) a JobXml file.  Indeed, a JobXml representation of most types of database objects can be obtained using tsc_Database methods.

A tsc_Database instance also contains objects that are attached to the open job, such as linked jobs and csv files.  These objects are all considered part of the database, but can be filtered out or otherwise detected through properties of the object.

Note however, that Custom records - which allow user-defined data to be stored in the job - are restricted to the main job. If any are present in a linked job, they will not be accessible through the main job's tsc_Database.

Public members

tsc_Job  Parent () const;
This returns a reference to the parent tsc_Job for this database.

Database entities

The database is divided into the various types of object that can be found there.  The database and the types it holds are members of the job and remain in scope as long the the tsc_Job instance exists and is open.

tsc_JobPoints    Points();
tsc_JobLines     Lines();
tsc_JobArcs      Arcs();
tsc_JobPolylines Polylines();
tsc_JobCustomEntities  CustomEntities();
Each of these methods returns a list of every entity of the given type in the database.  If the database is also the current job, then the list will also include all entities from linked files, except for CustomEntities() which only lists items in the main database, and never those in linked jobs.

tsc_EntityList MapSelections();
Survey Core has a graphical map window, and on this window database objects may be selected by clicking them, etc.  A list of the objects currently selected in the map can be obtained with this function.  Also see tsc_JobMap for other ways to interact with the map.

bool SetMapSelections (tsc_EntityList newSelection);
Replaces the list of the objects currently selected in the map with the supplied newSelection. This will result in the objects in the newSelection being highlighted in the map. Returns true if the selection was updated and false if this failed.

bool StoreFeatures (tsc_Entity& entity, tsc_EntityFeatures& features);
Adds or replaces the features and attributes of a database entity. Returns true on success.  All existing features and attributes are removed, so it is preferable to read them first using tsc_Entity::Features(), modify the returned features, and store the result back with StoreFeatures().

bool StoreNote (tsc_Entity& entity, tsc_String noteText);
Adds a note to a database entity. Returns true on success.

bool AppendNote (tsc_String noteText);
Appends an unattached note to the database. Returns true on success.

Custom data

Methods for dealing with custom database records and entities are documented on separate pages. These functions include the following:

int    AppendCustomRecord (tsc_DatabaseCustomType& customData);
x_Code ReadCustomRecord (int recordId, tsc_DatabaseCustomType& deSerializeInto);
int    AddCustomSubRecord (tsc_Entity addTo, tsc_DatabaseCustomType& customData);
x_Code ReplaceCustomSubRecord (tsc_Entity replaceIn, int existingRecordId,
sc_DatabaseCustomType& replacement);
x_Code ReplaceCustomSubRecord (tsc_DatabaseCustomXml& toUpdate, tsc_DatabaseCustomType& updated);
x_Code RemoveCustomSubRecord (tsc_Entity deleteFrom, int existingRecordId);
x_Code RemoveCustomSubRecord (tsc_DatabaseCustomXml& remove);

Current environments

tsc_TsEnvironment CurrentTsEnvironment();
This method returns the current total station environment for the database.  This includes station, instrument, target, atmospheric, and other correction information.  It must be used, for instance, to convert a raw total station observation to something more useful such as a polar coordinate from the station to the point measured.  See tsc_TsEnvironment for more information.

If the job is not open or contains no station setup then an empty environment will be returned.
Note that the environment will only be the one currently in use if called on the current job's tsc_Database.

tsc_GnssEnvironment CurrentGnssEnvironment();
This method returns the current GNSS environment for the database.  This includes survey and antenna information.  It must be used, for instance, to convert a raw ECEF or ECEF Deltas observations to something more useful such as a WGS84 coordinates of the point measured.  See tsc_GnssEnvironment for more information.

If the job is not open or contains no GNSS survey then an empty environment will be returned.
Note that the environment will only be the one currently in use if called on the current job's tsc_Database.

tsc_CogoEnvironment CurrentCogoEnvironment();

This method returns the current coordinate geoemtry environment for the database.  This includes coordinate system, job point and coordinate geometry settings.  See tsc_CogoEnvironment for more information.

If the job is not open then an empty environment will be returned.
Note that the environment will only be the one currently in use if called on the current job's tsc_Database.

XML access to database configuration objects

The following functions return a Job XML fragment for the current (ie, the most recently stored) database object of the given type.  The names and data types of the XML elements are documented in the Trimble Job XML schema(version 5.61). An example of any type of database object can be produced by creating a job using Trimble General Survey, creating objects of the desired type, exporting it as an XML file, and viewing the result. Use the schema URI from the top of an exported Job XML file to obtain a schema for the version you are working with.

These XML fragments may be modified by methods in the tsc_XmlElement class, however these will change only the XML, not the underlying database.

Note that the CurrentCoordinateSystemJxl method returns all seven coordinate system records.

The tsc_XmlElement that is returned by these functions is an internal representation of the XML data.  Properly formatted XML may be extracted from the tsc_XmlElement object by calling one of the ToString methods.

tsc_XmlElement CurrentJobPropertiesJxl();

tsc_XmlElement CurrentUnitsJxl();

tsc_XmlElement CurrentCorrectionsJxl();

tsc_XmlElement CurrentFeatureCodingJxl();

tsc_XmlElement CurrentCoordinateSystemJxl();

tsc_XmlElement CurrentBackgroundFilesJxl();

You can also send XML into the database to change the relevant configuration.  The required data must be JXL compatible and of the right schema - see the values retrieved from the database for examples.  An error x_Code is returned to help with debugging and success testing.  Note that some record types, such as the background files JXL, will trigger file loading that may take considerable time to complete.

Please be aware that the relative path filenames are generally referring to files in $(ProjectRootDir). Full paths will be accepted in most cases but consider the JXL job export format which other tools will use to retrieve your files with - most are configured to expect the data in the 'normal' place.  Also note that the JXL will be processed so backdrops will be loaded, missing backdrops will be stripped out, etc.

Currently supported XML inputs are:

x_Code CurrentFeatureCodingJxl  (tsc_XmlElement& newFeatureCoding);   // Use $(SharedDir) location.
x_Code CurrentBackgroundFilesJxl(tsc_XmlElement& newBackgroundFiles); // Use $(ProjectRootDir) location.
Sets the coordinate system for the job which will trigger recomputation of all calculated coordinates (a background or on-demand task).  See the output of CurrentCoordinateSystemJxl() for the format, you will need to follow this format closely in conjunction with the coordinate system record output in the FieldBook section of JXL files (refer to the Jxl Schema). 
Note: It is possible to include only the records you want to change - that is, SurveyCore will attempt to merge your new coordinate systems records into the database's existing set.

x_Code CurrentCoordinateSystemJxl(tsc_XmlElement& newCoordinateSystem);
Returns the JXL for the currently set coordinate system.

Schema version

static int JobXmlSchemaVersion();
This method returns the version number of the Job XML schema that is used with this build of the API.  This is always the latest version for the installed SDK; when updating the SDK from another version, any access to Job XML elements should be reviewed to ensure it is still correct.  In general, Job XML tries to be backwards compatible - elements and values are normally added and are rarely changed or removed.

The XML schema version is an integer value calulated as (majorVersion * 100 + minorVersion).  For example, 551 means Job XMLl version 5.51. This value reflects the schema version from the SDK used for the plugin build, not the version of Survey Core that the plugin is currently running with.  Survey Core supports all previous XML versions, and will always supply the version that the plugin was built with.

Database record access

Individual records in the job database can be accessed using the following methods.  Note that these records often do not represent an entire database entity such as a point, but instead provide small parts of objects such as an antenna height or a grid coordinate.  For the JXL representing a complete entity (eg, a point), use the appropriate method for the object, such as tsc_Entity::GetEntityJxl(), or CurrentCoordinateSystemJxl() in this class.

Each database record has a constant unique integer identifier which can be used to refer to the record at any time, or to iterate through a series of records.  A zero ID means "no record".

tsc_XmlElement GetRecordJxl (int recordId);
This method returns an XML fragment representing the record. This method provides access to almost anything in the database, however remember that this is raw data and using such data requires a good knowledge of the database and how it is structured.

int  GetFirstRecordId ();
Returns the Id of the first record in the database.  This is typically the Job record.

int  GetLastRecordId ();
Returns the Id of the last record in the database.

int  GetNextRecordId (int recordId);
Returns the Id of the record following the supplied Id.  Returns zero if there are no more records. This method allows iteration through the database which is generally quite quick but may become time-consuming if every record is read and examined.