You are here: Surpac Concepts > Macros > SCL > System and Misc > SclLogical

GEOVIA Surpac

SclLogical

Overview

The SclLogical command provides access to the systems logical to physical path name translation map. The command provides functions to add, delete, test, list, and translate logical names.

Synopsis

SclLogical <sub option> <optional parameters>

Description

The name logical is a term used by the software that refers to the use of a known name that is used to map to a physical directory path. This known name, the logical, is mapped onto a physical directory path at runtime. By using logicals you can insulate your scripts from having to know about the physical directory structure that may change and/or be different on other users computers that run your scripts.

For example the logical name SSI_ETC: (the known name) may be mapped to a directory "c:/ssi_v5.0-a/share/etc" on one machine and "s:/software/surpac/v5.0/share/etc/" on another. Because the software accesses the files in this directory via the logical name SSI_ETC: it does not need to know about the physical location as this is worked out at system startup time.

The reasons logicals are used can be summarised as:

Insulates the software and scripts from the file system
Shorten notation for accessing long directory names
Data standardisation

Logicals come in three flavours as follows:

System - defined by the software startup parameter "-trans <filename>" where <filename> usually refers to "/ssi_vx.x-x/share/etc/translate.ssi". This file is commonly know as the translate file.
User - defined in the file SSI_ETC:logicals.ssi
Personal - defined in any file and specified to the software via the system default option "user_logical"

Click here for further information on logicals.

The SclLogical command provides a mechanism to manage logicals at runtime. You can change, add, delete, test that a logical exists, get a list of current logical names, and importantly translate a logical name to a physical path.

Note: Any changes you make to logicals through the SclLogical command only persist for the current session. That is they do not get saved to the various files as described above.

The SclLogical command supports the following options:

SclLogical add <logicalName> <pathName>
SclLogical delete <logicalName>
SclLogical exists <logicalName>
SclLogical <list>
SclLogical translate <logicalName> [<slash>]

Synopsis

SclLogical <add> <logicalName> <pathName>

Description

Add a logical to the current translation table in memory. If the logical name already exists then the value of its path translation is updated.

Note than when defining a logical it is normal to end the logical name with a full colon character ":" and end the path name with a forward slash. It is also safer to use forward slashes as the directory separator as backslashes can at times be interpreted as special characters by the Tcl interpreter.

Arguments

<add>

A literal string to identify the sub function

<logicalName>

The name of the logical to create or update

<pathName>

The physical path to use for this logical

Returns

True if the logical is added/modified successfully, false otherwise.

Examples

# create a temporary directory and add a logical TMP_DATA: to map to it
file mkdir temp
SclLogical add "TMP_DATA:" "[pwd]/tmp/"
puts "TMP_DATA: --> [SclLogical translate TMP_DATA:]"
# save, redefine and then reset the SSI_PLOTTING: logical
set originalPlotting "[SclLogical translate SSI_PLOTTING:]"
SclLogical add "SSI_PLOTTING:" "c:/mydata/surpac/plotting/"
puts "SSI_PLOTTING: --> [SclLogical translate SSI_PLOTTING:]"
SclLogical add "SSI_PLOTTING:" "$originalPlotting"

Synopsis

SclLogical <delete> <logicalName>

Description

Delete a logical from the current translation table in memory. Note that this only persists for the current session. If the logical is defined in one of the logical definition files it will be defined next time the software is started.

Arguments

<delete>

A literal string to identify the sub function

<logicalName>

The name of the logical to delete

Returns

True if the logical is deleted successfully. False if the logical name cannot be deleted or does not exist.

Examples

# create a temporary directory and add a logical TMP_DATA: to map to it
file mkdir temp
SclLogical add "TMP_DATA:" "[pwd]/tmp/"
puts "TMP_DATA: --> [SclLogical translate TMP_DATA:]"
# now delete it
SclLogical delete "TMP_DATA:"

Synopsis

SclLogical <exists> <logicalName>

Description

Test to see if the given logical name exists.

Arguments

<exists>

A literal string to identify the sub function

<logicalName>

The name of the logical to test for existence

Returns

Returns True if the logical is defined or False otherwise.

Examples

# create a temporary directory and add a logical TMP_DATA: to map to it
file mkdir temp
SclLogical add "TMP_DATA:" "[pwd]/tmp/"
# test that it exists
if {[SclLogical exists "TMP_DATA:"]} {
  puts "TMP_DATA: --> [SclLogical translate TMP_DATA:]"
}
# now delete it
SclLogical delete TMP_DATA:
# test if it exists
if {[SclLogical exists "TMP_DATA:"]} {
  puts "TMP_DATA: should not exist anymore .. something is wrong!"
}

Synopsis

SclLogical <list>

Description

Get a list of all the currently defined logicals and their translations.

Arguments

<list>

A literal string to identify the sub function

Returns

A Tcl list containing the names of the logicals and their translations. The format of the list is pairs of items where the first item is the logical name with the next item being its translation path, and so on.

Examples

# list all defined logicals
set logicalList [SclLogical list]
foreach {logical path} $logicalList {
  puts "$logical --> $path"
}

Synopsis

SclLogical <translate> <logicalName> [<slash>]

Description

Returns the physical pathname represented by the value of logicalName. This function can also be used to convert all slashes in a string to either forward slashes or back slashes as required.

The use of the slash argument is optional and defaults to a forward slash if it is not present. Generally no value is required for this argument, but if you were creating a batch file or writing a path to a file to be read by another program, then backslashes may be necessary.

Note: It is not necessary to use SclLogical translate on arguments to the native TCL file, open or source commands. Logical pathnames in arguments sent to these commands will be translated automatically.

Arguments

<translate>

A literal string to identify the sub function

<logicalName>

The name of the logical to translate

<slash>

This argument is optional. By default, any slashes in the expanded path will be returned as forward slashes. To insist on back slashes, specify "\\" for this argument. To return the translation exactly as it is defined in the translation table, use "-" for this argument.

Returns

The logical to physical path translation. Note that if no translation can be performed the value of logicalName is returned.

Examples

# create a logical
SclLogical add "TEST:" "[pwd]/temp\\"
# now test variations of SclLogical translate  []
puts "TEST: --> [SclLogical translate TEST:]    (should have forward slashes)"
puts "TEST: --> [SclLogical translate TEST: /]  (should have forward slashes)"
puts "TEST: --> [SclLogical translate TEST: \\] (should have back slashes)"
puts "TEST: --> [SclLogical translate TEST: -]  (slashes exactly as defined)"