INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous page... Table of Contents

3.2.6 Structure References

Another type of variable is a structure reference. INTOUCH includes a transparent interface to several record management systems, including the VMS file management system. One of the major features of INTOUCH is its ability to perform database operations as a part of the language. INTOUCH's data structure statements allow you to manipulate stored data from within your own programs. (See Chapter 14, Data Structure Statements for informaton on the INTOUCH data structure statements.)

INTOUCH stores data in structures. Structures look something like this:

Example 3-2 Structures


FIELDS / | \ / | \ / | \ / | \ / | \ R | Client | Last name | First name E | Number | | C |---------|-----------------------------|-------------------- O _____ |8|0|5|4|3|C|a|s|s| | | | | | | | | | | |C|a|t|h|y| | | | | | R _____ |8|0|5|4|2|B|r|o|c|k| | | | | | | | | | |B|u|d| | | | | | | | D | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | S positions

Each structure is made up of records and fields. In the CLIENT structure above, we have a record for each customer.

Each record consists of fields. For example, our customer records might contain a field for the customer's ID number, last name, first name, address, phone number, company name, etc.. Each of these pieces of data is stored in its own field--the name field, address field, phone number field, etc.. These fields appear as columns in the example shown above.

For information on creating structures and defining fields, see Chapter 16, Creating Structures, Field Definitions with SETUP.

You can reference the field data in structures by using structure references. To reference a field, indicate the structure name and the expression of the field whose contents you want to access.

        struc_name(field_expr) 

struc_name is the name associated with the structure. field_expr is the name of a field in the structure. When you reference a field, INTOUCH searches the current record for this field and reads its contents. Some examples of structure references are:

        CLIENT(PHONE)          CATALOG(PART_NUM) 

The field_expr can be either a string or numeric expression.

You can use a string constant to specify the field name. If you give the field name as a string constant, you need not enclose it in quotes. INTOUCH will use the string constant as the field name:

                      PRINT CL(LAST) 
                                / 
           the field is specified by its field name 

