Topics   All   Mac OS X (Only)   Windows (Only)   Linux (Only, Not)   iOS (Only, Not)  
Components   Crossplatform Mac & Win   Server   Client   Old   Guides   Examples
New in version: 7.0   7.1   7.2   7.3   7.4   7.5   8.0   8.1   8.2   8.3    Statistic  

Shell.Execute

Executes a child process.

Component Version macOS Windows Server FileMaker Cloud FileMaker iOS SDK
Shell 7.5 Yes Yes Yes Yes No

MBS( "Shell.Execute"; ShellRef; Executable { ; Additional Arguments } )

Parameters

Parameter Description Example value
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"
Additional Arguments Optional
Pass additional arguments to send.
"-v"

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.

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/python"; "-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"; "--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) ]

See also

Example Databases


Shell.CloseStreams   -   Shell.ExitCode

Feedback: Report problem or ask question.




Links
MBS FileMaker Plugins