BlastDOS/Telix.rar/Telix/SALT.DOC

Text File | 1993-10-11 | 214KB | 6,734 lines

     T E L I X

     ─────────────────────────────────────────────────────────────────

     SALT Programming Manual

        Copyright (C) 1986,1987,1988,1989,1990,1991,1992 by Exis Inc.



                                 C O N T E N T S



     1.  The Telix SALT Language.....................................1
     1.1  What Can be Accomplished With SALT?........................1
     1.2  About This Manual..........................................1
     1.3  Notation...................................................1
     1.4  Creating SALT Programs.....................................1
     2.  Syntax......................................................3
     2.1  Comments...................................................4
     3.  Program Structure...........................................5
     3.1  Variables..................................................5
     3.2  Expressions and Operators..................................7
     3.3  Functions..................................................9
     3.4  Statements................................................10
       3.4.1  The Expression statement..............................11
       3.4.2  The If statement......................................11
       3.4.3  The While statement...................................13
       3.4.4  The Do...While statement..............................13
       3.4.5  The For statement.....................................14
       3.4.6  The Return statement..................................15
       3.4.7  The Break statement...................................15
       3.4.8  The Continue statement................................16
       3.4.9  The Goto statement....................................17
     4.  Built-in Functions.........................................19
     4.1  Quick Listing of Functions by Type........................20
     4.2  Complete Function Reference...............................22
     5.  System Variables...........................................97
     6.  Appendix A - ASCII Character Set..........................114
     7.  Appendix B - Extended Key Scan Codes......................115
     8.  Appendix C - Color Values.................................116
     9.  Index.....................................................117
     Telix v4.25 - SALT Programming                       Introduction    1





     1.  THE TELIX SALT LANGUAGE

     Telix has a built-in programming language called SALT (Script Applica-
     tion Language for Telix). SALT will allow you to perform almost any
     communications related applications with Telix. SALT looks similar to
     the C language, however if you have used almost any programming lan-
     guage (such as Pascal, BASIC, etc.), you should feel quite at home
     with SALT. While SALT was designed to be easy to learn, it is like
     most programming languages quite complete, so it is recommended that
     you read this chapter thoroughly and study the examples provided, as
     well as the sample SALT scripts included with Telix.


     1.1  What Can be Accomplished With SALT?
     ──────────────────────────────────────────────────────────────────────

     Like a program in any programming language, a SALT program (also
     called a 'script') is typically used to perform a needed task or func-
     tion. The task can range from the very simple to the very complicated.
     For example, a SALT script can be linked to a dialing directory entry,
     so that when you have established a connection to that service, it au-
     tomatically sends your i.d. and password to the remote service. A much
     more complicated SALT script is used as the basis for the Host Mode
     included with Telix.


     1.2  About This Manual
     ──────────────────────────────────────────────────────────────────────

     This manual is basically a reference to the SALT programming language.
     It is by no means a tutorial on programming in general. It is assumed
     that the reader of this manual is at least familiar with general pro-
     gramming concepts.


     1.3  Notation
     ──────────────────────────────────────────────────────────────────────

     Throughout this manual, certain words in examples and in the text will
     be surrounded by angle brackets and italicized, for example,
     <expression>. These words are not to be taken as literal text. they
     stand for something else, such as a word, a group of words, or even
     several lines of text. What these italicized words stand for will be
     explained as they come up.


     1.4  Creating SALT Programs
     ──────────────────────────────────────────────────────────────────────

     A SALT script is basically a sequence of instructions for Telix to
     follow, using a specific syntax. You may use any text editor to pro-
     duce this script file, as long as its output is normal ASCII text
     (this means that if you use your word processor, you must usually ex-
     plicitly tell it to write out the file using ASCII format and to not
     embed any special codes in the file). You may give any name you wish
     Telix v4.25 - SALT Programming                       Introduction    2



     to a SALT source file, although we recommend that you always use the
     extension .SLT for clarity.

     Once you have written your script file and saved it to disk, it must
     be compiled. The program CS.EXE included with Telix reads your
     'source' script file, and compiles it to a form which Telix can under-
     stand. The compiled script can then be loaded more quickly by Telix,
     and is also usually smaller.

     To compile a script source file, type

          cs <pathname>

     while at the DOS prompt and then press Enter (or Carriage Return). The
     CS.EXE program must be in the current directory or on the DOS PATH.
     <pathname> is the name of the file to compile, and may include the
     drive and directory as well as the filename. The output file is writ-
     ten to the same name except that the extension .SLC is used.

     When the script compiler finds an error in your source file, it will
     abort the compile process and give you the line number on which the
     error occurred, as well as the type of error. The error should then be
     fixed and the source re-compiled. This is repeated until the compiler
     detects no more errors in your source file.

     The compiled script can then be run in Telix using several methods. It
     may be run using the 'Run script' command, as a command-line option
     when running Telix from DOS, as a linked script to a dialing directory
     entry, or from another script. The first three methods are described
     in the Telix manual, while the last is described later in this manual.
     Telix v4.25 - SALT Programming                             Syntax    3





     2.  SYNTAX

     Case is not important in command, function, and variable names. The
     only time case matters is inside a string constant (e.g., "Hello" is
     not the same string as "hello"). Whitespace (such as the space, the
     tab, the Carriage Return, or the Line Feed character) is not impor-
     tant. The script compiler does not care where you place items, so that
     you may arrange the program as you see fit. For example,

          if (value == 1)
            prints("value is equal to 1!");
          else
            prints("values is not equal to 1.");

     is equivalent to

          if (value == 1) prints("value is equal to 1!");
          else            prints("value is not equal to 1");

     or even to

          if(value==1)prints("value is equal to 1!");else prints("value is
          not equal to 1.");

     The only time whitespace matters is when it would split up key-words
     or function name, or in a string. For example, the key-word 'while'
     must not be split up if it is to be recognized. The same applies to
     other key-words or function names. As well, there must be space be-
     tween the letters of a command and other letters. For example, 'while'
     is not the same as 'whileabc'. In the interest of clarity, it is rec-
     ommended that you try to make your code easy to understand, by indent-
     ing where appropriate, and by using space effectively. There is no
     reason, for example, to put more than one statement on a line, even if
     it is perfectly legal. A good example of program style can be found by
     looking at the sample scripts included with Telix.

     A string constant is a sequence of ASCII characters enclosed in
     quotes, for example, "Hello", "Good-bye", or "Telix". It is often nec-
     essary for a string constant to include special characters that can
     not easily be typed from the keyboard, or can not be easily displayed.
     This is done with something called the escape character, which is the
     caret ('^') symbol. When the SALT compiler is reading a string con-
     stant and comes to the '^' symbol, it replaces it with a certain ASCII
     code based on the character following the ^. Translations are as fol-
     lows:

          ^c        'c' is a letter. The Control representation of whatever
                    letter 'c' is, is inserted into the text. Therefore ^M
                    represents Ctrl-M, ^j represents Ctrl-J, etc. Whether
                    the letter 'c' is upper or lower case is not signifi-
                    cant. Note that what is really happening here is that
                    64 is being subtracted from the value of 'c', so for
                    example, the Escape character can be represented as ^[.
          ^^        An actual caret ('^') symbol is placed into the text.
     Telix v4.25 - SALT Programming                             Syntax    4



          ^"        An actual double quote symbol ('"') is placed into the
                    text. If a string must contain a double quote symbol,
                    this is how it has to be done. If the plain '"' symbol
                    were to be used, the compiler would think that the
                    string was terminated at that point. For example, the
                    string "He said, ^"Hello^"." is translated to 'He said,
                    "Hello".'.
          ^'        An actual single quote symbol (''') is placed into the
                    text.
          ^nnn      'nnn' is up to 3 digits representing the ASCII value of
                    the character which should be placed into the text. A
                    maximum of three digits is read, or up to the first
                    non-digit character. For example, the compiler would
                    read in the string "S^65LT" and output the string
                    "SALT", since 65 is the ASCII value of 'A'. Note that
                    if nnn is less than 3 digits you may have to pad it
                    with one or two leading zeros if there are digits imme-
                    diately following it in the string, so that the wrong
                    value is not read in. For example the string "^79 Park
                    Avenue" would translate to "O Park Avenue" since 79 is
                    the ASCII value of 'O'. If you actually wanted Ctrl-G
                    (ASCII code 7) followed by "9 Park Avenue", you would
                    use the string "^0079 Park Avenue".

     An integer constant is a sequence of digits representing an integer
     value in the range -2147483648 to 2147483647. An integer constant must
     start with a digit from 0 to 9 or the negative sign (-) followed by a
     digit. The following are all valid integer constants:

          10
          -400067
          999

     An integer constant may also be entered in hexadecimal form (base 16,
     where each digit may be from '0' to '9' or 'a' to 'f', to represent 16
     values). Hex values must be preceded by '0x' for the compiler to in-
     terpret them as such, and case is not important. The following are all
     valid integer constants enter in hexadecimal form:

          0xff00
          0Xa2
          0x7D
          0x1AbCdEf


     2.1  Comments
     ──────────────────────────────────────────────────────────────────────

     A comment in a source file is text that does not affect what the pro-
     gram does, and is meant purely for explaining or describing something.
     In a SALT source file, whenever the symbol // is encountered on a
     line, all the characters from that point on until the end of the line
     are considered to be a comment and are ignored. For example:

          prints("Hello");       // This line will print "Hello"
     Telix v4.25 - SALT Programming                  Program Structure    5





     3.  PROGRAM STRUCTURE

     A SALT script has the following format:

          <global_variable_definition>
               ...
          <global_variable_definition>

          <function_definition>

          <global_variable_definition>
               ...
          <global_variable_definition>

          <Function_definitions>

               ...

     and so on. Basically a script file consists of definition of global
     variables (variables which are available to any part of the script
     file after which they are defined, and function definitions (functions
     are lines of code clustered together in a group, so that they can be
     called by a name). A script file does not have to have any global
     variables or functions, but to run it must at least have one function
     called 'main'. The following, for example, is a complete script file:

          main()

          {

           prints ("hello");

          }

     When compiled and run, this script would print the string "hello" to
     the screen.


     3.1  Variables
     ──────────────────────────────────────────────────────────────────────

     A variable is a location in memory where something is stored. The con-
     tents of a variable can be changed by program code (hence the name).
     In SALT, there are two types of variables, integer variables, and
     string variables. The former holds an integer value (e.g., 485624, or
     -627), while the latter holds a text string (e.g. "Telix", or
     "SCRIPT"). Depending on where it is defined, a variable is either
     global or local. If a variable is global, it means that it can be used
     by any part of the script after the point where it is defined. If a
     variable is local, it means that it can only be used by the part of
     the script to which it is 'local', for example, the function inside
     which it is defined. A variable name can be up to 31 digits long, and
     may include the letters 'A' to 'Z' or 'a' to 'z', the digits '0' to
     '9', or the underscore character (_). The name may not start with a
     Telix v4.25 - SALT Programming                  Program Structure    6



     digit. For example, 'his_name2' and '_his_name2' are legal as variable
     names, while '2his_name' is not.

     An integer variable is defined in the form

          int <varname>;

     where <varname> is the name to be given to the variable. An alternate
     definition is

          int <varname1>, <varname2>, ..., <varnameN>;

     which allows you to define more than one integer variable in one
     statement. An original value can be assigned to the integer variable
     by using the form

          int <varname> = <int_const>;

     where <int_const> is an integer constant. Similarly, an original value
     can be assigned in the multiple definition above by placing the as-
     signment before the comma. Some examples are:

          int maximum;
          int start = 0;
          int level, i, count = 20, loop;

     A string variable is defined in the form

          str <varname>[<max>];

     where <varname> is the name to be given to the variable. <max> is the
     maximum number of characters that the string can hold, and must be in
     the range of 0 to 32767. An alternate definition is

          str <varname>[<max>], <varname2>[<max>], ..., <varnameN>[<max>];

     which allows you to define more than one string variable in a state-
     ment. An original value can be assigned to the string variable by us-
     ing the form

          str <varname>[<max>] = <str_const>;

     where <str_const> is a string constant. Similarly, an original value
     can be assigned in the multiple definition above by placing the as-
     signment before the comma. Some examples are:

          str password[80];
          str password[40] = "mypass", name[30];

     The string length field may be left empty if an original value is
     specified, in which case the length of the string variable is assumed
     to be that of the assigned text, e.g.

          str name[] = "John";

     If a variable is outside of a function, it is global. If it is defined
     inside a function, it is local to that function and will only be rec-
     Telix v4.25 - SALT Programming                  Program Structure    7



     ognized there. If a variable defined inside a function uses the same
     name as a global variable, any reference to that name while in the
     function will access the local variable. After the function has com-
     pleted, the local variable is removed and a reference to that name
     will access the global variable.


     3.2  Expressions and Operators
     ──────────────────────────────────────────────────────────────────────

     An expression is a mixture of symbols which resolves to a value when
     evaluated. In other words, an expression is basically a formula. An
     expression can consist of constants, variables, function calls, and
     operators. An expression can be very simple, or very complicated. For
     example, some expressions are:

          10 + 3 - 5
          9 * 7 / 63 - 30
          result = 10 * max(a, b)
          month >= 10
          200
          command == "bye"
          prints("Hello")

     In an expression, the data being acted upon are constants, variables,
     and functions calls, while the operators (+, *, etc.) are the symbols
     that do things with the data. There are many different operators, of
     which there are two basic types. Binary operators (such as +, *, /)
     perform a calculation on the expression on either side of them. Unary
     operators appear before a single expression and work on that. The fol-
     lowing table lists the operators available in SALT:

            Symbol      (Un/Bin)ary          What it is/does
              -            unary             Arithmetic negation
              !            unary             Logical NOT
             not           unary             Logical NOT (alternate)
              ++           unary             Increment
              --           unary             Decrement
              *            binary            Multiplication
              /            binary            Division
              %            binary            Remainder (Mod)
              +            binary            Addition
              -            binary            Subtraction
              <            binary            Less than
              >            binary            Grater than
              <=           binary            Less than or equal to
              >=           binary            Greater than or equal to
              ==           binary            Equality
              !=           binary            Inequality
              &            binary            Bitwise AND
              |            binary            Bitwise OR
              ^            binary            Bitwise Exclusive OR
              &&           binary            Logical AND
             and           binary            Logical AND (alternate)
              ||           binary            Logical OR
              or           binary            Logical OR (alternate)
              =            binary            Assignment
     Telix v4.25 - SALT Programming                  Program Structure    8




     Note that the hyphen symbol can be either an arithmetic negation or a
     subtraction depending on its use. Note that '!' is equivalent to
     'not', '&&' is equivalent to 'and', and '||' is equivalent to 'or'.
     The first form is preferred as you do not have to leave whitespace
     around it for the compiler to recognize it, but beginners may have an
     easier time remembering the second form. Also, do not confuse the '='
     (assignment operator) with the '==' (equality operator). The former is
     used to assign a value to a variable, while the latter is used to com-
     pare two values. Assuming you have the two expressions, <expr1> and
     <expr2>, <expr1> = <expr2> would assign one to the other, while
     <expr1> == <expr2> would test the two to see if they are equal. For
     example

          num = 10

     would assign the value 10 to the variable called 'num', while

          num == 10

     would resolve to a value of non-zero (TRUE) if num was equal to 10,
     and 0 (FALSE) if num was not equal to 10. There is also a difference
     between the Logical operators and the Bitwise operators. The Logical
     operators (such as and, &&, or, ||, etc), work with TRUE or FALSE val-
     ues and result in a TRUE or FALSE value, while the Bitwise operators
     (&, |, ^) work with the actual bits of the data they are handling. The
     Bitwise operators almost never have to be used in a Telix script, un-
     less it is needed to get at the actual bits in a data byte.

     Every operator resolves to a value, which is the result of the opera-
     tion performed (e.g, 10 * 7 would resolve to 70). The conditional or
     equality operators such as ==, >, <=, etc., resolve to  a 0 (FALSE))
     or non-zero (TRUE) value based on the results of the expression. Even
     the assignment operator = resolves to a value. The result of the ex-
     pression

          num = 10

     would be 10.

     All the operators have something called precedence, which is their im-
     portance, and determines the order in which they are evaluated. For
     example, 7 + 3 * 9 is equal to 34, because 3 * 9 is evaluated first,
     and then added to 7 (* has a higher precedence than +). All the opera-
     tors are listed below in order of decreasing precedence. All the oper-
     ators on the same line have the same precedence, and are resolved in
     the order that they are encountered.
     Telix v4.25 - SALT Programming                  Program Structure    9



          -  !
          ++  --
          *  /  %
          +  -
          <  >  <=  >=
          ==  !=
          &
          |
          and  &&
          or  ||
          =

     If a certain evaluation order is required that does not follow these
     rules of precedence, parentheses may be used. Thus, 99 + 1 * 10 equals
     109, while (99 + 1) * 10 equals 1000.

     If you are writing an expression of any sort, and are not sure of the
     exact precedence of the operators you are using, use parentheses!


     3.3  Functions
     ──────────────────────────────────────────────────────────────────────

     A function is a way of grouping together some lines of code. A Telix
     script consists of one or more functions. There are quite a few advan-
     tages to having functions:

          One function can be called from another, to do a certain task.
          The calling function does not have to know anything about the
          called function other than what it does. This allows a script to
          be split up into modular units, and makes code writing and debug-
          ging easier.

          As mentioned above, what a function does it private. This means
          that data variables defined in a function are local to that func-
          tion, and therefore you do not have to worry about another part
          of the script unintentionally modifying them.

          A library of functions can thus be built. Later, you do not have
          to re-write old code.

     Functions are defined in the following format:

          <funcname>(<arg1>, <arg2>, ..., <argN>)

          {
           <variable_def>
               ...
           <variable_def>

           <statement>
               ...
           <statement>
          }
     Telix v4.25 - SALT Programming                 Program Structure    10



     <funcname> is the name of the function. It follows the same rules of
     other identifiers in SALT. There can only be one function that uses a
     given name, however.

     <arg1> through <argN> are the declarations of the arguments
     (parameters) that have been passed to the function by its caller
     (sometimes, to accomplish its task, a function needs to have some val-
     ues passed to it). Each argument is defined in the form <type> <name>
     where <type> is 'int' or 'str', and <name> is the name it should be
     called by. At present, a function is not allowed to have more than 12
     values passed to it.

     <variable_def> is a variable definition, as described in the above
     section on that topic. Any number of variables may be declared at this
     part of the function. All such variables will be local variables and
     available only to this function.

     <statement> is an actual line of code. There may be as many lines of
     statements in the function as needed. The format of a statement is de-
     scribed below. First though, here is an example of a complete func-
     tion:

          max ( int a, int b )

          {

           int result;

           if (a > b)
            result = a;
           else
            result = b;

           return result;

          }

     This function returns the larger (maximum) of the two values passed to
     it. It could have been written much more simply (without the use of
     the variable), but was written this way so that all the function ele-
     ments would be there.


     3.4  Statements
     ──────────────────────────────────────────────────────────────────────

     A statement is the basic element of code. A statement ALWAYS ends with
     a semicolon character (;). In any location where a statement is ac-
     ceptable, you may use a group of statements, by enclosing them all in
     curly braces (more on this below). There are many types of statements,
     including: expression, if, while, do...while, for, return, break, con-
     tinue, and goto statements. Each type has several different parts.
     Telix v4.25 - SALT Programming                 Program Structure    11



     3.4.1  The Expression statement

     The 'expression' statement is the simplest and most common type of
     statement. Its format is

          <expression>;

     where <expression> is any expression. Example are:

          result = 20;
          password = "Beef";
          pause(20);
          num = 20 * max(a, b);

     Do not forget the semicolon character at the end of the statement. If
     you do, the compiler will think that the next statement is part of the
     current one, and will report some unexpected error.


     3.4.2  The If statement

     An 'if' statement is used when a statement or group of statements
     should be evaluated only if a condition is true. The format for an
     'if' statement is as follows:

          if (<expression>)
            <statement>

     <statement> is any statement as described above and below (that is, an
     expression, if, while, do...while, for, return, break, or continue
     statement), and will only be executed if <expression> evaluates to
     non-zero. By using curly braces around them, a whole group of state-
     ments may be conditionally evaluated. Some examples are:

          if (result == -1)
            prints("ERROR!");

          if (num_tries > maximum)
            return 0;

          if (month > 10 && day < 20)
           {
            clear();
            prints("In range.");
            return 1;
           }

     An alternate form of the if statement is:

          if (<expression>)
            <statement1>
          else
            <statement2>

     In this case, if <expression> evaluates to non-zero (TRUE),
     <statement1> is executed, otherwise <statement2> is executed. Again,
     Telix v4.25 - SALT Programming                 Program Structure    12



     multiple statements may be used instead by grouping them in curly
     braces. Some examples are:

          if (stat == -1)
            prints("Error status returned.");
          else
            prints("Function finished without problems.");

          if (level < 10)
           {
            alarm(1);
            prints("Warning!");
           }
          else
            prints("Everything's ok.");

     Since the statement to be executed conditionally can be of any type,
     that means that any number of if statement can be nested if needed.
     For example:

          if (num < 10)
            if (!error)
              if (read != 0)
                return 1;

     This also means that something like the following is legal:

          if (value == 10)
            do_this();
          else if (value == 100)
            do_that();
          else if (value == 1000)
            do_something_else();
          else
            do_whatever();

     What is really happening here is that each if statement is being
     nested after the else portion of the previous one. The above example
     could also be written as:

          if (value == 10)
            do_this();
          else
            if (value == 100)
              do_that();
            else
              if (value == 1000)
                do_something_else();
              else
                do_whatever();

     Any amount of nesting is theoretically legal, but the compiler does
     have a limit due to memory constraints.

     While you may write the code in any way which suits you, it is recom-
     mended that you use indenting, for clarity. Indenting your code at the
     proper places makes it a lot easier to read.
     Telix v4.25 - SALT Programming                 Program Structure    13



     A very common error to watch out for is accidentally placing a semi-
     colon after the parenthesis ending the expression. For example, if the
     following is run:

          if (num == 10);
            prints("Num is equal to 10);

     the string would always be printed, no matter what num was equal to.
     This is because the semicolon after the parenthesis ending the expres-
     sion signifies the end of the statement. In the above case, it would
     just be a null (empty) statement.


     3.4.3  The While statement

     The while statement is used to loop continuously while a certain con-
     dition is true. It has the form

          while (<expression>)
            <statement>

     <statement> would continue to be repeated over and over while
     <expression> evaluated to non-zero (TRUE). Note that if the expression
     evaluates to 0 (FALSE) from the beginning, the statement will never be
     executed. Again, multiple statements may be used by surrounding them
     in curly braces. A few examples are:

          while (stat != -1)
            stat = myfunc();

          while (num < 100)
            {
             printn(num);
             prints("");
             num = num + 1;
            }

          while (1)
            {
             if (func1())
               return 0;

             func2();
            }

     Again, be careful to not place a semicolon after the parenthesis end-
     ing the expression.


     3.4.4  The Do...While statement

     The do...while statement is similar to the while statement and has the
     form:

          do
            <statement>
          while (<expression>);
     Telix v4.25 - SALT Programming                 Program Structure    14




     <statement> will be executed at least once and will continue to be ex-
     ecuted repeatedly until the expression becomes 0 (FALSE). A few exam-
     ples are:

          do
            stat = func1();
          while (stat != -1);

          do
           {
            prints("hello");
            num = num + 1;
           }
          while (num < 100);


     3.4.5  The For statement

     The for statement is used to loop continuously while a certain condi-
     tion is true. The advantages over the while statement is that a count
     variable can be initialized and incremented quite easily. The for
     statement has the form:

          for (<expression1>; <expression2>; <expression3>)
            <statement>

     The first expression is the one that should initialize the count vari-
     able. For example, if you wanted to count from 1 to 100, and were
     keeping the count in a variable called 'num', the first expression
     would be 'num = 1'. The second expression is the conditional test. As
     long as it evaluates to non-zero (TRUE), the statement will be exe-
     cuted. Following the above example, this expression would be
     'num < 100'. The third expression is the one that is used to increment
     the count variable. For the above example, it would therefore be
     'num = num + 1'. This for statement differs in format from that in
     most other languages, but doing it this way is actually gives the pro-
     grammer a lot of power and flexibility. Note that any of the expres-
     sions can be left empty, in which case they evaluate to non-zero
     (TRUE). Some examples are:

          for (count = 0; count < 100; count = count + 1)
           {
            printn(count);
            prints("");
           }

          for (c = 1000; c > 0; c = c - 1)
            do_this(c);

     The following would execute an infinite loop:

          for (;;)
            prints("Hello!");

     Note that there is really no restriction on what the expressions are.
     For example, the following is quite legal:
     Telix v4.25 - SALT Programming                 Program Structure    15



          for (c = num = 0; c < 100 && stat != -1; c = c + 1)
            {
             stat = func(num);
             num = func2();
            }

     The statements would only be executed if c was smaller than 100 and
     stat didn't equal -1.


     3.4.6  The Return statement

     At some time, every function must be exited. If the end of the func-
     tion is reached, control will automatically return to the calling
     function. Very often however, it is necessary to leave a function
     somewhere while only halfway through it, perhaps based on a condi-
     tional test. As well, it is often necessary that a function returns a
     value to the caller. The format of the return statement is:

          return <expression>;

     If the return statement is encountered anywhere in the function, con-
     trol immediately returns to the function that called this function.
     The expression is the value that should be returned. If no expression
     is supplied, a dummy value is returned. The expression should match
     they type of value that the caller of this function is expecting. That
     is, if an 'int' type is expected, the expression should resolve to an
     integer value. If a 'str' type is expected, the expression should re-
     solve to a string value. Due to memory constraints, a local string
     variable may NOT be returned from a function. Some examples are:

          return;
          return 1;
          return level;
          return (sum + 25);
          return "hello";
          return (func() + 20);

     Notice that when a complex expression is returned it is usually sur-
     rounded by parentheses. This is done only for clarity and is not nec-
     essary. Also, it should be clear that what is returned is not the ex-
     pression but what it evaluates to.


     3.4.7  The Break statement

     Often while using a looping statement (while, do...while, for), it is
     necessary to break out of (exit) the loop. The break statement serves
     this purpose. When the break statement is encountered, execution of
     the smallest while, do...while, or for loop is terminated, and execu-
     tion continues immediately after the terminated loop statement. It is
     an error for a break statement to appear outside of a loop. The format
     of the break statement is:

          break;

     For example, assuming you had the following code:
     Telix v4.25 - SALT Programming                 Program Structure    16



          int num = 0;
          while (1)
           {
            num = num + 1;
            if (num > 100)
              break;
           }
          prints("Done");

     Ordinarily, since there will always be a non-zero (TRUE) value in the
     conditional part of this while statement, it would execute forever.
     However, when the 'num' variable is > 100, the break statement is exe-
     cuted to exit from the loop, at which point the next statement would
     be executed (the function call to prints).


     3.4.8  The Continue statement

     The continue statement is used within a loop (while, do...while, or
     for statement). The continue statement has the form:

          continue;

     It is illegal for a continue statement to appear outside of a loop
     body. When a continue statement is encountered, program control is im-
     mediately transferred to the end of the body of the innermost en-
     closing while, do...while, or for statement. The effect in a while or
     do...while statement is that the condition part of the while or
     do...while statement is evaluated, and the next iteration of the loop
     occurs. For example:

          num = 0;
          while (num < 100000)
           {
            num = num + 1;
            if (num > 100)
             continue;
            prints("Hello");
           }

     The effect of the continue statement in the above loop would be that
     'Hello' would only be printed while 'num' was smaller or equal to 100,
     as the continue statement is executed when num is bigger than 100,
     which causes the rest of the loop body to be skipped. An example for
     statement would be:

          for (num = 0; num < 100000; num = num + 1)
           {
            if (num > 100)
             continue;
            prints("Hello");
           }

     The effect in this case would be the same. While 'num' is smaller or
     equal to 100, the entire loop body executes. If 'num' is greater than
     100 however, the continue statement is executed. This causes the rest
     of the loop body to be skipped, so the 'Hello' is then not printed.
     Telix v4.25 - SALT Programming                 Program Structure    17



     3.4.9  The Goto statement

     The goto statement is used to branch (jump) from one place to another,
     within a function. The use of goto statements is considered bad style.
     They can make code very hard to understand, and are in fact almost
     never necessary. For example, Telix is written mainly in the C lan-
     guage, which has a goto statement, yet except for a few pieces of pre-
     written code, the goto statement was never used nor needed. On the
     other hand, used very sparingly and properly, it can sometimes make
     some code clearer and perhaps faster. The goto statement consists of
     two parts, the 'label' or marker, which is where execution will jump
     to, and the actual goto itself. A label is defined in the form

          <identifier>:

     where <identifier> follows the same rules as for variable names. Note
     that a colon follows the name, not a semicolon. The colon character
     must immediately follow the label name, with no intervening spaces. A
     label does not have to be on a line by itself, and is not considered a
     statement by itself. The goto takes the form

          goto <label>;

     where <label> is a label elsewhere in the function defined as de-
     scribed above. Execution of the script will immediately continue fol-
     lowing the label.

     An example is:

          start:
          prints("Hello");
          goto start;

     This would print the word "hello" over and over, forever. There is no
     restriction on the placement of a label, so the above can be written
     as:

          start: prints("Hello");
          goto start;

     As mentioned above, there are usually better ways than using a goto
     statement. For example:

          int i = 0;
          do
           i = i + 1;
          while (i < 100);

     is clearer than the equivalent:

          int i = 0;
          loop:
           i = i + 1;
           if (i < 100)
            goto loop;
     Telix v4.25 - SALT Programming                 Program Structure    18



     One good use of a goto statement is to get out of a deeply nested
     while statements, without having to do a lot of extra checking.
     Telix v4.25 - SALT Programming                Built-in Functions    19



     4.  BUILT-IN FUNCTIONS

     Telix's SALT has quite a large number of built-in functions. These
     functions are called just as you would call your own SALT functions.
     Each function does a certain task (print something to the screen, ma-
     nipulate strings, access disk files, etc.). Each function is called
     with parameters in a certain format and returns an integer or string
     value (the return value does not have to be used and is often a dummy
     variable).

     The following pages contain a quick listing of the functions by type
     followed by a complete description of each function, in alphabetical
     order. The complete reference contains for each function, a summary of
     the calling format, a description of what it does, and the return
     value of the function are all given. An example of actual usage of the
     function is often given. Note that the examples are fragments of pro-
     gram code for the most part, and may not explicitly declare all needed
     variables. So that you may find related functions, each function de-
     scription has a 'See Also' section, which lists related functions.
     Telix v4.25 - SALT Programming                Built-in Functions    20






     4.1  Quick Listing of Functions by Type
     ──────────────────────────────────────────────────────────────────────

     Video Operations

     box, cursor_onoff, clear_scr, getx, gety, gotoxy, printc, printn,
     prints, printsc, pstra, pstraxy, scroll, status_wind, update_term

     String Handling

     copychrs, copystr, delchrs, gets, getsxy, inschrs, itos, setchr,
     setchrs, stoi, strcat, strchr, strcmpi, strlen, strlower, strmaxlen,
     strpos, strposi, strupper, subchr, subchrs, substr

     Character Handling

     isascii, isalnum, isalpha, iscntrl, isdigit, islower, isupper,
     tolower, toupper

     Comm Port Operations

     carrier, cinp_cnt, cgetc, cgetct, cputc, cputs, cputs_tr, flushbuf,
     get_baud, get_datab, get_parity, get_port, get_stopb, hangup,
     set_cparams, set_port

     File and File I/O Operations

     fclearerr, fclose, fdelete, ferror, feof, fflush, fgetc, fgets,
     fileattr, filefind, filesize, filetime, fnstrip, fopen, fputc, fputs,
     fread, frename, fseek, ftell, fwrite

     Keyboard Operations

     inkey, inkeyw, keyget, keyload, keysave, keyset

     Date/Time and Timer Operations

     curtime, date, tsec, tday, thour, time, time_up, timer_free,
     timer_restart, timer_start, timer_total, tmin, tmonth, tyear

     File Transfers, Capture, Printer, and Usage Log

     capture, printer, receive, send, transtab, usagelog, ustamp

     Script Management

     call, calld, delay_scr, is_loaded, load_scr, unload_scr

     Input String Matching

     track, track_addchr, track_free, track_hit, waitfor
     Telix v4.25 - SALT Programming                Built-in Functions    21



     Other Functions

     alarm, chatmode, delay, dial, dos, dosfunction, exittelix, helpscreen,
     loadfon, newdir, redial, redirect_dos, run, send_brk, set_defprot,
     set_terminal, show_directory, terminal, tone
     Telix v4.25 - SALT Programming                Built-in Functions    22






     4.2  Complete Function Reference
     ──────────────────────────────────────────────────────────────────────




     ALARM
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     alarm(int <seconds>);

     ■  Description

     The alarm functions sounds an alarm for a a duration in seconds given
     by <seconds>.

     ■  Return Value

     The <seconds> argument is returned.

     ■  See Also

     tone, _alarm_on, _sound_on

     ■  Example

     while (!inkey())
       alarm(1);



     BOX
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     box(int <x>, int <y>, int <x2>, int <y2>, int <style>, int <hollow>,
     int <color>);

     ■  Description

     The box function is used to create a box on the screen. The box will
     have an upper left hand corner of <x>,<y> and a lower right hand cor-
     ner of <x2>,<y2>. The box must fit within the confines of the screen.
     <color> is the color to use in drawing the box. If <hollow> is a non-
     zero (TRUE) value, the inside of the box is not cleared. <style> se-
     lects what kind of box to draw, as follows:
     Telix v4.25 - SALT Programming                Built-in Functions    23



          0    Spaces
          1    Single lines
          2    Double lines
          3    Single vertical lines, double horizontal lines
          4    Double vertical lines, single horizontal lines

     If <style> is any other value, that character is used to construct the
     sides of the box.

     ■  Return Value

     None.

     ■  See Also

     scroll

     ■  Example

     box(10, 10, 70, 20, 1, 0, 112);    // draw box in inverse color


     CALL, CALLD
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     call(str <scriptname>, <arg1>, <arg2>, <arg3>, ...);

     calld(str <scriptname>, <arg1>, <arg2>, <arg3>, ...);

     ■  Description

     The call function is used when one script file must call (jump into
     and then return from) another. <scriptname> is the name of the script
     file to call. If no extension is given, .SLC is assumed. <arg1>
     through <argn> are the arguments or parameters to be passed to the
     'main' function of the called script. The value returned is the value
     returned by the 'main' function of the called script, and can be an
     integer or a string value, although the called script can not return
     string variables local to itself. If the script file to be called is
     already in memory because it was previously loaded and made resident,
     or it is still executing from a previous call, it is not released but
     instead the memory image is used. This means that global variables
     will have whatever values a previous run through left in them.

     The calld function is exactly the same as the call function, except
     that even if an image of the indicated script file is already in mem-
     ory, a new copy is still loaded from disk. This ensures that global
     variables within the script will be set as defined in the source file,
     and that there will be enough stack space, but requires more memory
     and is slower.

     ■  Return Value

     An integer or string value representing the value returned by the main
     function of the called script file. This value must not be a string
     Telix v4.25 - SALT Programming                Built-in Functions    24



     variable defined within the called script, for memory reasons. if the
     indicated script can not be found or loaded, a value of -1 is re-
     turned. If the called script is aborted by the user, a value of -1 is
     returned.

     ■  See Also

     load_scr, unload_scr, is_loaded

     ■  Example

     stat = call("TEST");
     if (stat == -1)
      prints("Called script could not be loaded or was aborted!");




     CAPTURE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     capture(str <filename>);

     ■  Description

     The capture function is used to open, close, pause, and unpause the
     Telix capture file. Depending on what the string variable <filename>
     contains, different actions will take place.

     If <filename> contains a valid filename (which can include a path),
     Telix opens and starts capturing data to that file.

     If <filename> is "*CLOSE*", and the capture file is currently open, it
     is closed.

     If <filename> is "*PAUSE*", and the capture file is currently open, it
     is paused.

     if <filename> is "*UNPAUSE*", and the capture file is currently open
     and paused, it is unpaused.

     If <filename> is an empty string (""), Telix takes the same action as
     if the user had pressed Alt-L while in terminal mode (which will de-
     pend on whether the capture file is currently open or closed).

     ■  Return Value

     A value of -1 is returned if there is a problem performing the indi-
     cated function, otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     printer, capture_stat, _capture_fname
     Telix v4.25 - SALT Programming                Built-in Functions    25



     ■  Example

     if (capture("TELIX.CAP") == -1)
      prints("Error opening capture file!");
        ...
     capture("*PAUSE*");
     capture("*UNPAUSE*");
     capture("*CLOSE*");




     CAPTURE_STAT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     capture_stat();

     ■  Description

     The capture_stat function returns an integer value representing the
     current status of the capture file, as follows:

               0    Capture File is closed
               1    Capture File is open
               2    Capture File is open and paused

     ■  Return Value

     An integer values as described above.

     ■  See Also

     capture, usage_stat




     CARRIER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     carrier();

     ■  Description

     The carrier functions returns a non-zero (TRUE) value if the Carrier
     Detect signal coming from the modem is on (high), otherwise it returns
     a zero (FALSE) value. Note that some modems by default override the
     real state of the signal and always send a high. For this function to
     work, the modem must be told to supply the real signal. This function
     may be used to check if Telix is connected to a remote service over
     the modem, as the Carrier Detect signal should be on if there is a
     connection. Note that if you are connecting two computers via a null-
     Telix v4.25 - SALT Programming                Built-in Functions    26



     modem cable, the value returned will depend on the wiring of the cable
     being used.

     ■  Return Value

     non-zero (TRUE) or zero (FALSE) based on the state of the Carrier De-
     tect signal.

     ■  Example

     if (carrier())
      prints("We are online.");


     CGETC, CGETCT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cgetc();

     cgetct(int <timeout>);

     ■  Description

     The cgetc function returns the first character waiting in the received
     data communications buffer. If there are no characters in the buffer,
     a value of -1 is returned. The cinp_cnt function may be used to see if
     there are any chars waiting in the buffer.

     The cgetct functions returns a character from the communications port,
     waiting up to <timeout> tenths of a second for it to arrive. If a
     character is already waiting in the communications buffer, it is imme-
     diately returned. If no character is received within the timeout pe-
     riod, a value of -1 is returned.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     cinp_cnt

     ■  Example

     if (cinp_cnt())
      chr = cgetc();
     if ((chr = cgetct(100)) == -1)
      prints("Timeout!");
     Telix v4.25 - SALT Programming                Built-in Functions    27






     CHATMODE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     chatmode(int <echo_remote>);

     ■  Description

     The chatmode function enters the chat mode as if the user had pressed
     Alt-Y while in terminal mode, If <echo_remote> is non-zero (TRUE),
     characters typed by the remote user are echoed back to him/her, other-
     wise they are not. The echo feature is for use in Host Mode
     implementations.

     ■  Return Value

     None.




     CINP_CNT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cinp_cnt();

     ■  Description

     The cinp_cnt function returns the number of characters waiting in the
     received data communications buffer.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     cgetc

     ■  Examples

     if (cinp_cnt() > 10)   // if more than 10 chars waiting
      handle_stuff();       //   do action
     while (!cinp_cnt())    // loop until no chars available
      ;
     if (cinp_cnt())        // if something available, get it
      c = cgetc();
     Telix v4.25 - SALT Programming                Built-in Functions    28






     CLEAR_SCR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     clear_scr();

     ■  Description

     The clear_scr function clears the screen and places the cursor in the
     upper left corner at position 0,0.

     ■  Return Value

     None.

     ■  See Also

     scroll




     COPYCHRS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     copychrs(str <source>, str <target>, int <pos>, int <count>);

     ■  Description

     The copychrs function copies a number of characters from one string
     into another, Characters from the string <source> are copied into the
     string <target> at the position <pos> (note that SALT string offsets
     start at 0, not 1 as in some languages). until <count> characters are
     copied. Only as many characters as will fit in <target> are copied.

     This function is very similar to substr, except that it is not string
     oriented, and does not stop copying characters when a 0 value is en-
     countered.

     The substr function copies a portion of one string to another. Char-
     acters from position <pos> in string <source> are copied until into
     string <target> (note that SALT string offsets start at 0, not 1 as in
     some languages). Characters are copied until a 0 (NULL) value is en-
     countered (normally at the end of every string), or <max> characters
     are copied. A 0 (NULL) is always copied at the end of the target
     string. The 0 does not count as part of the <max>. Only as many char-
     acters as will fit in <target> are copied.

     ■  Return Value

     None.
     Telix v4.25 - SALT Programming                Built-in Functions    29



     ■  See Also

     copystr, subchrs, substr




     COPYSTR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     copystr(str <source>, str <target>, int <pos>, int <count>);

     ■  Description

     The copystr function copies one string into another at a certain po-
     sition. Characters in string <source> are copied into string <target>
     at position <pos> (note that SALT string offsets start at 0, not 1 as
     in some languages). Characters are copied until a 0 (NULL) value is
     encountered (normally at the end of every string), or <max> characters
     are copied. A 0 (NULL) is always copied at the end of the target
     string. The 0 does not count as part of the <max>. Only as many char-
     acters as will fit in <target> are copied.

     ■  Return Value

     None.

     ■  See Also

     copychrs, substr, subchrs




     CPUTC
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cputc(int <character>);

     ■  Description

     The cputc function sends <character> to the communications port. This
     is the ASCII value of the character to be sent.

     ■  Return Value

     A non-zero (TRUE) value is returned unless the character can not be
     sent for some reason, in which case a value of -1 is returned.

     ■  See Also

     cputs
     Telix v4.25 - SALT Programming                Built-in Functions    30



     ■  Example

     cputc('A');
     cputc(27);          // send Escape to the comm port
     cputc('^M');        // send Ctrl-M (Carriage Return)
     cputc(inkeyw());




     CPUTS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cputs(str <outstr>);

     ■  Description

     The cputs function sends the passed string out over the modem port. A
     Carriage Return and Line Feed are NOT added after the string.

     ■  Return Value

     None.

     ■  See Also

     cputs_tr

     ■  Example

     cputs("Good-bye");
     str password[] = "mypass";
     cputs(password);




     CPUTS_TR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cputs_tr(str <outstr>);

     ■  Description

     The cputs_tr function sends the passed string out over the modem port,
     but pays attention to two output string translation characters,  ^ and
     ~, described in the Telix manual. This function is really only useful
     for sending the modem control strings that the user has defined in the
     Configuration Menu.

     ■  Return Value

     None.
     Telix v4.25 - SALT Programming                Built-in Functions    31



     ■  See Also

     cputs

     ■  Example

     cputs_tr(_modem_init);
     cputs_tr("good-bye~yes^M");




     CURSOR_ONOFF
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     cursor_onoff(int <state>);

     ■  Description

     The cursor_onoff functions turn the blinking cursor on or off (makes
     it disappear or reappear), depending on whether state is non-zero
     (TRUE) or zero (FALSE).

     ■  Return Value

     None.




     CURTIME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     curtime();

     ■  Description

     The curtime function returns the current date/time as the number of
     seconds since Jan 1, 1970. A date/time value in this format is used by
     many SALT functions.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     date, time, tyear, tmonth, tday, thour, tmin, tsec

     ■  Example

     // Print the current date
     Telix v4.25 - SALT Programming                Built-in Functions    32



     int t;
     str s[64];

     t = curtime();
     date(t, s);
     prints(s);




     DATE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     date(int <timeval>, str <buffer>);

     ■  Description

     The date function writes out a date in <buffer> in the form mm/dd/yy,
     dd/mm/yy, or yy/mm/dd (which is based on the system variable
     _date_format). <timeval> is the date, represented as the number of
     seconds since Jan 1, 1970. Time values in this form are returned by
     the curtime and filetime functions, among others.

     ■  Return Value

     None.

     ■  See Also

     time, curtime, filetime

     ■  Example

     str s[16];
     printsc("The current date is ");
     date(curtime(), s);
     prints(s);


     DELAY, DELAY_SCR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     delay(int <duration>);

     delay_scr(int <duration>);

     ■  Description

     The delay function pauses Telix for a length of time specified in
     tenths of a second by <duration>. During this pause, everything is
     shut off except the asynchronous reception of characters from the comm
     port.
     Telix v4.25 - SALT Programming                Built-in Functions    33



     The delay_scr function pauses only the execution of the current script
     file for the indicated duration. During that time, characters coming
     in from the serial port are printed on the terminal screen, while user
     keystrokes are also processed.

     ■  Return Value

     The <duration> argument is returned.




     DELCHRS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     delchrs(str <s>, int <pos>, int <num>);

     ■  Description

     The delchrs function is used to remove or delete a number of charac-
     ters in a string at a certain position. <s> is the string to handle.
     <pos> is the position at which <num> characters will be deleted (note
     that the first characters in a SALT string has the position 0). Re-
     maining characters in the string are be shifted left.

     ■  Return Value

     None.

     ■  See Also

     inschrs

     ■  Example

     // remove all but the first and last characters in a string

     str s[] = "0123456789";
     delchrs(s, 1, strlen(s) - 2);




     DIAL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     dial(str <dialstr>, int <maxtries>, int <no_link>);

     ■  Description

     The dial function dials the entries specified in <dialstr>. The en-
     tries should be entered in the same format as used when typing entries
     in the dialing directory. If <dialstr> is empty (""), the dialing di-
     Telix v4.25 - SALT Programming                Built-in Functions    34



     rectory is displayed. <maxtries> is the maximum number of dialing at-
     tempts. For example, if the string contains one entry, and <maxtries>
     is equal to 5, Telix will attempt to dial the number 5 times. If five
     entries are indicated, and <maxtries> is equal to 5, each number will
     only be attempted once.  If <maxtries> is 0, dialing will continue un-
     til a connection is established. If an entry is connected to, and has
     a linked script file attached, that script will be run, unless
     <no_link> is non-zero (TRUE).

     ■  Return Value

     If there was a connection, the dial function returns the entry number
     of the entry which was connected to (or 1 if a manual number was di-
     aled). If there was no connection established, 0 is returned. If the
     <dialstr> has a bad format, -1 is returned.

     Also, when a connection is successfully established, the entry number
     of the entry connected to is placed in the system variable
     _entry_enum, while the name of the entry connected to is placed in the
     system variable _entry_name.

     ■  See Also

     redial
     _entry_enum, _entry_name

     ■  Example

     int stat;
     dial("10 15", 0);
     dial("m967-1111", 5);
     stat = dial(number_list, 0);




     DOS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     dos(str <command>, int <mode>);

     ■  Description

     The dos function calls the DOS command interpreter (usually COM-
     MAND.COM, and gives it the passed command string. If the <command>
     string is empty (""), Telix will drop into a DOS shell, as if the Alt-
     J command had been executed. Make sure that if you specify a command
     or program that expects user input you are on hand to give it. The
     <mode> argument specifies several options, as follows:

          0    Original screen is restored when command is completed.
          1    When command is completed, the user is prompted to press a
               key and screen is restored as soon as it is pressed.
          2    Original screen is not restored when command is completed
     Telix v4.25 - SALT Programming                Built-in Functions    35



     This function is very similar to the run function. It should be used
     when an internal DOS command is needed or a DOS shell is needed, oth-
     erwise run is preferable as it uses less memory and executes faster.

     ■  Return Value

     The dos function returns a -1 if the command processor can not be
     found or there is not enough memory to load it, otherwise a 0 is re-
     turned.

     ■  See Also

     run, dosfunction

     ■  Example

     dos("copy a:*.* c:", 1);




     DOSFUNCTION
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     dosfunction();

     ■  Description

     The dosfunction function calls up the 'DOS Functions' menu, as if the
     user had pressed Alt-F while in terminal mode.

     ■  Return Value

     None.

     ■  See Also

     dos, run




     EXITTELIX
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     exittelix(int <returncode>, int <hangup>);

     ■  Description

     The exittelix function closes any currently open log file, and exits
     Telix to DOS, as if the user had pressed Alt-X while in terminal mode.
     The <returncode> argument is the value that should be returned to DOS.
     This value can be read by whatever called Telix (e.g., a batch file
     Telix v4.25 - SALT Programming                Built-in Functions    36



     using the errorlevel command). The <hangup> option affects what hap-
     pens if Telix is online. If it is set to non-zero (TRUE), Telix will
     hang-up before returning to DOS, otherwise the connection will not be
     disturbed.

     ■  Return Value

     Since this functions causes Telix to terminate, there is never any re-
     turn from it.

     ■  Example

     exittelix(0, 1);
     exittelix(100, 0);


     FCLEARERR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fclearerr(int <fh>);

     ■  Description

     The fclearerr function clears the error flag assigned to the open file
     represented by file handle <fh>. It also clears the End Of File flag
     for that file as well.

     ■  Return Value

     None.

     ■  See Also

     ferror, feof

     ■  Example

     int f;
     f = fopen("test.dat", "r");
        ...
     if (ferror(f))
      fclearerr(f);


     FCLOSE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fclose(int <fh>);

     ■  Description

     The fclose functions closes the file represented by the file handle
     <fh>, which must previously been opened for reading or writing with
     Telix v4.25 - SALT Programming                Built-in Functions    37



     the fopen function. If the file was opened for writing, any data which
     is still buffered and waiting to be written out to disk is written be-
     fore the file is closed.

     ■  Return Value

     A return value of -1 indicates a problem closing the file.

     ■  See Also

     fopen

     ■  Example

     int f;
     f = fopen("test.dat", "w");
        ...
     fclose(f);


     FDELETE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fdelete(str <filename>);

     ■  Description

     The fdelete function is used to delete a disk file from within a
     script. <filename> is the name of the file to delete. A full drive and
     path may be specified as part of the filename, and case is not signif-
     icant, but wildcard characters (* or ?) may NOT be part of the file-
     name.

     ■  Return Value

     A value of -1 is returned if there is a problem deleting the file, 0
     otherwise.

     ■  See Also

     frename

     ■  Example

     fdelete("C:\UTIL\TLX\TELIX.CAP");    // delete an old capture file




     FEOF
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     feof(int <fh>);
     Telix v4.25 - SALT Programming                Built-in Functions    38



     ■  Description

     The feof function determines if the file position for the open file
     represented by the file handle <fh> is at the end-of-file position.

     ■  Return Value

     A non-zero (TRUE) value is returned if the file position is at the end
     of the file.

     ■  See Also

     ferror

     ■  Example

     int f, chr;
     f = fopen("test.dat", "r");
     while ((chr = fgetc(f)) != -1)    // print contents of file
      printc(chr);
     if (feof(f))
      prints("Reached end of file.");
     else
      prints("Error reading file");


     FERROR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     ferror(int <fh>);

     ■  Description

     The ferror function checks the error flag for a file represented by
     the file handle <fh>. The error flag stays set until it is cleared
     with fclearerr or the file is closed.

     ■  Return Value

     A non-zero (TRUE) value is returned if the file's error flag is set.

     ■  See Also

     fclearerr, feof

     ■  Example

     int f;
     f = fopen("test.dat", "r");       // open file only for reading
     fputs("This should set the error flag!", f);
     if (ferror(f))
      prints("Error writing to file!");
     Telix v4.25 - SALT Programming                Built-in Functions    39



     FFLUSH
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fflush(int <fh>);

     ■  Description

     The fflush function flushes the buffer associated with the file rep-
     resented by file handle <fh>. If the file is opened for writing, any
     characters in the buffer are written. If the file is opened for read-
     ing, the buffer is cleared.

     ■  Return Value

     A value of -1 is returned if there is a problem flushing the buffer.

     ■  See Also

     fopen, fclose


     FGETC
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fgetc(int <fh>);

     ■  Description

     The fgetc function returns the next character from the file rep-
     resented by the file handle <fh>. The file must have been opened for
     reading or from reading and writing, using the fopen function.

     ■  Return Value

     Returns the character read if successful, or -1 if the end of the file
     has been reached or an error is encountered.

     ■  See Also

     fopen, fputc

     ■  Example

     int f;
     f = fopen("test.dat", "r");
     while (!feof(f))        // print all the characters in the file
      printc(fgetc(f));
     Telix v4.25 - SALT Programming                Built-in Functions    40



     FGETS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fgets(str <buffer>, int <n>, int <fh>);

     ■  Description

     The fgets function reads characters from the open file indicated by
     the file handle <fh> into the string variable <buffer>. Reading stops
     when a newline (Line Feed) character is read, and end-of-file is en-
     countered, a read error occurs, or <n> characters have been read. The
     Line Feed character (and the Carriage Return that usually precedes it
     on MS-DOS systems) is not kept as part of the string.

     Important: The SALT implementation of the fgets() function differs
     from the C language function of the same name. While both implemen-
     tations read until the Line Feed character, C keeps that character as
     part of the input string, while SALT doesn't. This change was made be-
     cause in almost every case, the Line Feed is not needed, and would
     otherwise have to be manually stripped by the script after every read.

     ■  Return Value

     A value of -1 is returned if there is a read error, or if there is an
     end-of-file before any characters can be read.

     ■  See Also

     fopen, fputs

     ■  Example

     int f;
     str s[100];
     f = fopen("test.dat", "r");
     while (!feof(f))         // print out contents of text file
      {
       fgets(s, 100, f);
       printsc(s);
      }


     FILEATTR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fileattr(str <filespec>);

     ■  Description

     Under the MS-DOS file system, files have a certain attributes which
     can determine their functions or the way certain things behave. For
     example if a file has the 'hidden' bit set as part of its attribute
     Telix v4.25 - SALT Programming                Built-in Functions    41



     byte, when you do a DOS dir command, the file is not shown. Similarly,
     if a file has the read only bit set, you may not overwrite it.

     The fileattr function returns an integer value representing the at-
     tributes of a specified file. <filespec> is the name of the file and
     may include a drive and directory portion, as well as the DOS wildcard
     characters * and ?.

     The value returned is a total of the following attributes.

          1    Read only file.

          2    Hidden file. The file is not listed when the DOS dir command
               is executed.

          4    System file. The file is not listed when the DOS dir command
               is executed.

          8    Volume label. This is the volume name of the disk.

          16   Subdirectory. This is a subdirectory name.

          32   Archive bit. This is set by DOS whenever a file has been
               written to and is then used by some backup software to check
               if a file has been modified since last backed-up.

     Each of these values is a certain bit in a byte. To test for the ex-
     istence of an attribute, the bitwise AND operator should be used. For
     example, the following fragment would check if the read only bit in an
     attribute is set:

     if (attrib & 1)
      ...

     If <filespec> is blank (""), then the attributes of the last file
     found with the filefind function is returned. Note that calling file-
     size or filetime in the meantime with a non-blank filename would in-
     stead make this call return the attributes of files found with those
     functions, as they use the same buffer.

     ■  Return Value

     An integer value representing the combined attributes of the indicated
     file is returned, or a value of -1 is returned if the indicated file
     could not be found.

     ■  See Also

     filefind, filesize, filetime

     ■  Example

     int attr;
     str filename[64];
     gets(filename, 64);
     attr = fileattr(filename);
     if (attr & 6)      // system _and_ hidden added together
     Telix v4.25 - SALT Programming                Built-in Functions    42



      prints("This file is marked as hidden and system");


     FILEFIND
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     filefind(str <filespec>, int <attrib>, str <buffer>);

     ■  Description

     The filefind function is used to search for the existence of one or
     more files or disk directories. Filefind puts in <buffer> the name of
     the first file matching <filespec>, which may include a drive and path
     as well as a filename, and may use the DOS wildcard characters * and ?
     (e.g., "*.*", "C:\TELIX\TELIX.EXE", "SCRIPTS\TEST??.*"). <attrib> is
     the attribute (also see fileattr) which files must match. The at-
     tribute is obtained by adding certain values as follows:

          0    Normal files and read only files
          2    Hidden files
          4    System files
          8    Disk volume label
          16   Subdirectory

     If the attribute is 0, only normal (and read-only) files are found. If
     the volume label is selected, only volume labels will be returned. Any
     other selected attribute or combination (addition) of attributes re-
     sults in those files and all normal files being matched.

     When a matching file, directory, or volume name is found, it is put in
     <buffer> (note that the drive and path portion of filespec are not
     copied), and a non-zero (TRUE) value is returned. The size, date/time,
     and attributes of the matched file can be seen with the filesize,
     filetime, and fileattr functions, respectively.  If no files matching
     the file specification are found, a zero (FALSE) value is returned.

     If <filespec> is blank (""), then filefind searches for the next
     matching file. Note that this will not work after an intervening call
     to filesize, filetime, or fileattr with a non-blank filename, as the
     same buffer is used for searches and to keep data.

     ■  Return Value

     A non-zero (TRUE) value is returned if a file matching the speci-
     fication was found, otherwise a value of zero (FALSE) is returned.

     ■  See Also

     filesize, filetime, fileattr

     ■  Example

     // show all normal files in the current directory
     str buf[16], fspec[16] = "*.*";
     while (filefind(fspec, 0, buf) != 0)
     Telix v4.25 - SALT Programming                Built-in Functions    43



      {
       prints(buf);    // show file found
       fspec = "";     // so we can continue searching for files
      }


     FILESIZE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     filesize(str <filespec>);

     ■  Description

     The filesize function returns the size in bytes of the specified file.
     <filespec> is the name of the file and may include a drive and direc-
     tory portion, as well as the DOS wildcard characters * and ?.

     If <filespec> is blank (""), then the size of the last file found with
     the filefind function is returned. Note that calling filetime or
     fileattr in the meantime with a non-blank filename would instead make
     this call return the size of files found with those functions, as they
     use the same buffer.

     ■  Return Value

     An integer value representing the size of the indicated file is re-
     turned, or a value of -1 is returned if the indicated file could not
     be found.

     ■  See Also

     filefind, filetime, fileattr

     ■  Example

     str filespec[24] = "*.*", buf[12];
     int size;
     siz = filesize("TELIX.EXE");   // get size of file TELIX.EXE
     // Add up size of all files int he current directory
     siz = 0;
     while (filefind(filespec, 0, buf) != 0)   // until no more files
      {
       siz = siz + filesize("");   // get size of last filefound file
       filespec = "";              // make sure filespec is "" on sub-
                                   // sequent calls to filefind to
                                   // continue searching for files
      }


     FILETIME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     filetime(str <filespec>);
     Telix v4.25 - SALT Programming                Built-in Functions    44



     ■  Description

     The filetime function returns the date/time of the specified file.
     <filespec> is the name of the file and may include a drive and di-
     rectory portion, as well as the DOS wildcard characters * and ?.

     The values returned represents the file's modification date as the
     number of seconds since Jan 1, 1970. A date/time in this form can be
     used by the date, time, tyear, tmonth, tday, thour, tmin, tsec, and
     other functions.

     If <filespec> is blank (""), then the date/time of the last file found
     with the filefind function is returned. Note that calling filesize or
     fileattr in the meantime with a non-blank filename would instead make
     this call return the time/date of files found with those functions, as
     they use the same buffer.

     ■  Return Value

     An integer value representing the date/time of the indicated file is
     returned, or a value of -1 is returned if the indicated file could not
     be found.

     ■  See Also

     filefind, filesize, fileattr

     ■  Example

     int time;
     str s[16];

     time = filetime("TELIX.EXE");
     if (time == -1)
      prints("'TELIX.EXE" could not be found!");
     else
      {
       printsc("TELIX.EXE was created at ");
       time(time, s);
       printsc(s);
       printsc(" on ");
       date(time, s);
       printsc(s);
      }

     // this example assumes both files exist
     if (filetime("FILE1") < filetime("FILE2"))
      prints("FILE1 is older than FILE2");
     else
      prints("FILE1 is newer than FILE2");
     Telix v4.25 - SALT Programming                Built-in Functions    45



     FLUSHBUF
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     flushbuf();

     ■  Description

     The flushbuf function flushes (throws away) any characters that may be
     waiting in Telix's remote input buffer. One use for this command is to
     get rid of unwanted line noise.

     ■  Return Value

     None.


     FNSTRIP
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fnstrip(str <filename>, int <specifier>, str <target>);

     ■  Description

     The fnstrip function allows specific parts of a filename to be ex-
     tracted. In the MS-DOS operating system, a filename can consist of up
     to four parts, the drive, the path, the name, and the extension (e.g.,
     C:\TELIX\TELIX.FON). fnstrip processes the filename specified in
     <filename>, and depending on the value of <specifier>, places any com-
     bination of these four parts in the <target> string. Legal values for
     <specifier> and their results are as follows:

          <specifier>    Filename portion copied

               0         Full file name
               1         All except the drive
               2         Drive, name, and extension
               3         Name and extension
               4         Drive, path, and name (no extension)
               5         Path and name (no extension)
               6         Drive and name (no extension)
               7         Name only (no extension)
               12        Drive and path only
               13        Path only
               14        Drive only

     ■  Return Value

     None.

     ■  See Also

     filefind
     Telix v4.25 - SALT Programming                Built-in Functions    46



     ■  Example

     str filename[64], shortname[16];
     gets(filename, 64);                 // ask for a filename
     fnstrip(filename, 3, shortname);    // keep only name & extension


     FOPEN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fopen(str <name>, str <mode>);

     ■  Description

     The fopen function is used to open a disk file for reading and/or
     writing. The file to be opened is given by <name>. <mode> is a string
     indicating for what use the file should be opened. Legal values for
     mode are:

          "r"       Opens for reading
          "w"       Opens for writing (truncates any existing file with the
                    same name)
          "a"       Opens for appending (writing at the end of the file).
                    Creates the file if it doesn't exist.
          "r+"      Opens for reading and writing. Initial position at the
                    beginning of the file (the file must already exist).
          "w+"      Opens for reading and writing. If the file exists its
                    contents are destroyed.
          "a+"      Opens for reading and appending. Creates the file if it
                    doesn't exist.

     If a file is opened for both reading and writing (when "r+", "w+", or
     "a+" are used as the mode), an fseek operation is necessary before
     switching from one to the other.

     ■  Return Value

     The fopen function returns a 'handle' which is an integer number by
     which this file is to be referred to until it is finally closed. A
     value of 0 is returned if the file can not be opened (because it
     doesn't exist, because a disk error occurred, or because there are no
     more file handles available). Only up to 8 files may be opened at a
     time. It is therefore very important to close open files if they are
     no longer needed and when a script is done, or else all available file
     handles will become used up.

     ■  See Also

     fclose

     ■  Example

     int f;
     f = fopen("data.txt", "r");    // open the file for reading
     if (f == 0)
     Telix v4.25 - SALT Programming                Built-in Functions    47



      prints("Error opening file!");


     FPUTC
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fputc(int <c>, int <fh>);

     ■  Description

     The fputc function writes a character to the file indicated by the
     file handle <fh>. <c> is the character to write.

     ■  Return Value

     The character written is returned, unless there is an error, in which
     case a value of -1 is returned.

     ■  See Also

     fputs, fgetc

     ■  Example

     int f, i;
     str teststr[] = "This is a test string";
     f = fopen("test.dat", "w");
     for (i = 0; i < 21; ++i)           // write out string to file
      fputc(subchr(teststr, i), f);     // character by character


     FPUTS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fputs(str <s>, int <fh>);

     ■  Description

     The fputs function writes a string to the file represented by file
     handle <fh>. The string must be 512 bytes in length or less (all
     strings end in a zero (0) value, the use of which is usually trans-
     parent; characters are written until this 0 is encountered. The 0 is
     not written).

     ■  Return Value

     A 0 value is returned if the write is successful, a non-zero value if
     it is not.

     ■  See Also

     fputc, fgets
     Telix v4.25 - SALT Programming                Built-in Functions    48



     ■  Example

     int f, i;
     f = fopen("test.dat", "w");
     for (i = 0; i < 100; ++i)      // write out "Hello" and a new-
      fputs("Hello^M^J", f);        // line one hundred times


     FREAD
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fread(str <buf>, int <count>, int <fh>);

     ■  Description

     The fread function reads up to <count> bytes from the file represented
     by file handle <fh>. Characters are written to the <buf> variable,
     which must be large enough.

     ■  Return Value

     The number of bytes actually read is returned, which may be less than
     <count> if an error occurs or and end-of-file is encountered.

     The ferror and feof functions should be used to distinguish an error
     from an end-of-file condition.

     ■  See Also

     fwrite

     ■  Example

     int f;
     str buffer[40];
     f = fopen("test.dat", "r");
     fseek(f, 1000, 0);       // goto offset 1000 in file
     fread(buffer, 40, f);    // and read 40 bytes of data


     FRENAME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     frename(str <oldname>, str <newname>);

     ■  Description

     The frename function is used to rename a disk file. <oldname> is the
     original name of the file, while <newname> is what it should be re-
     named to. A full drive and path may be included in the original name,
     but should not be placed before the new name. The renamed file will
     stay in the original drive and directory. Case is not significant.
     Telix v4.25 - SALT Programming                Built-in Functions    49



     ■  Return Value

     If successful, frename returns a 0 value, otherwise a non-zero value
     is returned.

     ■  See Also

     fdelete

     ■  Example

     frename("\TELIX\TELIX.CAP", "OLDTLX.CAP");


     FSEEK
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fseek(int <fh>, int <offset>, int <origin>);

     ■  Description

     The fseek function sets the position of the file pointer in the file
     represented by the file handle <fh>. The file position is where the
     next read or write will take place. <offset> is the signed offset from
     the location specified by <origin>. Legal values for <origin> are:

          0:   Beginning of file.
          1:   Current position.
          2:   End of file.

     The pointer can be positioned anywhere in the file, and even past the
     end of the file (which will extend it). It is illegal to try to posi-
     tion the pointer before the beginning of the file however.

     ■  Return Value

     If successful, fseek returns a 0 value, otherwise a non-zero value is
     returned.

     ■  See Also

     ftell

     ■  Example

     int f;
     f = fopen("test.dat", "r");
     fseek(f, 0, 0);       // go to offset 0 in file
     fseek(f, 1000, 0);    // go to offset 1000 in file
     fseek(f, -5, 1);      // go back 5 places in file
     fseek(f, 0, 2);       // go to the end of the file
     Telix v4.25 - SALT Programming                Built-in Functions    50



     FTELL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     ftell(int <fh>);

     ■  Description

     The ftell function returns the current file position in the file rep-
     resented by file handle <fh>. This is generally the position where the
     next read or write operation will take place. Note however that for a
     file opened in Append mode, the value returned will not necessarily
     return the position of the next write, since Append mode will force
     writes to the end of file regardless of the current file position.

     ■  Return Value

     An integer value as described above. A -1 value is returned if an er-
     ror occurs.

     ■  See Also

     fseek


     FWRITE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     fwrite(str <buf>, int <count>, int <fh>);

     ■  Description

     The fwrite function writes bytes to the file represented by the file
     handle <fh>. <count> number of bytes are written from <buf>.

     ■  Return Value

     The number of bytes actually written are returned, which may be less
     than <count> if an error occurred.

     ■  See Also

     fread

     ■  Example

     int f;
     str buffer[] = "1234567890123456789012345";
     f = fopen("test.dat", "w");
     fwrite(buffer, 25, f);       // write test pattern to file
     Telix v4.25 - SALT Programming                Built-in Functions    51



     GET_BAUD
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     get_baud();

     ■  Description

     The get_baud function returns an integer value which is the current
     baud rate in use on the current communications port (300 through
     115200).

     ■  Return Value

     As described above.

     ■  See Also

     get_parity, get_datab, get_stopb, get_port

     ■  Example

     prints("The current baud rate is ");
     printn(get_baud());
     prints("");


     GET_DATAB
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     get_datab();

     ■  Description

     The get_datab function returns the data bits setting in use on the
     current communications port (7 or 8).

     ■  Return Value

     As described above.

     ■  See Also

     get_baud, get_parity, get_stopb, get_port


     GETENV
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     getenv(str <varname>, str <target>);
     Telix v4.25 - SALT Programming                Built-in Functions    52



     ■  Description

     The getenv function may be used to access the DOS Environment and get
     the value assigned to an Environment Variable. <varname> is the name
     of the environment variable to be searched for, and <target>  is the
     string variable where whatever is assigned to the environment variable
     should be placed.

     ■  Return Value

     A non-zero (TRUE) value is returned if the function is successful,
     otherwise a zero (FALSE) values is returned (if the environment vari-
     able didn't exist);

     ■  Example

     // Get and print whatever is assigned to the TELIX env. variable
     str value[64];
     if (getenv("TELIX", value))    // if env. variable exists
      prints(value);                // print value


     GET_PARITY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     get_parity();

     ■  Description

     The get_parity function returns an integer value which represents the
     current parity setting in use on the current comm port.

     ■  Return Value

     Returned values are as follows:

               0    No parity
               1    Even parity
               2    Odd parity

     ■  See Also

     get_baud, get_datab, get_stopb, get_port


     GET_PORT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     get_port();
     Telix v4.25 - SALT Programming                Built-in Functions    53



     ■  Description

     The get_port function returns the number (1 through 8) of the current
     communications port being used.

     ■  Return Value

     As described above.

     ■  See Also

     get_baud, get_datab, get_parity, get_stopb

     ■  Example

     prints("Currently using COM");
     printn(get_port());
     prints("");


     GET_STOPB
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     get_stopb();

     ■  Description

     The get_stopb function returns the stop bits setting in use on the
     current com port (1 or 2).

     ■  Return Value

      As described above.

     ■  See Also

     get_baud, get_datab, get_parity, get_port


     GETS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     gets(str <buffer>, int <max>);

     ■  Description

     The gets function allows the user to enter a complete string, and use
     the arrow keys to edit it while it is being entered. <buffer> is the
     string variable where the string should be put, while <max> is the
     maximum number of characters the user may enter (from 0 to 80). The
     user may edit the string as it is being entered, with the Left-Arrow,
     Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it is being
     entered, and insert mode may be toggled on/off with the INS key.
     Telix v4.25 - SALT Programming                Built-in Functions    54



     String entry is over when the user presses Enter (Carriage Return on
     some computers). The user may press Esc to abort string entry, in
     which case the resulting string will have a length of 0.

     ■  Return Value

     The number of characters entered by the user are returned. If the user
     pressed Esc to abort string entry, a value of -1 is returned.

     ■  See Also

     getsxy

     ■  Example

     int n;
     str password[8];
     printsc("Enter a password? ");
     n = gets(password, 8);

     GETSXY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     getsxy(str <targets>, int <max>, int <x>, int <y>, int <color>);

     ■  Description

     The getsxy function is similar to the gets function, but the x,y lo-
     cation of string entry may be specified, as well as a color attribute.
     <buffer> is the string variable where the string should be put, while
     <max> is the maximum number of characters the user may enter (from 0
     to 80). The cursor will be moved to <x>,<y>, and text entered will use
     a color as described by <color>.

     The user may edit the string as it is being entered, with the Left-Ar-
     row, Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it is
     being entered, and insert mode may be toggled on/off with the INS key.
     String entry is over when the user presses Enter (Carriage Return on
     some computers). The user may press Esc to abort string entry, in
     which case the resulting string will have a length of 0.

     ■  Return Value

     The number of characters entered by the user are returned. If the user
     pressed Esc to abort string entry, a value of -1 is returned.

     ■  See Also

     gets

     ■  Example

     int n;
     str filename[64] = "C:\TELIX\TELIX.EXE";
       // allow use to enter filename in black on white
     Telix v4.25 - SALT Programming                Built-in Functions    55



       // at current cursor position
     n = getsxy(filename, 64, getx(), gety(), 112);


     GETX, GETY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     getx();

     gety();

     ■  Description

     The getx function returns the current column (horizontal x axis) po-
     sition of the cursor on the screen.

     The gety function returns the current row (vertical y axis) position
     of the cursor on the screen.

     ■  Return Value

     Returned values will range from 0 for the leftmost column to 79 for
     the rightmost column, for the getx function.

     Returned values range from 0 for the upper edge of the screen to 24
     for the lower edge, for the gety functions..

     ■  See Also

     gotoxy


     GOTOXY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     gotoxy(int <xpos>, int <ypos>);

     ■  Description

     The gotoxy function positions the cursor at the screen coordinates
     given by <xpos> and <ypos>. Note that 0,0 is the upper left corner. On
     a 80x25 text screen, the lower right corner would be 79,24.

     ■  Return Value

     None.

     ■  See Also

     getx, gety
     Telix v4.25 - SALT Programming                Built-in Functions    56



     ■  Example

     gotoxy(0, 0);      // go to the top left corner

     gotoxy(79, 24);    // go to the bottom right corner


     HANGUP
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     hangup();

     ■  Description

     The hangup function tries to hang-up the modem, exactly as if the user
     had pressed Alt-H while in terminal mode. This is accomplished by
     first dropping (turning off) a signal called the DTR line, and if that
     is unsuccessful, sending the hang-up string defined in the configu-
     ration menu.

     ■  Return Value

     A non-zero (TRUE) value is returned if the hang-up is  successful,
     otherwise a zero (FALSE) value is returned.


     HELPSCREEN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     helpscreen();

     ■  Description

     The helpscreen function displays the help/status screen, as if the
     user had pressed the appropriate key while in terminal mode.

     ■  Return Value

     None.


     INKEY, INKEYW
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     inkey();

     inkeyw();
     Telix v4.25 - SALT Programming                Built-in Functions    57



     ■  Description

     The inkey function returns a character from the keyboard, but does not
     wait for a key to be pressed.

     The inkeyw function returns a character from the keyboard, and waits
     for a key to be pressed if the keyboard buffer is empty.

     Note that Telix while executing a script file checks the keyboard be-
     tween every command to see if the user wants to abort the script. For
     these commands to work, this keyboard checking must be disabled. This
     is done by setting the _scr_chk_key system variable to a non-zero
     (FALSE) value (that variable is further described in the section on
     system variables).

     ■  Return Value

     inkey returns the first character in the keyboard buffer, or a value
     of 0 if the keyboard buffer is empty.

     inkeyw waits until a key has been pressed if none is available in the
     keyboard buffer, and returns that value.

     Both of these functions also return extended key code values which are
     not part of the ASCII character set (for example, the code for Alt-D).
     These values are described in the Appendix.

     ■  Example

     chr = inkey();


     INSCHRS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     inschrs(str <source>, str <target>, int <pos>, int <num>);

     ■  Description

     The inschrs function is used to insert characters from one string into
     another at a specific position, shifting existing characters to the
     right. Characters are taken from <source> and placed in <target>, at
     an offset indicated by <pos>. Note that string offsets are numbered
     starting at 0, so the first character would have an offset of 0, the
     second 1, etc. Only <num> characters are inserted, and existing char-
     acters are shifted to the right (and are lost if they shift past the
     space allocated for the string).

     ■  Return Value

     None.

     ■  See Also

     copystr, copychrs
     Telix v4.25 - SALT Programming                Built-in Functions    58



     ■  Example

     str test[24] = "Good-bye";
     // add "Hello" to the front of the existing string
     inschrs("Hello ", test, 0, 6);


     ISALNUM - ISUPPER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     isalnum(int <c>);   Test for alphanumeric ('A'-'Z', 'a'-'z', or '0'-
                              '9'

     isalpha(int <c>);   Test for letter ('A'-'Z' or 'a'-'z')

     isascii(int <c>);   Test for ASCII value (0-255)

     iscntrl(int <c>);   Test for Control character (0-31 or 127)

     isdigit(int <c>);   Test for digit ('0'-'9')

     islower(int <c>);   Test for lower case ('a'-'z')

     isupper(int <c>);   Test for upper case ('A'-'Z')

     ■  Description

     The functions listed above test an integer value and return a non-zero
     (TRUE) value if the test condition is satisfied, or a zero (FALSE) if
     it is not.

     Except for isascii, these functions give valid results only for in-
     teger values in the ASCII character set, that is, values for which
     isascii is true.

     ■  Return Value

     A non-zero (TRUE) value is returned if the test condition is sat-
     isfied, a 0 (FALSE) value otherwise.


     IS_LOADED
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     is_loaded(str <filename>);

     ■  Description

     The is_loaded function is used to determine if a SALT script, in-
     dicated by <filename> is currently loaded into memory. The script can
     be in memory if it was explicitly loaded with the load_script func-
     tion, or is still in memory because it previously was run and did not
     Telix v4.25 - SALT Programming                Built-in Functions    59



     finish executing. If filename does not include an extension, ".SLC" is
     automatically added.

     ■  Return Value

     A non-zero (TRUE) values is returned if the indicated script file is
     in memory, otherwise a zero (FALSE) value is returned.

     ■  See Also

     load_scr, unload_scr

     ■  Example

     if (!is_loaded("TESTSCR"))   // make sure script is in memory
      load_scr("TESTSCR");


     ITOS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     itos(int <value>, str <s>);

     ■  Description

     The itos function writes out the digits of the supplied integer value
     to <s>.

     ■  Return Value

     None.

     ■  See Also

     stoi

     ■  Example

     int chr;
     str s[16];
     chr = inkeyw();       // get a user keystroke
     itos(chr, s);         // and print out ASCII value of character
     prints(s);


     KEYGET
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     keyget(int <key>, int <table>, str <buffer>);
     Telix v4.25 - SALT Programming                Built-in Functions    60



     ■  Description

     The keyget function is used to look at what text is assigned to a key.
     <key> is an integer value representing the key (as described in the
     appendix). Any macro text assigned to this key will be placed in
     <buffer>. Telix keeps two key macro definition tables in memory at all
     times, a user key table, and a terminal key table, loaded in whenever
     the current terminal is changed. If <table> is 0, the key is assumed
     to be in the user table. If <table> is 1, the key is assumed to be in
     the terminal table.

     ■  Return Value

     None.

     ■  See Also

     keyset, keyload, keysave

     ■  Example

     str s[100];
     prints("Text currently assigned to the F1 key in user table is:");
     keyget(0x3b00, 0, s);
     prints(s);


     KEYLOAD
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     keyload(str <fname>, int <table>);

     ■  Description

     The keyload function is used to load a keyboard macro definition file
     into Telix. <fname> is the name of the definition file (if no exten-
     sion is given, .KEY is assumed). Telix always keeps two definition ta-
     bles in memory, a relatively constant user table, and a terminal table
     which changes with each different terminal and holds the proper key
     assignments for that terminal. If <table> is 0, then the definitions
     are loaded into the user table. If <table> is 1, the definitions are
     loaded into the terminal table.

     ■  Return Value

     A value of -1 is returned if there are problems loading the key file,
     otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     keysave, keyget, keyset

     ■  Example

     keyload("SPECIAL", 0);
     Telix v4.25 - SALT Programming                Built-in Functions    61





     KEYSAVE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     keysave(str <fname>, int <table>);

     ■  Description

     The keysave function is used to save the current macro key text def-
     initions to a disk file. <fname> is the file to save the definitions
     to, and if no extension is given, ".KEY" is added. Telix always keeps
     two key definition tables in memory, a relatively constant user table,
     and a terminal table which changes with each different terminal and
     holds the proper key assignments for that terminal. If <table> is 0,
     then the definitions from the user table are saved. If <table> is 1,
     the definitions from the terminal table are saved.

     ■  Return Value

     A value of -1 is returned if there is a problem writing to the file,
     otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     keyload, keyget, keyset


     KEYSET
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     keyset(int <key>, int <table>, str <text>);

     ■  Description

     The keyset function is used to assign text to a key. <key> is an in-
     teger value representing the key (as described in the appendix).
     <text> is what to assign to this key. Telix always keeps two key defi-
     nition tables in memory, a relatively constant user table, and a ter-
     minal table which changes with each different terminal and holds the
     proper key assignments for that terminal. If <table> is 0, the key
     definition in the user table is affected. If <table> is 1, the key
     definition in the terminal table is affected.

     ■  Return Value

     None.

     ■  See Also

     keyget, keyload, keysave
     Telix v4.25 - SALT Programming                Built-in Functions    62



     ■  Example

     // Assign a name to the F1 key in the user table
     // Note that if the terminal table also holds a
     // definition for that key it will take precedence
     keyset((0x3b00, 0, "Joe Smith");


     LOADFON
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int loadfon(str <filename>);

     ■  Description

     The loadfon function loads the given dialing directory file. The com-
     plete name must be given, including any extension (e.g. .FON) or the
     disk drive/directory if the file is not in the current directory.

     ■  Return Value

     A non-zero (TRUE) value is returned if the dialing directory file is
     successfully loaded. If some sort of error occurs (file does not ex-
     ist, file reading error, etc.) a zero (FALSE) value is returned.


     LOAD_SCR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     load_scr(str <filename>);

     ■  Description

     When a script is run (either by the user manually running it from ter-
     minal mode, or from within another script), it is usually loaded from
     disk. The load_scr function is used to load a script into memory ahead
     of time, providing a savings in time when the script must be run re-
     peatedly. <filename> is the name of the script file to load, and if no
     extension is given, ".SLC" is assumed.

     ■  Return Value

     If there is a problem loading the script file (it is not there or
     there is not enough memory),a value of -1 is returned. Otherwise a
     non-zero (TRUE) value is returned.

     ■  See Also

     unload_scr, is_loaded

     ■  Example

     int stat;
     Telix v4.25 - SALT Programming                Built-in Functions    63



     stat = load_scr("TEST");     // load TEST.SLC


     NEWDIR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     newdir(str <directory>);

     ■  Description

     The newdir function is used to change the current drive and/or di-
     rectory. The <directory> argument should be the drive and/or directory
     to change to.

     ■  Return Value

     A non-zero (TRUE) value is returned if the function is successful,
     otherwise a zero (FALSE) values is returned (if the drive or directory
     is illegal or doesn't exist).

     ■  See Also

     dos, run

     ■  Example

     newdir("C:\TELIX");


     PRINTC
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     printc(int <chr>);

     ■  Description

     The printc function prints the character represented by the ASCII
     value <chr> to the terminal screen.

     ■  Return Value

     <chr> is returned.

     ■  See Also

     prints, printsc, printn

     ■  Example

     printc('A');

     printc(7);            // print ASCII value 7 (BELL sound)
     Telix v4.25 - SALT Programming                Built-in Functions    64



     printc(keyinw());     // print user keypress


     PRINTER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     printer(int <state>);

     ■  Description

     The printer function is used within a script file to turn the printer
     on or off, as if the user had pressed the appropriate key in terminal
     mode. If <state> is a non-zero (TRUE) value, echoing to the printer is
     turned on, otherwise echoing is turned off

     ■  Return Value

     None.

     ■  See Also

     capture

     ■  Example

     printer(1);         // turn on printer log


     PRINTN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     printn(int <num>);

     ■  Description

     The printn function prints the passed integer number to the terminal
     screen. The cursor is NOT advanced to the beginning of the next line.

     ■  Return Value

     The value of the passed integer is returned.

     ■  See Also

     prints, printsc, printc

     ■  Example

     printsc("Current baud rate is ");
     printn(get_baud);
     Telix v4.25 - SALT Programming                Built-in Functions    65



     PRINTS, PRINTSC, PRINTSC_TRM
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     prints(str <outstr>);

     printsc(str <outstr>);

     printsc_trm(str <outstr>);

     ■  Description

     The prints function prints the passed string at the current cursor po-
     sition on the screen, followed by a Carriage Return and Line Feed
     (which places the cursor at the beginning of the next line).

     The printsc function prints the passed string at the current cursor
     position on the screen. The cursor is not advanced to the next line,
     hence the 'c', which stands for continuous.

     The printsc_trm function is similar to the above, except that out-
     putted characters pass through the current terminal emulator, so ter-
     minal escape sequences may be included in output strings.

     ■  Return Value

     None.

     ■  See Also

     printn, printc

     ■  Example

     prints("Hello");

     printsc("Hello^M^J");    // same effect as above

     printsc_trm("^[[H");     // go to top left corner in VT102 emulation


     PSTRA, PSTRAXY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     pstra(str <s>, int <color>);

     pstraxy(str <s>, int <x>, int <y>, int <color>);

     ■  Description

     The pstra (Print STRing with color Attribute) function is used to
     print a string to the screen, similar to the prints/printsc functions.
     This function is much faster however, and should be used when speed is
     important. As well, it allows a color to be specified for the text.
     Telix v4.25 - SALT Programming                Built-in Functions    66



     <s> will be printed to the screen at the current cursor position using
     a color as specified by <color>.

     The pstraxy function is similar to the above, but allows you to spec-
     ify where to print the string. The string is printed at <x>,<y>, with
     0,0 being the upper left corner of the screen.

     Note that prints goes through a basic TTY type terminal emulator, so
     strings printed using it may contain the basic cursor control code,
     while pstra writes directly to the screen, ignoring these sequences.

     ■  Return Value

     None.

     ■  See Also

     prints, printsc

     ■  Example

     pstraxy("Enter name:", 10, 10, 112);   // print in inverse text


     RECEIVE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     receive(int <protocol>, str <name>);

     ■  Description

     The receive function is used to receive (download) one or more files
     from another system. <protocol> is the letter used to select the ap-
     propriate protocol from the actual download menu in Telix (e.g., 'X'
     for Xmodem), as follows:

               'A'       ASCII
               'K'       Kermit
               'M'       Modem7
               'S'       SEAlink
               'T'       Telink
               'X'       Xmodem
               '1'       Xmodem-1k
               'G'       Xmodem-1k-g
               'Y'       Ymodem
               'E'       YmodEm-g
               'Z'       Zmodem

     If an external protocol is defined, <protocol> may also be the key
     used to select it. <name> is the name the file should take. For pro-
     tocols which pass the name, such as SEAlink, Zmodem, Ymodem (batch),
     and others, the name field should be an empty string, "". If a down-
     load directory has been defined in the Configuration Menu, received
     files will go there, unless the <name> string explicitly includes a
     path to another drive/directory.
     Telix v4.25 - SALT Programming                Built-in Functions    67



     ■  Return Value

     A value of -1 is returned if the transfer was aborted, except if the
     Carrier (connection) was lost, in which case a value of -2 is re-
     turned.

     ■  See Also

     send, _down_dir

     ■  Example

     int result;

     result = receive('X', "TEST.EXE");
     if (result < 0)
      prints("File transfer failed!");


     REDIAL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     redial(str <dialstr>, int <maxtries>, int <no_link>);

     ■  Description

     The redial function dials the entries specified in <dialstr>. The en-
     tries should be entered in the same format as used when typing entries
     in the dialing directory. If <dialstr> is empty (""), the redial queue
     is presented to the user, as if Alt-Q was pressed while in terminal
     mode. <maxtries> is the maximum number of dialing attempts. For exam-
     ple, if the string contains one entry, and <maxtries> is equal to 5,
     Telix will attempt to dial the number 5 times. If five entries are in-
     dicated, and <maxtries> is equal to 5, each number will only be at-
     tempted once. If <maxtries> is 0, dialing will continue until a con-
     nection is established. If an entry is connected to, and has a linked
     script file attached, that script will be run, unless <no_link> is
     non-zero (TRUE).

     ■  Return Value

     If there was a connection, the redial function returns the entry num-
     ber of the of the entry which was connected to (or 1 if a manual num-
     ber was dialed). If there was no connection established, 0 is re-
     turned. If the <dialstr> has a bad format, -1 is returned.

     Also, when a connection is successfully established, the entry number
     of the entry connected to is placed in the system variable
     _entry_enum, while the name of the entry connected to is placed in the
     system variable _entry_name.

     ■  See Also

     dial
     _entry_enum, _entry_name
     Telix v4.25 - SALT Programming                Built-in Functions    68



     ■  Example

     int stat;
     str number_list[] = "1 4 27";
     redial("10 15", 0);
     redial("m967-1111", 5);
     stat = redial(number_list, 0);


     RUN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     run(str <filename>, str <comline>, int <mode>);

     ■  Description

     The run function executes the indicated file. The indicated file must
     either be in the current directory, be on the DOS PATH, or must in-
     clude the full path to the file (i.e., specify the drive and/or direc-
     tory). Make sure that if you run a program that expects user input you
     are on hand to give it. The <comline> parameter is the command line
     which should be passed to the called program. The <mode> argument
     specifies several options, as follows:

          0    Original screen is restored when program is completed.
          1    When program is completed, the user is prompted to press a
               key and screen is restored as soon as it is pressed.
          2    Original screen is not restored when program is completed

     This function is similar to the dos function. Because it uses less
     memory and loads faster, it is preferable to that function unless a
     DOS Batch file has to be run, or an internal DOS command must be spec-
     ified, in which case the dos function has to be used.

     ■  Return Value

     The run function returns a -1 if the file can not be run (because it
     can not be found or there is not enough memory). Any other value is
     the value returned by the called program (usually 0), but a positive
     value may also result when the called program is aborted.

     ■  See Also

     dos, dosfunction

     ■  Example

     run("CS", "test", 1);
     Telix v4.25 - SALT Programming                Built-in Functions    69



     SCROLL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     scroll(int <x>, int <y>, int <x2>, int <y2>, int <lines>, int
     <color>);

     ■  Description

     The scroll function is used to scroll or clear a region of the screen.
     The area to handle is defined by <x>,<y> as the upper left corner, and
     <x2>,<y2> as the lower right corner (the upper left corner of the
     screen is 0,0). If the <lines> parameter is a positive value, text
     within the region is scrolled up that many lines. If <lines> is a neg-
     ative value, text within the region is scrolled down that many lines.
     If <lines> is equal to 0, the entire region is cleared. Empty lines
     scrolled into the region will have a color of <color>.

     ■  Return Value

     None.

     ■  See Also

     box

     ■  Example

     scroll(0, 0, 79, 24, 10, 7);      // scroll screen up 10 lines


     SEND
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     send(int <protocol>, str <name>);

     ■  Description

     The send function is used to send (upload) one or more files to an-
     other system over the comm port. <protocol> is the letter used to se-
     lect the appropriate protocol from the actual download menu in Telix
     (e.g., 'X' for Xmodem) as follows:
     Telix v4.25 - SALT Programming                Built-in Functions    70



               'A'       ASCII
               'K'       Kermit
               'M'       Modem7
               'S'       SEAlink
               'T'       Telink
               'X'       Xmodem
               '1'       Xmodem-1k
               'G'       Xmodem-1k-g
               'Y'       Ymodem
               'E'       YmodEm-g
               'Z'       Zmodem

     If an external protocol is defined, <protocol> may also be the key
     used to select. <name> is the file(s) to send. <name> may include the
     DOS wildcard characters * and ?, in which case all matching files will
     be sent (however the protocol used must be capable of sending more
     than one file at a time, e.g., SEAlink, Zmodem, Ymodem (batch), etc.).
     If an upload directory has been defined in the Configuration Menu,
     Telix will look there for files specified to be sent, unless the
     <name> string explicitly includes a path to another drive/directory.

     ■  Return Value

     A value of -1 is returned if the transfer was aborted, except if the
     carrier (connection) was lost, in which case a value of -2 is re-
     turned.

     ■  See Also

     receive, _up_dir


     SEND_BRK
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     send_brk(int <duration>);

     ■  Description

     The send_brk function sends a sustained break signal over the modem
     port, for a period of time, specified in tenths of a second, by
     <duration>.

     ■  Return Value

     None.


     SET_CPARAMS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     set_cparams(int <baud>, int <parity>, int <data>, int <stop>);
     Telix v4.25 - SALT Programming                Built-in Functions    71



     ■  Description

     The set_cparams function is used to set the communications parameters
     in use on the current communications port. Allowable <baud> values are
     300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. <parity>
     is an integer number which stands for the parity to use. Allowable
     values are 0, 1, and 2, which stand for None, Even, and Odd parity,
     respectively. <data> is the data bits setting to use; allowable values
     are 7 or 8. <stop> is the stop bits setting to use; allowable values
     are 1 or 2. Note that some combinations of settings are illegal.

     ■  Return Value

     If all the settings are legal values, a non-zero (TRUE) value is re-
     turned, otherwise a value of -1 is returned.

     ■  See Also

     set_port

     ■  Example

     set_cparams(2400, 0, 8, 1);

     set_cparams(9600, get_parity(), get_datab(), get_stopb());

     SET_DEFPROT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     set_defprot(int <protocol>);

     ■  Description

     The set_defprot function is used to set the default file transfer pro-
     tocol presented to the user when a file transfer is requested.
     <protocol> is the letter used to select the appropriate protocol at
     the file transfer menu (see the description of the receive function
     for possible options).

     ■  Return Value

     None.

     ■  See Also

     receive, send

     ■  Example

     set_defprot('Z');      // Select Zmodem as default protocol
     Telix v4.25 - SALT Programming                Built-in Functions    72



     SETCHR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     setchr(str <buf>, int <pos>, int <c>);

     ■  Description

     The setchr function puts the character <c> at position <pos> in the
     string indicated by <buf>.

     ■  Return Value

     The character <c> is returned.

     ■  See Also

     setchrs, subchr

     ■  Example

     int i;
     str s[100];
     for (i = 0; i < 10; ++i)     // set first 10 characters to 'A'
      setchr(s, i, 'A');


     SETCHRS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     setchrs(str <buf>, int <pos>, int <c>, int <count>);

     ■  Description

     The setchrs function is used to set a range of characters in a string
     to the same value. <buf> is the string in which characters will be
     set, starting at an offset indicated by <pos> (note that the first
     character in a SALT string has an offset of 0, the second, 1, and so
     on). <count> characters will be set to the value of <c>.

     ■  Return Value

     None.

     ■  See Also

     setchr, subchrs

     ■  Example

     str s[100];
     // zero out an entire string
     setchrs(s, 0, 0, strmaxlen(s));
     // set the first ten characters to 'A'
     Telix v4.25 - SALT Programming                Built-in Functions    73



     setchrs(s, 0, 'A', 10);


     SET_PORT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     set_port(int <port>);

     ■  Description

     The set_port function is used to select a communications port to use.
     Allowable values for <port> are 1 through 8.

     ■  Return Value

     If the new port can be successfully initialized, a non-zero (TRUE)
     value is returned, otherwise a value of -1 is returned.

     ■  See Also

     set_cparams


     SET_TERMINAL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     set_terminal(str <terminal_name>);

     ■  Description

     The set_terminal function is used to switch the current terminal being
     emulated. <terminal_name> is the name of the new terminal to use, as
     follows:

          "TTY"
          "ANSI-BBS"
          "ANSI"
          "VT102"
          "VT52"
          "AVATAR"

     ■  Return Value

     A value of -1 is returned if there is a problem switching to the in-
     dicated terminal emulator, otherwise a non-zero (TRUE) value is re-
     turned.

     ■  Example

     set_terminal("VT102");
     Telix v4.25 - SALT Programming                Built-in Functions    74



     SHOW_DIRECTORY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     show_directory(str <filespec>, int <cecho>, int <carrier>);

     ■  Description

     The show_directory function displays a files directory listing to the
     screen and optionally echoes it to the comm port. The <filespec> is
     the file mask to use (e.g., "*.*"), and may also include a drive
     and/or directory, just like the DOS 'dir' command. If the <cecho>
     argument is non-zero (TRUE), the listing is also be echoed to the comm
     port. If the <carrier> argument is non-zero (TRUE) and the listing is
     being echoed to the comm port, the carrier signal is monitored in case
     the connection is lost (which aborts the display). The user is
     prompted to press a key after every screen full of data.

     ■  Return Value

     None.

     ■  See Also

     dos, dosfunction

     ■  Example

     show_directory("*.DOC", 0, 0);


     STATUS_WIND
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     status_wind(str <message>, int <duration>);

     ■  Description

     The status_wind function is used to display a status message,
     <message>, in a pop up window. <duration> is the time in tenths of
     seconds to display the window, after which it is removed, and the pre-
     vious contents of that screen area are restored.

     ■  Return Value

     None.

     ■  See Also

     box, pstra, pstraxy

     ■  Example

     status_wind("File not found!", 10);
     Telix v4.25 - SALT Programming                Built-in Functions    75





     STOI
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     stoi(str <s>);

     ■  Description

     The stoi function assumes that <s> is a string which contains an in-
     teger number, written out. It processes the string digit by digit and
     returns that value. For example, stoi("123") would return the integer
     value 123. Processing stops at the first non-digit character. If an
     empty or invalid string is parsed, a value of 0 is returned.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     itos

     ■  Example

     str s[] = "123";
     if (stoi(s) == 123)
      prints("This will always be printed!");


     STRCAT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strcat(str <string1>, str <string2>);

     ■  Description

     The strcat function concatenates (adds or appends) one string to the
     other. <string2> is added to the end of <string1>. If <string1> is not
     large enough only as many characters as will fit are added.

     ■  Return Value

     None.

     ■  Example

     str s[80] = "hello";
     strcat(s, "good-bye");
     if (s == "hellogoodbye")
      prints("This will always be printed");
     Telix v4.25 - SALT Programming                Built-in Functions    76



     STRCHR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strchr(str <s>, int <pos>, int <c);

     ■  Description

     The strchr function is used to search for a character within a string.
     <s> is the string to search, and <pos> is the starting position of the
     search, and <c> is the character (ASCII value) to search for. If the
     character, its offset is returned, otherwise a value of -1 is re-
     turned. Note that the first character in a string has an offset of 0,
     not 1 as in some languages.

     ■  Return Value

     An integer value as described above.

     ■  Example

     // Count how many times a certain char occurs in a string

     int i, count = 0;
     str s[] = "abcabcabcabcabc";

     i = 0;
     do
      {
       i = strchr(s, i, 'a');
       if (i != -1)
        count = count + 1;
      }
     while (i != -1);


     STRCMPI
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strcmpi(str <string1>, str <string2>);

     ■  Description

     The strcmpi function is used to compare two strings (in a similar man-
     ner to the ==, >, and < operators, but ignoring the case of the
     strings). The strings are compared character by character until a dif-
     ference is found or the end of either string is found, and an integer
     value is returned as follows:
     Telix v4.25 - SALT Programming                Built-in Functions    77



          0         <string1> is equal to <string2>

          < 0       <string1> is less than <string2>

          > 0       <string1> is greater than <string2>

     ■  Return Value

     An integer value as described above.

     ■  Example

     if (strcmpi("HeLLo", "hEllO");
      prints("This will always be printed");


     STRLEN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strlen(str <s>);

     ■  Description

     The strlen function returns the number of characters in the string
     <s>. Since strings are terminated with a 0 (NULL) character, this
     function really counts the number of characters before a 0 is en-
     countered.

     ■  Return Value

     An integer value representing the length of a string.

     ■  See Also

     strmaxlen

     ■  Example

     str teststr[] = "This is a test string";
     printsc("The length of 'teststr' is ");
     printn(strlen(teststr));


     STRLOWER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strlower(str <s>);

     ■  Description

     The strlower function processes the string <s> and changes each upper
     case character to lower case. Other characters are left unchanged.
     Telix v4.25 - SALT Programming                Built-in Functions    78



     ■  Return Value

     None.

     ■  See Also

     strupper


     STRMAXLEN
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strmaxlen(str <s>);

     ■  Description

     The strmaxlen function returns the maximum number of characters that
     string <s> can hold. This is the same value as used when the string is
     defined elsewhere in the program (e.g. if the string was defined as
     'str hello[16];', a value of 16 would be returned). All strings are
     really one character larger than defined, as the last character is al-
     ways a terminating 0 (NULL). However, since this value can not be
     changed, it is not counted as part of the length of a string.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     strlen


     STRPOS, STRPOSI
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strpos(str <string1>, str <substr>, int <start>);

     strposi(str <string1>, str <substr>, int <start>);

     ■  Description

     The strpos function is used to search for one string within another.
     <string1> is scanned for <substr>, starting at the offset (position)
     indicated by <start>. If the sub-string is found, its offset is re-
     turned, otherwise a value of -1 is returned. Note that the first char-
     acter has an offset of 0, not 1 as in some languages.

     strposi is a case insensitive version of the above.

     ■  Return Value

     An integer value as described above.
     Telix v4.25 - SALT Programming                Built-in Functions    79



     ■  Example

     str teststr[] = "cat dog cat dog";
     int i = 0, num = 0;

     while (1)           // loop as long as needed
      {
       i = strpos(teststr, "cat", i);
       if (i == -1)
        break;
       i = i + 1;        // make sure we don't find the same one
       num = num + 1;    // increment count
      }

     prints("'cat' was found ");
     printn(num);
     prints(" times.");


     STRUPPER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     strupper(str <s>);

     ■  Description

     The strupper function processes the string <s> and changes each lower
     case character to upper case. Other characters are left unchanged.

     ■  Return Value

     None.

     ■  See Also

     strlower


     SUBCHR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     subchr(str <s>, int <pos>);

     ■  Description

     The subchr function returns the character found at position <pos> in
     string <s>. Note that an integer (representing the ASCII value of the
     character) is returned, not a string. <pos> may be anywhere within the
     string length as defined. Note that positions start from 0. The 1st
     character in a string is at position 0, the 40th at position 39, etc.
     A string defined with a length of 10 would have valid positions of 0
     to 9, with position 10 always returning the 0 value that terminates
     all strings.
     Telix v4.25 - SALT Programming                Built-in Functions    80



     ■  Return Value

     An integer value as described above.

     ■  See Also

     setchr, subchrs

     ■  Example

     // This will print out the contents of a test string, extracting
     // each character individually, and stopping when a 0 is reached
     // which marks the end of all proper strings

     int i;
     str s[] = "This is a test string";
     for (i = 0; subchr(s, i) != 0; ++i)
      printc(subchr(s, i));


     SUBCHRS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     subchrs(str <source>, int <pos>, int <count>, str <target>);

     ■  Description

     The subchrs function copies a number of characters from one string
     into another, Characters from position <pos> in <source> are copied
     into string <target> (note that SALT string offsets start at 0, not 1
     as in some languages). <count> characters are copied. Only as many
     characters as will fit in <target> are copied.

     This function is very similar to substr, except that it is not string
     oriented, and does not stop copying characters when a 0 value is en-
     countered.

     ■  Return Value

     None.

     ■  See Also

     substr, subchr, copystr, copychrs


     SUBSTR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     substr(str <source>, int <pos>, int <max>, str <target>);
     Telix v4.25 - SALT Programming                Built-in Functions    81



     ■  Description

     The substr function copies a portion of one string to another. Char-
     acters from position <pos> in string <source> are copied until into
     string <target> (note that SALT string offsets start at 0, not 1 as in
     some languages). Characters are copied until a 0 (NULL) value is en-
     countered (normally at the end of every string), or <max> characters
     are copied. A 0 (NULL) is always copied at the end of the target
     string. The 0 does not count as part of the <max>. Only as many char-
     acters as will fit in <target> are copied.

     ■  Return Value

     None.

     ■  See Also

     subchrs, copystr, copychrs

     ■  Example

     str s[] = "horse cat dog", s2[16];
     substr(s, 6, 3, s2);
     if (s2 == "cat")
      prints("This will always be printed");


     TDAY - TYEAR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     tday(int <timeval>);

     thour(int <timeval>);

     tmin(int <timeval>);

     tmonth(int <timeval>);

     tsec(int <timeval>);

     tyear(int <timeval>);

     ■  Description

     These functions all extract time information from <timeval>, which is
     a date and/or time of day. If <timeval> represents a date, it is the
     number of seconds from Jan 1, 1970 to that date. If <timeval> repre-
     sents a time of day, it is the number of seconds from midnight to that
     time. If it is both, the two above values are simply added together.
     Among others, the curtime and filetime functions return time/date in-
     formation in this format.

     tday returns an integer value from 1 to 31 representing the day por-
     tion of the date stored in <timeval>.
     Telix v4.25 - SALT Programming                Built-in Functions    82



     thour returns an integer value from 0 to 23 representing the hour por-
     tion of the time stored in <timeval>.

     tmin returns an integer value from 0 to 59 representing the minutes
     portion of the time stored in <timeval>.

     tmonth returns an integer value from 1 to 12 representing the month
     portion of the date stored in <timeval>.

     tsec returns an integer value from 1 to 59 representing the seconds
     portion of the time stored in <timeval>.

     tyear returns an integer value from 1970 to 2019 representing the year
     portion of the date stored in <timeval>.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     curtime, filetime

     ■  Example

     int t;
     t = curtime();
     printsc("This is month number ");
     printn(tmonth(t));
     printsc(" in the year ");
     printn(tyear(t));
     prints(".");


     TERMINAL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     terminal();

     ■  Description

     The terminal function when called allows Telix to process characters
     coming in from the serial port and print them on the terminal screen,
     and process user keystrokes. If a function has nothing to do (for ex-
     ample while using the track function), it can call terminal to make
     sure characters and user keystrokes are processed. Note that if a user
     script wants to process every incoming character (e.g., with the cgetc
     function, the terminal function should never be called).

     ■  Return Value

     None.
     Telix v4.25 - SALT Programming                Built-in Functions    83



     ■  See Also

     track

     ■  Example

     // This will wait forever for either of two strings
     // to come in from the comm port, and then stop.
     int t1, t2, stat;
     t1 = track("hello", 0);
     t2 = track("good-bye", 0);
     while (1)           // loop forever
      {
       terminal();       // The call to terminal() lets any characters
                         // that come in be looked at by Telix's
                         // internal routines for a match with.
                         // Incoming chars are also printed on the
                         // terminal screen and user keystrokes are
                         // handled
       stat = track_hit(0);
       if (stat == t1 || stat == t2)   // exit if one of the strings
        break;                         // came in
      }

     track_free(t1);     // stop Telix for looking for more matches
     track_free(t2);


     TIME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     time(int <timeval>, str <buffer>);

     ■  Description

     The time function writes out a time in <buffer> in the form hh:mm:ss,
     with hh being the hour in either 12 or 24 hour format based on the
     _time_format). <timeval> is the time, represented as the number of
     seconds since midnight. Time values in this form are returned by the
     curtime and filetime functions, among others.

     ■  Return Value

     None.

     ■  See Also

     date, curtime, filetime

     ■  Example

     str s[16];
     printsc("The current time is ");
     time(curtime(), s);
     prints(s);
     Telix v4.25 - SALT Programming                Built-in Functions    84





     TIME_UP - TIMER_TOTAL
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     time_up(int <thandle>);

     timer_free(int <thandle>);

     timer_restart(int <thandle>, int <time>);

     timer_start(int <time>);

     timer_total(int <thandle>);

     ■  Description

     The timer functions are used to set and keep track of a timer vari-
     able.

     The timer_start function is used to start a timer. This timer can
     later be used to check if a certain period of time has elapsed from
     when the timer was started. This function returns an integer value
     called a timer handle, that is used to refer to this timer in the fu-
     ture. The <time> parameter is the time from the present (in tenths of
     a second) after which the timer should be considered elapsed (for use
     with the time_up function). If the time_up function will not be used,
     then this parameter can be anything.

     The time_up function returns a non-zero (TRUE) value if the timer rep-
     resented by timer handle <thandle> has elapsed, otherwise a 0 (FALSE)
     value is returned. The period of time after which a timer will elapse
     is specified in the timer_start function.

     The timer_total function returns the total time (in tenths of a sec-
     ond) since the timer represented by timer handle <thandle> was started
     or restarted.

     The timer_restart function performs the same things as timer_start,
     except that it restarts an existing timer, represented by timer handle
     <thandle>.

     The timer_free function frees a timer variable when it is no longer
     needed. <thandle> is the timer handle of the timer to free, and should
     originally have been returned by the timer_start function. After a
     timer has been freed it should no longer be referred to.

     ■  Return Value

     timer_start returns an integer number representing a 'handle' by which
     a timer will be referred to.

     time_up returns a non-zero (TRUE) or 0 (FALSE) value depending on
     whether a timer has elapsed or not.
     Telix v4.25 - SALT Programming                Built-in Functions    85



     timer_total returns an integer value representing the elapsed time
     since a timer was started.

     timer_restart does not return any significant value.

     timer_free does not return any significant value.

     ■  See Also

     delay

     ■  Example

     int t;
     t = timer_start(100);    // delay for 10 seconds
     while (!time_up(t))
      ;
     timer_free(t);
     // start a timer and loop forever, printing the elapsed time
     // in tenths of seconds
     t = timer_start(0);
     while (1)
      {
       printn(timer_total(t));
       prints("");
      }


     TOLOWER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     tolower(int <chr>);

     ■  Description

     If the character <chr> is an uppercase character, the tolower function
     returns the lowercase equivalent. Otherwise <chr> is returned un-
     changed. Note that <chr> is an ASCII value, not a string.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     toupper


     TONE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     tone(int <frequency>, int <length>);
     Telix v4.25 - SALT Programming                Built-in Functions    86



     ■  Description

     The tone function makes Telix emit a sound of <frequency> for a period
     of time represented by length (in hundredths of a second).

     ■  Return Value

     None.

     ■  See Also

     alarm
     _sound_on

     ■  Example

     tone(659, 14);


     TOUPPER
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     tolower(int <chr>);

     ■  Description

     If the character <chr> is an lowercase character, the toupper function
     returns the uppercase equivalent. Otherwise <chr> is returned un-
     changed. Note that <chr> is an ASCII value, not a string.

     ■  Return Value

     An integer value as described above.

     ■  See Also

     tolower


     TRACK - TRACK_HIT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     track(str <trackstr>, int <mode>);

     track_addchr(int <chr>);

     track_free(int <handle>);

     track_hit(int <handle>);
     Telix v4.25 - SALT Programming                Built-in Functions    87



     ■  Description

     The track and related functions are used to keep track of and wait for
     certain strings to come in over the comm port, similar in nature to
     the waitfor function. However the latter function can only wait for
     one specific string, while with the track functions can handle more
     strings at the same time (currently up to 16), and they may arrive in
     any order (or not arrive at all).

     The track function tells Telix to keep track of (watch for) the string
     indicated by <trackstr> to come in over the comm port. If <mode> is 0,
     case is significant, if <mode> is 1, case is not significant. The for-
     mer is faster and should be used when the many strings are being
     watched for. Track returns an integer value called a 'track handle'
     which is later used with the track_hit function to check if this
     string came in.

     When track is called, Telix doesn't loop endlessly waiting for the
     string to come in, but instead returns back to the script. As char-
     acters come in, Telix checks to see if any of the strings to be
     tracked have been matched, and marks those that have. A script can at
     any time call the track_hit function to see if the string represented
     by <handle> was received. If track_hit returns a non-zero (TRUE)
     value, then that string was received, otherwise it wasn't. If <handle>
     is 0, then track_hit will return the lowest numbered handle of any
     strings that came in, or 0 if none did. The marker on a handle is
     cleared once track_hit has indicated that the appropriate string was
     received.

     While a script is executing, Telix is not in terminal mode, and there-
     fore does not have access to incoming characters, to scan for matching
     strings. Therefore, the terminal function must periodically be called
     to allow Telix to get a look at incoming characters. This function is
     described in the appropriate place in this manual. Alternately, if a
     script must process these characters itself (with a function like
     cgetc), and therefore can not call the terminal function, they must
     still be passed by the track routines for string matching to work. The
     track_addchr function is used for this. When it is called, Telix
     treats the character represented by <chr> as if it had been received
     from the terminal handler, and uses it to scan for matching strings.

     The track_free function is used to tell Telix to stop tracking a cer-
     tain string. <handle> is a track handle returned by a previous call to
     the track function. It is very important that when a certain string no
     longer needs to be tracked, track_free is called, as tracking a large
     number of strings can slow down Telix execution. If <handle> is 0,
     Telix will stop tracking all strings.

     ■  Return Value

     track_addchr and track_free do not return a value. The other functions
     return integer values as described above.

     ■  See Also

     waitfor
     Telix v4.25 - SALT Programming                Built-in Functions    88



     ■  Example

     // Log-on to a BBS, answering two prompts in any order.
     // This will wait forever, so for actual use would have
     // to be changed a bit. See sample scripts for examples.

     int stat, t1, t2;
     t1 = track("Name? ", 0);
     t2 = track("Password? ", 0);

     while (1)         // loop as long as needed
      {
       terminal();     // call terminal function to allow Telix
                       // to look at incoming characters for
                       // matches and let Telix process user
                       // keystrokes
       stat = track_hit(0);       // see if any matches
       if (stat == t1)            // name prompt
         cputs("Joe Smith^M");    // send name and continue looping
       if (stat == t2)            // password prompt
        {
         cputs("mypass^M");       // send password
         break;                   //   and get out of loop
        }
      }

     track_free(t1);              // free track handles
     track_free(t2);


     TRANSTAB
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     transtab(str <filename>, int <table>);

     ■  Description

     The transtab function is used to load or clear the incoming or out-
     going character translation table. <table> stands for the translate
     table to manipulate, with 0 being the incoming, and 1 being the out-
     going.

     If <filename> is empty (""), Telix will prompt for the name of a
     translate table to load into memory.

     If <filename> is a valid name for a Telix translate table (saved from
     the translate table menu in Telix), it is loaded into memory.

     If <filename> is "*CLEAR*", the current translate table in memory is
     cleared, and Telix will no longer translate incoming characters.

     ■  Return Value

     A value of -1 is returned if there is a problem loading the indicated
     translate table, otherwise a non-zero (TRUE) value is returned.
     Telix v4.25 - SALT Programming                Built-in Functions    89



     ■  Example

     transtab("TELIX.XLT", 0);


     UNLOAD_SCR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     unload_scr(str <filename>);

     ■  Description

     The load_scr function can be used by a script file to load another
     script into memory ahead of time (before it is run). The unload_scr
     function should then be used to unload or take out this script when it
     is no longer needed. <filename> is the name of the script file to un-
     load, and if no extension is given, ".SLC" is assumed. Note that a
     script that is currently executing or that is nested (has called the
     current script) must not be unloaded, since Telix is still executing
     it or will return to it eventually!

     ■  Return Value

     If there is a problem unloading the script file, a value of -1 is re-
     turned. Otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     load_scr, is_loaded

     ■  Example

     int stat;
     stat = load_scr("TEST");     // load TEST.SLC
         ...                      // do other things
     unload_scr("TEST");          // take TEST.SLC out of memory


     UPDATE_TERM;
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     update_term();

     ■  Description

     The update_term function is called to make sure Telix updates certain
     things relating to the video and terminal page. For example, changes
     made to the _back_color and _fore_color system variables will not take
     effect until this function is called. As well Telix may sometimes take
     up to 15 seconds to update the status bar (and in some cases while
     scripts are running, won't update it at all). Calling this function
     ensures that the status bar is updated.
     Telix v4.25 - SALT Programming                Built-in Functions    90



     ■  Return Value

     None.

     ■  Example

     int temp;               // reverse current terminal colors
     temp = back_color;
     back_color = fore_color;
     fore_color = temp;
     update_term();


     USAGELOG
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     usagelog(str <filename>);

     ■  Description

     The usagelog function is used to manipulate the Telix usage log fa-
     cility.

     If <filename> is an empty string (""), Telix will ask for the filename
     to open the usage log to, as if the user had pressed Alt-U in terminal
     mode.

     If <filename> contains a valid filename, the usage log is opened to
     that file. The standard usage log is usually called "TELIX.USE".

     If <filename> is "*CLOSE*", and the usage log is currently open, it is
     closed.

     ■  Return Value

     A value of -1 is returned if there is a problem performing the indi-
     cated operation, otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     ustamp, usage_stat
     _usage_fname

     ■  Example

     usagelog("TELIX.USE");


     USAGE_STAT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     usage_stat();
     Telix v4.25 - SALT Programming                Built-in Functions    91



     ■  Description

     The usage_stat function returns an integer value representing the cur-
     rent status of the Usage Log. If the Usage Log is currently open, a
     non-zero (TRUE) value is returned, otherwise a value of zero (FALSE)
     is returned.

     ■  Return Value

     An integer values as described above.

     ■  See Also

     usagelog, capture_stat


     USTAMP
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     ustamp(str <text>, int <new_entry>, int <add_nl>);

     ■  Description

     The ustamp function is used to place (stamp) text into the Telix usage
     log. If the usage log is currently not open, this function call is
     simply ignored. <text> is the entry that should be placed into the us-
     age log. If <new_entry> contains a non-zero (TRUE) value, the current
     date/time is placed ahead of the text, otherwise it is assumed that
     this is a continuation of a previous entry and no date/time is added.
     If <add_nl> (add new line) is a non-zero (TRUE) value, a Carriage Re-
     turn and Line Feed character are added after the entry. This is usu-
     ally the case unless something else must be added on the same line.

     ■  Return Value

     A value of -1 is returned if there is a problem writing to the usage
     log, otherwise a non-zero (TRUE) value is returned.

     ■  See Also

     usagelog

     ■  Example

     ustamp("Calling user subroutine... ", 1, 0);
     if (user_sub == -1)
      ustamp("Failed!, 0, 1);
     else
      ustamp("Successful", 0, 1);
     Telix v4.25 - SALT Programming                Built-in Functions    92



     VGETCHR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vgetchr();

     ■  Description

     The vgetchr function is used to read the character (including color
     information) at the current cursor position on the video screen. The
     return value contains the character in the first (low) byte, and the
     color of the character in the higher (second) byte. Each component may
     be extracted using the & and / operators as shown in the example be-
     low. Basically, if 'c' is the returned character/color value, the
     character alone may be obtained by using the expression

          (c & 255)

     while the color value is

          (c / 256)

     ■  Return Value

     An integer value as described above.

     ■  See Also

     vgetchrs, vgetchrsa, vputchr

     ■  Example

     int chr;
     chr = vgetchr();      // Get char/color at current cursor position
     printsc("The character was ");
     printc(chr & 255);    // get character by masking out color byte
     printsc(" with a color value of ");
     printn(chr / 256);     // shift color byte


     VGETCHRS, VGETCHRSA
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vgetchrs(int <x>, int <y>, str <buf>, int <pos>, int <num>);

     vgetchrsa(int <x>, int <y>, str <buf>, int <pos>, int <num>);

     ■  Description

     The vgetchrs and vgetchrsa functions are used to read multiple char-
     acters starting from a spot on the screen into a specified variable.
     The first function saves only the characters (a sequence of bytes)
     while the second saves both the characters and color attributes (a se-
     ries of double bytes). <x>,<y> is the spot on the screen to start
     Telix v4.25 - SALT Programming                Built-in Functions    93



     reading characters. <buf> is the string variable to put characters
     into, starting at an offset of <pos> in the variable. Note that each
     character read in with vgetchrsa will take up two bytes in the string
     variable, since the color attribute is also saved. Note also that
     these functions do not put a 0 (NULL, or end of string character) at
     the end of the sequence of characters they grab. If the characters re-
     turned by vgetchrs are to be manipulated as a string a 0 must be added
     at the end with the setchr function.

     ■  Return Value

     None.

     ■  See Also

     vgetchr, vputchrs, vputchrsa

     ■  Example

     // copy 20 characters starting from 10,10 on the screen to 20,20
     // Don't keep color attributes
     str buffer[20];
     vgetchrs(10, 10, buffer, 0, 20);
     vputchrs(20, 20, buffer, 0, 20);

     // copy a 20 by 10 grid of characters with a left hand corner of
     // 10,5 to 40,7, and keep color attributes
     str buffer[400];   // 20 wide * 10 tall * 2 bytes per character
     int y;
     for (y = 5; y < 15; y = y+1)         // read chars in a loop
      vgetchrsa(10, y, buffer, 2 * 20 * (y - 5), 20);
     for (y = 7; y < 17; y = y+1)         // now write them in a loop
      vputchrs(10, y, buffer, 2 * 20 * (y - 7), 20);


     VPUTCHR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vputchr(int <chr>);

     ■  Description

     The vputchr function is used to place a character on the screen at the
     current cursor position, specifying color information at the same
     time. <chr> is the character to place on the screen. the low byte con-
     tains the ASCII value of the character, while the second byte contains
     the color value. In general, a if 'c' is the character, and 'color' is
     the color to use, the proper value is obtained with the expression

          (c + color * 256)

     ■  Return Value

     None.
     Telix v4.25 - SALT Programming                Built-in Functions    94



     ■  See Also

     vgetchr

     ■  Example

     // Place an inverse 'X' in the left top corner of the screen
     gotoxy(0, 0);
     vputchr('X' + 112 * 256);


     VPUTCHRS, VPUTCHRSA
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vputchrs(int <x>, int <y>, str <buf>, int <pos>, int <num>, int
     <attr>);

     vputchrsa(int <x>, int <y>, str <buf>, int <pos>, int <num>);

     ■  Description

     The vputchrs and vputchrsa functions are used to write multiple char-
     acters from a spot in a string variable onto the screen at a certain
     position. The first function assumes that the string contains charac-
     ters only, and writes them to the screen using a color attribute of
     <attr>, as described in Appendix C. The second function assumes that
     each character in the string is immediately followed by a color value
     (a series of double bytes). <x>,<y> is the spot on the screen to start
     writing characters. <buf> is the string variable to read characters
     from, starting at an offset of <pos> in the variable. Note that each
     character written with vputchrsa will take up two bytes in the string
     variable, since the color attribute is also there, so the offset
     should reflect this.

     ■  Return Value

     None.

     ■  See Also

     vputchr, vgetchrs, vgetchrsa

     ■  Example

     // copy 20 characters starting from 10,10 on the screen to 20,20
     // Don't keep color attributes
     str buffer[20];
     vgetchrs(10, 10, buffer, 0, 20);
     vputchrs(20, 20, buffer, 0, 20);

     // copy a 20 by 10 grid of characters with a left hand corner of
     // 10,5 to 40,7, and keep color attributes
     str buffer[400];   // 20 wide * 10 tall * 2 bytes per character
     int y;
     for (y = 5; y < 15; y = y+1)         // read chars in a loop
     Telix v4.25 - SALT Programming                Built-in Functions    95



      vgetchrsa(10, y, buffer, 2 * 20 * (y - 5), 20);
     for (y = 7; y < 17; y = y+1)         // now write them in a loop
      vputchrs(10, y, buffer, 2 * 20 * (y - 7), 20);


     VRSTRAREA
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vrstrarea(int <vhandle>);

     ■  Description

     The vrstrarea function is used to restore a previously saved portion
     of the screen. <vhandle> is the video information handle returned by a
     previous call to vsavearea, which saved the screen area.

     Note, it is very important that <vhandle> is a valid handle, returned
     by a previous call to vsavearea, or unpredictable results will happen.

     ■  Return Value

     None.

     ■  See Also

     vsavearea


     VSAVEAREA
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     vsavearea(int <x1>, int <y1>, int <x2>, int <y2>);

     ■  Description

     The vsavearea function is used to save a rectangular portion of the
     screen (to be later restored). <x1>,<y1> is the upper left corner of
     the area to save, while <x2>,<y2> is the lower right corner. Charac-
     ters (and their colors) currently on the screen in this rectangle are
     saved in a buffer, and a 'handle' is returned, which must be stored
     and used in the subsequent call to vrstrarea to restore the saved
     area. If not enough memory exists to save the video bytes, a value of
     -1 is returned instead.

     Note that Telix has only a limited amount of space for allocating to
     video buffers of this type. At one time, only about as much area as
     would amount to a full screen should be saved with calls to this func-
     tion.

     It is also very important that for every call to this function, there
     is a subsequent call to vrstrarea. If this is not done, memory will
     become used up until no more is left.
     Telix v4.25 - SALT Programming                Built-in Functions    96



     ■  Return Value

     An integer value representing a 'handle' to the saved area.

     ■  See Also

     vrstrarea

     ■  Example

     int vhandle;
     vhandle = vsavearea(0, 0, 79, 24);  // save the current screen
     myfunc();                           // call a function
                                         // which modifies screen
     vrstrarea(vhandle);                 // restore previous screen

     WAITFOR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     waitfor(str <waitstr>, int <timeout>);

     ■  Description

     The waitfor function is used to wait for the given string to come in
     over the serial port. Timeout is the maximum amount of time, in sec-
     onds, to wait for the string. Case is not significant, and the string
     must be no longer than 40 characters.

     ■  Return Value

     A non-zero (TRUE) value is returned if the string is received from the
     serial port in the given time, otherwise a zero (FALSE) value is re-
     turned.

     ■  See Also

     track

     ■  Example

     if (waitfor("name?", 180))
      prints("The string 'name?' came in from the comm port.");
     else
      {
       prints("The string 'name?' did not come in from the");
       prints("comm port in 3 minutes!");
      }
     Telix v4.25 - SALT Programming                  System Variables    97



     5.  SYSTEM VARIABLES

     Telix has quite a large number predefined built-in variables. They are
     called System Variables and are used to store many preferences. There
     are both string and numeric system variables, and they are accessed
     just as you would access any other variable. To help distinguish them
     apart from normal variables, and to avoid confusion, they all start
     with an underscore (_) character.

     The following pages contain descriptions of all the system variables.
     For each variable, a summary and a description are given. An example
     of actual usage of the variable will often be given.

     The variables are listed in alphabetical order. So that you may find
     related variables (and built-in functions), most variable descriptions
     have a 'See also' section, which lists related variables and func-
     tions.
     Telix v4.25 - SALT Programming                  System Variables    98



     _ADD_LF
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _add_lf;

     ■  Description

     If the _add_lf system variable is set to non-zero (TRUE), a Line Feed
     character is automatically added after every Carriage Return character
     that comes in.


     _ALARM_ON
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _alarm_on;

     ■  Description

     If the _alarm_on system variable is set to non-zero (TRUE), alarms are
     enabled in Telix. Note that if the _sound_off system variable is set
     to zero (FALSE), alarms will not be heard no matter what the state of
     this variable.

     ■  See Also

     alarm
     _sound_on


     _ANSWERBACK_STR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _answerback_str[19];

     ■  Description

     The _answerback_str system variable holds the string which Telix will
     send when a Ctrl-E (ENQ) character is received while in terminal mode.
     If this string is empty, nothing is sent. Note that if Compuserve B
     transfers are enabled, the answerback string will not be sent, since
     CIS B uses the Ctrl-E as part of the transfer process. Maximum length
     is 19 characters.


     _ASC_RCRTRANS - _ASC_STRIPH
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _asc_rcrtrans;
     Telix v4.25 - SALT Programming                  System Variables    99



     int _asc_remabort;

     int _asc_rlftrans;

     int _asc_scpacing;

     int _asc_scrtrans;

     int _asc_secho;

     int _asc_sexpand;

     int _asc_slftrans;

     int _asc_slpacing;

     int _asc_spacechr;

     int _asc_striph;

     ■  Description

     _asc_rcrtrans determines what Telix does with Carriage Return char-
     acters during ASCII receives. 0 = do nothing; 1 = strip; 2 = add Line
     Feed afterwards.

     _asc_remabort is the character which when received from the remote
     side during an ASCII transfer is a signal to abort the transfer.

     _asc_rlftrans determines what Telix does with Line Feed characters
     during ASCII receives. 0 = do nothing; 1 = strip; 2 = add Carriage Re-
     turn before.

     _asc_scpacing is the time in milliseconds which Telix should wait be-
     fore transmitting each character during ASCII sends.

     _asc_scrtrans determines what Telix does with Carriage Return char-
     acters during ASCII sends. 0 = do nothing; 1 = strip; 2 = add Line
     Feed afterwards.

     If _asc_secho is set to non-zero (TRUE), Telix will echo each char-
     acter during ASCII sends.

     If _asc_sexpand is set to non-zero (TRUE), Telix will expand blank
     lines to a space character, during ASCII sends.

     _asc_slftran determines what Telix does with Line Feed characters dur-
     ing ASCII sends. 0 = do nothing; 1 = strip; 2 = add Carriage Return
     before.

     _asc_slpacing is the time in tenths of seconds which Telix should wait
     before transmitting each line during ASCII sends.

     _asc_spacechr is the character which Telix should wait for during
     ASCII sends, before transmitting each line (0 means no wait).
     Telix v4.25 - SALT Programming                 System Variables    100



     If _asc_striph is set to non-zero (TRUE), Telix will strip the high
     (most significant) bit of each character in an ASCII transfer.


     _AUTO_ANS_STR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _auto_ans_str[48];

     ■  Description

     The _auto_ans_str system variable holds the string that should be sent
     to the modem to make it automatically answer the phone when it rings.
     This string is used by the Host Mode script, among others. The string
     will possibly include translation characters as described in the Telix
     manual in the section by that name, and should be sent to the modem
     with the cputs_tr function. Maximum length is 49 characters.

     ■  See Also

     _mdm_init_str


     _BACK_COLOR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _back_color;

     ■  Description

     The _back_color system variable contains the background color which
     should be used for text in terminal mode. Allowable values are from 0
     - 15. Note that changes to this variable may not be reflected until
     the screen is cleared.

     ■  See Also

     _fore_color


     _CAPTURE_FNAME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _capture_fname[64];

     ■  Description

     The _capture_fname system variable holds the default capture file
     filename. The maximum length is 64 characters.
     Telix v4.25 - SALT Programming                 System Variables    101



     ■  See Also

     capture
     _usage_fname


     _CISB_AUTO
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _cisb_auto;

     ■  Description

     The _cisb_auto system variable controls whether Compuserve Quick B
     auto file transfer are allowed. If this variable is set to a 0 (FALSE)
     value, requests by the remote (Compuserve) to transfer files using the
     Quick B protocol will be ignored.

     ■  See Also

     _zmod_auto


     _CONNECT_STR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _connect_str[19];

     ■  Description

     The _connect_str system variable holds the string which Telix should
     scan for when dialing, and should take to mean that a connection has
     been established. For Hayes type modems it is usually set to
     "CONNECT". Maximum length is 19 characters.

     ■  See Also

     _no_connect1 - _no_connect4


     _DATE_FORMAT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _date_format;

     ■  Description

     The contents of the _date_format system variable determines what for-
     mat Telix uses for date strings it produces, as follows:
     Telix v4.25 - SALT Programming                 System Variables    102



                    0    mm/dd/yy
                    1    dd/mm/yy
                    2    yy/mm/dd

     ■  See Also

     _time_format
     date


     _DEST_BS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _dest_bs;

     ■  Description

     The _dest_bs system variable controls whether a backspace character
     received by Telix in Terminal Mode erases the character to the left of
     the cursor, or just moves the cursor on top of it on top of it without
     erasing it. If this variable is 0 (FALSE), Telix will treat the
     backspace as non-destructive, and destructive otherwise.

     ■  See Also

     _swap_bs


     _DIAL_PAUSE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _dial_pause;

     ■  Description

     The _dial_pause system variable holds (in seconds) the amount of time
     to wait between the end of one dialing attempt and the beginning of
     another. Most modems don't need more than a 1 second pause.


     _DIAL_TIME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _dial_time;

     ■  Description

     The _dial_time system variable holds the amount of time Telix should
     wait for a connection when dialing, in seconds (e.g. 30).
     Telix v4.25 - SALT Programming                 System Variables    103



     ■  See Also

     _dial_pause


     _DIALPOST
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _dialpost[19];

     ■  Description

     The _dialpost system variable holds the string (the dialing postfix)
     which should be sent to the modem after the number, when dialing. For
     Hayes type modems, it is usually just a Carriage Return. Maximum
     length is 19 characters. This string will possibly include some trans-
     lation characters, as described in the Telix manual, and should be
     sent to the modem with the cputs_tr function.

     ■  See Also

     _dialpref, _dialpref2, _dialpref3, _redial_stop


     _DIALPREF
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _dialpref[19];

     str _dialpref2[19];

     str _dialpref3[19];

     ■  Description

     The _dialpref system variable holds the string which should be sent to
     the modem before the number, when dialing. For Hayes type modems, it
     is usually set to "ATDT". Maximum length is 19 characters. This string
     will possibly include translation characters, as described in the
     Telix manual, and should be sent to the modem with the cputs_tr func-
     tion.

     The _dialpref2 and _dialpref3 variables are the other two dialing pre-
     fixes that may be defined in Telix.

     ■  See Also

     _dialpost, _redial_stop
     Telix v4.25 - SALT Programming                 System Variables    104



     _DIR_PROG
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _dir_prog[15];

     ■  Description

     The _dir_prog system variable holds the name of the disk directory
     program that should be run when the user selects the 'Files directory'
     option of the DOS Functions menu. If this variable is left empty (""),
     the DOS 'dir' command is used. Maximum length is 15 characters.


     _DISP_FREE
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _disp_free

     ■  Description

     If the _disp_free system variable is set to non-zero (TRUE), Telix
     will display the amount of free space available on the drive when the
     user presses Alt-R to download a file.


     _DOWN_DIR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _down_dir[64];

     ■  Description

     The _down_dir system variable holds the default download directory
     name. When a file is downloaded (received), if the user specifies a
     drive and/or directory in the name, the file is put there. However, if
     only a name is specified, the file is placed in the directory in-
     dicated by _down_dir. The maximum length is 64 characters, and this
     string should end with the backslash character, '\'.

     ■  See Also

     _up_dir, receive


     _EDITOR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _editor[64];
     Telix v4.25 - SALT Programming                 System Variables    105



     ■  Description

     The _editor system variable holds the name of the editor that should
     be run when the user presses Alt-A. The editor should either be on the
     DOS Path, in which case only the name needs to be given, or else the
     entire pathname (drive, directory, name) must be given. The maximum
     length is 64 characters. If a batch file is to be run the .BAT exten-
     sion must be given.


     _ENTRY_ENUM
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _entry_enum;

     ■  Description

     The _entry_enum variable is set by the dialing routines. When a con-
     nection is established while dialing, the entry number of the dialing
     directory entry connected to is stored here. If a manual number is
     connected to, the value 0 is stored here.

     ■  See Also

     _entry_name
     dial, redial


     _ENTRY_NAME - _ENTRY_PASS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _entry_name[29];

     str _entry_num[17];

     str _entry_pass[14];

     ■  Description

     The _entry_name system variable is set by the dialing routines. When a
     connection has been established the name portion of the dialing direc-
     tory entry connected to is copied here, for use by script files. The
     maximum length is 29 characters.

     The _entry_num system variable is set in the same way, and holds the
     phone number of the entry connected to. The maximum length is 17 char-
     acters.

     The entry_pass system variable is set in the same way, and holds the
     password from the entry connected to. This may be used to perform lo-
     gons. The maximum length is 14 characters.
     Telix v4.25 - SALT Programming                 System Variables    106



     ■  See Also

     _entry_enum
     dial, redial


     _EXT_FILESPEC;
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _ext_filespec[64];

     ■  Description

     This variable is for use by scripts implementing external protocols.
     When an external protocol has been defined as called by a script, this
     variable is first loaded with the filespec (file specification) typed
     by the user at the transfer menu. The appropriate script is then run.
     The script can for example pass this name to a program which imple-
     ments the actual protocol. Note that some file transfer protocols do
     not require the user to supply the name on downloads, in which case
     this variable is left empty.


     _FORE_COLOR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _fore_color;

     ■  Description

     The _fore_color system variable contains the foreground color which
     should be used for text in terminal mode. Allowable values are from 0
     - 15. Note that changes to this variable may not be reflected until
     the screen is cleared.

     ■  See Also

     _back_color


     _IMAGE_FILE;
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _image_file[64];

     ■  Description

     The _image_file system variable holds the full name of the file that
     screen images are saved to when the user presses Alt-I while in ter-
     minal mode. If this file already exists, data is appended to it.
     Telix v4.25 - SALT Programming                 System Variables    107



     _LOCAL_ECHO
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _local_echo;

     ■  Description

     The _local_echo system variable controls whether or not characters
     typed in terminal mode are echoed on the screen. If _local_echo is set
     to non-zero (TRUE), characters are echoed, otherwise they are not.


     _MDM_HANG_STR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _mdm_hang_str[19];

     ■  Description

     The _mdm_hang_str system variable holds the string that should be sent
     to the modem to hang it up when the user presses Alt-H. Note that this
     string will only be sent to the modem if Telix can't first hang-up the
     modem by turning off a signal on the serial port called the DTR line.
     This string may contain translation characters as defined in the Telix
     manual, and should be sent to the modem with the cputs_tr function.
     Maximum length is 19 characters.

     ■  See Also

     _mdm_init_str, _auto_ans_str


     _MDM_INIT_STR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _mdm_init_str[49];

     ■  Description

     The _mdm_init system variable holds the string that should be sent to
     the modem when Telix starts-up. It is usually used to make sure cer-
     tain settings in the modem are right. This string may contain transla-
     tion characters as defined in the Telix manual, and should be sent to
     the modem with the cputs_tr function. Maximum length is 49 characters.

     ■  See Also

     _auto_ans_str, _mdm_hang_str
     Telix v4.25 - SALT Programming                 System Variables    108



     _NO_CONNECT1 - _NO_CONNECT4
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _no_connect1[19];

     str _no_connect2[19];

     str _no_connect3[19];

     str _no_connect4[19];

     ■  Description

     These system variables contain the strings that Telix should scan for
     when dialing, and take to mean that a connection has not been estab-
     lished (i.e., the number was busy or there was no answer). The maximum
     length for each string is 19 characters.

     ■  See Also

     _connect_str


     _QDBAR_ON
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _qdbar_on;

     ■  Description

     If the _qdbar_on system variable is set to non-zero (TRUE), the quick
     dialing bar is shown first when Alt-D is pressed; otherwise the user
     is taken directly to the dialing directory screen.


     _REDIAL_STOP
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _redial_stop[19];

     ■  Description

     The _redial_stop system variable holds the string that should be sent
     to the modem to stop a dialing attempt. It usually just holds a Car-
     riage Return character. This string may contain translation characters
     as described in the Telix manual, and should be sent to the modem with
     the cputs_tr function. Maximum length is 19 characters.

     ■  See Also

     _dialpref, _dialpref2, _dialpref3, _dialpost
     Telix v4.25 - SALT Programming                 System Variables    109



     _SCR_CHK_KEY
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _scr_chk_key;

     ■  Description

     Between every command while executing a script file, Telix checks the
     keyboard buffer to see if the user has requested an abort. This how-
     ever gets in the way of the inkey function among others. As well, it
     is sometimes necessary to stop the user from being able to abort the
     script. If _scr_chk_key is set to zero (FALSE), Telix will no longer
     check for user aborts requests during script execution. Setting it
     back to non-zero (TRUE) will turn the checks back on. When modifying
     this variable in a script file, it is a good idea to save the old
     state in a scratch variable and restore it when done.

     ■  See Also

     inkey


     _SCRIPT_DIR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _script_dir[64];

     ■  Description

     The _script_dir system variable holds the full path of the directory
     where Telix should look for compiled script files when a script is se-
     lected to be run. When a script is selected to be run, Telix uses this
     procedure: if the name includes the drive and/or directory, only that
     path is searched. If the name includes only the filename, the current
     directory is first searched for the script file, and then the direc-
     tory pointed to by the _script_dir variable. This string should end in
     the slash character, '\'. The maximum allowed length is 64 characters.

     ■  See Also

     _telix_dir, _up_dir, _down_dir


     _SOUND_ON
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _sound_on;
     Telix v4.25 - SALT Programming                 System Variables    110



     ■  Description

     If the _sound_on system variable is set to non-zero (TRUE) sound is
     enabled in Telix, otherwise all sound is shut off.

     ■  See Also

     _alarm_on


     _STRIP_HIGH
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _strip_high;

     ■  Description

     The _strip_high system variable controls what Telix does with the high
     (most significant) bit of incoming characters while in terminal mode.
     If this variable is set to s non-zero (TRUE) value, Telix will strip
     the high bit of incoming characters.


     _SWAP_BS
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _swap_bs;

     ■  Description

     The _swap_bs system variable controls what Telix sends when the
     Backspace key is pressed. If this variable is 0, Telix will send a
     Backspace character when Backspace is pressed, and a DEL character
     when Ctrl-Backspace is pressed. If this variable is set to 1, Telix
     will reverse these codes.

     ■  See Also

     _dest_bs


     _TELIX_DIR;
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _telix_dir[64];

     ■  Description

     The _telix_dir system variable holds the full path to reach the Telix
     program's base directory (e.g. 'C:\TELIX\'). Changing this variable is
     not recommended, as if a wrong value is used, Telix will probably not
     Telix v4.25 - SALT Programming                 System Variables    111



     be able to find many needed files. The maximum length is 64 charac-
     ters.

     If this variable is changed, it is imperative that a backslash char-
     acter, '\', is found at the end. Telix builds paths to many files by
     appending certain names to this string. If the slash is missing, it
     will cause many problems.

     ■  See Also

     _script_dir, _up_dir, _down_dir


     _TIME_FORMAT
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _time_format;

     ■  Description

     The _time_format system variable determines what format Telix uses for
     time strings it produces. If _time_format is 0, Telix will use a 12
     hour format, otherwise a 24 hour format will be used.

     ■  See Also

     _date_format
     time


     _UP_DIR
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _up_dir[64];

     ■  Description

     The _up_dir system variable holds the default upload directory name.
     When a file is to be ed (sent), if the user specifies a drive and/or
     directory in the name, the file is taken from there. However, if only
     a name is specified, the file is searched for in the directory in-
     dicated by _up_dir. This variable should end with a slash character,
     '\'. The maximum length is 64 characters.

     ■  See Also

     _down_dir
     send
     Telix v4.25 - SALT Programming                 System Variables    112



     _USAGE_FNAME
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     str _usage_fname[64];

     ■  Description

     The _usage_fname system variable holds the default Usage Log filename.
     The maximum length is 64 characters.

     ■  See Also

     _capture_fname
     usagelog


     _ZMOD_AUTO
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _zmod_auto;

     ■  Description

     The _zmod_auto system variable controls whether or not Zmodem auto-
     downloads are allowed. If Telix is in terminal mode and receives an
     auto download request Telix will ignore it if this variable is set to
     a 0 (FALSE) value (however, the user can still receive the file by
     manually selecting the Zmodem protocol from the Alt-R menu).

     ■  See Also

     _cisb_auto


     _ZMOD_RCRASH
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _zmod_rcrash;

     ■  Description

     The _zmod_rcrash system variable controls whether the Zmodem receive
     Crash Recovery (resume) option is on. If this variable is set to a
     non-zero (TRUE) value, Telix will try to resume aborted transfers dur-
     ing a Zmodem download.

     ■  See Also

     _zmod_scrash
     Telix v4.25 - SALT Programming                 System Variables    113



     _ZMOD_SCRASH
     ──────────────────────────────────────────────────────────────────────

     ■  Summary

     int _zmod_scrash;

     ■  Description

     The _zmod_scrash system variable controls whether the Zmodem send
     Crash Recovery (resume) option is on. If this variable is set to a
     non-zero (TRUE) value, Telix will try to tell the other side to resume
     aborted transfers during a Zmodem upload.

     ■  See Also

     _zmod_rcrash
     Telix v4.25                                          Appendix A    114



     6.  APPENDIX A - ASCII CHARACTER SET

     The ASCII character set consists if 128 characters, with each char-
     acter having an ASCII value, in the range of 0 to 127. The IBM PC uses
     the IBM Extended ASCII set, which adds a further 128 values, to pro-
     vide extra symbols. The following table lists the regular ASCII char-
     acter set. The first column contains the ASCII control characters,
     which can not normally be printed, and are given by name.

     Dec Hex Ctrl Name    Dec Hex Chr   Dec Hex Chr     Dec Hex Chr
       0  00  ^@  NUL      32  20         64  40  @      96  60  `
       1  01  ^A  SOH      33  21  !      65  41  A      97  61  a
       2  02  ^B  STX      34  22  "      66  42  B      98  62  b
       3  03  ^C  ETX      35  23  #      67  43  C      99  63  c
       4  04  ^D  EOT      36  24  $      68  44  D     100  64  d
       5  05  ^E  ENQ      37  25  %      69  45  E     101  65  e
       6  06  ^F  ACK      38  26  &      70  46  F     102  66  f
       7  07  ^G  BEL      39  27  '      71  47  G     103  67  g
       8  08  ^H  BS       40  28  (      72  48  H     104  68  h
       9  09  ^I  HT       41  29  )      73  49  I     105  69  i
      10  0a  ^J  LF       42  2a  *      74  4a  J     106  6a  j
      11  0b  ^K  VT       43  2b  +      75  4b  K     107  6b  k
      12  0c  ^L  FF       44  2c  ,      76  4c  L     108  6c  l
      13  0d  ^M  CR       45  2d  -      77  4d  M     109  6d  m
      14  0e  ^N  SO       46  2e  .      78  4e  N     110  6e  n
      15  0f  ^O  SI       47  2f  /      79  4f  O     111  6f  o
      16  10  ^P  DLE      48  30  0      80  50  P     112  70  p
      17  11  ^Q  DC1      49  31  1      81  51  Q     113  71  q
      18  12  ^R  DC2      50  32  2      82  52  R     114  72  r
      19  13  ^S  DC3      51  33  3      83  53  S     115  73  s
      20  14  ^T  DC4      52  34  4      84  54  T     116  74  t
      21  15  ^U  NAK      53  35  5      85  55  U     117  75  u
      22  16  ^V  SYN      54  36  6      86  56  V     118  76  v
      23  17  ^W  ETB      55  37  7      87  57  W     119  77  w
      24  18  ^X  CAN      56  38  8      88  58  X     120  78  x
      25  19  ^Y  EM       57  39  9      89  59  Y     121  79  y
      26  1a  ^Z  SUB      58  3a  :      90  5a  Z     122  7a  z
      27  1b  ^[  ESC      59  3b  ;      91  5b  [     123  7b  {
      28  1c  ^\  FS       60  3c  <      92  5c  \     124  7c  |
      29  1d  ^]  GS       61  3d  =      93  5d  ]     125  7d  }
      30  1e  ^^  RS       62  3e  >      94  5e  ^     126  7e  ~
      31  1f  ^_  US       63  3f  ?      95  5f  _     127  7f DEL
     Telix v4.25                                          Appendix B    115



     7.  APPENDIX B - EXTENDED KEY SCAN CODES

     The following chart lists keyboard scan codes for special non-ASCII
     keys, as returned by inkey and inkeyw, and used by the keyget, keyset,
     keyload, and keysave SALT functions. Normal keys which are within the
     ASCII set are listed in the preceding appendix.


     Key      Normal        w / Ctrl        w / Alt       w / Shift
            Dec     Hex    Dec     Hex    Dec     Hex    Dec     Hex
     ---------------------------------------------------------------
     F1     15104  3b00    24064  5e00    26624  6800    21504  5400
     F2     15360  3c00    24320  5f00    26880  6900    21760  5500
     F3     15616  3d00    24576  6000    27136  6a00    22016  5600
     F4     15872  3e00    24832  6100    27392  6b00    22272  5700
     F5     16128  3f00    25088  6200    27648  6c00    22528  5800
     F6     16384  4000    25344  6300    27904  6d00    22784  5900
     F7     16640  4100    25600  6400    28160  6e00    23040  5a00
     F8     16896  4200    25856  6500    28416  6f00    23296  5b00
     F9     17152  4300    26112  6600    28672  7000    23552  5c00
     F10    17408  4400    26368  6700    28928  7100    23808  5d00
     ---------------------------------------------------------------
     1                                    30720  7800
     2                                    30976  7900
     3                                    31232  7a00
     4                                    31488  7b00
     5                                    31744  7c00
     6                                    32000  7d00
     7                                    32256  7e00
     8                                    32512  7f00
     9                                    32768  8000
     0                                    33024  8100
     ---------------------------------------------------------------
     Up     18432  4800
     Down   20480  5000
     Left   19200  4b00    29440  7300
     Right  19712  4d00    29696  7400
     Home   18176  4700    30464  7700
     End    20224  4f00    29952  7500
     PgUp   18688  4900    33792  8400
     PgDn   20736  5100    30208  7600
     Ins    20992  5200
     Del    21248  5300
     ---------------------------------------------------------------
     Telix v4.25                                          Appendix C    116



     8.  APPENDIX C - COLOR VALUES

     Several SALT functions, such as pstra, use color attribute values. A
     character on the text screen has a foreground color, and a background
     color. Possible colors are numbered as follows:

                         Black          00
                         Blue           01
                         Green          02
                         Cyan           03
                         Red            04
                         Magenta        05
                         Brown          06
                         Light Grey     07
                         Dark Grey      08
                         Light Blue     09
                         Light Green    10
                         Light Cyan     11
                         Light Red      12
                         Light Magenta  13
                         Yellow         14
                         White          15

     To obtain a color attribute value for a color combination, the formula
     is

          color attribute value =

                foreground color value + (16 * background color value)

     Therefore, a Yellow character on a Blue background would have a color
     attribute value of 30 (14 + (16 * 1)).

     Telix v4.25 - SALT Programming                            Index    117


                                          _time_format.................111
                                          _up_dir......................111
     9.  INDEX                            _usage_fname.................112
                                          _zmod_auto...................112
     _add_lf.......................98     _zmod_rcrash.................112
     _alarm_on.....................98     _zmod_scrash.................113
     _answerback_str...............98     Alarm.........................22
     _asc_rcrtrans.................98     Box...........................22
     _asc_remabort.................99     Call..........................23
     _asc_rlftrans.................99     Calld.........................23
     _asc_scpacing.................99     Capture.......................24
     _asc_scrtrans.................99     Capture_stat..................25
     _asc_secho....................99     Carrier.......................25
     _asc_sexpand..................99     Cgetc.........................26
     _asc_slftrans.................99     Cgetct........................26
     _asc_slpacing.................99     Chatmode......................27
     _asc_spacechr.................99     Cinp_cnt......................27
     _asc_striph...................99     Clear_scr.....................28
     _auto_ans_str................100     Copychrs......................28
     _back_color..................100     Copystr.......................29
     _capture_fname...............100     Cputc.........................29
     _cisb_auto...................101     Cputs.........................30
     _connect_str.................101     Cputs_tr......................30
     _date_format.................101     Cursor_onoff..................31
     _dest_bs.....................102     Curtime.......................31
     _dial_pause..................102     Date..........................32
     _dial_time...................102     Delay.........................32
     _dialpost....................103     Delay_scr.....................32
     _dialpref....................103     Delchrs.......................33
     _dialpref2...................103     Dial..........................33
     _dialpref3...................103     Dos...........................34
     _dir_prog....................104     Dosfunction...................35
     _disp_free...................104     Exittelix.....................35
     _down_dir....................104     Fclearerr.....................36
     _editor......................104     Fclose........................36
     _entry_enum..................105     Fdelete.......................37
     _entry_name..................105     Feof..........................37
     _entry_num...................105     Ferror........................38
     _entry_pass..................105     Fflush........................39
     _ext_filespec................106     Fgetc.........................39
     _fore_color..................106     Fgets.........................40
     _image_file..................106     Fileattr......................40
     _local_echo..................107     Filefind......................42
     _mdm_hang_str................107     Filesize......................43
     _mdm_init_str................107     Filetime......................43
     _no_connect1.................108     Flushbuf......................45
     _no_connect2.................108     Fnstrip.......................45
     _no_connect3.................108     Fopen.........................46
     _no_connect4.................108     Fputc.........................47
     _qdbar_on....................108     Fputs.........................47
     _redial_stop.................108     Fread.........................48
     _scr_chk_key.................109     Frename.......................48
     _script_dir..................109     Fseek.........................49
     _sound_on....................109     Ftell.........................50
     _strip_high..................110     Fwrite........................50
     _swap_bs.....................110     Get_baud......................51
     _telix_dir...................110     Get_datab.....................51

     Telix v4.25 - SALT Programming                            Index    118


     Get_parity....................52     Strmaxlen.....................78
     Get_port......................52     Strpos........................78
     Get_stopb.....................53     Strposi.......................78
     Getenv........................51     Strupper......................79
     Gets..........................53     Subchr........................79
     Getsxy........................54     Subchrs.......................80
     Getx, gety....................55     Substr........................80
     Gotoxy........................55     Tday..........................81
     Hangup........................56     Terminal......................82
     Helpscreen....................56     Thour.........................81
     Inkey.........................56     Time..........................83
     Inkeyw........................56     Time_up.......................84
     Inschrs.......................57     Timer_free....................84
     Is_loaded.....................58     Timer_restart.................84
     Isalnum.......................58     Timer_start...................84
     Isalpha.......................58     Timer_total...................84
     Isascii.......................58     Tmin..........................81
     Iscntrl.......................58     Tmonth........................81
     Isdigit.......................58     Tolower.......................85
     Islower.......................58     Tone..........................85
     Isupper.......................58     Toupper.......................86
     Itos..........................59     Track.........................86
     Keyget........................59     Track_addchr..................86
     Keyload.......................60     Track_free....................86
     Keysave.......................61     Track_hit.....................86
     Keyset........................61     Transtab......................88
     Load_scr......................62     Tsec..........................81
     Loadfon.......................62     Tyear.........................81
     Newdir........................63     Unload_scr....................89
     Printc........................63     Update_term...................89
     Printer.......................64     Usage_stat....................90
     Printn........................64     Usagelog......................90
     Prints........................65     Ustamp........................91
     Printsc.......................65     Vgetchr.......................92
     Printsc_trm...................65     Vgetchrs......................92
     Pstra.........................65     Vgetchrsa.....................92
     Pstraxy.......................65     Vputchr.......................93
     Receive.......................66     Vputchrs......................94
     Redial........................67     Vputchrsa.....................94
     Run...........................68     Vrstrarea.....................95
     Scroll........................69     Vsavearea.....................95
     Send..........................69     Waitfor.......................96
     Send_brk......................70
     Set_cparams...................70
     Set_defprot...................71
     Set_port......................73
     Set_terminal..................73
     Setchr........................72
     Setchrs.......................72
     Show_directory................74
     Status_wind...................74
     Stoi..........................75
     Strcat........................75
     Strchr........................76
     Strcmpi.......................76
     Strlen........................77
     Strlower......................77