D

Scripting Language

A scripting language is now available to automate network computer functions that can be started using a Tekterm session. For example, you can create a script that starts PPP, logs you onto a specific host, and opens a session window to a Windows NT or UNIX host.

The scripting language is very similar to functions used in the C language. It uses integer and string variables, flow control statements such as if, loop and goto, and special functions which can send characters on serial port or wait until a certain pattern is received on the port by setting timeouts.

The scripting language has these features:

• It is case-sensitive.
• It is free format, multi-line, and structured.
• It has no line/column orientation.
• Its statement delimiter is ";"
• The keywords for this scripting language are int, str, if, elseif, else, loop, goto, and break.
• It supports both C and C++ style comments.

Creating a Script

1. Create a script using the rules in this section.
2. Place the script in the /tekxp/boot/config/script directory.
3. Add the script's name to the script_files file located in the /tekxp/boot/config/script directory.

Sample Script

There is a sample script in the /tekxp/boot/config/script directory called startup. This sample script provides examples for opening a serial session window and logging you onto a host, opening a Telnet window, and closing the serial session window. It also accesses a second sample script, named conn, which starts a CSLIP session in the open Telnet window, logs you onto a host that has sxprocess, and starts Serial Xpress. These scripts are also listed in the script_files file.

Executing a Script

To execute a script, it must be in the correct script directory. For UNIX, this is /tekxp/boot/config/script. For NT and Windows 2000 hosts, it is \tekxp\boot\config\script . The VMS location for the script is TEK$XP_CONFIG:. The script name must also be included in the script_files file in the same directory.

1. Open the TekSetup client and select Configuration Summaries > Session Manager.
2. Under Connection Method, select Script.
3. Provide the PPP login information for the script:
   • Enter the User Name for the PPP server.
   • Enter the Password for the PPP server.
   • Select Serial Port 0 or 1, depending on where the modem is connected.
   • Enter the phone number for the PPP server.
4. In the Script Dialog box, enter the name of the script (Start_PPP).
5. Select Connect to establish the PPP connection to the PPP server.

Note:

To stop a script that is currently running, click Disconnect.

Remote Configuration Command

This command has been added to the remote configuration file (xp.cnf):

script_variable Command

script_variable variable_name value

This command defines variables and values used with scripts. Each network computer can use unique script variables and/or values.

variable_name specifies the name of the variable. This name can be placed in a script and then accessed when the script executes.

value specifies the value used for the variable defined above. One variable can have multiple values on different network computers. This allows you to customize network computer tasks.

In the following example, the variable is Phone, and the value is 9837813. The variable Phone can be added to a script and when encountered, the phone number 9837813 is accessed. The variable Phone can be used in different xp.cnf files on different network computers with different phone numbers as the value. This allows the network computers to use different phone numbers.

script_variable "Phone" "9837813"

Language Specifics

Variables

The language supports two types of variables; integers and strings. Internally, integers are stored as 32-bit numbers. There is no built-in limitation on string lengths. It is limited by available RAM. All variables should be declared explicitly at the beginning of the program. The scope of variables is always global. String variables are initialized to represent string of length zero.

To define a variable name, the first character must be a letter, subsequent characters can be letters or digits. No other symbols are valid. Here, a letter means a character from the set [a..z, A..Z, _] Sample valid declarations:

int xyz, abc;
str line [80], temp [20], name[75]
int _count2;

Sample invalid declarations:

int 2qwerty, zzz[23],

Literals

There are two type of literals; string and integer. String Literal is a quoted string.

For Example, "THIS IS QUOTED TEXT" is a string literal, Examples of integer literals are -234, 336, 2, 0. You can specify escape sequences in string literals. Most of the C language sequences like '\n', '\t' are accepted. You can also specify hex values directly by '\x<dig1><dig2>'. This is a list of supported escape sequences:

'\n' : Line Feed
'\r' : Carriage Return
'\t' : Tab
'\\' : '\'
\"' : '"'
'\x<dig1><dig2>':  Convert the hex value represented by <dig1><dig2>,
to corresponding byte. For example, "\x3A" converts
to ":". While specifying this sequence, both, upper-case and
lower-case letters, are treated similarly. So, "\x3A" is same
as "\x3a" or "\X3a".

