Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

Shell.Execute

Executes a child process.

Component Version macOS Windows Linux Server iOS SDK
Shell 7.5 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ❌ No
MBS( "Shell.Execute"; ShellRef; Executable { ; Arguments... } )   More

Parameters

Parameter Description Example Flags
ShellRef The reference number from the shell. $shell
Executable The path to the executable.
Should be full path to executable.
On Windows, the system also searches path if you just specify a file name.		 "/bin/ls"
Arguments... Pass additional arguments to send. "-v" Optional

Result

Returns OK or error.

Description

Executes a child process.
Parameters set by SetArgument* functions are passed first followed by any parameters you pass here.

On macOS, we use NSTask.
https://developer.apple.com/documentation/foundation/nstask

On Linux we use execve function.
https://www.unix.com/man-page/linux/3/execve/

On Windows we use CreateProcess function and we pass in a command line with the Executable parameter followed by all the arguments. If needed, we put them in quotes.
https://msdn.microsoft.com/en-us/library/windows/desktop/ms682425(v=vs.85).aspx

If username is given for Windows, we use CreateProcessWithLogon function instead to provide login as a local user.
https://msdn.microsoft.com/en-us/library/windows/desktop/ms682431(v=vs.85).aspx

If you just need to launch a file, please use Files.LaunchFile or Files.Launch.
You can run "/usr/bin/whoami" on Mac/Linux or "whoami.exe" on Windows to print the user who executes the shell tool.

For PowerShell scripts on Windows, you may need to check with the execution policy for the user account FileMaker is using or use an admin account. e.g. on FileMaker Server, may need to be installed as Admin user (not fmserver user).

This function takes variable number of parameters. Pass as much parameters as needed separated by the semicolon in FileMaker.
Please repeat Arguments parameter as often as you need.

Examples

Run ffmpeg in shell to convert video to mp3 file:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Field [ Shell::Output ; "" ]
Set Field [ Shell::Error ; "" ]
Commit Records/Requests [ With dialog: Off ]
# Where the app is:
Set Variable [ $executable ; Value: "/Applications/ffmpegX.app/Contents/Resources/ffmpeg" ]
# option: overwrite file
Set Variable [ $s ; Value: MBS( "Shell.AddArgument"; $shell; "-y" ) ]
# option: input file
Set Variable [ $s ; Value: MBS( "Shell.AddArgument"; $shell; "-i" ) ]
# Path to input file
Set Variable [ $InputFile ; Value: "/Users/cs/Desktop/movie.m4v" ]
# and output file
Set Variable [ $OutputFile ; Value: "/Users/cs/Desktop/sound.mp3" ]
# Run it!
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; $executable; $InputFile; $OutputFile) ]
Set Variable [ $error ; Value: "" ]
Set Variable [ $result ; Value: "" ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    # Loop while app runs and collect messages
    Loop
        # Wait a second or till it quits
        Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 1) ]
        # And read output
        Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
        Set Variable [ $result ; Value: $result & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
        Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
        Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
        # exit when done
        Exit Loop If [ MBS( "Shell.IsRunning"; $shell) ≠ 1 ]
    End Loop
    # We are done
    Commit Records/Requests [ With dialog: Off ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Query python version:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/python3"; "-E"; "-c"; "import sys;print(sys.version_info);") ]
Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 1) ]
Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Expand tar archive:

Set Variable [ $DestFolder ; Value: "/Users/cs/Desktop" ]
Set Variable [ $TarFile ; Value: "/Users/cs/Desktop/FNFTES.tar " ]
# run tar
Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/tar"; "-xv"; "-C"; $DestFolder; "-f"; $TarFile) ]
Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 10) ]
Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Run a python script:

Set Variable [ $shell ; Value: MBS("Shell.New") ]
Set Variable [ $s ; Value: MBS("Shell.execute"; $shell; "/usr/local/bin/python3"; "/Users/morkus/MBSTest/MBS.py"; PythonMBSTest::Input) ]
Set Variable [ $s ; Value: MBS("Shell.Wait"; $shell; 1) ]
Set Variable [ $error ; Value: MBS("Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: MBS("Shell.ReadOutputText"; $shell ; "UTF-8") ]
Set Field [ PythonMBSTest::output ; $result ]

Run defaults to change preferences for Dock application:

Set Variable [ $error ; Value: "" ]
Set Variable [ $result ; Value: "" ]
Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/defaults"; "write"; "com.apple.dock"; "persistent-apps"; "-array-add"; "<dict><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>/Applications/Font Book.app</string><key>_CFURLStringType</key><integer>0</integer></dict></dict></dict>") ]
Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 2) ]
Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: $result & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/killall"; "Dock") ]
Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 2) ]
Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: $result & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Start VPN on Mac:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/sbin/scutil"; "--nc"; "start"; "VPN Name") ]
Set Variable [ $error ; Value: "" ]
Set Variable [ $result ; Value: "" ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 2) ]
    Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
    Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]
