SclCreateSegment

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 SclCreateSegment command creates a new segment, at a specified position, in a string and returns a handle to that segment for future operations on that segment. If a segment at that position already exists then the handle to that segment is returned and the segment is not modified in any way.

Synopsis

$StringHandle SclCreateSegment SegmentHandle $SegmentPosition

Description

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

Arguments

StringHandle

This is the handle to the string in which the segment is to be created. The string handle must have previously been obtained by using SclCreateString or SclIterateNext to obtain the handle to an existing string from the set of strings in a SWA.

SegmentHandle

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

SegmentPosition

Passed by value. This is the position in the set of strings at which the segment is to be created. The segment position must be an integer >= 0, where a value of zero is the first segment in the string. If a segment already exists at the specified position in the string then the handle to that segment is returned and the segment is not modified. To guarantee that a new segment will be created the segment position must be equal to the number of segments in the string. This can be easily determined by using the SclCountItems command for the string to which the segment is to be added.

Segment positions that are <0 or> the number of segments in the string are illegal and will cause an error to be thrown.

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"

#
# this example creates 2 segments but for the second segment it first
# determines how many segments exist in the string by using
# SclCountItems - this method guarantees a new segment will always be
# created at the end of the set of segments in the string
#
# this example also shows how the variables in which the object handles
# may be re-used to refer to different objects throughout the script
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
$StringHandle SclCreateSegment SegmentHandle [$StringHandle SclCountItems]
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 4.0
$PointHandle SclSetValueByName y 5.0
$PointHandle SclSetValueByName z 6.0
$SwaHandle SclSwaSaveStringFile test1.str
SclDestroy SwaHandle
puts "String 1 created with 2 segments with 1 point each and saved to test1.str"