Operators

The scripting language supports the following arithmetic / logical / relational operators. The order of precedence is as in C language.

Available Operators

- : Unimary minus
! : not
* /  : Multiply & divide (integer)
+ - : Plus & minus
>  = < <= : Comparison operators
== != : is equal, is not equal
&& : Logical AND
||  : Logical OR
=  : Assignment

Program Definition

A program written in this scripting language consists of a list of variable declarations, followed by a list of statements. The list of declarations is optional. Variable declarations consist of string and integer declarations. A statement list, is a list of valid statements. Statements can optionally have labels.

The statements in the scripting language can be any of these:

• A blank line
• A semicolon on a line (;)
• Expressions

These are always evaluated from left to right. Expressions are combinations of literals, variables and function calls created using operators and parenthesis.

Examples

-20;
x;
x = 2;
x = x * 2 + (3 + y) * 5;
(x > 5 && x < 10 || y != 0)
(NvGetVar("login", login) != -1)

• Call to a Built-in function. For example:

echo ("THIS IS OUTPUT ON STDERR");
exit ();
strcmp ("QWERTY", "QWE");
a = atoi ("1234");

• if_statement.

The statements in an if block should be in curly braces. '{' and '}' and the expression associated with the condition must be in parentheses '(' and ')'. The language supports an elseif clause and an else clause. The syntax is as follows:

if (exprn)
{ /* Brackets are compulsory */
statement list
}
elseif (exprn2) /* This is optional */
{
statement list
}
else /* This is optional */
{
statement list
}

• goto statement. For example,

goto ERROR; /* ERROR is a label */

• block. A list of statements in curly braces. For example,

{
count = a * 3;
if ( count > 10 )
{
echo("count is more than ten\n");
}
}

• Loop statement. Syntax for this statement is as follows:

loop (expression)
{
<statement list>
}

The statements in a loop block should be in curly braces for example, '{' and '}' and the expression associated with the condition must be in parentheses '(' and ')'. The scripting language first evaluates the expression specified. Result of the expression defines the number of iterations of the loop block. It should be noted that the expression is evaluated only once, for example, before executing any statement in the loop block. For example:

loop (count)
{ /* Brackets are compulsory */
statement list
}

• Break statement

The program comes out of the current block and continues in the outer block. For example:

loop (5)
{
a = a - 1;
if (a == 1)
{
break;
}
}
CONTINUE: a = 4;
/* when the break statement is executed the program
 * continues execution from CONTINUE: a = 4;
 * statement.
 */

Built-in Functions

The scripting language supports a number of built-in functions:

• String operations

strncmp, strcat, strncat, strcmp, strcpy, strncpy, strcspn, strspn, stricpy, strincpy, strlen, strstr, strtok, sprintf.

isalpha, isupper, islower, isdigit, isspace, ispunct, isalnum, isascii, toupper, tolower, toascii, atoi, itoa.

These functions make it possible to carry out string manipulation with ease.

• Input/output related functions

echo, echochars, sendchars, recv, await, getkeyboard, setechomode, flush, setnoechomode, getTipPort.

These functions are used communicate with host systems and with users. Communication with host systems is through TIP, Telnet etc. Communication with user is via Tekterm window. It is possible to send/receive data to host and user using these functions.

• NVRAM related functions

NvSetVar, NvGetVar, NvUpdateVars, GetTagInt, GetTagStr, SetTagStr.

These functions are mainly useful for parameterizing scripts. Script parameters can be stored in NVRAM.

• Miscellaneous

sleep, killparent, settimeout.

Function Parameters

For most functions (e.g., NvGetVar) all parameters are mandatory. For functions await and sprintf, you can specify a variable number of parameters. In a function call, parameters can be either variables or literals. However, for some functions, certain parameters are expected to be variables (e.g., parameter s1 in strcpy(s1, s2) ). Passing a literal in such cases results in a run-time error.

