Print

SCL Extension Commands

Scl Constants

There are a number of predefined Scl constants to assist with checking command return values and using special numbers such as pi. Using these constants improves the legibility of your scripts. You can also create your own constant values with SclConstant

User Interface commands (GUIDO)

The user interface commands allow you to create and display custom forms in order to interactively collect input information to be used by the script. The user interface is split across a client/server architecture. Your Scl script runs on the server with the user interface portion (GUIDO) being dispatched and then run on the client.

Viewport and layer commands

The viewport and layer commands permit you to create, destroy and set viewports and layers in the 3D graphics environment. A single viewport might contain one or more layers into which all graphics data is drawn. You are guaranteed that there is always at least one viewport.

SWA commands

The SWA (Surpac Work Area) is where all string and DTM data processed by Surpac applications is stored. Scl provides several commands for creating, accessing, and manipulating this data in the SWA.

General graphics commands

Scl provides several commands for selecting data within and drawing data in the graphics viewport. There are also some special purpose graphics commands that are described in the section on Scl Graphics drawing commands.

Object manipulation commands

Scl provides several commands for accessing the Scl data structures associated with viewports, layers, and SWAs. These commands are generic to all these data structures.

Range commands

The range commands allow a Surpac range specification to be manipulated. A description of Surpac ranges can be found here.

Geometric and mathematical commands

Geometric and mathematical calculations can be performed in your scripts using the following commands.

Database Commands

Scl provides several commands for developing applications that interact with database objects, such as tables, rows, and fields. These commands permit query, update, insert and delete activity on database tables. For an overview of the database commands, click here.

Drillhole commands

Database applications permit drillholes to be displayed in the 3D graphics environment and to be used for various other purposes. These SCL commands permit interaction with the drillholes as a special type of object that can be selected in the 3D graphics environment. The commands also allow you to perform calculations of XYZ positions at any depth down the drillhole trace.

System and miscellaneous commands

System and miscellaneous commands provide mechanisms for accessing and using functions and information stored within the program. There are also commands to create custom interfaces and display messages.

Scl Graphics drawing commands

The Scl Graphics drawing commands provide an interface to the 3D graphics rendering system used in Surpac. These commands permit Scl authors to draw geometric objects, markers, polylines, polygons, and text in the 3D graphics viewports along with data that is drawn using the various drawing functions of Surpac.

The rendering attributes such as, colour, line style, and marker style of the geometry can also be defined.

Geometry that is rendered using these commands cannot be selected nor can it be processed through the Autoplot module. Benefits of using these commands is to aid in adding annotation and additional geometry to the screen image for presentation purposes and to achieve animation by rendering geometry at different locations with high frequency.

This overview explains some important concepts for the effective use of the Scl graphics drawing commands.

Block model commands

These commands enable you to get and manipulate data from the block model. To see a description of each command, move the mouse pointer over the name of each command.

Superseded commands

The following commands have been superseded and their use is not recommended.

Scl naming and capitalisation conventions

All the Scl commands that have been introduced into the Tcl interpreter are named with an Scl suffix. This is to distinguish these commands from other commands that may have been introduced in another Tcl package that advanced users of Scl and Tcl might encounter. To avoid name clashes, the Scl prefix ensures that each command name is unique.

The Scl prefix tends to make the command names more verbose. However, it almost guarantees that the advanced Scl programmer developing sophisticated applications will not be hampered by a restrictive initial design.

Capitalisation rules for the names of Scl commands follow one of the following rules:

• All capitals

Scl constants, for example $SCL_TRUE, $SCL_FALSE, are named using all capitals.

• Title case capitalisation

Almost all Scl commands use this convention. This method is where only the first letter of each word that constitutes the name of an Scl command is in upper case. For example, SclSwaOpenFile, SclIsSwaGraphicsLayer. This method of capitalisation enhances the readability of the Scl command name.

• The exception for Scl object names

