Macro (.cmd) to SCL conversion guide

Some special values are defined by SCL as a convenience for authors of SCL scripts.

These values are

• SCL_OK

The command completed successfully.

• SCL_ERROR

The command completed with some type of error condition.

• SCL_UNDEFINED_HANDLE

The command returns the handle to an object in a variable that is passed by reference. For some reason the command has failed. When this occurs, the variable that was intended to receive the object handle will be assigned the value of $SCL_UNDEFINED_HANDLE so that an appropriate test can be performed if necessary.

if {[SclRangeExpand range "1,10,1"] == $SCL_OK} {
  puts "Range expanded OK"
} else {
  puts "Range expansion failed range = $SCL_UNDEFINED_HANDLE"
}
SclDestroy range

The # character only has significance as a comment if it occurs where the TCL interpreter is expecting the start of a new command.

Comments are most commonly found with the # character at the start of a new line.

Comments can be included at the end of a command by using the ; character to terminate a command. See the example.

# Everything that follows the # is a comment
    puts "Comment at the end of a line"; # in line comment
    

The \ character in TCL also serves as an escaping character to permit special characters to be defined. Details of special escaping characteristics of \ can be found here

for {set i 0} \
    {i < 10} \
    {incr i} \
    {puts "i = $i"}

Arrays are permitted and are denoted by a variable name and an array index enclosed by parentheses ().

The values of variables are obtained by prefixing the variable name by the variable substitution operation, $.

Variable names are case sensitive.

set names(1) "John Smith"
set names(2) "Mary Smith"
puts "names1=$names(1), names2=$names(2)"

set name(first) "John" set name(last) "Smith" puts "First name=$name(first), Last name=$name(last)"

Variables are created in TCL using the set command. Until a variable is set it does not exist.

Variables are disposed of by using the SclDestroy command.

When the variable refers to an SCL object (dtm or string file that has been loaded using extension commands) destroying the variable will cause the SCL object to be removed from memory.

The SclFunction command is used to execute functions in the software that are normally accessed by choosing a menu item, for example, CREATE DTM or RECALL FILE.

The SclFunction command requires one mandatory argument, the name of the function that is to be invoked. Optionally the SclFuntion command may have a body that contains a list of name=value pairs that define the parameters to that function.

The _action, _error, _missing and _pause parameters can be used to control the behaviour of the forms that are required when the function executes. Note that these parameters are NOT recorded with the scripts as the default behaviour for each of these parameters is suitable for most cases.

Experienced script authors will find these parameters useful to enable particular behaviour in circumstances where forms may fail various validation criteria and you might want to give the user interactive control for making corrections to the parameters on the form.

set status [ SclFunction "CREATE DTM" {
  frm00126={
    {
      _action="display"
      location="gol"
      id="1"
      swadesc="Y"
      break="Y"
      anyspots="N"
      brktest="Y"
      check_distance="0.005"
    }
  }
}]

The old macro language permitted macros to call other macros to aid in the development of complex macro solutions. Each macro existed in its own .cmd file.

TCL provides procedures for this purpose. Procedures must exist in the same script file unless they are defined in a library package to permit them to be used from another script file.

The old macro language permitted the passing of arguments to other macros but did not permit values to be returned from the called macro.

TCL permits values to be returned for some or all of the arguments to a procedure. This is achieved by using the upvar command.

