INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous page... Table of Contents

11.11.2 ON...GOSUB

FORMAT:

        ON int_expr GOSUB target1 [, target2...] [ELSE statement] 

EXAMPLE:

        10  start: INPUT 'Procedure (1=add, 2=del, 3=exit)': pro 
        20  ON pro GOSUB add, del, done ELSE PRINT 'Enter 1, 2 or 3' 
            GOTO start 
            add: 
              PRINT 'Adding...' 
              RETURN 
            del: 
              PRINT 'Deleting...' 
              RETURN 
        30  done: 
            PRINT 'Finished' 
            END 
 
        RNH 
        Procedure (1=add, 2=del, 3=exit)? add 
        Non-numeric input when number expected at START 
        Procedure (1=add, 2=del, 3=exit)? 5 
        Enter 1, 2 or 3 
        Procedure (1=add, 2=del, 3=exit)? 1 
        Adding... 
        Procedure (1=add, 2=del, 3=exit)? 3 
        Finished 

PURPOSE:

Use ON..GOSUB when you want to jump to one of several subroutines depending on a condition you set up. ON..GOSUB jumps to one of the locations, executes the code at that location and then returns to the first statement after the ON..GOSUB.

DESCRIPTION:

ON..GOSUB transfers control to one of several subroutines depending on the value of an integer expression. The simplest version of ON..GOSUB is:

        ON int_expr GOSUB target1, target2... 

int_expr is an integer expression whose value determines where control is transferred. The targets begin subroutines. They can be ROUTINE statements, labels or line numbers. The subroutines are blocks of code. When INTOUCH branches to a subroutine, it executes the block of code until it reaches a RETURN or END ROUTINE statement. INTOUCH then returns to the statement following the ON..GOSUB.

When INTOUCH executes the ON GOSUB, it evaluates the integer expression. If the value is one, INTOUCH branches to the first target and executes the subroutine. If the integer is two, INTOUCH branches to the second subroutine, and so on.

int_expr must evaluate to an integer. If it does not, INTOUCH rounds the value and uses the resulting integer. The integer expression must yield an integer within the range of the target list. For example, if there are five targets in the list, the integer value must be in the range of 1 to 5. If the integer value is not in the range of the target list, and there is no ELSE clause, an exception is generated.

INTOUCH supports 128 targets for ON..GOSUB. More targets than 128 gives an "expression too complex" exception.

11.11.2.1 ELSE Option

The ELSE option executes a statement if the integer value does not yield a target. ON GOSUB with the ELSE option looks like this:

        ON int_expr GOSUB target1, target2... ELSE statement 

ELSE must be followed by a statement. The ELSE is executed if the integer value exceeds the number of targets in the list, is 0 or is negative.

The previous example shows how ELSE is used.

11.12 DISPATCH

FORMAT:

        DISPATCH str_expr 
             . 
             . 
             . 
        target 
             --- 
             ---  block of code 
             --- 
        RETURN 

EXAMPLE:

        10  INPUT 'Routine name', DEFAULT 'add': routine$ 
            DISPATCH routine$ 
            STOP 
        20  add: 
              PRINT 'Adding information...' 
            RETURN 
 
        30  change: 
              PRINT 'Changing information...' 
            RETURN 
 
        40  END 
 
        RNH 
        Routine name? add 
        Adding information... 

PURPOSE:

DISPATCH executes a routine that the program determines at run-time.

DESCRIPTION:

DISPATCH looks at the contents of the string expression (str_expr), searches for a routine with that name and GOSUBS to the routine.

str_expr is the name of the subroutine to execute.

11.13 ROUTINE/END ROUTINE

FORMAT:

        ROUTINE routine_name 
           --- 
           --- block of code 
           --- [REPEAT ROUTINE] 
           --- [EXIT ROUTINE] 
        END ROUTINE          

EXAMPLE:

        10      get_username 
        20      END 
 
        12000   ROUTINE get_username 
                  INPUT PROMPT 'Username: ': uname$ 
                  IF  _BACK  or  _EXIT  THEN  EXIT ROUTINE 
                END ROUTINE 
 
        RNH 
        Username: Tester 

