Rexec Method

Description

Uses the remote execute protocol common to UNIX systems, which is intended to execute commands on a remote UNIX host. User and Password must match an account on the remote host.

Syntax

Visual Basic
Public Sub Rexec( _ ByVal RemoteName As String, _ ByVal User As String, _ ByVal Password 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 Rexec( _
   ByVal RemoteName As String, _
   ByVal User As String, _
   ByVal Password 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.
Password: Password of the user.
Command: Command(s) to execute on the remote host.
RemotePort: Must be a value between 1 and 65535, inclusive. Defaults to 512.
LocalName: Local interface to bind socket to.
LocalPort: Local port to bind socket to.

Remarks

This method differs from the Rsh method (which implements the remote shell protocol) by performing a full login sequence on the remote host. The Rsh method is typically faster and requires no password, but does require special configuration entries for security reasons. The UNIX pages provide a complete description of this protocol.

When this method is used a connection is initiated with the remote host using the remote execute 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, User, Password and Command is formatted and sent to the remote host. Use the Receive method or Search method to capture the results. When complete, the remote host closes the connection and the State event fires with the State property set to tcpClosing. After the output is captured, the State Property changes 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.

The first character received from the host indicates the success or failure of the command. An ASCII '0' indicates success, and the rest of the buffer contains the result of the command sent. An ASCII '1' indicates failure, and the rest of the buffer contains the error description generated by the host.

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

ptAddressInUse
ptAddressNotAvailable
ptBlocked
ptConnectionRefused
ptHostNotFound
ptInvalidParam1 (RemoteName is not a valid string)
ptInvalidParam2 (User is not a valid string)
ptInvalidParam3 (Password is not a valid string)
ptInvalidParam4 (Command is not a valid string)
ptNetworkDown
ptNetworkUnreachable
ptNoBufferSpace
ptNoData
ptNotInitialized
ptTimeout
ptTryAgain

Example

Blocking Example (Visual Basic)

Private Sub Command1_Click()
On Error GoTo OnError ' use intrinsic error handling
	Telnet1.Timeout = 30000
	Telnet1.Rexec "myhost", "myUsername", "myPassword", "reboot" 'reboot UNIX host
	' didn't go to OnError, so we connected and executed command before 30 seconds elapsed!
	Dim Output As String
	' Telnet1.State should be tcpClosing at this point
	Telnet1.Receive Output
	' Telnet1.State should be tcpClosed at this point
	' First character is completion code, so strip it off and display rest
	Text1.Text = Right(Output, Len(Output)-1)
	Exit Sub
OnError: ' Any error jumps here
	' no connection within 30 seconds, or other error (Telnet1.State is tcpClosed)
	Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub

Non-Blocking Example (Visual Basic)

Private Sub Command1_Click()
	' intrinsic error handling is of limited value for asynchronous connection&ldots;
	Telnet1.Timeout = 0
	'connect and start executing listing followed by the date command
	'this demonstrates executing multiple commands
	Telnet1.Rexec "myhost", "myUsername", "myPassword", "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
	' First character is completion code, so strip it off and display rest
	Text1.Text = Right(Output, Len(Output)-1)
End Sub