Rsh Method

Description

Uses the remote shell protocol common to UNIX systems, which is intended to execute shell commands on a remote UNIX host. This method differs from the Rexec method (which implements the remote execute protocol) by being faster and not requiring a full login. For full description of the remote shell protocol, see the UNIX man pages.

Syntax

Visual Basic
Public Sub Rsh( _ ByVal RemoteName As String, _ ByVal User As String, _ ByVal Command As String, _ Optional ByVal RemotePort As Long = 0, _ Optional ByVal LocalName As String, _ Optional ByVal LocalPort As Long = 0 _ )

Visual Basic

Public Sub Rsh( _
   ByVal RemoteName As String, _
   ByVal User As String, _
   ByVal Command As String, _
   Optional ByVal RemotePort As Long = 0, _
   Optional ByVal LocalName As String, _
   Optional ByVal LocalPort As Long = 0 _
)

Parameters

RemoteName: Can be either a host name (host.dart.com) or dot address (nnn.nnn.nnn.nnn).
User: Login name of the user.
Command: Command(s) to execute on the remote host.
RemotePort: Must be a value between 1 and 65535, inclusive. Defaults to 514.
LocalName: Local interface to bind socket to.
LocalPort: Local port to bind socket to.

Remarks

This method requires authorization for the local host running your application. This is done by adding the proper entries to the hosts.equiv or .rhosts files located on the remote host. These files enable logins to be performed from other machines and users. The hosts.equiv file is a system file containing names of remote hosts authorized to execute the remote protocol. If not authorized in this file, the remote host looks for the .rhosts file located in the user's account on the remote host. The .rhosts file contains lines of host names and login names paired together. Your local host with login name is authorized if found in this file.

When invoked, a connection is initiated with the remote host using the remote shell protocol. The State property immediately changes to tcpConnecting and then changes to tcpConnected when the connection is established. The State Property can be checked in the body of the State event, polled off a timer, or checked immediately after the method is invoked when a positive Timeout is specified. Once connected, Command is sent where it executes on the remote host. Use the Receive method or Search method to capture output generated from the command. Upon command completion, the remote host closes the connection and the State event fires with the State property set to tcpClosed. This method is invoked as blocking or non-blocking, depending on the value of the Timeout property.

When performing blocked method calls, the Blocked property may be checked to verify the control is not busy executing another method.

Error Codes
The Rsh method may generate the following error codes (refer to the ErrorConstants topic for a complete list of error codes):

ptAddressInUse
ptAddressNotAvailable
ptBlocked
ptConnectionRefused
ptHostNotFound
ptInvalidParam1 (RemoteName is not a valid string)
ptInvalidParam2 (User is not a valid string)
ptInvalidParam3 (Command is not a valid string)
ptNetworkDown
ptNetworkUnreachable
ptNoBufferSpace
ptNoData
ptNotInitialized
ptProtocol (the host returned an error)
ptTimeout
ptTryAgain

Example

Blocking Example (Visual Basic)

Private Sub Command1_Click()
On Error GoTo OnError ' use intrinsic error handling
	Telnet1.Timeout = 1000
	Telnet1.Rsh "myhost", "myUsername", "reboot" 'reboot remote UNIX host
	' didn't go to OnError, so we connected and execute listing before 30 seconds elapsed!
	Exit Sub
OnError: ' Any error jumps here
	' no connection within 30 seconds, or other error (Tcp1.State is tcpClosed)
	Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub

Non-Blocking Example (Visual Basic)

Private Sub Command1_Click()
	Telnet1.Timeout = 0
	'connect and start executing listing followed by the date command
	'this demonstrates executing multiple commands
	Telnet1.Rsh "myhost", "myUsername", "ls la; date"
End Sub
 
Private Sub Telnet1_State()
	If Telnet1.State = tcpConnected Then MsgBox "Connected!"
End Sub
 
Private Sub Telnet1_Receive()
	Dim Output As String
	Telnet1.Receive Output
	Text1.Text = Output
End Sub