From Xojo Documentation
|You are currently browsing the old Xojo documentation site. It will go offline as of October 2, 2023. Please visit the new Xojo documentation site! - you will be redirected shortly...|
Used to execute Unix or DOS shell commands under Windows, macOS, or Linux.
Use the Shell class to execute DOS or Unix commands and get the results. The Execute method executes a one-line command in Synchronous mode. This causes two properties of the Shell object to change: ErrorCode, which is a system-supplied error code or 0 for no error; and Result, which is a string containing the output of the command. The TimeOut property specifies how long (in milliseconds) a process can run before it is automatically terminated. A value of -1 means the process can run indefinitely. This property currently applies only to Windows.
The process running in the Shell is killed when the object gets out of scope even if running in asynchronous or interactive modes.
The Shell is not equivalent to the Terminal or Command app for your OS. Paths and other default settings will likely not be the same. If you need to do configuration of the Shell before you use it, be sure to set it up to be interactive so you can set up the configuration before calling other shell commands. Alternatively you could create a batch file that sets everything up and call that instead.
|If you send a unavailable command to the Shell, a ShellNotAvailableException will be raised.|
Shell Differences on Windows
It appears that some Windows shell commands such as ftp or telnet will not work as expected due to these tools not using the standard IO streams that can be read by the Shell class.
- Take advantage of the ftp commands built-in scripting capability.
- Spawn the ftp app in a hidden console window and read its input using low-level console IO functions as described in this Microsoft document: http://msdn.microsoft.com/en-us/library/ms684965(VS.85).aspx
- Use a 3rd part ftp or telnet class.
Using the synchronous mode, the following code lists the current directory's files using the dir command on Windows and ls on macOS and Linux.
s = New Shell
#If TargetWindows Then
#ElseIf TargetMacOS Or TargetLinux Then
If s.ExitCode = 0 Then
MessageBox("Error code: " + s.ErrorCode.ToString)
The following example gets the names and values of the environment variables on the user's computer and displays the information in a TextField. You can use the EnvironmentVariable method of the System module to get or set individual environment variables.
Var cmd As String
#If TargetMacOS Or TargetLinux Then
cmd = "env"
#ElseIf TargetWindows Then
cmd = "set"
If s.ExitCode = 0 Then
TextField1.Text = s.Result
TextField1.Text = "Error " + Str(s.ErrorCode)
The following terminal application allows you to submit Unix commands using the interactive mode. The interface consists of two TextFields, InputField, in which the user can enter a command, and OutputField that displays the results.
The Open event for the window initializes the shell object (declared as a property of the window).
mShell.ExecuteMode = Shell.ExecuteModes.Interactive
The user can type a unix command into the TextField, InputField. When he presses Return, the following code in the TextField's KeyDown event runs. The Write method sends the command to the Shell's input buffer.
If Not mShell.IsRunning Then
InputField.Text = ""
A Timer calls the ReadAll method in its Action event and displays the output in OutputField:
Var output As String = mShell.ReadAll
If output <> "" Then
OutputField.SelectedText = output