DESCRIPTION:

ROUTINES are block-structured subroutines. They provide a convenient way to name a block of code. Routines can be edited as a complete unit, or partially edited by line number.

To execute a ROUTINE, use the GOSUB or DISPATCH statement or just the name of the routine. You CANNOT fall into a routine the way you can a subroutine that starts with a label.

11.13.1 EXIT ROUTINE

FORMAT:

        EXIT ROUTINE 

DESCRIPTION:

The EXIT ROUTINE statement enables you to exit from the executed routine.

The above example shows how EXIT ROUTINE can be used.

11.13.2 REPEAT ROUTINE

FORMAT:

        REPEAT ROUTINE 

EXAMPLE:

        10      get_username 
        20      END 
 
        12000   ROUTINE get_username 
                  INPUT PROMPT 'Username: ': uname$ 
                  IF  _BACK  or  _EXIT  THEN  EXIT ROUTINE 
                  IF  uname$ = ''  THEN  REPEAT ROUTINE 
                END ROUTINE 
 
        RNH 
        Username: 
        Username: Sunny 

DESCRIPTION:

The REPEAT ROUTINE statement enables you to repeat the entire routine execution. When INTOUCH executes the REPEAT ROUTINE statement, the routine is re-executed.


Chapter 12
Exception Handling

Exception handling routines intercept run-time exceptions and execute a block of code which handles them. If you do not have an exception handler, INTOUCH returns an exception message specifying what the exception was and where it occurred. INTOUCH stops program execution or tries the offending statement again.

There are two types of exception handlers: attached handlers and detached handlers.

When you have an attached handler, you use a WHEN EXCEPTION IN statement. WHEN EXCEPTION IN puts the handler (the block of code to execute) right after the block of code it protects.

You can also have a detached handler. For a detached handler, use the statement WHEN EXCEPTION USE. When an exception occurs in the protected block, WHEN EXCEPTION USE calls a handler routine located in some other part of the program. The same handler routine can be used by any number of WHEN EXCEPTION USE statements and can be placed anywhere in your program.

This section explains exception handlers. It also describes the handling statements--RETRY, CONTINUE and EXIT HANDLER.

The following functions are also related to exception handling:

For a full description of these functions, see Section A.2, Other Functions.

12.1 CAUSE EXCEPTION

FORMAT:

        CAUSE EXCEPTION exception_number 

EXAMPLE:

        10  DO 
              INPUT 'Select a number between 1 and 10': no 
              IF  no < 1  OR  no > 10  THEN  CAUSE EXCEPTION 1001 
              REPEAT DO 
            END DO 
        20  END 
 
        RNH 
        Select a number between 1 and 10? 8 
        Select a number between 1 and 10? 99 
        Illegal number at 10.2 

PURPOSE:

Use CAUSE EXCEPTION when you need to generate an exception under specific conditions.

DESCRIPTION:

CAUSE EXCEPTION causes the specified exception to occur. exception_number can be any integer expression. When INTOUCH executes the CAUSE EXCEPTION statement, it generates the exception specified. See Section C.2, Exceptions for a list of exception messages.

12.2 WHEN EXCEPTION IN

FORMAT:

        WHEN EXCEPTION IN 
          --- 
          ---  protected block 
          --- 
        USE 
          --- 
          ---  handler 
          --- 
        END WHEN 

EXAMPLE:

        10  INPUT 'Your name, please': name$ 
            WHEN EXCEPTION IN 
              INPUT 'How old are you': age 
            USE 
              PRINT 'Not a valid age' 
              RETRY 
            END WHEN 
            PRINT 
            PRINT NAME$; ' is'; age 
        20  END 
 
        RNH 
        Your name, please? Tester 
        How old are you? 3x 
        Not a valid age 
        How old are you? 35 
 
        Tester is 35 

PURPOSE:

