INTOUCH® 4GL
A Guide to the INTOUCH Language
Previous Contents Index

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

4.2.5 RANDOMIZE

FORMAT:


        RANDOMIZE

EXAMPLE:


        10  RANDOMIZE 
        20  x = RND 
            PRINT x 
        30  END 
 
        RNH 
         .244013674718 
 
        INTOUCH 
 
        RNH 
         .524856061388

PURPOSE:

RANDOMIZE gives the RND function a new starting point. This ensures that you will get a different random number sequence each time your program executes.

DESCRIPTION:

INTOUCH uses a list of random numbers when the RND function is used. If no RANDOMIZE statement is used, INTOUCH starts at the same place in this list each time the program executes. This means the same series of random numbers is returned each time the program executes.

RANDOMIZE tells INTOUCH to pick a random starting point in the list. This ensures that a different series of random numbers is returned each time the program executes. (See RND for information on the RND function.)

4.3 Debug Facilities

INTOUCH detects and announces run-time and compile-time errors. Sometimes errors occur which don't prevent execution, but cause a program to execute incorrectly. INTOUCH provides a high-level DEBUG system for detecting these more subtle errors.

DEBUG ON enables INTOUCH's Debug System. DEBUG OFF disables the system. When DEBUG is enabled, a DEBUG flag will appear at the status message in the upper right corner of the INTOUCH screen. When DEBUG is disabled, the flag disappears from the screen. DEBUG ON turns on the frame if it was off.

The related function for the INTOUCH Debug System is _DEBUG. See _DEBUG for information on the _DEBUG system function.

Some DEBUG features automatically switch DEBUG ON or OFF when they are executed. Others require that DEBUG be enabled. (See DEBUG ON.)

Note
Using the debugging facilities impacts the INTOUCH system's performance. The system has been designed for optimal performance in a normal production environment. Therefore, DEBUG will slow INTOUCH response time.

4.4 DEBUG ON/OFF

4.4.1 DEBUG ON

FORMAT:


        DEBUG ON

EXAMPLE:


        DEBUG ON 
        1050 DEBUG ON

PURPOSE:

Use DEBUG ON to enable INTOUCH's debug system. The DEBUG system helps you find problems in the way your program runs. You must enable the system in order to use its features.

DESCRIPTION:

When DEBUG is enabled, all of INTOUCH's DEBUG features are available. DEBUG remains enabled until a DEBUG OFF command or statement is executed or until a DEBUG feature is executed which disables it.

DEBUG ON can be issued in immediate mode or as a statement in a program. If DEBUG ON is used in a program, INTOUCH enables DEBUG when it encounters the DEBUG ON statement. After you turn DEBUG ON, you must use RUN or RNH to start the program before you can use the STEP statement.

4.4.2 DEBUG OFF

FORMAT:


        DEBUG OFF

EXAMPLE:


        DEBUG OFF 
        1050 DEBUG OFF

PURPOSE:

Use DEBUG OFF to disable INTOUCH's DEBUG system. You should turn DEBUG OFF when you have finished correcting your program.

DESCRIPTION:

DEBUG OFF can be issued in immediate mode or as a statement in a program. If DEBUG OFF is used in a program, INTOUCH disables DEBUG when it encounters the DEBUG OFF statement.

DEBUG will remain disabled until a DEBUG ON statement is executed, or until a DEBUG feature is executed which enables it.

4.5 Monitoring Program Execution

DEBUG's TRACE and STATISTICS features monitor your program's execution. These features take effect only during program execution.

TRACE traces your program line by line as it executes. TRACE lists the number of each program line as it is executed. STATISTICS records information on your program's execution. It records the time each program line takes to execute and the number of times the line is executed. The word "STATISTICS" can be abbreviated to "STATS" (STATS ON, STATS OFF, LIST STATS). This abbreviation will be used frequently in this Guide.

4.6 The TRACE and STATISTICS Features

Both the TRACE and STATISTICS features operate on program lines. A number of program lines can be attached to one line number. 


        10  PRINT a$ 
            PRINT b$ 
            PRINT c$

The TRACE feature notes these program lines by line number. For instance: 


        10  PRINT a$ --- 10

