Skip to main content

Local and Global Properties for Files and File Systems

The local and global properties described here affect the way SenseTalk scripts access or interact with files and file system objects. For additional information about working with files and the file system in SenseTalk, see File and Folder References and File and Folder Interaction.

Setting or Changing Local and Global Property Values:

You can set a global property value with the SenseTalk commands Set or Put. Note that when you reference one of these properties, you must use the word the before the property name to distinguish it from an ordinary variable.


set the searchrectangle to [1,2,2,3]
put 2 into the remoteworkinterval

You can add or change specific named properties within a global property like this:

set the to color("RGB,1.0,0.5,0.5") -- Adds pink to the namedColors global property and defines its RGB color value
set the listFormat's separator to " & " -- Sets the separator property of the listFormat global property

Properties can also be set or updated by using the setoption or setoptions commands. The setoption command lets you update a single property, and setoptions lets you update multiple properties.


setoption searchrectangle, [1,2,2,3]
setoptions {searchrectangle: [1,2,2,3], scriptlogging: yes}

Because setoption and setoptions are specific for use with global and local properties, you omit the word the from the property name in the command syntax for these commands.

For additional information about working with local and global properties, see Local and Global Properties in SenseTalk.

the folder, the directory Global Properties

Values: The path for the current working directory

Default: Typically, the path to the Documents folder; however, this value can be changed by updating the Default Suite Directory setting in the General section of Preferences.

Behavior: This property lets you access or change the current working folder. The value returned by the folder ends with a slash unless the folderNamesEndWithSlash global property is set to false. The slash at the end makes it easy to create a full path name by appending a file name, as shown in the example below.


The words folder and directory are used interchangeably within SenseTalk scripts. Wherever the word folder is used in a script, you can use the word directory instead.


set the directory to "C:\Users\Carrie\Desktop\"


set the folder to "C:\Users\Carrie\Desktop\"


set the directory to "C:\Users\Carrie\Desktop\data\"
put the files of the folder into fileObjects // Returns a list of the file objects for any files in the current working directory and stores them in a variable


set the folder to "/tmp/myWorkArea" -- Sets the working folder
put the folder & "newfile.txt" into filePath
put "xyz" into file filePath


the folderNamesEndWithSlash Global Property

Values: True, False

Default: True

Behavior: This property determines whether folder or directory names are returned with a slash at the end. This property applies to the folder and the directory global properties as well as the various SenseTalk commands and functions that return directory paths.


set the folderNamesEndWithSlash to false


log the folder // Logs the current working directory with a slash at the end. For example: 'C:/Users/Carrie/Documents/'
set the folderNamesEndWithSlash to false
log the folder // Logs the current working directory without a slash at the end. For example: 'C:/Users/Carrie/Documents'


set the folderNamesEndWithSlash to false
put the folder & "\newfile.txt" into filepath // Concatenates the / to create a valid path, because the / is not returned by the folder function
put "xyz" into file filepath


the strictFiles Global Property

Values: True, False

Default: False

Behavior: This property can be used to provide stricter control over the use of files at runtime. When this property is set to True, reading a nonexistent file as a container throws an exception rather than returning empty.

When set to False, reading from a nonexistent file returns a value as though that file were empty. Sometimes this behavior can lead to unexpected results. For example, if a file name is entered incorrectly, a script treats it as empty rather than giving an error indicating that the file could not be found.


set the strictFiles to true


set the StrictFiles to true
put file "C/Desktopmyfile.txt" into myData // Throws exception: StrictFilesViolation Attempt to read nonexistent file: C:/Users/Carrie/Documents/C/Desktopmyfile.txt'


  • the strictProperties
  • the strictVariables

the defaultStringEncoding Global Property

Values: The current string encoding method. To see the full list of available values, use the availableStringEncodings() function:

put availableStringEncodings()

Default: UTF8

Behavior: This property specifies how text strings are encoded when they are read from or written to a file, socket, or URL. This setting is used by the read and write commands, and also when treating either a file or a URL as a container. Acceptable values for the defaultStringEncoding include: UTF8, Unicode, ASCII, and many others.


set the defaultStringEncoding to "ASCII"


put BlackDiamond as data // Displays '<e29786>'
set the defaultStringEncoding to "Unicode"
put BlackDiamond as data // Displays '<fffec625>'


put "C:\Users\Carrie\Desktop\Data\characters.txt" into filePath // The file at this path contains unicode characters
set the DefaultStringEncoding to "Unicode"
put file filePath // Displays unicode characters from the file. For example: ʘʤϬϮ


