SclSwaOpenFile

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.

This function opens a .str file, or a .str and .dtm file pair, and loads the data into a SWA.

Synopsis

$SwaHandle SclSwaOpenFile $FileName $Option1 | $Option2 |...

Description

Open the .str file, or .str and .dtm files if a .dtm file is named, and load the contents of the specified files into the specified SWA. The options ($Option1, $Option2, etc.) define optional arguments to the SclSwaOpenFile command that influence its behaviour.

This command will only fail, throwing a Tcl error, if the optional arguments are of the incorrect format or, if the files cannot be opened because of protection problems, i.e. the files are write protected or because of incorrectly formatted data in the .str or .dtm files.

Arguments

SwaHandle

This variable must contain the handle to the Swa into which the .str and .dtm files are to be loaded.

FileName

Passed by value. The name of the string file (eg. test1.str) that is to be loaded into the specified SWA by the SclSwaOpenFile command. If a .str file is named then only the string data is loaded into the SWA. If a .dtm file is named then the .dtm file AND the .str file are both loaded into the specified SWA.

Optional arguments ($Option1, $Option2, etc)

Passed by value. A number of optional arguments to the SclSwaOpenFile command permit various modifications to be made to its basic behaviour. These optional arguments take the form of a string of characters separated by the | character. Each optional argument takes the form of either, name=value, or value. If value is a phrase that has words (or characters) separated by spaces then it must be a quoted string. The table below shows the various optional arguments that may be used and what default value is assumed if the optional argument is not present.

Option name	Description	Default value if undefined	Example
range	The range of strings that are to be loaded from the .str file that is being read. This option is very useful when a subset of the strings in a SWA are to be loaded from a file rather than the entire file. This option is uncommonly used when loading .dtm files since it is difficult to determine if, by excluding some strings from the load operation, a valid DTM will eventuate.	If this optional argument is not defined then all strings will be loaded from the file.	range=1 This means that string 1 only will be loaded from the string file.
append replace	Determines if the data being loaded from the .str, or from the .str and .dtm files, is to be appended to the data already in the SWA or if it is to replace completely the data already in the SWA.	The default value is replace so that if some data are loaded and neither append nor replace options are defined, any data already in the SWA will be replaced by the data being in the files that is being loaded into the swa.	append replace
load draw styles	The header record of a string file contains, in the 4th field, the name of the styles file whose contents determine how the strings are to be rendered when drawn in the Graphics viewport. If you wish to ensure that the associated drawing styles file is also loaded when a string or DTM file is loaded then you must use this option. See below for an example of how this can be used.	The default behaviour is to NOT load the drawing styles file.	load draw styles

Examples

#
# This example loads a string file into a graphics layer and then draws
# the strings in the active viewport. Note that it ensures that the 
# drawing styles file associated with the string file is also loaded
#
# To run this example you must either have a file called pit1.str
# in your working directory or, you must change the name of the file being 
# loaded to match a .str file of your own
#
SclGetActiveViewport ViewportHandle
SclCreateSwa SwaHandle "pit layer"
$ViewportHandle SclSetActiveLayer $SwaHandle 
if {[catch {$SwaHandle SclSwaOpenFile pit1.str "load draw styles"}] != 0} {
  # this is how we trap for errors
  puts "Error loading pit1.str"
} else {
  # load was successful
  SclFunction "ZOOM ALL" {}
  $SwaHandle SclGetStrings StringsHandle
  $StringsHandle SclDraw
}

#
# This example loads a string fileinto the active graphics layer and 
# appends the data being loaded to the data already in the active graphics
# layer. The strings loaded from the file, and all strings that were
# already in the graphics layer prior to the load are then drawn.
#
# To run this example you must either have a file called pit1.str
# in your working directory or, you must change the name of the file being 
# loaded to match a .str file of your own.
#
# To see how the append feature works ensure that there is already some data
# the active graphics layer.
#
SclGetActiveViewport ViewportHandle
$ViewportHandle SclGetActiveLayer SwaHandle
if {[catch {$SwaHandle SclSwaOpenFile pit1.str append}] != 0} {
  # this is how we trap for errors
  puts "Error loading pit1.str"
} else {
  # load was successful
  SclFunction "ZOOM ALL" {}
  $SwaHandle SclGetStrings StringsHandle
  $StringsHandle SclDraw
}

#
# This example loads a dtm fileinto a graphics layer and then draws
# the triangles in the active viewport with hidden surface removal enabled
#
# To run this example you must either have files called pit1.str and pit1.dtm
# in your working directory or, you must change the name of the file being 
# loaded to match a .str and .dtm pair of your own
#
SclGetActiveViewport ViewportHandle
SclCreateSwa SwaHandle "pit layer"
$ViewportHandle SclSetActiveLayer $SwaHandle
if {[catch {$SwaHandle SclSwaOpenFile pit1.dtm}] != 0} {
  # this is how we trap for errors
  puts "Error loading pit1.str and pit1.dtm"
} else {
  # load was successful
  SclFunction "ZOOM ALL" {}
  SclFunction "HIDE ON" {}
  $SwaHandle SclGetTriobjects TriobjectsHandle
  $TriobjectsHandle SclDraw
}