SclSwaSaveStringFile

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 saves the string data in a SWA to a .str file.

Synopsis

$SwaHandle SclSwaSaveStringFile $FileName "$Options"

Description

Save the contents of the specified SWA to a .str file. The options ($Option1, $Option2, etc.) define optional arguments to the SclSwaSaveStringFile 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 created because of protection problems, i.e. the files are write protected.

Arguments

SwaHandle

This variable must contain the handle to the Swa whose point data is to be saved.

FileName

Passed by value. The name of the string file (eg. test1.str) that is to be created by the SclSwaSaveStringFile command.

"$Options"

Passed by value. A number of options to the SclSwaSaveStringFile command permit various modifications to be made to its basic behaviour. These options take the form of a string of characters separated by the | character. Since it is very likely that the contents of the Options variable will contain spaces, it is best to use " characters around the entire options string to ensure Tcl interprets it as a single argument. Each individual option takes the form of name=value. 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 saved to the file that is created. This option is very useful when a subset of the strings in a SWA are to be saved to a file rather than the entire SWA.	If this optional argument is not defined then all strings will be saved to the file.	range=1,10 This means that strings 1 to 10 inclusive only will be saved to the string file.
binary	Determines if the string file is to be written in binary or text format. The binary format is more efficient and has advantages with very large data sets through reduced file size and more efficient save, and load performance. There is no difference in performance and memory requirements once the data is loaded into memory. When loading string files it is not necessary to specify if they are in text or binary format as this is determined automatically.	The default value is off so that text format files are written. If the value is on the binary format files will be written.	binary=on binary=off
axis	Defines the coordinate data that is written to the second record of the string file to define the coordinates that are used for extracting cross sections from string and DTM files. The axis record takes the form of 0, y1, x1, z1, y2, x2, z2 where y1, x1, z1 are the coordinates for the start of the axis and y2,x2,z2 are the coordinates of the end of the axis.	If undefined an axis record of 0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 is written.	axis=0, 125.0, 322.0, 0.0, 125.0, 556.0, 0.0
header	The header string that is to be saved to the string file. The first record of a string file has 4 fields separated by commas. The convention for these fields are, in order, the file location, the file date, the file description, the name of the associated string styles file.	If undefined a default header will be written that looks like " , , , SSI_STYLES:styles.ssi"	header=test, 29-Feb-2000, A sample file, SSI_STYLES:styles.ssi

Examples

#
# This example will save a string file from the active
# graphics layer for the active viewport. Before executing this script
# load a string file into a graphics layer
#
set today [clock format [clock seconds] -format "%d %b %Y"]
set options "header=test, $today, Test of SclSwaSaveStringFile, mystyles.ssi|axis=0, 0.0, 0.0, 0.0, 100.0, 100.0, \
0.0|binary=on"
SclGetActiveViewport ViewportHandle
$ViewportHandle SclGetActiveLayer SwaHandle
if {[catch {$SwaHandle SclSwaSaveStringFile test1.str "$options"}] != 0} {
  # this is how we trap for errors
  puts "Error saving active layer to test1.str"
} else {
  # save was successful
  puts "active layer saved to test1.str"
}