Routines can be called from anywhere in your INTOUCH program, including from within other routines. There are two basic ways to call an INTOUCH routine by name, and a third way to call a routine whose name is determined only at runtime. Here are the three ways to call routines:

1. GOSUB routine_name
   INTOUCH routines are primarily called using the GOSUB statement.
2. routine_name (without the GOSUB)
   If the routine name contains at least one underscore "_" character, the routine can be called without specifying GOSUB.
3. DISPATCH str_expr
   INTOUCH offers an alternate method to call routines whose names are not known until runtime. This is the DISPATCH statement. DISPATCH examines the contents of a string variable which is loaded when the program is run and gosubs to that routine.

9.3.2 REPEAT, EXIT Routines

9.4 PASSing OpenVMS Commands

Example

1 program application_9_3 10 clear print at 1, 1:; 20 message 'Enter lst letter of last names to be selected ' & + 'separated by commas' line input 'Letters (A,B,C)': list$ print 30 open structure cl: name 'tti_run:client' out_channel = _channel open #out_channel: unique, access output ask #out_channel: name out_file$ 40 extract structure cl include match(list$, cl(last)[1:1]) > 0 sort ascending by cl(last) end extract 50 for each cl print #out_channel: cl(id); tab(12); cl(last); ' '; cl(first); & ' '; cl(middle); tab(45); cl(city); ' '; cl(state) next cl 60 close all 70 print 'The output file name is: '; out_file$ print 'Passing to OpenVMS to type the output file data...' print pass_command$ = 'type ' + out_file$ pass pass_command$ 80 print print at 20, 1: 'You are now back in INTOUCH...' delay 90 end

Letters (A,B,C)? w,s,a,b,f The output file name is: USER:[JEANNIE]TMP_540006.TMP Passing to OpenVMS to type the output file data... 80531 Abott Al A New York NY 80542 Brock Bud B Duluth MN 80573 Farmer Fred F Miami FL 20000 Smith Sam S Washington WA 32001 Waters Wayne W San Diego CA You are now back in INTOUCH... Press the RETURN key to continue

This chapter addresses INTOUCH and its environment. Topics include the basic INTOUCH file types, working in INTOUCH and special commands.

10.1 Switching between INTOUCH and OpenVMS

To get to the OpenVMS prompt, enter $$ at the INTOUCH prompt. This will take you to the "$$" prompt. To resume your INTOUCH session, press the [Return] key or type EXIT.

Passed to VMS... Press RETURN when done. USER:[TESTER] $$

This feature enables you to quickly switch between OpenVMS and INTOUCH, depending on what you need to do. The created subprocess goes away upon exit from INTOUCH. The subprocess will also go away if it is not used within a certain amount of time.

10.1.1 Running OpenVMS Commands from INTOUCH

INTOUCH $DIR *.INT Directory USER:[TESTER] BOX_TEST.INT;1 DATE_TIME.INT;2 FS1.INT;1 FS2.INT;2 FS3.INT;1 INPUT_TEST.INT;1 MESS_TEST.INT;1 Total of 7 files. INTOUCH

10.2 Recalling Previous Commands

Programming can be a tedious task, when you are dealing with lengthy statements which you type repeatedly. INTOUCH reduces the typing time by offering its own command recall history feature.

The INTOUCH environment supports command recall a little differently than OpenVMS. The last 50 previously entered INTOUCH statements can be recalled using a variety of methods.

There are three basic methods to scan the recall list. Each method uses one key (or key combination) to move one statement up and one key (or key combination) to move one statement down in the recall list.

• [UP] and [DOWN] keys
• [Prev] and [Next] keys
• [Ctrl/B] and [Ctrl/V] key combinations

If you remember part of the command you want to recall, you can have INTOUCH search the command recall list for the statement.

To search the command recall list for a particular statement, type the partial statement and press the [Find] key or the [PF2] key. INTOUCH will locate the first statement which matches the pattern you typed in. [PF2] is also associated with the [Help] key.

10.3 The [Tab] Key

The [Tab] key functions can be used when at the INTOUCH prompt or while in the INTOUCH editor.

10.3.1 Command Completion

entering: 30 dis[Tab] produces: 30 dispatch

If there are several INTOUCH commands which match the pattern, the command choices are displayed in a menu. You can then select one of the items. If you want the first menu item, press the [Tab] key and that item will automatically be selected.

10.3.2 Command Abbreviations

The abbreviated statements are:

Table 10-1 Abbreviated INTOUCH Statements

	os.	OPEN STRUCTURE
	es.	EXTRACT STRUCTURE
	ee.	END EXTRACT
	in.	INCLUDE
	ex.	EXCLUDE
	fe.	FOR EACH
	e.	EDIT
	l.	LIST
	p.	PRINT
	pu.	PRINT USING
	ss.	SET STRUCTURE
	pa.	PRINT AT
	li.	LINE INPUT
	pc.	PRINT #
	oc.	OPEN #
	pe.	PRINT _EXTRACTED
	lm.	LINE INPUT MENU
	ls.	LINE INPUT SCREEN

10.3.3 Correcting Misspelled Words

10.4 Using the INTOUCH Editor

Creating Routine Headers

Creating routine headers is very time consuming and most programmers detest this chore. If you are in the INTOUCH editor, you can let the editor create the routine headers for you and then just fill in the appropriate information. Here is how this is done.

1. At the INTOUCH prompt, enter EDIT to get into the INTOUCH editor
2. Press the DO key
3. At the Command prompt, enter the word ROUTINE
4. At the Routine prompt, enter the routine name. For example, enter DO_INITIALIZE