Script Parameters

The previous section listed some functions which operate on NVRAM. This facility makes it possible to parameterize scripts. For example, consider the case of automating log-in operations through Telnet. Each person has a different log-in name and possibly a different host. The script accepts host name and log-in name as parameters. Setup provides a facility to define and save script parameters (under Network Tables and Utilities Menu). NvGetVar() assigns a value to a parameter. NvSetVar() sets a parameter. A subsequent call to NvUpdateVars() stores the parameter in NVRAM.

The script parameters can also be set using remote configuration commands. The syntax in the xp.cnf file is: script_variable "<variable name>" "<value>" For example, to set the parameter login to be guest:

script_variable "login" "guest"

Usage of Various Language Constructs

• Variable declarations

str str1[22], stringvar[20];
int count;

• Integer Assignments

int b, c, d;
b = c = 3;
d = -3456;

• String assignments

str s[15];
strcpy(s, "Hello World\n");

• Expressions

c == 3 // Result is zero or 1

c * 3 + d // Evaluated with same precedence rules as 'C'

c * (3 + d) // Explicitly specifying order of evaluation

c < 3 && c > 12 // Use of comparison and logical operators.
// Precedence same as that in 'C'.

(NvGetVar("login", login) == 1) && (strlen(login) > 0)) // Use of function calls within expressions.

• if statement

if (c == 3)
{
echochars("3");
}
elseif ((c == 2) || (c - c/6*6) == 0)
{
echochars("2 or divisible by 6");
}
elseif (c == 1)
{
echochars("1");
} else { echochars("Some other value\n"); }

• Loop statement and break statement

loop (count * 2 + 3)
{
echochars("Looping...\n");
if (count > 100)
{
break;
}
}
// Changing value for count within the loop block does not
// change number of iterations.

• sprintf example

int a;
str z[50];
a = 35;
sprintf(z,"%s : %d base is %d\n", "value for a ", a, 10);

• Example of user input without echo (Useful for password entry etc.):

str pass[25];
echochars("Password :");
setnoechomode();
settimeout(15);
getkeyboard(pass, 24);
echochars("\nOK\n");

• Examples for keyboard input and NVRAM operations:

str name_var[25], login[25];
// set timeout to 15 seconds.
echochars("Enter your name :");
settimeout(15);
// Get user input (through keyboard) for "name"
getkeyboard(name_var, 24);
// Set variable "name"
if (NvSetVar ("name", name_var) == -1)
{
echochars("Error setting variable\n");
}
// Set variable "host"
if (NvSetVar ("host", "falcon") == -1);
{
echochars("Error setting variable\n");
}
// Save the updated values in NVRAM.
NvUpdateVars();
// Get value for variable login.
if (NvGetVar ("login", login) == -1)
{
echo("Error reading variable"); }

• Examples of usage of some string functions:

strincpy :
// copy 3 characters to str1 from displacement 2 in
// string "abcdefghijk"
strincpy (str1, "abcdefghijk", 2, 3);
// str1 will now contain "cde"
strtok :
// The following script results in display :
// abc
// def
// ghijk
strtok ("abc def ghijk", " ", str1);
echochars (str1); echochars("\n");
strtok ("", " ", str1);
echochars (str1); echochars("\n");
strtok ("", " ", str1);
echochars (str1); echochars("\n");

• Example of receiving data from host:

// Assume that host sends following string:
// " Set address to : 128.1.0.25"
// It is required to extract address from this string.
// Following script achieves this.
int a;
str addr[20];
a = await("Set address to : ", 1);
if (a == 1)
{
settimeout(3);
// The script assumes that within next 3 seconds all the
// required data will come.
recv(addr, 15);
// In case 15 characters are not received within the timeout
// period, then 'recv' will put available characters in 'addr'
// and return.
echochars("Address is :");
echochars(addr);
}
else
{
echochars("Did not receive address from host\n");
}

Starting CSLIP Using a Script

Note:

See also the sample script named startup in the /tftpboot/tekxp/boot/config/script directory.

