TrFile_ExecuteShell (function reference)

By January 1, 2021May 26th, 2021Online Help, Troi File Plug-in
Troi File Plug-in > Functions reference > TrFile_ExecuteShell
Troi File Plug-in for FileMaker Pro

TrFile_ExecuteShell

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

SyntaxFunction badge

TrFile_ExecuteShell ( switches ; shellCommand )

Parameters

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

Switches

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=UTF8
-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

Text

Result

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

Compatibility

FileMaker Pro 16 to 19

Considerations

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>.

Example

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

ExecuteShell.fmp12

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 19 –> TrFile_ExecuteShell (filep4295) 2021-0526 08:25:27