Share Gallery 1/share_gal_1.zip/share_gal_1/CO/CO018.ZIP/TLX312-4.ZIP/SALT.DOC

Text File | 1989-12-11 | 217KB | 7,304 lines

      T E L I X

      --------------------------------------------------------------------

      SALT Programming Manual














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

                              ALL RIGHTS RESERVED.



                                   Exis Inc.

                  P.O. Box 130, West Hill, ON  CANADA  M1E 4R4

                                 (416)-289-4641
                               (416)-289-4645 fax
                               (416)-439-8293 BBS

          Telix v3.12 - SALT Programming               COPYRIGHT    ii








                                COPYRIGHT NOTICE


      Telix is Copyright (c) 1986,1987,1988,1988 by Exis Inc.

      This document is Copyright (c) 1988,1989 by Exis Inc.

      No parts of Telix or this document may be copied in part or in
      whole, except as provided in the License included with Telix.





                                   Disclaimer


      Exis Inc. makes no warranty of any kind, either express or implied,
      including but not limited to implied warranties of merchantability
      and fitness for a particular purpose, with respect to this software
      and accompanying documentation.

      IN NO EVENT SHALL EXIS INC. BE LIABLE FOR ANY DAMAGES (INCLUDING
      DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF
      BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE
      USE OF OR INABILITY TO USE THIS PROGRAM, EVEN IF EXIS INC. HAS BEEN
      ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.




                                   Trademarks


      Telix and SALT are trademarks of Exis Inc.

          Telix v3.12 - SALT Programming               Contents    iii












                                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                                        6
      3.1  Variables                                             6
      3.2  Expressions and Operators                             8
      3.3  Functions                                            10
      3.4  Statements                                           11
        3.4.1  The Expression statement                         12
        3.4.2  The If statement                                 12
        3.4.3  The While statement                              14
        3.4.4  The Do...While statement                         15
        3.4.5  The For statement                                15
        3.4.6  The Return statement                             16
        3.4.7  The Break statement                              17
        3.4.8  The Continue statement                           17
        3.4.9  The Goto statement                               18

      4 Built-in Functions                                      20
      4.1  Quick Listing of Functions by Type                   21
      4.2  Complete Function Reference                          23

      5  System Variables                                      120

      6  Appendix A - ASCII Character Set                      140

      7  Appendix B - Extended Key Scan Codes                  141

      8  Appendix C - Color Values                             142

          Telix v3.12 - SALT Programming            Introduction    1







      1.  THE TELIX SALT LANGUAGE

      Telix has a built-in programming language called SALT (Script
      Application Language for Telix). SALT will allow you to perform al-
      most any communications related applications with Telix. SALT looks
      similar to the C language, however if you have used almost any
      programming language (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
      function. The task can range from the very simple to the very com-
      plicated. For example, a SALT script can be linked to a dialing di-
      rectory entry, so that when you have established a connection to
      that service, it automatically 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 lan-
      guage. 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 programming 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
      explicitly 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

          Telix v3.12 - SALT Programming            Introduction    2




      wish 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
      understand. 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
      written 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 com-
      piler 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 op-
      tion 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 v3.12 - 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 recommended that you try to make your code easy to understand,
      by indenting 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
      necessary for a string constant to include special characters that
      can not easily be typed from the keyboard, or can not be easily dis-
      played. This is done with something called the escape character,
      which is the caret ('^') symbol. When the SALT compiler is reading a
      string constant and comes to the '^' symbol, it replaces it with a
      certain ASCII code based on the character following the ^. Transla-
      tions are as follows:

           ^c        'c' is a letter. The Control representation of what-
                     ever letter 'c' is, is inserted into the text. There-
                     fore ^M represents Ctrl-M, ^j represents Ctrl-J, etc.
                     Whether the letter 'c' is upper or lower case is not
                     significant. Note that what is really happening here
                     is that 64 is being subtracted from the value of 'c',

          Telix v3.12 - SALT Programming                  Syntax    4




                     so for example, the Escape character can be repre-
                     sented as ^[.
           ^^        An actual caret ('^') symbol is placed into the text.
           ^"        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 ex-
                     ample, 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 immediately 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 (-) fol-
      lowed 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 repre-
      sent 16 values). Hex values must be preceded by '0x' for the com-
      piler to interpret them as such, and case is not important. The fol-
      lowing 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
      program does, and is meant purely for explaining or describing some-
      thing. In a SALT source file, whenever the symbol // is encountered
      on a line, all the characters from that point on until the end of

          Telix v3.12 - SALT Programming                  Syntax    5




      the line are considered to be a comment and are ignored. For exam-
      ple:

           prints("Hello");       // This line will print "Hello"

          Telix v3.12 - SALT Programming       Program Structure    6







      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 com-
      plete 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
      contents 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

          Telix v3.12 - SALT Programming       Program Structure    7




      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 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 al-
      ternate 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 assignment 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
      using 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 as-
      sumed to be that of the assigned text, e.g.

          Telix v3.12 - SALT Programming       Program Structure    8




           str name[] = "John";

      If a variable is outside of a function, it is global. If it is de-
      fined inside a function, it is local to that function and will only
      be recognized 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 completed, 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, vari-
      ables, and functions calls, while the operators (+, *, etc.) are the
      symbols that do things with the data. There are many different oper-
      ators, 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 following 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)
               *            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)

          Telix v3.12 - SALT Programming       Program Structure    9




               ||           binary            Logical OR
               or           binary            Logical OR (alternate)
               =            binary            Assignment

      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 compare 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
      values and result in a TRUE or FALSE value, while the Bitwise opera-
      tors (&, |, ^) work with the actual bits of the data they are han-
      dling. The Bitwise operators almost never have to be used in a Telix
      script, unless 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
      operation performed (e.g, 10 * 7 would resolve to 70). The condi-
      tional or equality operators such as ==, >, <=, etc., resolve to  a
      0 (FALSE)) or non-zero (TRUE) value based on the results of the ex-
      pression. Even the assignment operator = resolves to a value. The
      result of the expression

           num = 10

      would be 10.

      All the operators have something called precedence, which is their
      importance, 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 operators are listed below in order of decreasing precedence.
      All the operators on the same line have the same precedence, and are
      resolved in the order that they are encountered.

          Telix v3.12 - SALT Programming       Program Structure    10




           -  !
           *  /  %
           +  -
           <  >  <=  >=
           ==  !=
           &
           |
           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 paren-
      theses!


      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
      advantages 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
           debugging easier.

           As mentioned above, what a function does it private. This means
           that data variables defined in a function are local to that
           function, 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 v3.12 - SALT Programming       Program Structure    11




      <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
      values 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 vari-
      ables 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
      described below. First though, here is an example of a complete
      function:

           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
      elements 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
      acceptable, you may use a group of statements, by enclosing them all
      in curly braces (more on this below). There are many types of state-
      ments, including: expression, if, while, do...while, for, return,
      break, continue, and goto statements. Each type has several differ-
      ent parts.

          Telix v3.12 - SALT Programming       Program Structure    12




      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 con-
      tinue statement), and will only be executed if <expression> eval-
      uates to non-zero. By using curly braces around them, a whole group
      of statements 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>

          Telix v3.12 - SALT Programming       Program Structure    13




      In this case, if <expression> evaluates to non-zero (TRUE),
      <statement1> is executed, otherwise <statement2> is executed. Again,
      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.

          Telix v3.12 - SALT Programming       Program Structure    14




      While you may write the code in any way which suits you, it is
      recommended that you use indenting, for clarity. Indenting your code
      at the proper places makes it a lot easier to read.

      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
      expression 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
      condition 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 ex-
      pression 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
      ending the expression.

          Telix v3.12 - SALT Programming       Program Structure    15




      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>);

      <statement> will be executed at least once and will continue to be
      executed repeatedly until the expression becomes 0 (FALSE). A few
      examples 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
      condition 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
      variable. For example, if you wanted to count from 1 to 100, and
      were keeping the count in a variable called 'num', the first ex-
      pression would be 'num = 1'. The second expression is the condi-
      tional test. As long as it evaluates to non-zero (TRUE), the state-
      ment will be executed. 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 programmer a lot of power and flexibility. Note that any
      of the expressions 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("");
            }

          Telix v3.12 - SALT Programming       Program Structure    16




           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:

           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,
      control immediately returns to the function that called this func-
      tion. The expression is the value that should be returned. If no ex-
      pression 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 resolve to a string value. Due to memory con-
      straints, a local string variable may NOT be returned from a func-
      tion. 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
      necessary. Also, it should be clear that what is returned is not the
      expression but what it evaluates to.

          Telix v3.12 - SALT Programming       Program Structure    17




      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, execu-
      tion of the smallest while, do...while, or for loop is terminated,
      and execution continues immediately after the terminated loop state-
      ment. 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:

           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 for-
      ever. However, when the 'num' variable is > 100, the break statement
      is executed 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
      immediately 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");
            }

          Telix v3.12 - SALT Programming       Program Structure    18




      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 ex-
      ample 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.

      3.4.9  The Goto statement

      The goto statement is used to branch (jump) from one place to an-
      other, 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 language, 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 state-
      ment consists of two parts, the 'label' or marker, which is where
      execution will jump to, and the actual goto itself. A label is de-
      fined 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 char-
      acter 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
      following the label.

      An example is:

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

          Telix v3.12 - SALT Programming       Program Structure    19




      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;

      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 v3.12 - SALT Programming      Built-in Functions    20




      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,
      manipulate 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
      program code for the most part, and may not explicitly declare all
      needed variables. So that you may find related functions, each func-
      tion description has a 'See Also' section, which lists related func-
      tions.

          Telix v3.12 - SALT Programming      Built-in Functions    21






      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

      Other Functions

          Telix v3.12 - SALT Programming      Built-in Functions    22




      alarm, chatmode, delay, dial, dos, dosfunction, exittelix, help-
      screen, loadfon, newdir, redial, redirect_dos, run, send_brk,
      set_defprot, set_terminal, show_directory, terminal, tone

          Telix v3.12 - SALT Programming      Built-in Functions    23






      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

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    24





      --------------------------------------------------------------------
      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
      corner 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> selects what kind of box to draw, as follows:

           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

          Telix v3.12 - SALT Programming      Built-in Functions    25






      --------------------------------------------------------------------
      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
      memory, 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 variable defined within the called script, for memory rea-
      sons. if the indicated script can not be found or loaded, a value of
      -1 is returned. 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!");

          Telix v3.12 - SALT Programming      Built-in Functions    26





      --------------------------------------------------------------------
      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
      depend 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

      image, printer

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    27





      --------------------------------------------------------------------
      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

      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 re-
      turns a zero (FALSE) value. Note that some modems by default over-
      ride 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-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
      Detect signal.

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    28





      --------------------------------------------------------------------
      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, otherwise 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 v3.12 - SALT Programming      Built-in Functions    29






      --------------------------------------------------------------------
      cgetc, cgetct

      ■  Summary

      cgetc();

      cgetct(int <timeout>);

      ■  Description

      The cgetc function returns the first character waiting in the re-
      ceived 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 immediately returned. If no character is received within the
      timeout period, 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 v3.12 - SALT Programming      Built-in Functions    30





      --------------------------------------------------------------------
      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>, int <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> char-
      acters 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 encountered.

      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
      encountered (normally at the end of every string), or <max> char-
      acters 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 characters as will fit in <target> are copied.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    31




      None.

      ■  See Also

      copystr, subchrs, substr

      ■  Example



      --------------------------------------------------------------------
      copystr

      ■  Summary

      copystr(str <source>, int <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 characters as will fit in <target> are copied.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    32




      None.

      ■  See Also

      copychrs, substr, subchrs

      ■  Example



      --------------------------------------------------------------------
      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

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    33





      --------------------------------------------------------------------
      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 charac-
      ters,  ^ and ~, described in the Telix manual. This function is re-
      ally only useful for sending the modem control strings that the user
      has defined in the Configuration Menu.

      ■  Return Value

      None.

      ■  See Also

      cputs

          Telix v3.12 - SALT Programming      Built-in Functions    34




      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    35




      An integer value as described above.

      ■  See Also

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

      ■  Example

      // Print the current date

      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 vari-
      able 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);

          Telix v3.12 - SALT Programming      Built-in Functions    36






      --------------------------------------------------------------------
      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.

      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). Remaining 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);

          Telix v3.12 - SALT Programming      Built-in Functions    37





      --------------------------------------------------------------------
      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 en-
      tries in the dialing directory. If <dialstr> is empty (""), the di-
      aling directory is displayed. <maxtries> is the maximum number of
      dialing attempts. 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, dial-
      ing will continue until 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 num-
      ber of the entry which was connected to (or 1 if a manual number was
      dialed). 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 num-
      ber 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);

          Telix v3.12 - SALT Programming      Built-in Functions    38





      --------------------------------------------------------------------
      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


      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,
      otherwise 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);

          Telix v3.12 - SALT Programming      Built-in Functions    39





      --------------------------------------------------------------------
      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 using the errorlevel command). The <hangup> option af-
      fects what happens 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
      return from it.

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    40






      --------------------------------------------------------------------
      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
      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 before the file is closed.

      ■  Return Value

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

      ■  See Also

      fopen

          Telix v3.12 - SALT Programming      Built-in Functions    41




      ■  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
      significant, but wildcard characters (* or ?) may NOT be part of the
      filename.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    42




      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>);

      ■  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");

          Telix v3.12 - SALT Programming      Built-in Functions    43






      --------------------------------------------------------------------
      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!");



      --------------------------------------------------------------------
      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
      reading, the buffer is cleared.

      ■  Return Value

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

      ■  See Also

      fopen, fclose

          Telix v3.12 - SALT Programming      Built-in Functions    44






      --------------------------------------------------------------------
      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 v3.12 - SALT Programming      Built-in Functions    45






      --------------------------------------------------------------------
      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 encountered, 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 because in almost every case, the Line Feed is not needed, and
      would otherwise have to be manually stripped by the script after ev-
      ery 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);
       }

          Telix v3.12 - SALT Programming      Built-in Functions    46






      --------------------------------------------------------------------
      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
      byte, when you do a DOS dir command, the file is not shown. Simi-
      larly, 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 wild-
      card 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 com-
                mand is executed.

           4    System file. The file is not listed when the DOS dir com-
                mand 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
      filesize or filetime in the meantime with a non-blank filename would
      instead make this call return the attributes of files found with
      those functions, as they use the same buffer.

          Telix v3.12 - SALT Programming      Built-in Functions    47




      ■  Return Value

      An integer value representing the combined attributes of the in-
      dicated file is returned, or a value of -1 is returned if the in-
      dicated 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
       prints("This file is marked as hidden and system");

          Telix v3.12 - SALT Programming      Built-in Functions    48






      --------------------------------------------------------------------
      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 attribute is obtained by adding certain values as fol-
      lows:

           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 re-
      turned. Any other selected attribute or combination (addition) of
      attributes results 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

          Telix v3.12 - SALT Programming      Built-in Functions    49




      ■  Example

      // show all normal files in the current directory
      str buf[16], fspec[16] = "*.*";
      while (filefind(fspec, 0, buf) != 0)
       {
        prints(buf);    // show file found
        fspec = "";     // so we can continue searching for files
       }

          Telix v3.12 - SALT Programming      Built-in Functions    50






      --------------------------------------------------------------------
      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
      directory 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
       }

          Telix v3.12 - SALT Programming      Built-in Functions    51






      --------------------------------------------------------------------
      filetime

      ■  Summary

      filetime(str <filespec>);

      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    52




      if (filetime("FILE1") < filetime("FILE2"))
       prints("FILE1 is older than FILE2");
      else
       prints("FILE1 is newer than FILE2");



      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.

          Telix v3.12 - SALT Programming      Built-in Functions    53






      --------------------------------------------------------------------
      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
      combination 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

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    54






      --------------------------------------------------------------------
      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 val-
      ues 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 ex-
                     ist).
           "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 be-
      fore 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 avail-
      able 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)
       prints("Error opening file!");

          Telix v3.12 - SALT Programming      Built-in Functions    55






      --------------------------------------------------------------------
      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

          Telix v3.12 - SALT Programming      Built-in Functions    56






      --------------------------------------------------------------------
      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

      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    57






      --------------------------------------------------------------------
      fread

      ■  Summary

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

      ■  Description

      The fread function reads up to <count> bytes from the file repre-
      sented 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 signifi-
      cant.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    58






      ■  See Also

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

      ■  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
      position 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 v3.12 - SALT Programming      Built-in Functions    59






      --------------------------------------------------------------------
      ftell

      ■  Summary

      ftell(int <fh>);

      ■  Description

      The ftell function returns the current file position in the file
      represented by file handle <fh>.

      ■  Return Value

      An integer value as described above. A -1 value is returned if an
      error 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 v3.12 - SALT Programming      Built-in Functions    60






      --------------------------------------------------------------------
      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

          Telix v3.12 - SALT Programming      Built-in Functions    61






      --------------------------------------------------------------------
      getenv

      ■  Summary

      getenv(str <varname>, str <target>);

      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    62




      A non-zero (TRUE) value is returned if the function is successful,
      otherwise a zero (FALSE) values is returned (if the environment
      variable 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

          Telix v3.12 - SALT Programming      Built-in Functions    63






      --------------------------------------------------------------------
      get_port

      ■  Summary

      get_port();

      ■  Description

      The get_port function returns the number (1 through 8) of the cur-
      rent 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

          Telix v3.12 - SALT Programming      Built-in Functions    64






      --------------------------------------------------------------------
      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. String entry is over when the user presses Enter (Carriage Re-
      turn on some computers). The user may press Esc to abort string en-
      try, 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);

          Telix v3.12 - SALT Programming      Built-in Functions    65






      --------------------------------------------------------------------
      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 at-
      tribute. <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-
      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. String entry is over when the user presses Enter (Carriage Re-
      turn on some computers). The user may press Esc to abort string en-
      try, 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
        // at current cursor position
      n = getsxy(filename, 64, getx(), gety(), 112);

          Telix v3.12 - SALT Programming      Built-in Functions    66






      --------------------------------------------------------------------
      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 v3.12 - SALT Programming      Built-in Functions    67




      ■  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
      configuration 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.

          Telix v3.12 - SALT Programming      Built-in Functions    68






      --------------------------------------------------------------------
      inkey, inkeyw

      ■  Summary

      inkey();
      inkeyw();

      ■  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
      between 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 sec-
      tion 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();

          Telix v3.12 - SALT Programming      Built-in Functions    69






      --------------------------------------------------------------------
      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 characters 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

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    70






      --------------------------------------------------------------------
      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')

      isupperint <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.

          Telix v3.12 - SALT Programming      Built-in Functions    71






      --------------------------------------------------------------------
      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
      function, or is still in memory because it previously was run and
      did not 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

          Telix v3.12 - SALT Programming      Built-in Functions    72




      ■  Example

      int chr;
      str s[16];
      chr = keyinw();       // 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>);

      ■  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 as-
      sumed 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);

          Telix v3.12 - SALT Programming      Built-in Functions    73






      --------------------------------------------------------------------
      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
      extension is given, .KEY is assumed). Telix always keeps two defini-
      tion 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, 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);



      --------------------------------------------------------------------
      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

          Telix v3.12 - SALT Programming      Built-in Functions    74




      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
      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, 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

      ■  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");

          Telix v3.12 - SALT Programming      Built-in Functions    75






      --------------------------------------------------------------------
      loadfon

      ■  Summary

      int loadfon(str <filename>);

      ■  Description

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

      ■  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
      terminal mode, or from within another script), it is usually loaded
      from disk. The load_scr function is used to load a script into mem-
      ory ahead of time, providing a savings in time when the script must
      be run repeatedly. <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;
      stat = load_scr("TEST");     // load TEST.SLC

          Telix v3.12 - SALT Programming      Built-in Functions    76






      --------------------------------------------------------------------
      newdir

      ■  Summary

      newdir(<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 direc-
      tory 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 direc-
      tory 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

          Telix v3.12 - SALT Programming      Built-in Functions    77




      ■  Example

      printc('A');

      printc(7);            // print ASCII value 7 (BELL sound)

      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

          Telix v3.12 - SALT Programming      Built-in Functions    78




      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 v3.12 - SALT Programming      Built-in Functions    79






      --------------------------------------------------------------------
      prints, printsc

      ■  Summary

      prints(str <outstr>);

      printsc(str <outstr>);

      printsc_trm(str <outstr>);

      ■  Description

      The prints function prints the passed string at the current cursor
      position 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
      terminal 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

          Telix v3.12 - SALT Programming      Built-in Functions    80






      --------------------------------------------------------------------
      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 func-
      tions. 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. <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
      specify 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

          Telix v3.12 - SALT Programming      Built-in Functions    81






      --------------------------------------------------------------------
      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.

      ■  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!");

          Telix v3.12 - SALT Programming      Built-in Functions    82






      --------------------------------------------------------------------
      redial

      ■  Summary

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

      ■  Description

      The redial function dials the entries specified in <dialstr>. The
      entries should be entered in the same format as used when typing en-
      tries in the dialing directory. If <dialstr> is empty (""), the re-
      dial queue is presented to the user, as if Alt-Q was pressed while
      in terminal mode. <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 until a connection is established. If an entry is con-
      nected 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
      number of the of the entry which was connected to (or 1 if a manual
      number 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 num-
      ber 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

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    83






      --------------------------------------------------------------------
      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
      include the full path to the file (i.e., specify the drive and/or
      directory). 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
      specified, 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 v3.12 - SALT Programming      Built-in Functions    84






      --------------------------------------------------------------------
      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 cor-
      ner 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 negative 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

          Telix v3.12 - SALT Programming      Built-in Functions    85




      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
      select the appropriate 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. <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 Con-
      figuration 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

          Telix v3.12 - SALT Programming      Built-in Functions    86




      receive, _up_dir



      --------------------------------------------------------------------
      send_brk

      ■  Summary

      send_brk(<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>);

      ■  Description

      The set_cparams function is used to set the communications param-
      eters 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

          Telix v3.12 - SALT Programming      Built-in Functions    87




      ■  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
      protocol 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 v3.12 - SALT Programming      Built-in Functions    88






      --------------------------------------------------------------------
      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

          Telix v3.12 - SALT Programming      Built-in Functions    89




      ■  Example

      str s[100];
      // zero out an entire string
      setchrs(s, 0, 0, strmaxlen(s));
      // set the first ten characters to 'A'
      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 be-
      ing emulated. <terminal_name> is the name of the new terminal to
      use, as follows:

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

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    90




      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");



      --------------------------------------------------------------------
      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 mon-
      itored 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);

          Telix v3.12 - SALT Programming      Built-in Functions    91






      --------------------------------------------------------------------
      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
      previous contents of that screen area are restored.

      ■  Return Value

      None.

      ■  See Also

      box, pstra, pstraxy

      ■  Example

      status_wind("File not found!", 10);



      --------------------------------------------------------------------
      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 charac-
      ter. If an empty or invalid string is parsed, a value of 0 is re-
      turned.

      ■  Return Value

      An integer value as described above.

      ■  See Also

      itos

          Telix v3.12 - SALT Programming      Built-in Functions    92




      ■  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 v3.12 - SALT Programming      Built-in Functions    93






      --------------------------------------------------------------------
      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 posi-
      tion 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 returned. 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);

          Telix v3.12 - SALT Programming      Built-in Functions    94






      --------------------------------------------------------------------
      strcmpi

      ■  Summary

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

      ■  Description

      The strcmpi function is used to compare two strings (in a similar
      manner to the ==, >, and < operators, but ignoring the case of the
      strings). The strings are compared character by character until a
      difference is found or the end of either string is found, and an in-
      teger value is returned as follows:

           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

          Telix v3.12 - SALT Programming      Built-in Functions    95




      ■  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 up-
      per case character to lower case. Other characters are left un-
      changed.

      ■  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 always 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

          Telix v3.12 - SALT Programming      Built-in Functions    96






      --------------------------------------------------------------------
      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
      character 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.

      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    97




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

      ■  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 posi-
      tion 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.

      ■  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));

          Telix v3.12 - SALT Programming      Built-in Functions    98






      --------------------------------------------------------------------
      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 encountered.

      ■  Return Value

      None.

      ■  See Also

      substr, subchr, copystr, copychrs

          Telix v3.12 - SALT Programming      Built-in Functions    99






      --------------------------------------------------------------------
      substr

      ■  Summary

      substr(str <source>, int <pos>, int <max>, str <target>);

      ■  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
      encountered (normally at the end of every string), or <max> char-
      acters 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 characters as will fit in <target> are copied.

      ■  Return Value

      None.

      ■  See Also

      subchrs, copystr, copychrs

      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    100






      --------------------------------------------------------------------
      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>
      represents 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 information in this format.

      tday returns an integer value from 1 to 31 representing the day por-
      tion of the date stored in <timeval>.

      thour returns an integer value from 0 to 23 representing the hour
      portion 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

          Telix v3.12 - SALT Programming      Built-in Functions    101




      ■  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 example 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.

      ■  See Also

      track

          Telix v3.12 - SALT Programming      Built-in Functions    102




      ■  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 date_format). <timeval> is the time, represented as the
      number of seconds since midnight. Time values in this form are re-
      turned by the curtime and filetime functions, among others.

      ■  Return Value

      None.

      ■  See Also

      date, curtime, filetime

          Telix v3.12 - SALT Programming      Built-in Functions    103




      ■  Example

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

          Telix v3.12 - SALT Programming      Built-in Functions    104






      --------------------------------------------------------------------
      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
      future. 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
      represented 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 han-
      dle <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.

          Telix v3.12 - SALT Programming      Built-in Functions    105




      time_up returns a non-zero (TRUE) or 0 (FALSE) value depending on
      whether a timer has elapsed or not.

      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 func-
      tion returns the lowercase equivalent. Otherwise <chr> is returned
      unchanged. Note that <chr> is an ASCII value, not a string.

      ■  Return Value

      An integer value as described above.

      ■  See Also

      toupper

          Telix v3.12 - SALT Programming      Built-in Functions    106






      --------------------------------------------------------------------
      tone

      ■  Summary

      tone(int <frequency>, int <length>);

      ■  Description

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

      ■  Return Value

      None.

      ■  See Also

      alarm

      ■  Example

      tone(659, 14);



      --------------------------------------------------------------------
      toupper

      ■  Summary

      tolower(int <chr>);

      ■  Description

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

      ■  Return Value

      An integer value as described above.

      ■  See Also

      tolower

          Telix v3.12 - SALT Programming      Built-in Functions    107






      --------------------------------------------------------------------
      track - track_hit

      ■  Summary

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

      track_hit(int <handle>);

      track_addchr(int <chr>);

      track_free(int <handle>);

      ■  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 ar-
      rive 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 sig-
      nificant. The former 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 repre-
      sented 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 han-
      dle is cleared once track_hit has indicated that the appropriate
      string was received.

          Telix v3.12 - SALT Programming      Built-in Functions    108




      While a script is executing, Telix is not in terminal mode, and
      therefore 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. Al-
      ternately, if a script must process these characters itself (with a
      function like cgetc), and therefore can not call the terminal func-
      tion, 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
      certain 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

      All functions return integer values as described above.

      ■  See Also

      waitfor

      ■  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
         }

          Telix v3.12 - SALT Programming      Built-in Functions    109




       }

      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 indi-
      cated translate table, otherwise a non-zero (TRUE) value is re-
      turned.

      ■  Example

      transtab("TELIX.XLT");

          Telix v3.12 - SALT Programming      Built-in Functions    110






      --------------------------------------------------------------------
      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
      unload, 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
      returned. 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 cer-
      tain things relating to the video and terminal page. Fro 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). Call-
      ing this function ensures that the status bar is updated.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    111




      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 file-
      name 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

      ■  Example

      usagelog("TELIX.USE");

          Telix v3.12 - SALT Programming      Built-in Functions    112






      --------------------------------------------------------------------
      usage_stat

      ■  Summary

      usage_stat();

      ■  Description

      The usage_stat function returns an integer value representing the
      current 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

      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 us-
      age 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 usage log. If <new_entry> contains a non-zero (TRUE) value, the
      current date/time is placed ahead of the text, otherwise it is as-
      sumed 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 Return and Line Feed character are added after the
      entry. This is usually the case unless something else must be added
      on the same line.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    113




      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);



      --------------------------------------------------------------------
      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
      below. 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

          Telix v3.12 - SALT Programming      Built-in Functions    114




      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
      series of double bytes). <x>,<y> is the spot on the screen to start
      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 charac-
      ter) at the end of the sequence of characters they grab. If the
      characters returned by vgetchrs are to be manipulated as a string a
      0 must be added at the end with the setchr function.

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    115




      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 contains the ASCII value of the character, while the second
      byte contains the color value. In general, a if 'c' is the charac-
      ter, and 'color' is the color to use, the proper value is obtained
      with the expression

           (c + color * 256)

      ■  Return Value

          Telix v3.12 - SALT Programming      Built-in Functions    116




      None.

      ■  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
      characters from a spot in a string variable onto the screen at a
      certain position. The first function assumes that the string con-
      tains characters 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 vari-
      able. 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

          Telix v3.12 - SALT Programming      Built-in Functions    117




      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
       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, re-
      turned by a previous call to vsavearea, or unpredictable results
      will happen.

      ■  Return Value

      None.

      ■  See Also

      vsavearea

          Telix v3.12 - SALT Programming      Built-in Functions    118






      --------------------------------------------------------------------
      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
      function.

      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.

      ■  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

          Telix v3.12 - SALT Programming      Built-in Functions    119






      --------------------------------------------------------------------
      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
      returned.

      ■  See Also

      track

      ■  Example

      if (waitfor("name?", 1800))
       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 v3.12 - SALT Programming        System Variables    120




      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 ac-
      cessed just as you would access any other variable. To help distin-
      guish 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 vari-
      ables. 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 descrip-
      tions have a 'See also' section, which lists related variables and
      functions.

          Telix v3.12 - SALT Programming        System Variables    121






      --------------------------------------------------------------------
      _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

      _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 termi-
      nal 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 pro-
      cess. Maximum length is 19 characters.

          Telix v3.12 - SALT Programming        System Variables    122






      --------------------------------------------------------------------
      _asc_rcrtrans - _asc_striph

      ■  Summary

      int _asc_rcrtrans;

      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
      Return before.

      _asc_scpacing is the time in milliseconds which Telix should wait
      before 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.

          Telix v3.12 - SALT Programming        System Variables    123




      _asc_slftran determines what Telix does with Line Feed characters
      during ASCII sends. 0 = do nothing; 1 = strip; 2 = add Carriage Re-
      turn 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).

      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 char-
      acters.

      ■  See Also

      _mdm_init_string



      --------------------------------------------------------------------
      _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 un-
      til the screen is cleared.

      ■  See Also

      _fore_color

          Telix v3.12 - SALT Programming        System Variables    124






      --------------------------------------------------------------------
      _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.

      ■  See Also

      _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

          Telix v3.12 - SALT Programming        System Variables    125






      --------------------------------------------------------------------
      _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
      format Telix uses for date strings it produces, as follows:

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

      ■  See Also

      _time_format

          Telix v3.12 - SALT Programming        System Variables    126






      --------------------------------------------------------------------
      _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 be-
      ginning 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).

      ■  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
      translation 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

          Telix v3.12 - SALT Programming        System Variables    127






      --------------------------------------------------------------------
      _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
      function.

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

      ■  See Also

      _dialpost, _rdl_stop



      --------------------------------------------------------------------
      _dir_prog

      ■  Summary

      str _dir_prog[64];

      ■  Description

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

          Telix v3.12 - SALT Programming        System Variables    128






      --------------------------------------------------------------------
      _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];

      ■  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 max-
      imum length is 64 characters. If a batch file is to be run the .BAT
      extension must be given.

          Telix v3.12 - SALT Programming        System Variables    129






      --------------------------------------------------------------------
      _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 dial-
      ing 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
      directory 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
      characters.

      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
      logons. The maximum length is 14 characters.

      ■  See Also

      _entry_enum
      dial, redial

          Telix v3.12 - SALT Programming        System Variables    130






      --------------------------------------------------------------------
      _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 implements 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 un-
      til 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 v3.12 - SALT Programming        System Variables    131






      --------------------------------------------------------------------
      _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

      ■  Summary

      str _mdm_hang[19];

      ■  Description

      The _mdm_hang 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 de-
      fined 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, _auto_ans_str

          Telix v3.12 - SALT Programming        System Variables    132






      --------------------------------------------------------------------
      _mdm_init_str

      ■  Summary

      str _mdm_init_str[49];

      ■  Description

      The _modem_init system variable holds the string that should be sent
      to the modem when Telix starts-up. It is usually used to make sure
      certain settings in the modem are right. 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 49
      characters.

      ■  See Also

      _auto_ans_str, _mdm_hang



      --------------------------------------------------------------------
      _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
      established (i.e., the number was busy or there was no answer). The
      maximum length for each string is 19 characters.

      ■  See Also

      _connect_str

          Telix v3.12 - SALT Programming        System Variables    133






      --------------------------------------------------------------------
      _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
      Carriage 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 charac-
      ters.

      ■  See Also

      _dialpref, _dialpref2, _dialpref3, _dialpost

          Telix v3.12 - SALT Programming        System Variables    134






      --------------------------------------------------------------------
      _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
      however 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. Set-
      ting 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
      selected 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 directory 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

          Telix v3.12 - SALT Programming        System Variables    135






      --------------------------------------------------------------------
      _sound_on

      ■  Summary

      int _sound_on;

      ■  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 v3.12 - SALT Programming        System Variables    136






      --------------------------------------------------------------------
      _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 be able to find many needed files. The maximum length
      is 64 characters.

      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

          Telix v3.12 - SALT Programming        System Variables    137






      --------------------------------------------------------------------
      _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
      indicated by _up_dir. This variable should end with a slash charac-
      ter, '\'. The maximum length is 64 characters.

      ■  See Also

      _down_dir



      --------------------------------------------------------------------
      _usage_fname

      ■  Summary

      str _usage_fname[64];

      ■  Description

      The _usage_fname system variable holds the default Usage Log file-
      name. The maximum length is 64 characters.

      ■  See Also

      _capture_fname

          Telix v3.12 - SALT Programming        System Variables    138






      --------------------------------------------------------------------
      _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
      during a Zmodem download.

      ■  See Also

      _zmod_scrash

          Telix v3.12 - SALT Programming        System Variables    139






      --------------------------------------------------------------------
      _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 re-
      sume aborted transfers during a Zmodem upload.

      ■  See Also

      _zmod_rcrash

          Telix v3.12                                 Appendix A    140




      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
      provide extra symbols. The following table lists the regular ASCII
      character set. The first column contains the ASCII control charac-
      ters, 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 v3.12                                 Appendix B    141




      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, key-
      set, 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
      10                                   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 v3.12                                 Appendix C    142




      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 back-
      ground 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 for-
      mula 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 v3.12 - SALT Programming                   Index    143




                                          alarm  23
                                          box  24
                                          call  25
      9.  INDEX                           calld  25
                                          capture  26
      _add_lf  121                        capture_stat  27
      _alarm_on  121                      carrier  27
      _answerback_str  121                cgetc, cgetct  29
      _asc_rcrtrans - _asc_striph         chatmode  28
          122                             cinp_cnt  28
      _auto_ans_str  123                  clear_scr  30
      _back_color  123                    copychrs  30
      _capture_fname  124                 copystr  31
      _cisb_auto  124                     cputc  32
      _connect_str  125                   cputs  33
      _date_format  125                   cputs_tr  33
      _dial_pause  126                    cursor_onoff  34
      _dial_time  126                     curtime  34
      _dialpost  126                      date  35
      _dialpref  127                      delay  36
      _dialpref2  127                     delay_scr  36
      _dialpref3  127                     dial  37
      _dir_prog  127                      dos  38
      _disp_free  128                     dosfunction  39
      _down_dir  128                      exittelix  39
      _editor  128                        fclearerr  40
      _entry_enum  129                    fclose  40
      _entry_name  129                    fdelete  41
      _entry_num  129                     feof  42
      _entry_pass  129                    ferror  43
      _ext_filespec  130                  fflush  43
      _fore_color  130                    fgetc  44
      _image_file  130                    fgets  45
      _local_echo  131                    fileattr  46
      _mdm_hang  131                      filefind  48
      _mdm_init_str  132                  filesize  50
      _no_connect1  132                   filetime  51
      _no_connect2  132                   flushbuf  52
      _no_connect3  132                   fnstrip  53
      _no_connect4  132                   fopen  54
      _qdbar_on  133                      fputc  55
      _redial_stop  133                   fputs  56
      _scr_chk_key  134                   fread  57
      _script_dir  134                    frename  57
      _sound_on  135                      fseek  58
      _strip_high  135                    ftell  59
      _swap_bs  135                       fwrite  59
      _telix_dir  136                     get_baud  60
      _time_format  136                   get_datab  60
      _up_dir  137                        get_parity  62
      _usage_fname  137                   get_port  63
      _zmod_auto  138                     get_stopb  63
      _zmod_rcrash  138                   getenv  61
      _zmod_scrash  139                   gets  64
                                          getsxy  65

          Telix v3.12 - SALT Programming                   Index    144




      getx, gety  66                      subchrs  98
      gotoxy  66                          substr  99
      hangup  67                          tday  100
      helpscreen  67                      terminal  101
      inkey, inkeyw  68                   thour  100
      inschrs  69                         time  102
      is_loaded  71                       time_up  104
      isalnum  70                         timer_free  104
      isalpha  70                         timer_restart  104
      isascii  70                         timer_start  104
      iscntrl  70                         timer_total  104
      isdigit  70                         tmin  100
      islower  70                         tmonth  100
      isupper  70                         tolower  105
      itos  71                            tone  106
      keyget  72                          toupper  106
      keyload  73                         track  107
      keysave  73                         track_addchr  107
      keyset  74                          track_free  107
      load_scr  75                        track_hit  107
      loadfon  75                         transtab  109
      newdir  76                          tsec  100
      printc  76                          tyear  100
      printer  77                         unload_scr  110
      printn  78                          update_term  110
      prints  79                          usage_stat  112
      printsc  79                         usagelog  111
      printsc_trm  79                     ustamp  112
      pstra  80                           vgetchr  113
      pstraxy  80                         vgetchrs, vgetchrsa  114
      receive  81                         vputchr  115
      redial  82                          vputchrs, vputchrsa  116
      run  83                             vrstrarea  117
      scroll  84                          vsavearea  118
      send  85                            waitfor  119
      send_brk  86
      set_cparams  86
      set_defprot  87
      set_port  89
      set_terminal  89
      setchr  88
      setchrs  88
      show_directory  90
      status_wind  91
      stoi  91
      strcat  92
      strchr  93
      strcmpi  94
      strlen  94
      strlower  95
      strmaxlen  95
      strpos  96
      strposi  96
      strupper  96
      subchr  97