TrFile_ExecuteShell (function reference)

By May 1, 2017 May 22nd, 2019 Online 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

switchesthese alter the behavior of the function
shellCommandthe command to be executed

Switches

Switches can be empty or one of this:

-TimeoutSecs=xspecify the timeout time in x seconds (default = 20 seconds)
-DontWaitOnResultexecute 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_DOSuse OEM DOS ASCII for the higher ASCII’s 128-255
-Encoding=ASCII_Windowsuse Ansi Windows ASCII for the higher ASCII’s 128-255
-Encoding=ASCII_Macuse 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 errorcode

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:

$$-4218kErrCanNotEnablecan not start a shell
$$-4230kErrTimeouttimeout error

Other errors may be returned.

Originated in

Troi File Plug-in 4.0

Compatibility

FileMaker Pro 14 to 18

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 Mac OS:

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 Mac OS:

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.

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 14 to 18 –> TrFile_ExecuteShell (filep4295) 2019-0522 16:37:36