Skip to main content

TrFile_ExecuteShell (function reference)

Troi File Plug-in > Functions reference > TrFile_ExecuteShell
Troi File Plug-in for FileMaker Pro


Execute a command in the (UNIX or Windows) shell of the operating system.

SyntaxFunction badge

TrFile_ExecuteShell ( switches ; shellCommand )


switches these alter the behavior of the function
shellCommand the command to be executed


Switches can be empty or one of this:

-TimeoutSecs=x specify the timeout time in x seconds (default = 20 seconds)
-DontWaitOnResult execute the shell command without waiting on a result
-ShowCommandWindow (Windows only) show the command window when the shell is running
-WaitAfterExitTicks=x (Windows only) wait x ticks (= 1/60th of a sec) after the command finishes

You can specify the encoding with one of these switches:

-Encoding=Native (default) uses the native encoding for the command
-Encoding=ASCII_DOS use OEM DOS ASCII for the higher ASCII’s 128-255
-Encoding=ASCII_Windows use Ansi Windows ASCII for the higher ASCII’s 128-255
-Encoding=ASCII_Mac use Mac ASCII for the higher ASCII’s 128-255 (as used in fmp 6)

Returned Result

Data type returned



The result of the shell command or an error code

If an error occurs it will start with 2 dollars, followed by the error code. You should always check for errors. Returned error codes can be:

$$-4218 kErrCanNotEnable can not start a shell
$$-4230 kErrTimeout timeout error

Other errors may be returned.

Originated in

Troi File Plug-in 4.0


FileMaker Pro 16 to FileMaker Pro 2023


This is a powerful function, with which you can accomplish multiple commands. Please read about the shell command in Unix or Windows before using this.

For Windows: to be able to use spaces and quotes in the command wrap the whole command in 2 extra double quotes, one at the beginning and one at the end, like “”C:\testapp.exe” “test param””

The maximum number for the -TimeoutSecs switch is 1800.

(Windows) If you use the switch “-Encoding=UTF8” the plug-in indicates invalid UTF-8 characters with the string <INVALID UTF8>.

(macOS) If you need sudo (execute as superuser) you can do this like this:

echo "yourPassword" | sudo -S yourCommand variables etc

For example:

echo "topsecret" | sudo -S  ls -al

This will execute the ls command as the superuser.


On Windows:

Set Field [ gResult ; TrFile_ExecuteShell ( "-Unused" ; "dir C:\" ) ]

On macOS:

Set Field [ gResult ; TrFile_ExecuteShell ( "-Unused" ; "ls /" ) ]

This will list the contents of the root folder.

Example 2

On Windows:

Set Field [ gResult ; TrFile_ExecuteShell ( "-TimeoutSecs=5" ; "echo testtext > C:\example.txt" ) ]

On macOS:

Set Field [ gResult ; TrFile_ExecuteShell ( "-TimeoutSecs=5" ; "echo testtext > /example.txt" ) ]

This will create a text file example.txt on your startup disk. If the command takes more time than 5 seconds the plug-in will return with a timeout error $$-4230.

Used in example file


Related script stepScript step badge

Execute Shell

Related topics

Troi File Plug-in online help (overview)

Online Help Page for Troi File Plug-in for 16 to 2023 –> TrFile_ExecuteShell (filep4295) 2023-0601 16:42:04