tsc_Job

The tsc_Job class represents a .job file on disk, along with any attachments it may have, such as linked jobs, linked csv files, background dxf, ifc, shape, image etc. files, coordinate systems, and so forth.

In Survey Core, there is the notion of a Current job.  This is the job which by default is used for storing observations and almost all other operations carried out by the user.  The few exceptions to this are functions like copying data from other jobs, importing and exporting, opening a different job as the current job, and so forth.  To control which job is the current job, see the tsc_CurrentJob class.

The tsc_Job class itself provides the methods to open any job which is independent of the current job, or it can represent the current job itself.  Most API job functions will operate correctly in both situations, however some may give surprising results when, for instance, one is dealing with coordinate transformations in a job which is not the current job, and the job's coordinate system differs from the current job.  Check the documentation or contact Trimble for more details if you really must do this.

The tsc_Job only deals with the job as a whole - opening, closing, creating, obtaining file information, etc.  The data within the job is accessed through the tsc_Database class, a reference to which can be obtained by calling the job's Database() function.

A tsc_Job is a smart pointer internally and should be a simple instance rather than a pointer. One is typically created (either as a local instance or with the new operator) and then opened, or a pointer to the current job may be obtained by calling the static CurrentJob function.  Either way, the job object must be freed (destructed) when finished with, either by delete or falling out of scope.

See the sub-pages of this one for classes that provide access to the job database.

Public methods of tsc_Job

Some functions - notably the Open and Create methods - may fail, and return additional information via the LastError() method.  The error codes are x_Codes and are designed to be useful for debugging and possibly for run-time checking for certain error types.  Avoid using their translations as messages to the user.

x_Code LastError();
Returns the result of the last Open or Create operation.  The possible x_Codes are documented at the bottom of this page.

Static methods

static tsc_Job CurrentJob ();
This method obtains a reference to the currently open job, or to a closed and empty job if there is no current job.  Always store the returned tsc_Job as an instance, because it is the place from which all other job and database objects are derived.  Note that the current job may be closed by a plugin application or by the user.  To avoid this possibility, references to the current job should only be made within a tsc_UiTask which specifies that a job is required. This will cause the UI Task to be shut down before the job is closed by the user.

Other methods

tsc_String Name ();
To obtain the name of the job, excluding any directory information or file extension.

tsc_String Project ();
To obtain the name of the project directory, which is the directory name between the user's directory and the job filename.  If the job is in the user's root directory, an empty string is returned.

tsc_String Path ();
The job's full (absolute) directory path, filename, and extension.

bool IsOpen ();
Whether the job is currently open and therefore able to be accessed.

bool IsWritable ();
Whether data can be written to the job.  This is false if (for instance) the job file is read-only, or if a demo license of Survey Core is in use and the limit on total points in the job has been reached.

bool IsCurrent ();
Returns true if this job represents the currently open SC job.

bool Open (const char* project, const char* jobName);
Opens a job file and its attachments, given the project directory name (which should be a single sub-directory name) and the job name.  The opened job is entirely separate from the current job; this method can not affect the current job. This method does not open files that are linked to the job.

bool Open (const char*  jobName);
Opens a job file in the current projects directory.   The opened job is entirely separate from the current job; this method can not affect the current job.  This method does not open files that are linked to the job.

bool Create (const char*  project, const char*  jobName);
Creates a new job of the given name in the specified project sub-directory.  project may be NULL or empty to create the job in the project's root directory.  The current default job template is used. Any path parameter may contain standard path macros (see tsc_Path).  After a successful call, the tsc_Job object will be an open job.  The new job is separate from the current job and does not affect it.
Note: To use the resulting tsc_Job instance as the current job it is necessary to close the job, then close the current job (tsc_CurrentJob::Close()), and then open the job as the current by calling tsc_CurrentJob::Open(project, jobname).

bool Create (const char*  project, const char*  jobName, const char* templatePath);
Creates a job using the supplied template (.jot) file.  If templatePath contains no directory name then $(SharedDir) is prepended.  This is the normal location of template files. Any path parameter may contain standard path macros (see tsc_Path).  After a successful call, the tsc_Job object will be an open job.    The new job is separate from the current job and does not affect it.

void Close ();
Closes this job and releases local resources.  If the tsc_Job represents the currently open SC job, the connection to the job is broken, but the job itself remains open in SC as the current job.   To close the current job, see tsc_CurrentJob::Close().

virtual void OnClose ();
Override this member to be notified of the job being closed.  This is of most use when the tsc_Job is representing the current job, since the user may close the job at any time.  If your UITask specifies that it requires a job, then the job cannot be closed by the user while your UITask is still running.

tsc_Database& Database ();
Provides access to the data model within this job.  This method creates a number of internal objects, so if multiple accesses are to be made to a job's database it is a good idea to store the tsc_Database object as a local variable.

x_Code LastError ();
Returns an x_Code describing any error that occurred in the last tsc_Job function call.  Zero means no error code was posted, but does not necessarily mean the function worked.  Use the bool return code for that. 

x_Code AttachFeatureLibrary (const char* path);
Attaches the named feature/attribute library to the current job, after detaching any current library. This function works with FAL, FCL and FXL file formats. A return code of X_NULL indicates success, otherwise an error is indicated. After any error, the job will be left with no current library attached. The path parameter may be just a filename to load a library from the standard (System) folder, or an absolute path may be given by using the predefined macros to generate a path, such as $(SharedDir)\mine.fxl.  The return value is an error x_Code (see table below) or X_NULL if the attach operation succeeded.

Feature libraries should be located in the Shared Directory (confusing named System Files). It is possible to use libraries from outside of this folder but the various database import and export features expect this location.

If only a filename or relative path is given then it is relative to the Shared folder, $(SharedDir).

The job's feature library attachment state is persistent.  If the job is closed and reopened at any later time, the specified library will be automatically reattached.  Note that the user may also attach or detach feature libraries through the standard UI, including any attached by this method.

Important: When the feature library of an existing job is changed or detached, any attributes that were entered on database objects by the user will become read-only since the information that would allow them to be edited is no longer available.  Reinstating the original library will make them editable again.

bool DetachFeatureLibrary ();
Detaches any current feature/attribute library from the job.  The job's feature library attachment state is persistent.  If the job is closed and reopened at any later time after the library was detached, no feature library reattachment will occur.

Important: When the feature library of an existing job is detached, any attributes that were entered on database objects by the user will become read-only since the information that would allow them to be edited is no longer available.  Reinstating the original library will make them editable again.

tsc_FeatureLibrary CurrentFeatureLibrary ();
Returns the feature library currently attached to the job.  This is a read-only object which may be used for any purpose, but is typically utilised to control user input of attribute values. Further information can be found in tsc_FeatureLibrary.

Error codes

The following x_Codes may be returned by the LastError() method.  After a job is created, it is opened automatically, so theoretically any open error can occur during a create.