SCL constants

Overview

Scl has a number of predefined constants that are provided as a convenience. These constants are provided as read-only TCL variables whose values can be accessed by using the variable substitution operator $. These variables should be used in preference to the literal values that they refer to as a matter of good programming practise.

Note: If these constants/variables are used inside a procedure, then they must be used in a special way. Details of how to use these constants/variables inside procedures can be found here.

Summary

The constants that are provided with SCL include:

SCL_OK

All SCL functions, unless documented otherwise, return $SCL_OK to indicate success. $SCL_OK evaluates to 0.

SCL_ERROR

All SCL functions, unless documented otherwise, return $SCL_ERROR to indicate failure. $SCL_ERROR evaluates to -1.

SCL_UNDEFINED_HANDLE

SCL functions that return, usually in variable that is passed by reference, a handle to an SCL object return $SCL_HANDLE if the requested object does not exist or cannot be created.

SCL_TRUE

Some SCL functions return true/false values. $SCL_TRUE is the value returned for true. $SCL_TRUE evaluates to 1.

SCL_FALSE

Some SCL functions return true/false values. $SCL_FALSE is the value returned for false. $SCL_FALSE evaluates to 0.

SCL_PI

The mathematical value for PI to 20 decimal places. $SCL_PI evaluates to 3.14159265358979323846.

SCL_E

The mathematical value for the natural logarithm base (e) to 19 decimal places. $SCL_E evaluates to 2.7182818284590452354.

$SCL_OK, $SCL_ERROR, $SCL_UNDEFINED_HANDLE, $SCL_TRUE and $SCL_FALSE are read-only global variables that should be used for comparison with the result of a number of functions.

Description

All Scl commands, unless otherwise documented, return an integer value to indicate the completion status of the command. If the completion status is $SCL_OK then the command completed successfully.

If the completion status of a command is $SCL_ERROR the command failed to successfully complete. The reason of failure to complete requires diagnosis by the script author.

Some SCL commands return either a true or false value. For these commands $SCL_TRUE and $SCL_FALSE may be used for comparisons.

Some Scl commands return in a variable a handle (unique identifier) to an Scl object, i.e. a point, segment, string, triangle, etc. Scl commands that return such object handles will return a handle that can be used for operations on that object. If the Scl command fails though, the variable to which the handle is to be assigned will receive a value of $SCL_UNDEFINED_HANDLE.

Thus comparison of the handle variable with $SCL_UNDEFINED_HANDLE provides method of ensuring attempts to continue execution with an invalid handle are not made.

For mathematical and trigonometric functions $SCL_PI and $SCL_E may be used to get values of PI and e (natural logarithm base) respectively.

Examples

Range expansion

		set RangeExpr "1,10,1"
		set status [SclRangeExpand range $RangeExpr]
		if {status == $SCL_OK} {
		  puts "$RangeExpr is a valid range expression"
		} else {
		  puts "$RangeExpr is an invalid range expression"
		}
		SclDestroy range

Range expansion - another way

		if {[SclRangeExpand range "1,10,1"] == $SCL_OK} {
		  puts "1,10,1 is a valid range expression"
		} else {
		  puts "1,10,1 is an invalid range expression"
		}
		SclDestroy range

Cicumference of a circle

		set circum [expr 2 * $SCL_PI * r]

SCL Constants in procedures

SCL constants are defined in the global namespace. This means that constants such as SCL_PI, SCL_TRUE, etc. can be used in any SCL script by using the variable reference operator $. For example $SCP_PI, $SCL_TRUE, etc.

The scoping rules of TCL prevent these constants from being used like this when inside a procedure. This is because variables inside a procedure must be defined and set a value inside the procedure unless they are explicitly declared as global variables or unless the global namespace qualifier is used to explicitly reference these constants from the global namespace where they are defined.

There are therefore 2 methods or using these SCL constants inside a procedure. These methods are:

Use the global namespace qualifier.
Any variable that exists in the global namespace can be referenced inside any procedure by preceding the variable name with the global namespace qualifier ::. For example:

		        proc DisplayConstants {} {
		          puts "SCL_OK               = $::SCL_OK"
		          puts "SCL_ERROR            = $::SCL_ERROR"
		          puts "SCL_UNDEFINED_HANDLE = $::SCL_UNDEFINED_HANDLE"
		          puts "SCL_TRUE             = $::SCL_TRUE"
		          puts "SCL_FALSE            = $::SCL_FALSE"
		          puts "SCL_PI               = $::SCL_PI"
		          puts "SCL_E                = $::SCL_E"
		        }
		        DisplayConstants

Use the global command to reference the global variables.
The global command allows you to define, inside a procedure, certain variables that exist in the global namespace so that they can be used. An example of this is:

		        proc DisplayConstants {} {
		          global SCL_OK
		          global SCL_ERROR
		          global SCL_UNDEFINED_HANDLE
		          global SCL_TRUE
		          global SCL_FALSE
		          global SCL_PI
		          global SCL_E
		          puts "SCL_OK               = $SCL_OK"
		          puts "SCL_ERROR            = $SCL_ERROR"
		          puts "SCL_UNDEFINED_HANDLE = $SCL_UNDEFINED_HANDLE"
		          puts "SCL_TRUE             = $SCL_TRUE"
		          puts "SCL_FALSE            = $SCL_FALSE"
		          puts "SCL_PI               = $SCL_PI"
		          puts "SCL_E                = $SCL_E"
		        }
		        DisplayConstants

The first method described above is the simplest method to use and certainly the briefest method in terms of the volume of code that must be written to use these constants inside procedures.