If you specify the field as an expression, you will need to precede the expression with a pound sign (#). The pound sign tells INTOUCH that the following characters are an expression, not the field name. If you do not include the pound sign, INTOUCH will interpret the characters as a field name. Here are two examples:

                     PRINT CL(#FIELDNAME$) 
                                 / 
          the field is specified by the variable FIELDNAME$ 
 
 
                     PRINT CL(#FIELDNUM) 
                              / 
          the field is specified by the variable FIELDNUM 

See Section 14.8.1.1, FIELD Expressions for an example of a program that uses field expressions.

3.2.7 Multiple Occurrence Fields

Fields with multiple occurrences (single dimension array) are supported.

When defining a field with multiple occurrences, the length of the field must be the length of a single occurrence. Individual occurrences of a field are accessed by including the occurrence number in the field expression.

        10  OPEN STRUCTURE cust: NAME 'tti_run:customer', ACCESS INPUT 
        20  EXTRACT STRUCTURE cust 
              PRINT cust(address#1) 
              PRINT cust(address#2) 
            END EXTRACT 
        30  END 
 
        RNH 
        10010 Sunset Cliffs Blvd. 
 
        1122 Monroe Ave. 
        PO Box 8765 
        11A SE. Hwy A1A 
        PO Box 11A-A 
        2111 Brawley Blvd. 
                . 
                . 
                . 
        999 World Vista Avenue 
 
        #2 Bougainvillea Blvd. 

3.2.8 Compound Expressions

You can use compound expressions in your programs. Compound expressions consist of operators and operands. There are three types of compound expressions:

3.2.8.1 Numeric Expressions

Numeric expressions consist of numeric (integer or real) variables, constants or expressions separated by arithmetic operators. The arithmetic operators are +, -, *, /, and ^.

                        Constants    Variables 
 
                       
        +         Add 
 
                        4%+2%        Z + TWO16 
 
        -         Subtract 
 
                        4%-2%        Z - TWO16 
 
        /         Divide 
 
                        4%/2%        Z / TWO16 
 
        *         Multiply 
 
                        4%*2%        Z * TWO16 
 
        ^         Raise to a power 
 
                        4%^2%        Z ^ TWO16 
 

You can combine any number of these operators in an expression.

        4 + Z ^ TWO16                Z * TWO16 / 2 

You cannot generally use two arithmetic operators next to each other. However, you can use a + or - sign to indicate a positive or negative number. For example:

                TOTAL * -2   =   TOTAL * (-2) 
                TOTAL / +2   =   TOTAL / (+2) 

If all the values in an arithmetic expression are of the same data type, the result of the expression will be that data type. For example, if an expression consists only of integer numbers, it will yield an integer result. If an expression consists only of real numbers, the result will be a real number. If an expression consists of integers and real numbers, the result will be a real number. If the target of a real calculation is an integer (a% = 1.5 + 2.8) the result is rounded before it is assigned to the target.

3.2.8.2 String Expressions

String expressions are strings concatenated (joined). String expressions can be joined by a plus sign (+) or by an ampersand (&). INTOUCH evaluates this type of string expression by concatenating the strings. For example:

        10  z$ = 'MO' + 'TH' & 'ER' 
        20  PRINT z$ 
        30  END 
 
        RNH 
        MOTHER 

In the above example, INTOUCH joins the strings separated by a plus sign and an ampersand, and assigns their value to Z$. You can include string constants, variables, functions, etc. in your string expressions. For example:

        10  LET last$ = ' is it.' 
        20  PRINT 'This' + last$ 
        30  END 
 
        RNH 
        This is it. 

3.2.8.3 Conditional Expressions

Conditional expressions are expressions which yield a TRUE (1) or FALSE (0) value. Conditional expressions are created by using either relational or logical operators. When INTOUCH evaluates a conditional expression, it returns a value of either TRUE or FALSE. If the expression is TRUE, INTOUCH returns the integer 1. If the expression is FALSE, INTOUCH returns the integer 0.

Conditional Numeric Expressions

Relational operators are similar to those used in algebra. The relational operators are:

 
=      equals                           X=Y           X is equal to Y 
 
<      less than                        X<Y           X is less than Y 
 
>      greater than                     X>Y           X is greater than Y 
 
<=     less than or equal to            X<=Y          X is less than or equal 
                                                        to Y 
 
>=     greater than or equal to         X>=Y          X is greater than or 
                                                        equal to Y 
 
<>     not equal to                     X<>Y          X is not equal to Y 
 

X and Y can be any unconditional or conditional expression.

Performing Relational Operations on Strings

When you perform relational operations on strings, INTOUCH determines which string occurs first in the the ASCII collating sequence and returns TRUE or FALSE. For instance, when you perform relational operations on two strings, INTOUCH checks the ASCII values for each character in each string. INTOUCH compares the strings character by character--using these ASCII values--and determines where there is a difference in the values.

When INTOUCH finds a character that differs, it compares the two and determines which one is less (which has a smaller ASCII code number). INTOUCH then returns a TRUE or FALSE value depending on the relational expression. For example:

        10  a$ = 'TEXT' 
            b$ = 'TEST' 
            MESSAGE$ = 'Strings are equal' 
        20  IF  a$ < b$  THEN  message$ = a$ + ' is less than ' + b$ 
            IF  b$ < a$  THEN  message$ = b$ + ' is less than ' + a$ 
        30  PRINT message$ 
        40  END 
 
        RNH 
        TEST is less than TEXT 

INTOUCH compares the two strings. They are identical up to the third character. The ASCII value of S is 53. The ASCII value of X is 58. Therefore INTOUCH prints "TEST is less than TEXT".

Logical Operators

The logical operators are:

NOT     NOT X           TRUE  if X is false and 
                        FALSE if X is true. 
 
AND     X AND Y         TRUE  if X and Y are true. 
 
OR      X OR Y          TRUE  if X or Y is true. 
 
XOR     X XOR Y         TRUE  if X is true, or if Y is true but 
                          FALSE if both X and Y are true. 
 
EQV     X EQV Y         TRUE  if X and Y are true, or 
                        TRUE  if X and Y are false, 
                          but FALSE otherwise. 
 
IMP     X IMP Y         TRUE if X is true and Y is false. 

X and Y can be any expressions. Logical operators are usually used on integers or expressions which yield an integer result such as conditional expressions. Logical operators will always yield an integer result. If a logical operator is used on a real number, the real number is rounded and the resulting integer is used.

Logical expressions always return an integer value. If the integer value is a 1, the expression is TRUE. If the integer value is a 0, the expression is FALSE. (NOT 0 is equal to -1 and is TRUE. NOT 1 is equal to -2 and is FALSE.)

                          VALUE     TRUE   FALSE 
                      +--------------------------+ 
                      |        0  |      |   X   | 
                      |-----------|------|-------| 
                      |        1  |   X  |       | 
                      |-----------|------|-------| 
                      | NOT 0 (-1)|   X  |       | 
                      |-----------|------|-------| 
                      | NOT 1 (-2)|      |   X   | 
                      +--------------------------+ 

Bit Manipulation

Logical operators can be used to do bit manipulation. Computers represent values in a binary code, using ones and zeros. INTOUCH integer values are represented as a 32-bit binary longword. A bit which is set to 1 is considered on. A bit which is set to 0 is off. The value of the word is equal to the value of all the bits which are on, added together. For example:

           0 0 0 1 0 1 1 1  =  16 + 4 + 2 + 1 = 23 

The last bit has a value of 1. The second to the last bit has a value of 2. The third bit has a value of 4, the fourth a value of 8, the fifth bit has a value of 16, and so on. Each bit has a value double that of the previous one.

                0   0   0   0   0   0   0   0 
         --------------------------------------------- 
               128  64  32  16  8   4   2   1 

Bits can be manipulated and tested using logical operators. The logical operators work on bits. They compare each position in each word according to the particular rules of the logical operator. For instance, here is the AND operator used on two values:

        10  LET a% = 23%       ! 00010111 
        20  LET b% = 37%       ! 00100101 
        30  LET c% = (a% AND b%) 
        40  PRINT c% 
        50  END 
 
        RNH 
         5 

When INTOUCH executes this program, it compares the two values. It sets a bit in the result to 1 (on), only if both the bits at a given position are on (1). The value of the resultant word is 5.

                A%    0 0 0 1 0 1 1 1 = 23 
                B%    0 0 1 0 0 1 0 1 = 37 
                      --------------- 
                C%    0 0 0 0 0 1 0 1 =  5 

3.2.9 Order of Evaluation

When INTOUCH evaluates an expression, it evaluates it in a specific order. INTOUCH evaluates expressions from left to right.

        1+Z+4                 equals          (1+Z)+4 
        1+Z-4                 equals          (1+Z)-4 
 
        3*4/QUANTITY          equals          (3*4)/QUANTITY 
        12/QUANTITY*3         equals          (12/QUANTITY)*3 

The following priorities take precedence over the left to right evaluation rule:

  1. INTOUCH always evaluates expressions in parentheses first. Parentheses, ( ), can be used to change the order of any of the following operations. If parentheses are nested, INTOUCH evaluates them from the inside out. For example:

                    Z%-(X% / (Y% + AMOUNT)) 
    

    INTOUCH evaluates the expression Y% + AMOUNT first. Next, it divides the X% by AMOUNT to determine that result. Finally, it subtracts the entire sum from Z%.
  2. INTOUCH performs functions second.
  3. INTOUCH performs exponentiation.
  4. INTOUCH performs multiplication and division.
  5. INTOUCH performs addition and subtraction.
  6. INTOUCH performs relational operations from left to right. (The relational operators are: =, <, >, <=, >= and <>.) The only exception is the assignment of the result. The result is always assigned last.
  7. INTOUCH performs logical operations in the following order:
    • NOT
    • AND
    • OR
    • XOR
    • IMP
    • EQV


Chapter 4
Writing and Debugging INTOUCH Programs

This chapter describes some statements that are used in basically all INTOUCH programs. It also describes the INTOUCH debug facilities and how to use them.

4.1 Comments

You might want to include comments in programs. Comments are not executable statements. They are simply included in source code for informational purposes. They are seen when a program is listed or printed out. However, INTOUCH will ignore them when it executes a program.

There are two types of comments allowed in INTOUCH: REM comments and exclamation points (!). The following example shows each of these statements in use:

        10  DIM name$(10)                                 ! Setup array 
        20  REM Main logic 
            FOR i = 1 TO 10                               ! Begin the loop 
              INPUT 'Please enter your name': name$(i)    ! Ask for a name 
              IF  _EXIT  THEN  EXIT FOR                   ! End if they want 
              PRINT 'Hello, '; name$(i)                   ! Print hello 
            NEXT i                                        ! End the loop 
        30  END 
 
        RNH 
        Please enter your name? Mary 
        Hello, Mary 
        Please enter your name? exit 

4.1.1 REM

FORMAT:

        REM comment_text 

EXAMPLE:

        10  REM Get a name 
            INPUT 'Please enter your name': name$ 
        20  PRINT 'Hello, '; name$ 
        30  END 
 
        RNH 
        Please enter your name? Lucy 
        Hello, Lucy 

PURPOSE:

Use REM to put remarks on program lines. You can use these remarks to clarify your code.

DESCRIPTION:

When a program is listed on the screen or printed out, the REM lines are displayed exactly as they were written in the source code.

A REM statement must be placed at the beginning of a program line. INTOUCH ignores the REM statement and everything after it up until the end of the line and it continues execution at the next executable line. REM can be used anywhere in a multiple line statement. For example:

        10  INPUT 'Please enter your name': name$ 
            REM Print hello 
            PRINT 'Hello, '; name$ 
        20  END 
 
        RNH 
        Please enter your name? Lucy 
        Hello, Tom 

When the above program is run, INTOUCH executes the INPUT statement, ignores the REM statement, and then executes the PRINT and END statements.

4.1.2 ! comment_text

FORMAT:

        ! comment_text 

EXAMPLE:

        10  INPUT 'Please enter your name': name$    ! Ask for a name 
            PRINT 'Hello, '; name$                   ! Say hello 
        20  END 
 
        RNH 
        Please enter your name? Mike 
        Hello, Mike 

PURPOSE:

Use the ! to put comments in a program.

DESCRIPTION:

You can use comments to clarify parts of your program as shown in the example above.

When the program is listed or printed, the "!" line is displayed as it was written in the source code.

When INTOUCH executes the above program, it executes the INPUT statement, ignores the "!" and the comment text following it and continues execution at the PRINT statement. The "!" does not have to be placed at the beginning of a physical line. It can be used anywhere on a program line.

The Exclamation Point with Line Continuation

The exclamation point can be used after an ampersand to document continued lines. When a line is continued with an ampersand, any comments must follow the ampersand. For example:

        10  INPUT a$ 
            IF  a$ = ''  THEN  PRINT a$; &     ! Here is the trailing 
                ' is OK.'                      ! comment text 
        20 END 

4.1.3 ~ Used to Border Part of a Program

EXAMPLE:

        10  DIM name$(10)                                 ! Setup array 
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~    
        20  REM Main logic 
            FOR i = 1 TO 10                               ! Begin the loop 
              INPUT 'Please enter your name': name$(i)    ! Ask for a name 
              IF  _EXIT  THEN  EXIT FOR                   ! End if they want 
              PRINT 'Hello, '; name$(i)                   ! Print hello 
            NEXT i                                        ! End the loop 
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~    
        30  END 

PURPOSE:

Use the TILDE to highlight and/or border parts of your program source code.

DESCRIPTION:

The tilde can be used to clarify or highlight code. Tildes appear when the program is listed or printed but INTOUCH ignores them when it executes the program. Tildes within quotes ('~~') are treated as string constants.

4.2 PROGRAM, END, STOP and HALT Statements

4.2.1 PROGRAM

FORMAT:

        PROGRAM prog_name 

EXAMPLE:

        10  PROGRAM DISPLAY_NAME 
        20  INPUT 'Please enter your name': name$ 
            PRINT 'Hello, '; name$ 
        30  END 

PURPOSE:

Use the PROGRAM statement to name your program.

DESCRIPTION:

PROGRAM is used to name programs. prog_name is the program name. The program name must meet the specifications for variable names. It must:

4.2.2 END

FORMAT:

        END 

EXAMPLE:

        10  INPUT 'Please enter your name': name$ 
        20  PRINT 'Hello, '; name$ 
        30  END 
 
        RNH 
        Please enter your name? John 
        Hello, John 

PURPOSE:

Use the END statement to end program execution. If you have EXTERNAL subprograms or functions, use END to mark the end of the main program unit.

DESCRIPTION:

The END statement marks the end of a program. When INTOUCH executes the END statement, it:

The END statement does not have to be the last physical line in a program. If you have subprograms, functions, etc., they can physically follow the END statement. However, END marks the end of the source code for the main program unit.

4.2.3 STOP

FORMAT:

        STOP 

EXAMPLE:

        10  INPUT 'Please enter your name': name$ 
            INPUT 'How old are you': age 
            IF  age < 1  THEN 
              PRINT 'Not a valid age' 
              STOP 
            END IF 
        20  PRINT name$; ' is'; age 
        30  END 
 
        RNH 
        Please enter your name? Ted 
        How old are you? 38 
        Ted is 38 

PURPOSE:

Use STOP to terminate program execution where you do not want to mark the physical end of your program.

DESCRIPTION:

STOP behaves exactly as the END statement does. However, STOP does not mark the end of a program.

STOP ends program execution and returns control to the INTOUCH environment. For instance, the example program would run as follows:

        RNH 
        Please enter your name? Ted 
        How old are you? .5 
        Not a valid age 
 
        INTOUCH 

4.2.4 HALT

FORMAT:

        HALT 

EXAMPLE:

        10  INPUT 'Please enter your name': name$ 
            INPUT 'How old are you': age 
            IF  age < 1  THEN 
              PRINT 'Not a valid age' 
              HALT 
            END IF 
        20  PRINT name$; ' is'; age 
        30  END 
 
        RNH 
        Please enter your name? Tex 
        How old are you? 0 
        Not a valid age 
        Halt at 10.4 
 
        INTOUCH 

PURPOSE:

Use HALT if you want to interrupt program execution, check values, and then continue execution.

DESCRIPTION:

HALT interrupts program execution, but it does not close any files, nor does it write the active output buffer. HALT interrupts program execution and returns to the INTOUCH prompt. Execution can be continued with the GO command.

The EXAMPLE program would run as follows:

        RNH 
        Please enter your name? Tex 
        How old are you? 0 
        Not a valid age 
        Halt at 10.4 
 
        INTOUCH 
 
        let age = 34 
 
        INTOUCH 
 
        go 
        Tex is 34 


Next page... | Table of Contents