Use WHEN EXCEPTION IN to catch run-time exceptions and resolve them within your program when you want the code, handling the exception, to be next to the code you are protecting.

DESCRIPTION:

WHEN EXCEPTION IN begins the protected block of code. Everything between the WHEN EXCEPTION IN and USE statements constitutes the section of code protected by the handler---the protected block.

USE begins the handler routine. Everything between the USE and the END WHEN statements constitutes the handler. If an exception occurs in the protected block, the handler code is executed. END WHEN ends the routine.

12.3 WHEN EXCEPTION USE

FORMAT:

        WHEN EXCEPTION USE handl_name 
          ---               
          ---  protected block 
          --- 
        END WHEN 
                 . 
                 . 
                 . 
        HANDLER handl_name 
          --- 
          ---  handler 
          --- 
        END HANDLER 

EXAMPLE:

        10  INPUT 'Enter total sales amount': tsales 
            INPUT 'Enter number of sales': nsales 
            WHEN EXCEPTION USE fix_average 
              average = tsales/nsales 
            END WHEN 
            PRINT 'The average is:'; average 
 
        20  HANDLER fix_average 
              average = 0 
              CONTINUE 
        30  END HANDLER 
        40  END 
 
        RNH 
        Enter total sales amount? 25.00 
        Enter number of sales? 0 
        The average is: 0 

PURPOSE:

Use WHEN EXCEPTION USE to catch run-time exceptions and resolve them within a program when you need the same handler for several protected blocks, or when you want all the handlers in one place in your program.

DESCRIPTION:

WHEN EXCEPTION USE begins the protected block of code and specifies the HANDLER routine to use. handl_name is the name of the handler routine. The handler name must meet the specifications for variable names. The protected block is everything between the WHEN EXCEPTION USE and the END WHEN statements. If an exception occurs in this block of code, INTOUCH calls the handler specified. If the handler does not exist, an error is generated.

HANDLER begins the handler routine. Everything between the HANDLER and the END HANDLER constitutes the handler routine. END HANDLER returns control to the statement following the END WHEN. When the handler is called, this block of code is executed. In the example above, INTOUCH would normally return an exception when it tried to divide 25.00 by 0. The exception handler FIX_AVERAGE intercepts this exception and sets AVERAGE equal to 0.

The handler routine can occur before or after the protected block. For example:

        10  HANDLER fix_average 
              average = 0               <--- handler routine 
              CONTINUE 
            END HANDLER 
 
        20  INPUT 'Enter total sales amount': tsales 
            INPUT 'Enter number of sales': nsales 
            WHEN EXCEPTION USE fix_average 
              average = tsales/nsales 
            END WHEN 
        30  PRINT 'The average is'; average 
        40  END 

One of the advantages of WHEN EXCEPTION USE is that the same handler routine can be called by any number of WHEN EXCEPTION USE statements. For example:

        10  WHEN EXCEPTION USE numbers 
              INPUT 'How old are you': age      <--- first protected block 
            END WHEN 
 
        20  INPUT 'Your name, please': name$ 
 
        30  WHEN EXCEPTION USE numbers 
              INPUT 'Your birthdate': birth     <--- second protected block 
            END WHEN 
 
        40  PRINT name$; ' was born on'; birth 
 
        50  HANDLER numbers 
              PRINT 'Enter numbers only, please.'    <--- handler routine 
              RETRY 
            END HANDLER 
        60  END 

12.4 HANDLER Routine Actions

12.4.1 RETRY

FORMAT:

        USE 
          --- 
          ---  RETRY 
          --- 
        END WHEN 
 
           or 
        
        HANDLER handl_name 
          --- 
          ---  RETRY 
          --- 
        END HANDLER 

EXAMPLE:

        10  INPUT 'Your name, please': name$ 
        20  WHEN EXCEPTION IN 
              INPUT 'How old are you': age 
            USE 
              PRINT 'Not a valid age' 
              RETRY 
            END WHEN 
        30  PRINT 
            PRINT name$; ' is'; age 
        40  END 
 
        RNH 
        Your name, please? Tester 
        How old are you? 3x 
        Not a valid age 
        How old are you? 35 
 
        Tester is 35 

