 |
TrFile_ExecuteShell |
Execute a command in the (UNIX or Windows) shell of the operating system.
Syntax
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 17 to FileMaker Pro 21 (2024)
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>.
(macOS) If you need sudo (execute as superuser) you can do this like this:
echo "yourPassword" | sudo -S yourCommand variables etcFor example:
echo "topsecret" | sudo -S ls -alThis will execute the ls command as the superuser.
(macOS) TIP By default the plug-in only returns results from the Unix standard output (stdout). Some Unix commands send error and diagnostic messages to the standard error output (stderr).
If you want the standard error output to be added to the function result add a redirection to stdout to the end of the Unix command: 2>&1. This will redirect stderr (2) to stdout (1).
For example when using the rm (remove) command you can add the redirect like this:
rm nonexistingfile.txt 2>&1Instead of an empty result the result will be:
rm: nonexistingfile.txt: No such file or directoryExample
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 step
| Execute Shell |
Related topics
Troi File Plug-in online help (overview)