The routine header and framework will be created for the DO_INITIALIZE routine.

12000 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! D O I N I T I A L I Z E !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! ! Expected: ! ! Locals: ! ! Results: ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine do_initialize end routine

You can then add the program information.

12000 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! D O I N I T I A L I Z E !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! Initialize some constant variables. ! ! Expected: ! ! Locals: ! ! Results: ! group_count count of customers in a group ! final_count count of all customers in all groups ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine do_initialize group_count = 0 final_count = 0 end routine

Some comments about the ROUTINE command:

• If you enter a routine name (at the routine prompt) that already exists in your program, the editor will take you to that routine. Otherwise, if this is a new routine name, the routine framework will be created.
• The editor starts the line numbers with 12000 and increments by 1000. However, if you want to insert a routine between two existing line numbers, the editor will assign a line number that fits into the range. For example, if line numbers 12000 and 12500 exist, the editor will assign 12100 to the new routine.
  NOTE: If you are inserting a new routine between two existing routines, you MUST place the cursor where you want the routine to be located before you use the ROUTINE command.

  12100 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! header information ... !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine xxx end routine X <-- place the cursor here 12500 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! header information ... !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine xxx end routine

You can refer to The TTI Editor manual for more information on the INTOUCH editor and the other edit commands.

10.5 About the INTOUCH Editor

If you do not want to use the INTOUCH editor, you will need to define the logical, INTOUCH_EDITOR, to FALSE and the EDIT symbol to the editor of your choice.

$ DEFINE INTOUCH_EDITOR FALSE $ DEFINE EDIT == "EDIT/EDT"

10.6 INTOUCH File Names

The following is a list of the types of files used in the INTOUCH environment.

• program_name.INT
  Programs written in INTOUCH are given the default .INT extension. When you are bringing an INTOUCH program into the workspace or saving the current program to a file, INTOUCH attaches .INT to the file name unless you specify a different extension.
• file_name.INC
  Included files contain source code common to programs. They are included into a main program by means of the %INCLUDE directive. Included files might or might not contain line numbers. The default extension is .INC.
• program_name.RUN
  A file with the default .RUN extension is created when an INTOUCH program is compiled at the INTOUCH prompt. This file can then be executed either inside or outside the INTOUCH environment.
• program_name.INT_IMAGE
  Another type of compiled file is the *.INT_IMAGE file. This is a fast-starting memory image file created explicitly from a compile performed outside of INTOUCH. Compiled images have a minimum size of 500 disk blocks, increasing in increments of 256 blocks.
  For AXP (Alpha) systems, the compiled image file will have the extension of INT_IMAGE_AXP.
• file_name.TMP
  If you transfer to and from an editor while in INTOUCH, temporary files are created which have the extension of .TMP.

Once you have entered the INTOUCH environment (typed INTOUCH), you can perform different procedures. Some of the procedures are listed here. For a list of all the procedures and more detailed information, you can refer to the INTOUCH - A Guide to the Language manual.

NEW ['program_name']

If you want to start writing a new program, enter NEW followed by a program name enclosed in quotes. If you do not provide a name, the default program name will be NONAME.

new 'client_list'

If you want to start a new program and already have a program in the workspace, be sure to SAVE it. When NEW is entered, the workspace is cleared and renamed to the program name you provide or NONAME.

OLD ['program_name']

If you want to bring an existing program into the INTOUCH environment, enter OLD followed by the program name in quotes.

old 'convert_date_time'

INTOUCH appends .INT to the file name (unless an extension is provided), searches for the file and loads the file into the workspace.

EDIT

You can write or edit a program at the INTOUCH prompt. Use the EDIT statement to get into edit mode.

edit or edit ask_date

EDIT transfers control to the INTOUCH editor. Exiting the editor returns you to the INTOUCH prompt.

If you want to use an editor in INTOUCH other than the INTOUCH editor, you will need to define the INTOUCH_EDITOR logical (see Section 10.5).

Programs can be edited in sections. You can specify line numbers, a label or a routine name. If no section is specified, INTOUCH loads the entire program into the editor's workspace.

SAVE ['program_name']

When you want to save your program, use the SAVE statement followed by the program name you want to give your program. The program name is enclosed in quotes. If you do not provide a program name, INTOUCH will use the workspace name as the program name (i.e. the name you provided or NONAME).

save or save 'client_list'

INTOUCH writes out the program as a text file with the extension .INT unless you provide a different extension.

REPLACE ['program_name']

If you change your program and want to save the changes, use the REPLACE statement. Use SAVE to save the program the first time and use REPLACE thereafter.

replace or replace 'client_list'

RUN ['program_name']

You can run your program by entering RUN. If RUN is followed by a program name, INTOUCH will OLD in the program and then RUN it.

run or run 'convert_date_time'

INTOUCH programs can also be run at the OpenVMS prompt ($). To run an INTOUCH program outside of the INTOUCH environment, you need either a compiled file (*.RUN) or a compiled image file (*.INT_IMAGE).

10.8 END, STOP, HALT, GO Statements

The STOP statement brings program execution to an end the same as the END statement. However, STOP does not mark the end of the program. The STOP statement is sometimes used to stop program execution when a fatal data error is found.

The HALT statement interrupts program execution but does not close files or write active output buffers. The INTOUCH prompt is displayed when the HALT statement is executed. Use HALT if you want to interrupt the program to check values or modify code and then continue. Use the GO statement to continue with program execution.