pkg_mkIndex c:/temp/*.tcl
c:\temp\SsiMain.tcl
package require SsiPackage
SayHelloWorld
c:\temp\SsiPackage.tcl
package provide SsiPackage 1.0
proc SayHelloWorld {} {
        puts "HELLO WORLD"
}

sample.tclproc changevars {arg1name arg2name} {
    upvar $arg1name x
    upvar $arg2name y
    set x [expr $x + 1]
    set y [expr $y + 2]
}
set a 1
set b 2
set status [externproc a b]
puts "a is now $a, b is now $b"a is now 2, b is now 3

Procedure Example

proc sum_proc {a b} {
    return [expr $a + $b]
}
proc magnitude {num} {
    if {$num > 0} {
        return $num
    } 
    set num [expr $num * (-1)]
    return $num
}
set num1 12
set num2 14
set sum [sum_proc $num1 $num2]
puts "The sum is $sum"
puts "The magnitude of 3 is [magnitude 3]"
puts "The magnitude of -2 is [magnitude -2]"
   
Output: 
The sum is 26
The magnitude of 3 is 3
The magnitude of -2 is 2

Pauses the application for period seconds if period is defined or until some button on the keyboard is pressed if period is not defined.

Displays messagetext in the message window used by Report class messages. The normal behaviour of puts is changed if no explicit output channel is defined and the message is directed to the Surpac message logging window.

SclBeep will cause a single ring of the terminal bell and will also display the text, if it is present, of the OptionalMessage in the message window.

Causes an immediate return of the procedure currently executing and returns a value to the calling procedure.

$guido_object SclRunGuido

$guido_object SclSetGuidoValue $name $value

$guido_object SclGetGuidoValue $name value

SclDestroy guido_object

Old macros only use @menu to record the displayed menus during macro execution. They really don’t serve any real purpose apart from showing the menus changing during macro playback.

Graphical User Interface Design Objects, Guido, is the system component that is used for constructing the entire user interface. Guido is developed in TCL also and for this reason it is very easy to write Guido scripts that contain user interface components for SCL/TCL scripts.

All user interface commands in the old macro language are therefore replaced by a suite of commands to create and execute Guido objects through SCL.

# Create the guido object 
set status [ SclCreateGuido guido_object "inputs.tcl" ] 
if { $status == $SCL_OK } { 
    # Initialise the guido object 
    $guido_object SclSetGuidoValue "location" "topo"
    $guido_object SclSetGudioValue "id" "1"
    $guido_object SclSetGuidoValue "breaklines" "Y"
    # Run the guido object 
    set status [ $guido_object SclRunGuido ] 
    if { $status == $SCL_OK } { 
        # Examine the guido object after it has returned 
        $guido_object SclGetGuidoValue "location" location
        $guido_object SclGetGuidoValue "id" id
        $guido_object SclGetGuidoValue "breaklines" breaklines
    } 
    # Clean up - this destroys the Guido object
    SclDestroy guido_object 
} 

The Guido user interface script - inputs.tcl

GuidoForm inputs {
  -default_buttons 
  -label "User Interface Example"
  -layout BoxLayout Y_AXIS
  -tip "Help that is displayed with the pointer over the form"
  GuidoPanel panel1 {
    -border etched true
    -label "User inputs"
    -layout CentreLineLayout
    GuidoFileBrowserField location {
      -display_length 26
      -file_mask *.dtm
      -link id
      -label Location
      -max_length 252
      -tip "select the file to be processed"
    }
    GuidoField id {
      -display_length 16
      -format real_8
      -label "ID number"
      -max_length 16
    }
    GuidoCheckBox breaklines {
      -default true
      -font_style bold
      -label "Breaklines "
      -selected_value Y
      -unselected_value N
      -tip "Tick the checkbox to use breaklines"
    }
  }
}

The example shows simple use of the while command.

Braces {} are used as delimiters for the conditional part of the while statement and for the body of the while statement.

set x 0
while {$x<10} {
  puts "x is $x"
  incr x
}

SclRangeGet $handle $item value

SclRangeGetCount $handle

SclRangeIncludes $handle $value epsilon

Provides an iterator for an GEOVIA range. The range expression may be any valid range including a range file whose name is preceded by the @ symbol.

set status [SclRangeExpand handle "1,16,2"]
if {$handle == SCL_UNDEFINED_HANDLE} {
    puts "Undefined range handle"
} else {
    # Loop through the range
    set count [ SclRangeGetCount $handle ]
    for { set i 0 } { $i < $count } { incr i } {
        set status [ SclRangeGet $handle $i value ]
        if {$status == $SCL_OK} {
            # Do some processing with $value
        } else {
            puts "Error getting range value"
            break
        }
    }
    # destroy the range object
    SclDestroy handle
}

if {expr} {
} elseif {expr} {
} else {
}

if, elseif, else and switch provide different methods of conditional code execution. The switch statement is a tidier way of dealing with a large number of alternatives than repeated elseif commands.

set temp 95
if {$temp < 80} {
  puts "It's a little chilly."
} else {
  puts "Warm enough for me."
}

set num_legs 4
switch $num_legs {
  2 {puts "It could be a human."}
  4 {puts "It could be a cow."}
  6 {puts "It could be an ant."}
  8 {puts "It could be a spider."}
  default {puts "It could be anything."}
}

Returns 1 if a variable of the name requested exists, 0 otherwise

The info command may be used for a variety of other purposes also.

When using the MACRO PLAYBACK function to invoke a TCL script up to 10 optional arguments may be passed to the TCL script that is to be executed. This is done by creating a TCL list variable argv that contains one entry for each value that is entered into the fields on the form for the MACRO PLAYBACK function.

Procedures with variable length argument lists

If required variable length argument lists can be supported by making the last formal parameter in a procedure argument list args.

This results in a variable called args being available to the procedure. This variable contains a list of the optional argument values and the values of these arguments can be obtained by using the list processing functions of Tcl.

Llength to get number of items in the list
Lindex to get an item from the list
foreach to iterate over each element in the list

Passing arguments form MACRO PLAYBACK example

The script sample below exists in the file a.tcl. It invokes the script b.tcl and passes the 10 optional parameters to b.tcl through the automatically created argv variable.

set status [ SclFunction "MACRO PLAYBACK" {
  frm00197={
    {
      continue_on_error="N"
      slow_motion="N"
      macro_name="b.tcl"
      arg1="This input came via arg1"
      arg2="This input came via arg2"
      arg3="This input came via arg3"
      arg4="This input came via arg4"
      arg5="This input came via arg5"
      arg6="This input came via arg6"
      arg7="This input came via arg7"
      arg8="This input came via arg8"
      arg9="This input came via arg9"
      arg10="This input came via arg10"
    }
  }
}]

The script sample below exists in the file b.tcl. It shows how the optional arguments are passed to the argv list variable and how each value can be obtained.

for {set i 0} {$i < [llength $argv]} {incr i} {
  puts "argument $i=[lindex $argv $i]"
}

Variable length argument list example

proc testproc {arg1 arg2 args} {
  puts "arg1=$arg1"
  puts "arg2=$arg2"
  
  set numargs [llength $args]
  if {numargs > 0} {
    puts "$numargs optional arguments to the procedure"
    set count 1
    foreach optarg $args {
      puts "Optional argument #$1=$optarg"
      incr count
    }
  } else {
    puts "No optional arguments to the procedure"
  }
}

Displays a prompt to instruct the user to use the mouse to digitise a location in a 2D or 3D graphics viewport.

The digitise event may be generated in any 2D or 3D graphics window. The digitise request may be cancelled by pressing the Escape key. If no 2D or 3D graphics windows presently exist then the only valid action is to cancel the digitise request by pressing Escape.

The digitised location is returned in variables whose names are passed as arguments to the command.

The function returns SCL_OK on success and SCL_ERROR for failure.

All commands that permit graphic selections, unless otherwise stated, behave the same in that they return SCL_OK for success and SCL_ERROR for failure. Values are returned by passing the names of the variables to which digitised or selected values are assigned.

set status [ SclDigitise "Digitise a location on the graphics window" x y z ]
if { $status == $SCL_OK } {
  puts "x = $x, y = $y, z = $z"
} else {
  puts "Status = $status"
}

SclSelectTriangle triangle_handle "prompt text" layer triobject_no trisol_no triangle_no

Permit selection operations on points and triangles and return appropriate values to variables named in the argument list.

SclSelectPoint returns SCL_OK if successful and SCL_ERROR if unsuccessful. The point_handle variable will have a value that permits direct access to the selected point that can be used by other TCL extension commands.

SclSelectTriangle returns SC_OK if successful, SCL_ERROR if unsuccessful. The triangle_handle variable will have a value that permits direct access to the selected triangle that can be used by other SCL extension commands.

set status [SclSelectTriangle "prompt text" layervar triobjectvar trisolvar trianglevar]

Prompt the user to use the mouse to click and drag to define a rectangle on the screen by defining its centre point and the point where the mouse is released.

x1,y1,z1 are returned with the coordinates where the mouse button is depressed

x2, y2, z2 are returned with the coordinates where the mouse button is released.

Prompt the user to use the mouse to click and drag to define a rectangle on the screen by defining its two corners.

x1,y1,z1 are returned with the coordinates of the corner where the mouse button is depressed.

x2, y2, z2 are returned with the coordinates of the corner where the mouse button is released.

Prompt the user to use the mouse to define a line on the screen and return the coordinates of the two ends of the line

SclDragSegment segment_handle $prompt delx dely delz

SclDragPoint point_handle $prompt delx dely delz

Prompt the user to select and drag a string, segment or point from its current location to a new location.

Note that the string, segment or point is not changed.

The purpose of the function is to display feedback of the drag operation and to return the displacement defined by the drag operation.

The handle of the selected string, segment or point is returned in the string/segment/point_handle variable.

SclDragSegmentConstrained segment_handle $prompt $constraint delx dely delz

SclDragPointConstrained point_handle $prompt $constraint delx dely delz

Prompt the user to select and drag a string, segment or point from its current location to a new location and constrain the movement to be in a particular direction or plane.

Note that the string, segment or point is not changed.

The purpose of the function is to display feedback of the drag operation and to return the displacement defined by the drag operation.

The handle of the selected string, segment or point is returned in the string/segment/point_handle variable.

The constraint defines the number of degrees of freedom in the drag operation. Permitted values are any combination of the letters X, Y and Z.

XYZ = 3 degrees of freedom
XY = 2 degrees of freedom and movement in the XY plane only, etc.

set segment [SclDragSegmentConstrained "Prompt text" $constraint delx dely delz]

set point [SclDragPointConstrained "Prompt text" $constraint delx dely delz]

Returns 1 if the file exists, 0 otherwise

Returns a handle to the file for use in read, puts, gets and close commands.

Read and write from/to a file previously opened using open.

Returns 1 if the last gets command resulted in an end of file condition, 0 otherwise

Closes currently open file.

The Tcl interpreter includes an expression evaluation command expr, that does a lot of what the expr command implemented in the existing macro system does at present.

It does not however do everything that the expr command in the old macro language did. Consequently the SclExpr command has been created to emulate this older expr command.

The SclExpr command accepts one argument. This is the expression that is to be evaluated and must be delimited by " characters.