Shell

From Xojo Documentation
Jump to: navigation, search

Class (inherits from Object)

Used to execute Unix or DOS shell commands under Windows, macOS, or Linux.

Events
Completed DataAvailable


Properties
Arguments ErrorCode PID
Backend IsRunning Result
Canonical Mode TimeOut


Methods
Close Poll Write
Execute ReadAll WriteLine

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: 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 mode (Mode = 1 or 2).

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.

Shell Differences on Windows

It appears that some Windows shell commands such as ftp or telnet will not work as expected.

See this post to learn about shell differences on Windows.

Examples

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.

Dim s As Shell
s = New Shell
#If TargetWindows Then
s.Execute("dir")
#ElseIf TargetMacOS Or TargetLinux Then
s.Execute("ls -la")
#Endif
If s.ErrorCode = 0 Then
TextField1.Text = s.Result
Else
MsgBox("Error code: " + Str(s.ErrorCode))
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.

Dim s As New Shell
Dim cmd As String
#If TargetMacOS Or TargetLinux Then
cmd = "env"
#ElseIf TargetWindows Then
cmd = "set"
#Endif
s.Execute(cmd)
If s.ErrorCode = 0 Then
TextField1.Text = s.Result
Else
TextField1.Text = "Error " + Str(s.ErrorCode)
End If

Interactive Shells

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 = New Shell
mShell.Mode = 2

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 key = Chr(13) Then
If Not mShell.IsRunning Then
mShell.Execute("sh")
End If
mShell.Write(InputField.Text)
mShell.Write(Chr(13))
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:

If mShell <> Nil Then
Dim output As String = mShell.ReadAll
If output <> "" Then
OutputField.SelText = output
End If
End If

See Also

TargetLinux, TargetMachO, TargetMacOS, TargetWin32, TargetX86, TargetCocoa constants.

Personal tools
Namespaces

Variants
Actions
Main
Content
Starting Out
Dig Deeper
More Help
Toolbox
About