# InetTelnetRunScript

int InetTelnetRunScript (int telnetHandle, const TelnetScript script[], char lineTerminatingCharacters[], int itemsInScript, char log[], int timeout);

## Purpose

Executes a script on the specified Telnet connection. If a timeout occurs, this function returns an error.

The script consists of an array of clusters of two strings: prompt and reply. For each cluster, the function reads from the connection until the prompt matches the characters read. Then the function writes the reply to the connection. Finally, the function returns the data read from and written to the connection in the log, if desired.

This function is useful when you know what data is coming from the connection. For example, you can log on to a UNIX shell whose prompt character is %, execute a command, and log out with the following script:

prompt: login:
reply: <user name>

prompt: sword:
reply: <user password>

prompt: %
reply: <a command you want to run>

prompt: %
reply: logout

To construct this script, you must use an array of type TelnetScript. Each element in this array has a prompt and a reply string (char*). You can declare and construct such a script using the following code:

/* Declare a TelnetScript array */
TelnetScript script[4];

/* Fill the array with prompt/reply strings */
script[0].prompt = "login:";
script[0].reply = <user name>;

script[1].prompt = "sword:";
script[1].reply = <user password>;

script[2].prompt = "%";
script[2].reply = <a command you want to run>;

script[3].prompt = "%";
script[3].reply = "logout";

## Parameters

Input
Name | Type | Description
telnetHandle | integer | An integer handle identifying the Telnet connection. You can call InetTelnetOpen to obtain this handle.
script | const TelnetScript [] | The list of strings to be read and written on the Telnet connection. These strings are passed as a TelnetScript array. Refer to the function help for detailed instructions for constructing such an array.
lineTerminatingCharacters | char [] | Character(s) that will be written to the Telnet connection after each reply has been sent. When you send a command to a remote computer by way of a Telnet server, the command is not processed until you terminate the line (press <Enter>). You must send line terminating characters that the particular Telnet server understands. National Instruments recommends using the default - carriage return and line feed.
itemsInScript | integer | The number of prompt/reply pairs in the script array that will be sent over the Telnet connection. This value must be less than or equal to the number of elements in the script array.
logLength | integer | Length of the array passed to the Log parameter in bytes.
timeout | integer | Timeout in milliseconds for an individual read or write in the script. The timer is restarted for each prompt/reply. If timeout ms pass while a particular prompt/reply is processing, the function returns with an error indicating that the script did not complete. You can examine the log to determine exactly where the script failed. Passing –1 for timeout causes each read and write to wait indefinitely until it is finished.
Output
Name | Type | Description
log | char [] | The data read from and written to the Telnet connection with the Telnet control characters filtered out. If an error occurs during the operation of the script, you can examine the log to determine what was successfully read from and written over the Telnet connection. log must be able to hold all the bytes read and written plus one extra byte for the NUL character. Passing NULL for log causes the function to discard this data.
| Note This function converts any NUL characters received from the Telnet server into line feeds ('\n' or ASCII decimal value 10). This makes log viewable as a string.

## Return Value

Name | Type | Description
result | integer | Return value indicating whether the function was successful. A negative number indicates that an error occurred.