If more than one program line is attached to a line number, the program lines are denoted by a period and the number of the sub-line. 


        10  PRINT a$ --- 10 
            PRINT b$ --- 10.1 
            PRINT c$ --- 10.2

In the example above, the first line is noted as 10. The program line following the first line is 10.1. The next line is 10.2 and so on. Labels are noted in the same way. For example: 


        10  show: PRINT a$ --- SHOW 
            PRINT b$       --- SHOW.1 
            PRINT c$       --- SHOW.2

4.6.1 TRACE ON

FORMAT:


        TRACE ON

EXAMPLE:


        TRACE ON 
        1050 TRACE ON

PURPOSE:

Use TRACE ON to turn INTOUCH's trace feature on. The trace feature lists the number of each program line as it is executed. Use TRACE to see if your statements are being executed in the correct order and the correct number of times.

DESCRIPTION:

To use TRACE, you must have the frame on.

TRACE ON enables INTOUCH's trace feature. The trace feature lists each program line as it is executed. TRACE ON can be executed as a command or as a statement. If TRACE ON is executed as a command, DEBUG is automatically switched on. If TRACE ON is executed as a statement, and DEBUG is off, INTOUCH ignores the TRACE ON. The following program is executed with the trace feature on: 


        10  DIM name$(5) 
            MAIN: FOR i = 1 TO 5 
                    INPUT 'Please enter your name': name$(i) 
                    IF  _EXIT  THEN  EXIT FOR 
                    PRINT 'Hello, '; name$(i); '!' 
                  NEXT i 
        20  END

Example 4-1 Debug TRACE ON Example 


INTOUCH                       Program: NONAME                             DEBUG 
The Next Generation Language  Status :   RUN                                    
 
 
 
INTOUCH
 
TRACE ON 
 
INTOUCH
 
RNH 
Please enter your name? John 
Hello, John! 
Please enter your name? 
                  [10]  [MAIN]  [MAIN.1]  [MAIN.2]  [MAIN.3]  [MAIN.4]  [MAIN.1]
                                                                                
EXIT = Exit                                                \ = Back  HELP = Help

The trace remains in effect until a TRACE OFF command or statement is executed. When program execution stops, the trace stops. If program execution continues and the TRACE ON command is still in effect, the trace continues.

4.6.2 TRACE OFF

FORMAT:


        TRACE OFF

EXAMPLE:


        TRACE OFF 
        1050 TRACE OFF

PURPOSE:

Use TRACE OFF to turn the trace feature off.

DESCRIPTION:

TRACE OFF disables the trace feature. INTOUCH stops listing program line numbers when TRACE OFF is executed. If TRACE OFF is executed as a statement in a program and DEBUG is off, INTOUCH ignores the statement.

4.6.3 STATS ON

FORMAT:


        STATS ON

EXAMPLE:


        STATS ON 
        1020 STATS ON

PURPOSE:

Use STATS ON to turn on the statistics feature, which stores the execution time and count for each program line. Use STATS to tell if your statements are being executed the correct number of times and which parts of your program are taking the most time. STATS is especially useful for speeding up your program's execution time.

DESCRIPTION:

STATS ON enables INTOUCH's statistics feature. INTOUCH begins recording statistics when program execution begins. The statistics feature remains enabled until the STATS OFF statement is executed.

STATS ON can be executed in immediate mode or in a program. If STATS ON is executed in immediate mode, DEBUG is automatically switched on. If STATS ON is executed in a program, and DEBUG is off, INTOUCH ignores the statement. When STATS ON is executed, any statistics previously recorded are lost.

4.6.4 STATS OFF

FORMAT:


        STATS OFF

EXAMPLE:


        STATS OFF 
        1020 STATS OFF

PURPOSE:

Use STATS OFF to turn off the statistics feature.

DESCRIPTION:

STATS OFF turns off INTOUCH's statistics feature. STATS OFF can be executed in immediate mode or in a program. If STATS OFF is executed in a program and DEBUG is off, INTOUCH ignores the statement. STATS OFF leaves DEBUG on.

4.6.5 LIST STATS

FORMAT:


        LIST STATS [:label | line_num [- | ,] label | line_num...]

Previous Next Contents Index