Utilities

The primary purpose of a utility is to run external tools on a subset of open data. The implementation is general, however, so other use cases are also supported.

Utilities can:

• Export selected vector features to HOB, GML or Shapefile.

• Open selected data in a specified application - either a CARIS application or a third-party application.

• Process or analyze data, using anything that can be run from a command line, such as

• a CARIS Batch process,

• a PL/SQL script,

• a Windows command, or

• a Python script.

• Open a specified output file automatically in the original application.

The utilities are user-defined macros in XML format files. A default file called utilities.xml is provided with the application and can be found here:

c:\Program Files\CARIS\<application>\<version>\system\Utilities

The sample file adds the "Show command prompt" utility to the drop-down list in the Interactive toolbar. This utility is used to launch a command prompt directly from the application with the current application environment. This file can be used as a template to create custom utility files or they can be created from scratch. More than one macro can be contained in a single file.

In order for additional macros to be added to the Interactive toolbar, the Utilities option under the Files and Folders category in Tools > Options must point to the folder containing the XML file(s). Any utilities defined in the specified location when the application is started will be displayed in the drop-down of the toolbar, in addition to the one(s) in the installation directory.

The diagram below shows how the utility file is used to initiate an external process:

(The red text indicates the tags that would be used in the utilities.xml file.)

• Teledyne CARIS Application: The Teledyne CARIS application in which you are running the utility.

• Utility: The individual utility selected from the drop-down list and being run from the utilities file.

• Selection/SuperSelection: An optional parameter that applies the selected utility to a selection and/or superselection of features in the application. For example, you could opt to export the selected features to one file and perform validation on those features while the superselected feature is exported to a separate file for a different type of validation.

• External Process: The process run in the external DOS command prompt.

• Return File: An optional parameter that opens a specified file created by the external process in the original application.

• Output Window/Output File: Optional parameters that control how text provided by the external process is to be logged. It can be displayed in the Output winodw of the original application, and/or it can be written to a specified log file.

See Utilities File Structure for details on each of the tags and how to define them.

Procedure: Create a Utility

1. Create a folder to hold utility files.

2. Define the new utility in a text editor.

3. Save the utility as an XML file in the utilities folder.

Procedure: Access a Utility

1. Set the Utilities option in Tools > Options to point to the folder containing the utility files.

2. Select the Toolbars > Interactive command to display the Interactive toolbar.

The Interactive toolbar is added to the interface of the application. If no utilities file exists in the selected location, the drop-down list is inactive.

Procedure: Run a Utility

1. Open the relevant dataset.

2. If necessary, select the features in the 2D View to be processed.

3. Expand the drop-down list in the Interactive toolbar and select a utility.

The Run button becomes active.

4. Click Run.

The external process begins and this message is displayed.

If the utility expects a Return File, or has been set as Blocking in the utilities file, then this message will remain visible until the external process is complete.

Note that the Return File is always created as a new file. If it is desired to reintegrate this data into another file, a process such as Import Selected Objects or Import as Update needs to be run.