SclCreateString

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 SclCreateString command creates a new string with a specified string number in a SWA and returns a handle to that string for future operations to that string. If a string of that number already exists then the handle to that string is returned and the string is not modified in any way.

Synopsis

$SwaHandle SclCreateString StringHandle $StringNumber

Description

Create a string of the specified number in the specified SWA and return the handle to that string for later use by other Scl commands. If the string already exists then just return the handle to the string without modifying it in any way.

Initially the string is empty, that is it has no segments and no points and will not be saved to a string file until at least 1 segment with at least one point is created in it.

Arguments

SwaHandle

This is the handle to the SWA in which the string is to be created. The SWA handle must have previously been obtained by using SclCreateSwa or SclIterateNext to obtain the handle to an existing SWA or Graphics layer.

StringHandle

Passed by reference. This is the variable to which the string handle is assigned. This string handle must be used in later references to the string for adding, deleting or modifying segments in the string.

StringNumber

Passed by value. This is the string number that is to be created, or for which the handle is required if the string number in question already exists in the SWA. Note that the string number is in fact an identifier for the string and may only by a positive integer, greater than 0 that is.

Examples

#
# create a swa then create a string (number = 1) in that swa 
# then a create a segment with a single point 
# save the string to a string file and finally destroy the swa
#
SclCreateSwa SwaHandle "temporary swa"
$SwaHandle SclCreateString StringHandle 1
$StringHandle SclCreateSegment SegmentHandle 0
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 1.0
$PointHandle SclSetValueByName y 2.0
$PointHandle SclSetValueByName z 3.0
$SwaHandle SclSwaSaveStringFile test1.str
SclDestroy SwaHandle
puts "String 1 created with 1 segment and 1 point and saved to test1.str"