put the defaultStringEncoding into origEncoding
set the defaultStringEncoding to "Unicode" -- Full 16-bit Unicode text
put myInternationalText into file "/tmp/twoByteText"
set the defaultStringEncoding to origEncoding -- Restores original value

Tech Talk

Within SenseTalk, text characters are simply what they are: the letter A is the letter A, and the letter é is the letter é (an e with an acute accent). Externally, though, there are a number of different ways that the same characters might be represented as sequences of bits and bytes. Each different text representation is called an encoding. The standard encoding used by SenseTalk is UTF8, which is a widely used 8-bit system for encoding Unicode characters.

the umask Global Property

Values: A 3-digit number; see the Behavior section for detailed description

Default: 022

Behavior: Sets or retrieves the posix permissions mask for newly created files. Use the umask property to control the access permissions for any file or folder created by SenseTalk, either directly or indirectly. The mask is a 3-digit number: the digits control file permissions for the user, the group, and others, respectively. Each digit is a number from 0 to 7 indicating the permissions that will be blocked, with the value 4 used to block read permission, 2 to block write permission, and 1 to block execute permission. The values may be added together to block more than one permission.


set the umask to 077


put the umask into origMask
set the umask to 247 -- Set so user can't write, group members can't read, and others have all permissions blocked
create file "/tmp/permissionsTest"
set the umask to origMask -- Restore it to its original value


the autoSaveDatabaseUpdates Global Property

Values: True, False

Default: True

Behavior: This property determines whether updates to databases are saved automatically. When set to True, all updates are automatically saved. Set this property to False if you want to write changes manually by using the save changes command.


set the autoSaveDatabaseUpdates to false


set the autoSaveDatabaseUpdates to false // Turns off automatic updates
set info to table "memberinfo" of myDB
set member to the record of info where memberNumber is 16
Add 60 days to member's expirationDate
put "23" into member's memberNumber
put the records of info // Displays '((expirationdate:"2020-04-13", membernumber:"16"),(expirationdate:"2019-12-30", membernumber:"18"))'
save all changes to info // Sends all pending updates to the table
put the records of info // Displays '((expirationdate:"2019-12-30", membernumber:"18"),(expirationdate:"2020-06-12", membernumber:"23"))'


the shellCommand Global Property

Values: A full path to the shell program you want to execute shell commands; ShellExecute; empty

Default: Varies by platform; see the Behavior section below.

Behavior: This property controls which shell program is used to run the command when you use the shell command or function. By default, on Mac and Linux the shellCommand is set to /bin/sh (the Bourne shell). To run commands in a different shell, set the shellCommand to the full path of the shell you want to use before calling the shell function, or to "ShellExecute" or empty.

On Windows, the default setting of the shellCommand global property is ShellExecute. This setting causes the Windows ShellExecute() function to be used to run the specified file.

When using ShellExecute on Windows, several additional parameters besides the command or file can optionally be passed. The second parameter, if given, specifies any parameters to be passed to the command being run. The third parameter specifies the default working directory for the action. The fourth parameter should be a number specifying any optional flags to pass to the underlying ShellExecute() function. Finally, the fifth parameter, if given, specifies an explicit verb to use (such as open, explore, edit, find, or print). Otherwise the default verb defined in the registry (or open) will be used. (When using ShellExecute, no output is returned.) If an error occurs, the result will be set to a number; otherwise it will be empty.

When the shellCommand is not empty and is not set to ShellExecute (the usual case on Mac and Linux, where it is set to /bin/sh by default), if multiple parameters are passed to the shell function, they are treated as separate commands to each be run in sequence within a single shell context.

When the shellCommand is empty, shell treats its first parameter as the command to run and any additional parameters as parameters to be passed to that command. If only a single parameter is passed, it is split by any spaces that are present in the parameter to derive the command and its parameters.


set the shellCommand to "ShellExecute"
shell "example.bat" -- Runs the indicated batch file


set the shellCommand to empty
put shell("ls -l") -- Runs the 'ls' command with '-l' parameter
put shell("ls", "-l") -- Does the same thing

There is a Windows operating system limitation when running shell commands. When you run a shell command on Windows, you won't see any output from the shell command. To resolve this issue, redirect the output of the command by piping the output to a file. After the script completes, manually read the file contents to see the result.

shell "c:\windows\system32\cmd.exe", <</c "C:\Program Files (x86)\adt-bundle-windows-x86_64\sdk\platform-tools\adb" >> && MyCommand && "> someFile.txt"
put file "C:\wherever\someFile.txt"