If [ Length ( $error ) > 0 ]
    Show Custom Dialog [ "VPN Start" ; $error & ¶ & $result ]
End If

Register FileMaker with Launch Services:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister"; "-r"; "-f"; "/Applications/FileMaker Pro 16 Advanced/FileMaker Pro Advanced.app") ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 5) ]
    Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
    Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
    If [ Length ( $error ) > 0 ]
        Show Custom Dialog [ "Failed" ; $error ]
    End If
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Zip files on FileMaker Cloud using Wait function waiting for 2 minutes maximum:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/zip"; "-r"; "/tmp/Logs.zip"; "/FileMakerData/Logs") ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $running ; Value: MBS( "Shell.Wait"; $shell; 120) ]
    Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
    Set Variable [ $output ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]
New Record/Request
Set Field [ MBS Test::Result ; $output ]
Set Field [ MBS Test::Error ; $error ]
Commit Records/Requests [ With dialog: On ]

Zip files on FileMaker Cloud using IsRunning in a loop waiting for 2 minutes maximum:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/zip"; "-r"; "/tmp/Logs.zip"; "/FileMakerData/Logs") ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $error ; Value: "" ]
    Set Variable [ $running ; Value: MBS( "Shell.IsRunning"; $shell) ]
    Set Variable [ $output ; Value: "" ]
    Set Variable [ $count ; Value: 0 ]
    Loop
        Set Variable [ $count ; Value: $count + 1 ]
        Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
        Set Variable [ $output ; Value: $output & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
        Exit Loop If [ MBS( "Shell.IsRunning"; $shell) ≠ 1 ]
        Exit Loop If [ $count > 1200 ]
        Pause/Resume Script [ Duration (seconds): ,1 ]
    End Loop
    Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
    Set Variable [ $output ; Value: $output & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]
New Record/Request
Set Field [ MBS Test::Result ; $output ]
Set Field [ MBS Test::Error ; $error ]
Commit Records/Requests [ With dialog: On ]

Convert Word file using LibreOffice to PDF:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/Applications/LibreOffice.app/Contents/MacOS/soffice"; "--convert-to"; "pdf"; "--headless"; "--outdir"; "/Users/cs/Desktop"; "/Users/cs/Documents/test.doc" ) ] 
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 10) ] 
    Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ] 
    Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ] 
    Show Custom Dialog [ "Converted" ; $result & ¶ & $error ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Zip Files on Mac with current directory to get relative paths in zip archive:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $Folder ; Value: MBS( "Folders.UserDesktop" ) ]
Set Variable [ $s ; Value: MBS( "Shell.SetCurrentDirectory"; $shell; $Folder) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/zip"; "-r"; "-X"; "ziptest.zip"; "Test") ]
Set Variable [ $error ; Value: "" ]
Set Variable [ $result ; Value: "" ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    # Loop while app runs and collect messages
    Loop
        Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 1) ]
        Set Variable [ $error ; Value: $error & MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
        Set Variable [ $result ; Value: $result & MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
        Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
        Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
        Exit Loop If [ MBS( "Shell.IsRunning"; $shell) ≠ 1 ]
    End Loop
    Commit Records/Requests [ With dialog: Off ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Translate ffmpeg command line:

# ffmpeg -i "D:\Test\fmp\1901070400.mp4" -ss 00:00:05.435 -vframes 1 "D:\Test\fmp\1901070400.jpg"

MBS( "Shell.Execute"; $shell; "C:\ffmpeg\bin\ffmpeg.exe"; "-i"; "D:\Test\fmp\1901070400.mp4"; "-ss"; "00:00:05.435"; "-vframes"; "1"; "D:\Test\fmp\1901070400.jpg")

Run fmsadmin via Shell:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ] 
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "C:\Program Files\FileMaker\FileMaker Server\Database Server\fmsadmin.exe"; "-v"; "-u"; "admin"; "-p"; "xxx") ] 
If [ MBS("IsError") ] 
    Show Custom Dialog [ "Failed to run" ; $s ] 