PURPOSE:

Use RETRY after an exception to re-execute the statement that generated the exception.

DESCRIPTION:

RETRY can only be used in a HANDLER routine. RETRY causes INTOUCH to leave the handler and re-execute the statement that generated an exception.

12.4.2 CONTINUE

FORMAT:

        USE 
          --- 
          ---  CONTINUE 
          --- 
        END WHEN 
 
           or 
 
        HANDLER handl_name 
          --- 
          ---  CONTINUE 
          --- 
        END HANDLER 

EXAMPLE:

        10  INPUT 'Enter total sales amount': tsales 
            INPUT 'Enter number of sales': nsales 
        20  WHEN EXCEPTION USE fix_average 
              average = tsales / nsales 
            END WHEN 
        30  PRINT 'The average is:'; average 
 
        40  HANDLER fix_average 
              average = 0 
              CONTINUE 
            END HANDLER 
        50  END 
 
        RNH 
        Enter total sales amount? 18.00 
        Enter number of sales? 0 
        The average is: 0 

PURPOSE

Use CONTINUE to continue normal program execution at the statement following the one that generated the exception.

DESCRIPTION:

CONTINUE causes INTOUCH to exit the exception handler and continue program execution at the first statement following the statement which generated the exception. CONTINUE can only be used in a HANDLER routine.

12.4.3 RESUME

FORMAT:

        USE 
          --- 
          ---  RESUME target 
          --- 
        END WHEN 
 
           or 
 
        HANDLER handl_name 
          --- 
          ---  RESUME target 
          --- 
        END HANDLER 

EXAMPLE:

        10  INPUT 'Enter total sales amount': tsales 
            INPUT 'Enter number of sales': nsales 
        20  WHEN EXCEPTION USE fix_average 
              average = tsales / nsales 
            END WHEN 
        30  PRINT 'The average is:'; average 
 
        40  HANDLER fix_average 
              average = 0 
              PRINT 'Invalid numbers.  Try again.' 
              RESUME 10 
            END HANDLER 
        50  END 
 
        RNH 
        Enter total sales amount? 75.00 
        Enter number of sales? 0 
        Invalid numbers.  Try again. 
        Enter total sales amount? 75.00 
        Enter number of sales? 3 
        The average is: 25 

PURPOSE:

Use RESUME to resume normal program execution at the statement label that you specify.

DESCRIPTION:

RESUME causes INTOUCH to exit the exception handler and resume program execution at the target line specified. The target can be a line number or a label.

RESUME can only be used in a handler routine.

12.4.4 EXIT HANDLER

FORMAT:

        USE 
          --- 
          ---  EXIT HANDLER 
          --- 
        END WHEN 
 
           or 
 
        HANDLER handl_name 
          --- 
          ---  EXIT HANDLER 
          --- 
        END HANDLER 

EXAMPLE:

        10  WHEN EXCEPTION USE mistake 
              INPUT 'Enter your age': age 
            END WHEN 
            PRINT 'You are'; age; 'years old' 
 
        20  HANDLER mistake 
              PRINT 'Oops...' 
              DELAY 2 
              EXIT HANDLER 
            END HANDLER 
        30  END 
 
        RNH 
        Enter your age? 3x 
        Oops... 
        Non-numeric input when number expected at 10.1 
        Enter your age? 35 
        You are 35 years old 

PURPOSE:

Use EXIT HANDLER to exit a handler routine and pass the exception up to the next level of exception handling.

DESCRIPTION:

EXIT HANDLER exits the current HANDLER routine. If the current handler is nested within another handler, INTOUCH jumps to the outside handler and executes the code for that handler. If there is no other exception handler, control returns to the INTOUCH system. INTOUCH prints the exception message and takes whatever action it normally would.

EXIT HANDLER can only be used within an exception handler.


Chapter 13
Calling Routines Written In Other Languages

You can call routines written in other languages and run them from an INTOUCH program.