// This script performs following functions:
// a. Login for cslip account on host
// b. Start local cslip
// c. Invoke a Telnet session

int c;
str login[25];

// Get login name for cslip from NVRAM
if (NvGetVar("login", login) == -1)
{
// Could not get the variable from NVRAM

echochars("variable login not defined in NVRAM\n");
exit();
}
// Could get the variable from NVRAM

// Set timeout to 15 seconds.
settimeout (15);

// Flush buffer for data from host.
flush();

// Send a '\n' so that host will respond with login prompt
sendchars ("\n");

// Wait to receive login string from host
c = await ("login", 1);

if (c == 1)
{
// Received login prompt

// Send login name for cslip
strcat(login, "\n");
sendchars(login);

// In our setup, starting host-cslip does not require password.
// A login immediately results in startup of cslip on host

// Await for a startup message
c = await ("starting", 1, "willing to manage", 2, "Willing to Manage", 3,
"cslip started", 4); if (!(c == 1 || c == 2 || c == 3 || c == 4) )
{
echo ("\n Could not start cslip on the host....\n");
exit();
}
}

else
{
// Did not get login prompt from host
echochars ("\n No Response, ...CSLIP is probably already started on
host.\n");
}

// Download Telnet so that login over cslip can be done
exec ("tek340 -e telnet");

// Download local cslip
exec ("cslip");

// Kill the Tekterm(TIP) session to allow local cslip to
// take control of serial port
killparent();

// END of script for CSLIP //

Command Reference

These commands are available with the scripting language.

Table D-1 General Commands 

Command	Description
isalpha()	Checks if passed argument is an alphabetic string. Returns 1 if true, 0 if false, and -1 on ERROR.
isupper()	Checks if passed argument is an upper case string. Returns 1 if true, 0 if false, and -1 on ERROR.
islower()	Checks if passed argument is a lower case string. Returns 1 if true, 0 if false, and -1 on ERROR.
isdigit()	Checks if passed argument is a string of digits. Returns 1 if true, 0 if false, and -1 on ERROR.
isspace()	Checks if passed argument is a string of spaces. Returns 1 if true, 0 if false, and -1 on ERROR.
ispunct()	Checks if passed argument is a string of punctuation. Returns 1 if true, 0 if false, and -1 on ERROR.
isalnum()	Checks if passed argument is a string of alpha numeric. Returns 1 if true, 0 if false, and -1 on ERROR.
isascii()	Checks if passed argument is a string of ASCII. Returns 1 if true, 0 if false, and -1 on ERROR.
isxdigit()	Checks if passed argument is a string of hex digits. Returns 1 if true, 0 if false, and -1 on ERROR.
isprint()	Checks if passed argument is a string of printable characters. Returns 1 if true, 0 if false, and -1 on ERROR.
iscntrl()	Checks if passed argument is a string of delete or control characters. Returns 1 if true, 0 if false, and -1 on ERROR.
isgraph()	Checks if passed argument is a string of visible graphic. Returns 1 if true, 0 if false, and -1 on ERROR.
toupper()	Converts string s2 to a string of upper case characters. Returns 1 on success.
tolower()	Converts string s2 to a string of lower case characters. Returns 1 on success.
toascii()	Converts string s2 to a string of ASCII characters. Returns 1 on success.
atoi()	Converts the string s1 to an interger equivalent and returns it.
itoa()	Converts the interger n to its string equivalent in s1.
strcpy()	Copies source string s2 to destination string s1.
strncpy()	Copies as most n characters from source string s2 to destination string s1. In case source string is shorter than n, destination string is null padded.
strcat()	Concatenates source string s2 to the end of destination string s1.
strncat()	Concatenates at most n characters from source string s2 to the end of string s1.
strlen()	returns length of string.
strcmp()	Compares string s1 to sting s2. Returns an interger greater than, equal to, or less than 0, depending on whether s1 is lexicographically greater than, equal to, or less then s2, respectively. If parameters are improper, it returns -257.
strncmp()	Compares at most n characters of string s1 to string s2. Returns the same values as for strcmp.
strspn()	Gives the length of prefix of s1 consisting of characters in s2.
strcspn()	Gives the length of prefix of s1 consisting of characters not in s2.
strstr()	Gives the offset to first occurrence of string s2 in string s1, or -1 if not present.
strtok()	Searches string s1 for tokens delimited by characters from s2 and returns the NULL terminated token in the string s3. The first call in a sequence of calls should have a non-empty string s1. The string s1 may be different on each call.
stricpy()	Copies characters from the given index i from string s2 to string s1.
strincpy()	Copies at most n characters from the given index i from string s2 to string s1.
sprintf()	Similar to the corresponding function in'C' library. However, it provides only a subset of functionality provided by the'C' library function. Outputs string s1 using the format string fit and the list of values specified. It supports only these two formats: %d: for printing integers. &s: for printing strings. There is no limitation on the number of arguments to this function.

Table D-2 NVRAM Access Commands

Command	Description
NvGetVar()	Gets string value for the named script variable. Returns 1 to indicate success, or -1 if the variable does not exist, or if a wrong argument is passed.
NvSetVar()	Sets value for the named script variable. Returns 1 if the operation succeeds, and -1 if it fails. The value does not actually get updated in NVRM until NvUpdateVars() is called. It does, however, set the tag corresponding to script variables.
NvUpdateVars()	Updates NVRAM with current tag values. It takes some time to update NVRAM. Returns 1 on success and -1 on failure.

Table D-3 System Related Commands 

Command	Description
echo()	Outputs the specified string on console. Always returns 1.
exec()	Downloads and executes a task. For example, exec("tek220 -e telnet"); Returns 1 on success and -1 on failure.
exit()	Exits from the task.
sleep()	Sleeps for the specified number of seconds. Returns 1.
settimeout()	Sets the time out for all the operations which need a timeout. Functions await, recv, and getkeyboard require timeout to be set. The default value for timeout is 10 seconds.
getkeyboard()	Waits for the user to enter a string of length `len' or a new line terminated string from the keyboard. On return, it puts user's input in the buffer passed. The buffer is null terminated and new line character typed by user is stripped.
recv()	Waits for a string of length `len' from the host, or for the timeout period. This function is used to receive data from the connected host. The connection could be through Telnet or TIP. Received data is returned in the buffer passed. It is null terminated as well. If timed out, this function returns the available data.
flush()	Flushes the keyboard buffer and the buffer for data from host. Also flushes any data in the pipe used between tekterm and script. Is typically used when the host sends large amounts of data. If this data is not flushed out, there is a chance that local buffers in the scripting language may overflow. In this case, some of the data coming from the host may be discarded.
setechomode()	Sets the characters typed on the keyboard to be echoed on the screen when typed.
setnoechomode()	Prevents the echoing of characters typed from the keyboard. It can be used when user is entering data through the keyboard that is being captured using the "getkeyboard" function. If setnoecho() function is called before doing "getkeyboard", then data being entered by the user is not echoed on the screen. This facility is useful for entry of information such as a password.
killparent()	Kills the parent Tekterm from which the script is executed. This also results in ending the script.
echochars()	Echoes the string given as its argument on the display (i.e. the Tekterm window)
sendchars()	Sends the argument string to the host. The host connection could either be through TIP or Telnet.
await()	Takes variable parameters as input. Parameters are specified two at a time. The first parameter is a string and the second is a value. The command waits for one of the specified strings to come from the host and returns the value associated with the string. It waits for a period specified by settimeout(). If none of the specified strings is received within this time, then it returns -1. The check for string match is from left to right. Therefore, if more than one match is possible then the value corresponding to the left-most string is returned. A string match also causes corresponding data from the host to be flushed. Example: await("login", 1, "LOGIN", 1, "fail" ,2);
getTipPort()	Returns the serial port number through which the current scripting language session was invoked. If the script is invoked via a TIP session for serial port 0 (or port 1), then getTipPort returns 0 (or 1, for port 1). If the script was not invoked via a TIP session then it returns -1.