Glossary of API terms
An alphabetic list of terms that are related to the Survey Core plugin API. They may vary from some terms used internally in SC.
Application
Survey Core supports the idea of multiple 'applications' running within it. Each application has its own Main window which appears when the 'Application' is started, either with the command "survey.exe app=appGuid" or via the Trimble Access Launcher. Built-in applications (otherwise known as Facades) include General Survey, Roads, Tunnels and Mines. A plugin may register itself as an application using the tsc_Application class, or it may simply modify the behaviour of General Survey and/or other built-in applications.
Atmosphere record
A database record which records the atmospheric conditions when a station setup is started. These conditions include the air pressure, temperature, PPM correction (computed or keyed in), refraction coefficient, and whether certain corrections are to be applied or not.
Best point
Any given point name may have multiple coordinates, which have been obtained from measurements, key-in, linked files, and so forth. When a single coordinate for a particular name is required (eg, to display on the map), the "best point" out of all identically named points is computed and used. The algorithm is somewhat complex, but suffice to say that the choice depends primarily on the point's quality. For points of equal quality, the earliest is used, and points in the main job are always chosen over identically-named points in linked files.
Code (or, Feature code)
Points, and other entities in the database, may have a Code property. The code may contain an arbitrary string, or - if a feature code library is attached - it may be a space-separated list of feature codes. The code may be entered when keying-in a point, storing a measured point, or it may be set by the plugin. The tsc_FeatureCodeField allows entry of the code field in a standard way. When a feature code library is attached to the current job, it is possible to prompt the user for attribute values that relate to the feature codes that have been entered into the code field.
Current job
This is an important concept in Survey Core. Many operations occur by default on the current job. For instance surveying (ie, the measuring of points) may only occur in relation to the current job, the map always displays the objects in the current job, etc. The system configuration in use is also represented in the current job, which is updated as the configuration changes. The user is always in control of the current job, and plugins should not interfere with this.
Database
This refers to the in-memory representation of a Survey Core .job file's content, plus the content of any attached or linked jobs, csv and other files. This implies that linking and unlinking files by the user may alter the database, possibly quite dramatically.
Delegate
Implemented by the tsc_EventDelegate macro, a delegate is effectively a pointer to a method in a class that is called to handle events. An event may be raised using the tsc_Event class, which contains a list of the delegates to be called. SCAPI delegates bear only a passing resemblance to delegates in the .NET framework.
Emulator
Survey Core supports screen emulation modes. Because testing and debugging is often carried out on a non-mobile platform such as a desktop or laptop computer, a number of screen-size emulations have been built in. The page describing Image resources explains these modes, but put simply, one of the following words can be added as a parameter to the survey.exe command line to invoke a platform mode: tsc5, tsc7, etc.
Entity
An entity is any named object within a job database and is represented in the API by the tsc_Entity class. Such objects include Points, Lines, Arcs, Stations, etc. Many database items are not considered to be entities, such as configuration data, status information, etc.
Event
An event is some action that is initiated either from inside or outside the scope of the plugin and that may be handled by an event handler within the plugin. Events are handled using Monitor classes (see Monitor). Typical events include notification of records being written to the database, a mobile device about to suspend, a shortage of file system space, a new measurement from a total station or GNSS receiver, and so forth. These are global events, as opposed to local events which are generated directly as a result of an operation initiated by the plugin such as turning the total station's laser pointer on. Windowing events are handled specially by the form system and sent directly to the tsc_Form subclass without the need for a Monitor. A plugin may also raise and handle its own events using the tsc_Event and tsc_EventDelegate classes.
Feature code
A feature code typically identifies the kind of object that has been measured (eg, a manhole) and is attached to the entity in the database. Feature codes are also present in a Feature code library, which may be attached to the current job.
Feature code library
This is a file which lists a number of feature codes, and for each feature code contains zero or more attributes. An attribute has a name and a set of input rules which allows the user to be prompted to enter information about some measured feature. For instance, a manhole feature might have an attribute named diameter, which must be entered as a number between 0.1 and 10 metres. Feature library files have the extension FXL or FAL.
Global event
Global events are sent to all forms, windows, and threads and reflect general changes in the overall environment. Many of these refer to changes in the currently open job. Typical examples are the current job being opened or closed, the controller being suspended, the file system becoming full, and so forth. Contrast with Local event.
GNSS
Global Navigation Satellite System. This system is comprised of the US-based NAVSTAR (GPS) system, the Russian GLONASS system, and the planned European (Galileo) and Chinese (Beidou) systems. Throughout Survey Core and the API, GNSS means any kind of positioning which employs one or more of these satellite systems. Depending on the capabilities of the GNSS receiver in use, some of these may be unavailable for use. Note that some older parts of Survey Core may still use the term "GPS" to mean GNSS.
Gridable
Of a coordinate, means that the coordinate can be converted into a grid coordinate in the two horizontal dimensions. This requires sufficient information in the original position and a suitable environment. The required environment could be nothing at all, or it might require a job, a coordinate system, atmospheric information, base or station information, depending on the type of conversions that need to occur. A summary of coordinate types and the conversions between them can be found here.
Interface
Has a variety of meanings, but in terms of the API an interface is an abstract class, being a class containing only pure (ie unimplemented) virtual member functions. This abstract class can then be subclassed, the member functions implemented, and the result passed into an API method which accepts the interface type. The API method is then able to call any interface function and have the caller's implementation run as a result. Interfaces are useful for event handlers and callback functions, and are also the means used internally to call Survey Core functions from the plugin.
Job
A job refers to a .job file that is the central database file for Survey Core. A job may have linked or attached files which are automatically opened when the job is opened, and whose database objects appear as part of the job's database objects. The corresponding API class is tsc_Job.
Job map
The Job map displays a 2D or 3D representation of the current job and attached files and jobs. It displays points, lines, arcs, and attribute-generated linework. It is possible for a SCAPI plugin to add its own graphical items to the map using the tsc_JobMap class, as well as having some control over the UI.
Job XML (.JXL)
Many Trimble Access and other applications use the Job XML file format for transferring survey data between them. It is also used in a similar form to allow plugins to access objects within a job database. The Job XML format is formally described by a set of XML Schema files, each of which describes one version of the file format. The following URIs can be used to obtain a copy. Other versions can be found by adjusting the version number in the URI, or obtaining a new URI from near the top of any properly formatted Trimble Job XML (JXL) file.
A number of API classes will return JXL fragments for database objects. These fragments are generally the same as one would expect to find in an export of the same job. Note that a plugin requesting database records in Job XML format will always be returned the version of Job XML that was current in the SDK it was built with, even if the version of Survey Core that is running the plugin supports a later version.
Licence
A licensing system allows duly authorized Trimble customers and SCAPI developers to download and install the software they are entitled to, using the TAIM installer program.
Local event
Contrast with Global event. A local event occurs as the result of some specific operation started by the plugin, and will not occur for any event started by anything else.
Log
Survey Core writes a log of significant events, including useful debugging information. The file can be found at:
(...)\Trimble Data\System files\sc.log
A number of useful logging functions can be found in the tsc_SurveyCore class.
Note that this file does not grow forever; when it exceeds a certain size (presently 250KB), it is reduced in size by removing the lines in the first half of the file.
Main Menu
Otherwise known as the burger menu. This is displayed using three-line icon that appears at the top-left of most Trimble Access windows. A plugin that implements an application uses the tsc_AppMainWindow class to generate its own main menu.
Map
See Job Map.
Monitor class
There are a number of monitor interface classes in the API. Each allows the plugin programmer to capture events and pass them to custom event handlers which have been implemented as virtual overrides. Monitor interfaces should generally be subclassed by some other useful class such as a form, so that the one class (the form) can handle any system event as well as the form UI events. Survey Core events may be handled in any class, provided the class has been subclassed off the appropriate monitor interface and the Start() method called. See the event handling page for more information.
Plugin
A windows which is DLL used to add functionality to Survey Core. Plugins may be installed separately, and are detected when Survey Core starts up. Each detected plugin is initialized before use. If a DLL fails the initialization process (for example, if no SCAPI initialization function is exported by the DLL), then the DLL is unloaded and no futher attempt is made to use it.
Point
A stored position, along with its properties. Points are stored in the most unprocessed form possible along with environment details to allow the coordinate to be transformed into more useful forms. Total station measurements, for instance, are typically stored as an EDM distance, the two angles, and some environmental information such as the target and instrument details. Points are represented in the tsc_Point class. Access to other properties of a point is possible using Job XML, which may be obtained from a tsc_Point. A point may also carry other information such as quality control records or stakeout information, depending on the type of measurement.
Quick task
Survey Core implements a lightweight high-performance means to run tasks that execute quickly, possibly quite often, implemented by the tsc_QuickTask class. Examples of such tasks include flushing a buffer to disk, regularly checking some metric such as the free space of disk, monitoring a communications channel that lacks an event system, and so forth.
Resources
Non-code items required by a plugin (or any program) are known as resources. Examples include strings, images, icons, version information, etc. Resources are included in plugins simply by adding the files to the installation. The Windows type of resource that is built into the executable or a dll was previously supported but we no longer use that. The manner in which these may be set up is explained in detail on the Image resources page.
SCAPI
Survey Core Application Programming Interface. This term refers to the headers and libraries that make up the interface used to write Survey Core plugin applications.
Station setup
This is the process by which a total station is set up so that observations to known or unknown points can be resolved. There are many ways to do this, and a plugin may implement its own methods. A station setup involves writing a set of database records which will allow General Survey and API methods to resolve an observation into a useful result, such as a grid coordinate. Station setups are managed by the tsc_Station, tsc_StationCalculationBase, and tsc_StationSetup classes, and are described in great detail here.
Survey Core
The large program, survey.exe, along with a host of dynamically loaded libraries, that provides the core functionality used by plugins. This is a technical term, not a "public name".
TAIM or TIM
Trimble (Access) Installation Manager. This is a program used by Trimble customers as well as SCAPI developers to download and install Trimble software. It will install to a desktop computer or to a supported mobile device such as a TSC7 or a Trimble Tablet. The latest production version may be downloaded here. For the latest beta version, install and run the production version. If you are licensed for the beta version then TAIM will first upgrade itself before offering to install Trimble Access and the SDK.
TASDK
Trimble Access Software Development Kit. This refers to the software, the SDK, that is installed by TAIM which allows Survey Core plugins to be developed. It contains header files and libraries for building a plugin application, plus a number of tools and code samples.
TDB
Translation database, an XML file with an extension of .tdb, which contains strings translated into a variety of languages. See Translation database below.
Thread
Survey Core makes use of the Windows threading API. Each task that a user initiates (such as keying in a point) runs in a separate thread known as a UI Task. A SCAPI plugin may start its own threads, preferably using the tsc_Thread or tsc_MonitorThread class.
Translation database
This is an XML file provided by a plugin writer, used to supply translations of strings into other languages. A TDB file is used in conjunction with the ApiLanguageTool to provide easy access to the translations using x_Codes.
Trimble Access
The Official name of the Trimble field Surveying application which uses the Survey Core infrastructure. It encompasses all related applications such as General Survey, Roads, Tunnels, Mines, as well as the installable plugins.
UI Task
A single task undertaken by the user. This generally leads to one or more windows or forms that the user can interact with. A UI Task typically runs on its own thread and can be launched, closed, switched-to, aborted, etc - a little like a windows process. Examples of UI tasks are the Map, Key-in point, Calculator, Continuous topo, the various forms of Stakeout, and so forth. A plugin will usually implement its own UITasks through the use of the tsc_UITask class. Forms and windows are modal within each UI task. For instance, if a UI task displays a window and then another form over top,the form will cover the window, and the window will not be accessible by the user until the form is closed. The user may switch to another UITask which will switch the entire window stack to the new task.
x_Code
Short for translate-code, an x_Code is an enumeration, which is simply an integer value that represents a string in the currently selected language. x_Code values are mapped to names in the module pluginName_xcodes.h and these names are known as Tokens throughout the language translations system. A translated string for the language currently being used can be obtained by calling the Translate method of the tsc_SurveyCore class. A plugin may provide its own translations through an XML file known as a translation database, or TDB. See the Language Translations page for further information.
XML
A file format commonly used for data interchange between applications. Also see Job XML. SCAPI fully supports XML format files.