Else
    # Loop while app runs and collect messages
    Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 5) ] 
    Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ] 
    Show Custom Dialog [ "Result" ; $result ] 
End If

Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

Run shell command with several tools concated:

MBS( "Shell.Execute"; $shell; "/bin/sh"; "-c"; "diskutil list | grep /dev | awk '{print $1}'")

Run command in one Let statement:

Let ( [
// new Shell
shell = MBS( "Shell.New" );
// run command with parameters
r = MBS( "Shell.Execute"; shell; "/bin/ls"; "/");
// wait for a result up to 5 seconds
r = MBS( "Shell.Wait"; shell; 5);
// read output
error = MBS( "Shell.ReadErrorText"; shell; "UTF-8");
output = MBS( "Shell.ReadOutputText"; shell; "UTF-8");
// free shell
r = MBS("Shell.Release"; shell)
]
; output & error )

Run bat file with one parameter:

MBS( "Shell.Execute"; $shell; "C:\Users\Christian\Desktop\test.bat"; "123")

Rename file with cmd.exe on Windows:

MBS( "Shell.Execute"; $shell; "cmd"; "/c"; "ren C:\Users\Christian\Desktop\test.pdf test2.pdf")

Run php on macOS to point to a file:

Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/php"; "-f"; "/Users/cs/Desktop/test.php") ]

Run whois on Windows:

MBS( "Shell.Execute"; $shell; "C:\whois.exe"; "-v"; "-nobanner"; "google.com")

Run PowerShell with a batch file:

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.SetArgumentsList"; $shell; Shell::Arguments List ) ]
Set Variable [ $s ; Value: MBS( "Shell.SetApplicationName"; $shell; "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "powershell.exe"; "-file"; "c:\Users\Christian\Desktop\test.ps1") ]
#
Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 5) ]
Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
Set Field [ Shell::Error ; MBS( "Text.ReplaceNewline"; $error; 1) ]
Set Field [ Shell::Output ; MBS( "Text.ReplaceNewline"; $result; 1) ]
#
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]
#
# You need first to run via powershell as admin those commands to enable execution of powershell from FileMaker:
# Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine
# Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Query distribution description for Linux server:

Let ( [
// new Shell
shell = MBS( "Shell.New" );
// run lsb release to print description for distribution
r = MBS( "Shell.Execute"; shell; "/usr/bin/lsb_release"; "-d");
// wait for a result up to 5 seconds
r = MBS( "Shell.Wait"; shell; 5);
// read result
output = MBS( "Shell.ReadOutputText"; shell; "UTF-8");
// free shell
r = MBS("Shell.Release"; shell)
]
; output )

Example result:
on CentOS 7.9 we get:
"Description:   CentOS Linux release 7.9.2009 (Core)"
on Ubuntu 18.04 we get:
"Description:   Ubuntu 18.04.5 LTS"

Query list of clients on Linux via fmsadmin:

Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/usr/bin/fmsadmin"; "list"; "clients"; "-s"; "-c"; "-u"; "admin"; "-p"; "admin") ]

Run shell script on Linux server:

# run shell in file Anlagen (fmsubuntu)

Set Variable [ $shell ; Value: MBS( "Shell.New" ) ]
Set Variable [ $s ; Value: MBS( "Shell.Execute"; $shell; "/bin/bash"; "/opt/FileMaker/FileMaker Server/Data/Documents/test.sh") ]
If [ MBS("IsError") ]
    Show Custom Dialog [ "Failed to run" ; $s ]
Else
    Set Variable [ $s ; Value: MBS( "Shell.Wait"; $shell; 10) ]
    Set Variable [ $error ; Value: MBS( "Shell.ReadErrorText"; $shell; "UTF-8") ]
    Set Variable [ $result ; Value: MBS( "Shell.ReadOutputText"; $shell; "UTF-8") ]
End If
Set Variable [ $r ; Value: MBS("Shell.Release"; $shell) ]

See also

Release notes

Example Databases

Blog Entries

This function checks for a license.

Created 11st November 2017, last changed 10th January 2024


Shell.CloseStreams - Shell.ExitCode