Callable routines are stored in libraries. The LIBRARY statement tells INTOUCH what library a routine is located in. You must use the LIBRARY statement to specify where routines are located before you call them in your program.

The CALL statement calls routines and executes them. You can call any routine in a shared VMS library and execute it. The CALL and LIBRARY statements make your programs more powerful, more versatile, and give you more programming options.

13.1 LIBRARY

FORMAT:

        LIBRARY 'libr_name' 

EXAMPLE:

        10  LIBRARY 'BASRTL' 
        20  PRINT 'Waiting 5 seconds...' 
        30  CALL BAS$SLEEP(5% BY VALUE) 
        40  END 
 
        RNH 
        Waiting 5 seconds... 

DESCRIPTION:

You can use the LIBRARY statement to specify the libraries you will use in your program.

The LIBRARY statement specifies libraries from which you CALL routines. The routines can be written in any VMS language that supports the standard calling interface (FORTRAN, BASIC, COBOL, etc.).

libr_name is the file specification of a library. The library can be one of the VMS supplied libraries, or a user-defined library. You must name a library with the LIBRARY statement before you call a routine from it. The library name must be a string constant in quotes.

To create libraries for INTOUCH, you can refer to Appendix E, Creating Libraries for Use with INTOUCH.

13.2 CALL

FORMAT:

        CALL routine_name(arg [BY pass_mech], arg...) 

EXAMPLE:

        10  LIBRARY 'BASRTL' 
        20  PRINT 'Waiting 5 seconds...' 
        30  CALL BAS$SLEEP(5% BY VALUE) 
        40  END 
 
        RNH 
        Waiting 5 seconds... 

DESCRIPTION:

You can use the CALL statement to call and execute library routines. You can use these routines to perform procedures rather than writing the code yourself.

The library to which the routine belongs must have been specified in a LIBRARY statement.

routine_name is the name of the routine you are calling. Some routines take arguments. arg is an argument you are passing to or getting from the routine. If more than one argument is passed, separate the arguments with commas:

        CALL routine_name(arg, arg, arg...) 

13.2.1 Optional Arguments

Some routines have optional arguments--arguments which can be used, but do not have to be used. To pass an optional argument, include it in the appropriate place in the argument list. If you do not want to pass an optional argument, specify that no argument is to be used by typing two commas side by side at the appropriate place in the argument list.

For example, the routine LIB$GET_INPUT gets a record of ASCII text. Its argument list contains two optional arguments:

        LIB$GET_INPUT(get-str.wt.dx [,prompt-str.rt.dx [,out-len.wwu.r]]) 
                         |                 |                  | 
            string variable the      a prompt string        length of the 
            input is assigned to                           string variable 

To input a line without using a prompt string, your CALL statement would have the following format:

        CALL routine_name(str_var,,num_var) 

The double commas tell INTOUCH that the optional variable prompt-str is not used. For example:

        10  LIBRARY 'LIBRTL' 
            BUF$ = REPEAT$(' ', 200) 
            CALL LIB$GET_INPUT(BUF$, , OUT_LEN%) 
            PRINT 'You typed: ';BUF$[1:OUT_LEN%] 
        20  END 

13.2.2 Passing Mechanisms

pass_mech refers to the mechanism by which values are passed to the routine. The default passing mechanism for reals and integers is by reference. The default passing mechanism for strings is by descriptor. Here is an explanation of the passing mechanisms available:
BY REF By reference. This is the default passing mechanism for real and integer data. Arguments passed by reference can be changed by the routine they are passed to.
BY VALUE By value. Arguments passed by value cannot be changed by the routine they are passed to.
BY DESC By descriptor. This is the default passing mechanism for strings. By descriptor causes INTOUCH to use the argument's descriptor when passing the argument. Arguments passed by descriptor can be changed by the routine they are passed to.

The system functions _REAL and _INTEGER can be used in conjunction with the library statements. These functions return resulting data associated with the CALL. (See Section A.1, System Functions for more information.)


Next page... | Table of Contents