B ON int_expr GOSUB target1 [, target2...] [ELSE statement]
A 10 start: INPUT 'Procedure (1=add, 2=del, 3=exit)': pro E 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 8 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
= Use ON..GOSUB when you want to jump to one of several F subroutines depending on a condition you set up. ON..GOSUB jumps to J one of the locations, executes the code at that location and then returns , to the first statement after the ON..GOSUB.
G ON..GOSUB transfers control to one of several subroutines depending on K the value of an integer expression. The simplest version of ON..GOSUB is:
. ON int_expr GOSUB target1, target2...
F int_expr is an integer expression whose value determines where E control is transferred. The targets begin subroutines. They can be K ROUTINE statements, labels or line numbers. The subroutines are blocks of L code. When INTOUCH branches to a subroutine, it executes the block of code J until it reaches a RETURN or END ROUTINE statement. INTOUCH then returns * to the statement following the ON..GOSUB.
J When INTOUCH executes the ON GOSUB, it evaluates the integer expression. K If the value is one, INTOUCH branches to the first target and executes the O subroutine. If the integer is two, INTOUCH branches to the second subroutine, and so on.
F int_expr must evaluate to an integer. If it does not, INTOUCH I rounds the value and uses the resulting integer. The integer expression I must yield an integer within the range of the target list. For example, H if there are five targets in the list, the integer value must be in the I 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.
I INTOUCH supports 128 targets for ON..GOSUB. More targets than 128 gives ' an "expression too complex" exception.
A The ELSE option executes a statement if the integer value I does not yield a target. ON GOSUB with the ELSE option looks like this:
= ON int_expr GOSUB target1, target2... ELSE statement
F ELSE must be followed by a statement. The ELSE is executed if H the integer value exceeds the number of targets in the list, is 0 or is negative.
- The previous example shows how ELSE is used.
DISPATCH str_expr . . . target --- --- block of code --- RETURN
: 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...
? DISPATCH executes a routine that the program determines at run-time.
8 DISPATCH looks at the contents of the string expression D (str_expr), searches for a routine with that name and GOSUBS to the routine.
: str_expr is the name of the subroutine to execute.
ROUTINE routine_name --- --- block of code --- [REPEAT ROUTINE] --- [EXIT ROUTINE] END ROUTINE
10 get_username 20 END % 12000 ROUTINE get_username 4 INPUT PROMPT 'Username: ': uname$ ; IF _BACK or _EXIT THEN EXIT ROUTINE END ROUTINE RNH Username: Tester
@ ROUTINES are block-structured subroutines. They provide G a convenient way to name a block of code. Routines can be edited as a 3 complete unit, or partially edited by line number.
K To execute a ROUTINE, use the GOSUB or DISPATCH statement or just the name L of the routine. You CANNOT fall into a routine the way you can a subroutine that starts with a label.
EXIT ROUTINE
? The EXIT ROUTINE statement enables you to exit from the executed routine.
6 The above example shows how EXIT ROUTINE can be used.
REPEAT ROUTINE
10 get_username 20 END % 12000 ROUTINE get_username 4 INPUT PROMPT 'Username: ': uname$ ; IF _BACK or _EXIT THEN EXIT ROUTINE 8 IF uname$ = '' THEN REPEAT ROUTINE END ROUTINE RNH Username: Username: Sunny
> The REPEAT ROUTINE statement enables you to repeat the D entire routine execution. When INTOUCH executes the REPEAT ROUTINE ' statement, the routine is re-executed.
F Exception handling routines intercept run-time exceptions and execute E a block of code which handles them. If you do not have an exception B handler, INTOUCH returns an exception message specifying what the F exception was and where it occurred. INTOUCH stops program execution ( or tries the offending statement again.
A There are two types of exception handlers: attached handlers and detached handlers.
F When you have an attached handler, you use a WHEN EXCEPTION IN E statement. WHEN EXCEPTION IN puts the handler (the block of code to 4 execute) right after the block of code it protects.
= You can also have a detached handler. For a detached P handler, use the statement WHEN EXCEPTION USE. When an exception occurs in the D protected block, WHEN EXCEPTION USE calls a handler routine located D in some other part of the program. The same handler routine can be F used by any number of WHEN EXCEPTION USE statements and can be placed anywhere in your program.
A This section explains exception handlers. It also describes the 7 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.
) CAUSE EXCEPTION exception_number
10 DO ; INPUT 'Select a number between 1 and 10': no H 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
8 Use CAUSE EXCEPTION when you need to generate an % exception under specific conditions.
9 CAUSE EXCEPTION causes the specified exception to occur. E exception_number can be any integer expression. When INTOUCH N executes the CAUSE EXCEPTION statement, it generates the exception specified. > See Section C.2, Exceptions for a list of exception messages.
WHEN EXCEPTION IN --- --- protected block --- USE --- --- handler --- END WHEN
- 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
K Use WHEN EXCEPTION IN to catch run-time exceptions and resolve them within K your program when you want the code, handling the exception, to be next to the code you are protecting.
= WHEN EXCEPTION IN begins the protected block of code. C Everything between the WHEN EXCEPTION IN and USE statements ? constitutes the section of code protected by the handler---the protected block.
D USE begins the handler routine. Everything between the USE and the ; END WHEN statements constitutes the handler. If an G exception occurs in the protected block, the handler code is executed. END WHEN ends the routine.
& WHEN EXCEPTION USE handl_name --- --- protected block --- END WHEN . . . HANDLER handl_name --- --- handler --- END HANDLER
5 10 INPUT 'Enter total sales amount': tsales 2 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
L Use WHEN EXCEPTION USE to catch run-time exceptions and resolve them within J 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.
A WHEN EXCEPTION USE begins the protected block of code and ? specifies the HANDLER routine to use. handl_name D is the name of the handler routine. The handler name must meet the N specifications for variable names. The protected block is everything between B the WHEN EXCEPTION USE and the END WHEN statements. If an M exception occurs in this block of code, INTOUCH calls the handler specified. 6 If the handler does not exist, an error is generated.
L HANDLER begins the handler routine. Everything between the HANDLER and the A END HANDLER constitutes the handler routine. END HANDLER K returns control to the statement following the END WHEN. When the handler K is called, this block of code is executed. In the example above, INTOUCH L would normally return an exception when it tried to divide 25.00 by 0. The I exception handler FIX_AVERAGE intercepts this exception and sets AVERAGE equal to 0.
C The handler routine can occur before or after the protected block. For example:
10 HANDLER fix_average @ average = 0 <--- handler routine CONTINUE END HANDLER 5 20 INPUT 'Enter total sales amount': tsales 2 INPUT 'Enter number of sales': nsales + WHEN EXCEPTION USE fix_average & average = tsales/nsales END WHEN , 30 PRINT 'The average is'; average 40 END
E One of the advantages of WHEN EXCEPTION USE is that the same handler G routine can be called by any number of WHEN EXCEPTION USE statements. For example:
' 10 WHEN EXCEPTION USE numbers N INPUT 'How old are you': age <--- first protected block END WHEN - 20 INPUT 'Your name, please': name$ ' 30 WHEN EXCEPTION USE numbers O INPUT 'Your birthdate': birth <--- second protected block END WHEN / 40 PRINT name$; ' was born on'; birth 50 HANDLER numbers M PRINT 'Enter numbers only, please.' <--- handler routine RETRY END HANDLER 60 END
USE --- --- RETRY --- END WHEN or HANDLER handl_name --- --- RETRY --- END HANDLER
- 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
H Use RETRY after an exception to re-execute the statement that generated the exception.
; RETRY can only be used in a HANDLER routine. G RETRY causes INTOUCH to leave the handler and re-execute the statement that generated an exception.
USE --- --- CONTINUE --- END WHEN or HANDLER handl_name --- --- CONTINUE --- END HANDLER
5 10 INPUT 'Enter total sales amount': tsales 2 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
M Use CONTINUE to continue normal program execution at the statement following & the one that generated the exception.
A CONTINUE causes INTOUCH to exit the exception handler and J continue program execution at the first statement following the statement F which generated the exception. CONTINUE can only be used in a HANDLER routine.
USE --- --- RESUME target --- END WHEN or HANDLER handl_name --- --- RESUME target --- END HANDLER
5 10 INPUT 'Enter total sales amount': tsales 2 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 3 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
J Use RESUME to resume normal program execution at the statement label that you specify.
? RESUME causes INTOUCH to exit the exception handler and L resume program execution at the target line specified. The target can be a line number or a label.
5 RESUME can only be used in a handler routine.
USE --- --- EXIT HANDLER --- END WHEN or HANDLER handl_name --- --- EXIT HANDLER --- END HANDLER
' 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... 7 Non-numeric input when number expected at 10.1 Enter your age? 35 You are 35 years old
H Use EXIT HANDLER to exit a handler routine and pass the exception up to & the next level of exception handling.
? EXIT HANDLER exits the current HANDLER routine. If the G current handler is nested within another handler, INTOUCH jumps to the H outside handler and executes the code for that handler. If there is no I other exception handler, control returns to the INTOUCH system. INTOUCH J prints the exception message and takes whatever action it normally would.
B EXIT HANDLER can only be used within an exception handler.
C You can call routines written in other languages and run them from an INTOUCH program.
B Callable routines are stored in libraries. The LIBRARY statement F tells INTOUCH what library a routine is located in. You must use the C LIBRARY statement to specify where routines are located before you call them in your program.
G The CALL statement calls routines and executes them. You can call any F routine in a shared VMS library and execute it. The CALL and LIBRARY F statements make your programs more powerful, more versatile, and give you more programming options.
LIBRARY 'libr_name'
10 LIBRARY 'BASRTL' ) 20 PRINT 'Waiting 5 seconds...' ( 30 CALL BAS$SLEEP(5% BY VALUE) 40 END RNH Waiting 5 seconds...
B You can use the LIBRARY statement to specify the libraries you will use in your program.
H The LIBRARY statement specifies libraries from which you CALL routines. K The routines can be written in any VMS language that supports the standard 1 calling interface (FORTRAN, BASIC, COBOL, etc.).
F libr_name is the file specification of a library. The library K can be one of the VMS supplied libraries, or a user-defined library. You I 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.
2 To create libraries for INTOUCH, you can refer to 5 Appendix E, Creating Libraries for Use with INTOUCH.
6 CALL routine_name(arg [BY pass_mech], arg...)
10 LIBRARY 'BASRTL' ) 20 PRINT 'Waiting 5 seconds...' ( 30 CALL BAS$SLEEP(5% BY VALUE) 40 END RNH Waiting 5 seconds...
B You can use the CALL statement to call and execute library H routines. You can use these routines to perform procedures rather than writing the code yourself.
G The library to which the routine belongs must have been specified in a LIBRARY statement.
F routine_name is the name of the routine you are calling. Some D routines take arguments. arg is an argument you are passing F to or getting from the routine. If more than one argument is passed, $ separate the arguments with commas:
, CALL routine_name(arg, arg, arg...)
B Some routines have optional arguments--arguments which can L be used, but do not have to be used. To pass an optional argument, include I it in the appropriate place in the argument list. If you do not want to L pass an optional argument, specify that no argument is to be used by typing G two commas side by side at the appropriate place in the argument list.
I For example, the routine LIB$GET_INPUT gets a record of ASCII text. Its / argument list contains two optional arguments:
J LIB$GET_INPUT(get-str.wt.dx [,prompt-str.rt.dx [,out-len.wwu.r]]) @ | | | J string variable the a prompt string length of the K input is assigned to string variable
I 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) 1 CALL LIB$GET_INPUT(BUF$, , OUT_LEN%) 1 PRINT 'You typed: ';BUF$[1:OUT_LEN%] 20 END ? G pass_mech refers to the mechanism by which values are passed to I 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 | eBy 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. |
L The system functions _REAL and _INTEGER can be used in conjunction with the K library statements. These functions return resulting data associated with E the CALL. (See Section A.1, System Functions for more information.)
4