Some Scl commands actually represent objects and a variation of the Title case capitalisation is used where the scl prefix is all lower case but the remainder of the command (object) name obeys title case capitalisation. For example:

• sclSwas

This command represents the set that comprises all SWAs that exist at any point in time.

• sclGraphicsLayers

This command represents the set that comprises all SWAs that exist as graphics layers at any point in time.

• sclViewports

This command represents the set of viewports in the 3D graphics environment at any point in time.

• sclDatabases

This command represents the set that comprises all databases that are currently connected. At this time only one database can be connected but this may change in a future release.

Scl completion status

Unless described otherwise, all Scl commands return an integer value to indicate the completion status of the command. The completion status will either be:

• $SCL_OK
• $SCL_ERROR

Scl argument passing conventions

The arguments to all Scl commands are described as either:

Pass by value

This means that the value of a variable must be passed to the procedure by prefixing the variable name with the $ variable substitution operator. Alternatively values may be passed as arguments to procedures as literal values, in other words as quoted text like "a literal argument".

• Pass by reference

This means that the variable name, as opposed to its value, must be passed to the procedure. Arguments that are described as Pass by reference must not be prefixed by the $ variable substitution operator.

An argument that is described as Pass by reference will be assigned a new value by the called procedure and this value will be available for use in the calling procedure by using the $ variable substitution operation.

Configuring the Scl Library Search Path

When a package is loaded in an SCL macro using the package require command the TCL interpreter uses the auto_path variable to search for the package to load.

Use the SCL Library Path in the Default Preferences to configure the auto_path for Surpac's SCL interpreter. From the Customise menu, select Default Preferences, then on the Miscellaneous tab, look under SCL pane. The search path specified is appended to auto_path so that any existing search paths are preserved. This is important because the SCL interpreter sets auto_path on startup with its own search path necessary for locating system libraries.

The SSI_LIB: directory contains package files that are distributed with Surpac. To ensure that any user packages that are created are not destroyed by installing or removing Surpac, move the user packages to a location that is independent of the SSI_LIB: directory.

See also library, package, pkg_mkIndex.

Errors

Most Scl commands throw Tcl errors whenever a problem occurs. Uncaught, these errors immediately terminate the execution of the script. To catch and manage errors, and to prevent the premature termination of scripts, use the Tcl catch command. To understand how the catch command is used to manage errors, review the examples in the catch help topic.

Note: Use of the catch command is not necessary unless you are an advanced Scl programmer since the reasons for such errors occurring generally indicate logic errors that a better managed by early termination of scripts.

User abort

A running macro can be aborted by pressing the flashing playback icon on the toolbar or by pressing the abort button on the progress feedback status bar. User aborts are handled automatically by the macro interpreter unless the script indicates that it will handle this event.

For a user script to handle user abort events, the script must first set a user option user_abort to the value false using the SclSystemOption command. After this has been done, the system will no longer handle the user abort event except to set a global variable sclUserAbort to the Tcl true value of 1 (one) when a user attempts to abort the script. If the value of the user_abort option is set back to true, the system will again automatically handle this event. This allows a script to handle the condition in critical code sections.

To handle the user abort event, write a simple if statement to check the value of the sclUserAbort variable in appropriate places in the script. The following code segment illustrates this method.

# a recursive procedure to consume some processor time
# ie this procedure calls itself until a specific condition
proc aProcessingProcedure {num} {
  global sclUserAbort
  # test for a user abort and throw an error if one is detected
  if {$sclUserAbort} {
    # place your cleanup/error handling code here
    error 100 "User Aborted"
  }
  incr num
  if {$num < 450} {
    for {set i 0} {$i < 10000} {incr i} {
      #just waste some time
    }
    set num [aProcessingProcedure $num]
  }
  return $num
}
# the mainline starts here
puts "Starting"
# set the system to not automatically do user aborts
SclSystemOption set user_abort false
# go off and do something
set num [aProcessingProcedure 1]
# reset the user_abort back to true
SclSystemOption set user_abort true
puts "Finished"