` event for the window initializes the Shell object (declared as a property of the window).
>
> ``` xojo
> mShell = New Shell
> mShell.ExecuteMode = Shell.ExecuteModes.Interactive
> ```
>
> The user can type a unix command into the `TextField`, InputField. When they press Return, the following code in the `TextField`'s KeyDown event runs. The Write method sends the command to the Shell's input buffer.
>
> ``` xojo
> If Key = EndOfLine.CR Then
>
> If Not mShell.IsRunning Then
> mShell.Execute "sh"
> End If
>
> mShell.Write(InputField.Text)
> mShell.Write(EndOfLine.CR)
> InputField.Text = ""
> Return True
>
> Else
> Return False
> End If
> ```
>
> A `Timer` calls the ReadAll method in its Action event and displays the output in OutputField:
>
> ``` xojo
> If mShell <> Nil Then
>
> Var output As String = mShell.ReadAll
>
> If Not output.IsEmpty Then
> OutputField.SelectedText = output
> End If
>
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.ExitCode
**ExitCode** As `Integer`
> The exit code returned by the Shell.
>
> It returns `0` if the Execute method was executed successfully. Otherwise, it returns a system-supplied exit code. On Windows, it returns `-1` if execution fails.
>
> This example checks the value of exit code and prints it if it is not zero.
>
> ``` xojo
> Var sh As New Shell
>
> sh.Backend = TextField1.Text
> sh.Arguments = TextField2.Text
> sh.Execute TextField3.Text
> TextArea1.Text = sh.Result
>
> If sh.ExitCode <> 0 Then
> MessageBox("The exit code is: " + sh.ExitCode.ToString)
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.IsRunning
**IsRunning** As `Boolean`
> `True` if an asynchronous or interactive Shell process is running.
>
> This example checks whether the Shell is running before trying to use it.
>
> ``` xojo
> If sh.IsRunning Then
> sh.Poll
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.PID
**PID** As `Integer`
> The ID of the interactive Shell process.
>
> On Windows, this is the process handle rather than the ID of the process.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Result
**Result** As `String`
> Contains the contents of the output buffer without clearing the buffer.
>
> This example runs the `ls` command in a Shell and displays the results:
>
> ``` xojo
> Var sh As New Shell
>
> sh.Execute("ls")
> TextArea1.Text = sh.Result
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.TimeOut
**TimeOut** As `Integer`
> The time (in milliseconds) that specifies how long a process can run before it is automatically terminated (Windows only). The default is `2000` or `2` seconds. Use `-1` to indicate no timeout.
>
> Timeout is only used on Microsoft Windows.
>
> ``` xojo
> Var s As New Shell
>
> s.ExecuteMode = Shell.ExecuteModes.Synchronous
> s.TimeOut = 10000
> s.Execute("DIR")
>
> Select Case s.ExitCode
> Case -2
> 'the command timed out
> Case 0
> 'the command succeeded
> Else
> 'Something else happened
> End Select
> ```
## Method descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Close
**Close**
> Shuts down the running command. Calling Close triggers the Completed event.
>
> ``` xojo
> Var sh As New Shell
> .
> .
> sh.Close
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Execute
**Execute**(command As `String`)
**Execute**(command As `String`, parameters As `String`)
> Executes a one-line Unix or DOS Shell command.
>
> If you are in **Synchronous mode** (mode 0), the `Result` property will contain the results. The *command* parameter is the path/name of the executable to run and the second parameter contains the arguments to pass to the executable. You can specify the executable without passing a second parameter. On Windows, if the path/name of the executable contains spaces and you want to pass arguments to it, it is safer to separate the two.
>
> If you are in **Asynchronous mode** (mode 1 or 2), use the *Execute* method for the first command to be executed. In **Interactive mode** (mode 2), you can then later use `Write` or `WriteLine` to send data or new commands to the Shell.
>
> Execute the `ls` command in a Shell and display the results in a `TextArea`:
>
> ``` xojo
> Var sh As New Shell
>
> sh.Execute("ls")
> TextArea1.Text = sh.Result
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Poll
**Poll**
> Looks for data returned from the running Shell and may trigger a DataAvailable event.
>
> ``` xojo
> Var sh As New Shell
> .
> .
> sh.Poll
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.ReadAll
**ReadAll** As `String`
> Returns the contents of the output buffer and clears the buffer. As a consequence, the property `Result` will return an empty string.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Write
**Write**(s As `String`)
> Sends the passed string to the Shell's input buffer.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.WriteLine
**WriteLine**(s As `String`)
> Sends the passed string ending in a linefeed to the Shell's input buffer.
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.Completed
**Completed**
> Called only in modes Asynchronous and Interactive. Triggered whenever the executed command is finished or the Close method is called.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Shell.DataAvailable
**DataAvailable**
> Occurs when additional data has come into the internal receive buffer.
## Notes
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: `ExitCode`, 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.
Warning
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.
Some workarounds:
- 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: ).aspx
- Use a 3rd part ftp or telnet class.
## Sample code
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.
``` xojo
Var s As New Shell
#If TargetWindows Then
s.Execute("dir")
#ElseIf TargetMacOS Or TargetLinux Then
s.Execute("ls -la")
#EndIf
If s.ExitCode = 0 Then
TextField1.Text= s.Result
Else
MessageBox("Error code: " + s.ExitCode.ToString)
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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.
``` xojo
Var s As New Shell
Var cmd As String
#If TargetMacOS Or TargetLinux Then
cmd = "env"
#ElseIf TargetWindows Then
cmd = "set"
#EndIf
s.Execute(cmd)
If s.ExitCode = 0 Then
TextField1.Text = s.Result
Else
TextField1.Text = "Error " + s.ExitCode.ToString
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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 Opening event for the window initializes the Shell object (declared as a property of the window).
``` xojo
mShell = New Shell
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.
``` xojo
If key = EndOfLine.CR Then
If Not mShell.IsRunning Then
mShell.Execute("sh")
End If
mShell.Write(InputField.Text)
mShell.Write(EndOfLine.CR)
InputField.Text = ""
Return True
Else
Return False
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
A `Timer` calls the ReadAll method in its Action event and displays the output in OutputField:
``` xojo
If mShell <> Nil Then
Var output As String = mShell.ReadAll
If Not output.IsEmpty Then
OutputField.SelectedText = output
End If
End If
```
## Compatibility
| | |
|-----------------------|-----------------------|
| **Project Types** | Console, Desktop, Web |
| **Operating Systems** | All |
`Object` parent class; `System.EnvironmentVariable`; `TargetLinux`, `TargetMachO`, `TargetMacOS`, `TargetWindows`, `TargetX86` constants.