SclCreateSwa

Overview

The SWA (Surpac Work Area) is where all String and DTM data processed by Surpac applications is stored. A complete description of the SWA can be found here.

The SclCreateSwa command creates a new SWA using a name to distinguish it from other SWAs that may already exist. Data from String and DTM files may be loaded into a SWA. Furthermore, the contents of a SWA may be saved to a String or DTM file.

Synopsis

SclCreateSwa SwaHandle $SwaName

Description

The SclCreateSwa command creates a SWA that can be used for loading String and/or DTM files to manipulate the String and DTM data. Alternatively, the SWA may be populated with data resulting from calculations that produce points in some geometric configuration.

After creating the SWA, the Swa handle provides the means to refer to the data stored in the SWA. Good programming practices require that the SWA be destroyed after it is no longer required otherwise the memory required to store the data in the SWA is never released until the software exits. Misuse by neglecting to destroy the SWA when it is no longer required may consume all available memory requiring the software to be terminated abnormally.

Arguments

SwaHandle

Passed by reference. The variable to which the handle to the swa is to be assigned. All future references to the SWA require the contents of this variable to be dereferenced using the $ variable substitution operator.

SwaName

Passed by value. The name of the swa that is to be created. If a SWA with this name already exists then the handle to that swa is returned and the data in the SWA is not modified. If a SWA with name does not exist then a new SWA is created.

Errors

Throws a TCL error whenever a problem occurs. Uncaught, this error will immediately terminate the execution of the script. Errors may be caught and managed, preventing premature termination of the script, by using the Tcl catch command.

Examples

#
# create the swa
# load a string file into the swa
# show all the strings in the swa using the standard iterators
# and finally destroy the swa
#
if {[catch {SclCreateSwa SwaHandle "main graphics layer"}] != 0} {
  # catch any errors rather than terminating abnormally
  # this will give the handle to the SWA used for the initial graphics layer
  puts "SclCreateSwa failed"
} else {
  # swa created OK so load a file and display the string numbers in it
  puts "SclCreateSwa succeeded"
  $SwaHandle SclSwaOpenFile "pit1.str"
  $SwaHandle SclGetStrings StringsHandle
  set status [$StringsHandle SclIterateFirst i]
  while {[$i SclIterateNext StringHandle] == $SCL_TRUE} {
    set StringId [$StringHandle SclGetId]
    puts "The file has string #$StringId"
  }
  SclDestroy SwaHandle
}