| Previous | Contents | Index |
Debugging a program can often take a lot of time and resources. A good debug utility packaged within a language is therefore, very helpful. The INTOUCH debug utility has several features which help in writing code and debugging programs.
INTOUCH automatically interprets each line as it is entered at the INTOUCH prompt. If any syntax errors are detected, the error location and cause are displayed.
INTOUCH 10 open structure cl name 'tti_run:client', access input 10 open structure cl name 'tti_run:client', access input .....................1 Expected ':' |
Running programs containing syntactically incorrect statements produces compile errors. A list of INTOUCH error messages can be found in the appendix section of the INTOUCH - A Guide to the Language manual.
Some language interpreters do not allow you to see variables local to routines. Not only does INTOUCH allow you to trace local variables, it also keeps all variables defined even after the program has completed running. This allows you to verify the values of program variables after runtime.
11.1 Enabling the Debug System
The DEBUG ON statement enables INTOUCH's DEBUG system.
When DEBUG is enabled, all of the DEBUG features are available. DEBUG
remains enabled until a DEBUG OFF statement is
executed or until a DEBUG feature is executed which disables it.
DEBUG ON can be issued in immediate mode (at the INTOUCH prompt) or as a statement in a program. If DEBUG ON is used in a program, INTOUCH enables DEBUG when the DEBUG ON statement is encountered.
11.2 Setting a Break point to Check Variables
If you want to check variables at a specific point in the program, you
can use the BREAK statement to interrupt program
execution. When BREAK is encountered, the INTOUCH
prompt is displayed and you can print the variables. When you are ready
to continue program execution, enter GO and the
program will resume execution.
After a BREAK and when at the INTOUCH prompt, you can use the STEP statement to step through lines of your program. If STEP is followed by a number (i.e. STEP 10), INTOUCH will execute that number of lines and issue a BREAK.
BREAK statements are ONLY activated when DEBUG is ON. If DEBUG is OFF, BREAK statements are ignored.
BREAK statements are sometimes put into routines where problems might occur. Then, if a problem does occur, DEBUG can be set ON, the program rerun and the programmer can step through the code, check variables, etc. at the break points.
1 program application_11_1
10 clear
20 open structure cl: name 'tti_run:client'
30 extract structure cl
include cl(state) = 'CA'
exclude cl(phone)[1:3] = '619'
sort descending by cl(last)
end extract
break
40 for each cl
print cl(id); tab(12); cl(last); ' '; cl(first), cl(city); ' '; &
cl(state), cl(phone)
next cl
50 close structure cl
60 end
|
INTOUCH run <--- run the program 80522 Errant Earl Monterey CA (408) 844-7676 80561 Derringer Dale Los Angeles CA (818) 223-9014 INTOUCH debug on <--- activate the DEBUG system |
The INTOUCH screen frame is displayed. You can now RUN the program again.
INTOUCH 4.4 Program: NONAME DEBUG
The Next Generation Language Status : BREAK at 40.1
INTOUCH
run <--- run the program again
BREAK at 30.5 <--- 1st break caused by program code
INTOUCH
print _extracted <--- display a variable
2
INTOUCH
step <--- give STEP command
shows break, line number at top of screen
INTOUCH shows code at bottom of screen
go <--- Enter GO to resume program execution
print cl(id); tab(12); cl(last); ' '; cl(first), cl(city); ' '; &
EXIT = Exit \ = Back HELP = Help
|
11.2.1 Checking Variables
INTOUCH allows you to check your variables either during runtime (i.e.
at BREAK) or after your program has completed running.
If the program variables are such that they do not change during the course of the program, you do not need to turn the DEBUG system on to see the variables. Once the program has completed its run, the variables still contain their last active values.
You can check user input two ways. First, you can print the variable the input is stored in. However, more conveniently, you can print out the _REPLY INTOUCH function, which always contains the last user entered input in string format.
11.3 STATS and TRACE Features
Although we make it a point to write efficient code, we are not always
successful. Locating performance bottlenecks (i.e. what is causing a
program to run so long) can be complicated. INTOUCH, however, provides
the STATS debug feature, which enables you to pinpoint
problem areas in the source code.
Once enabled, the STATS feature tracks the number of times each line of code is executed and how long it takes to execute. This feature goes above and beyond the TRACE debug feature, which lists the line number as it is executed. To list the statistic information gathered during runtime, you use the LIST STATS statement.
The following example shows how to set STATS ON and what information is displayed.
INTOUCH stats on <--- turning STATS ON, turns on DEBUG INTOUCH run <--- run the program INTOUCH list stats <--- list the statistics |
NONAME 31-MAY-1996 16:22
1 0.00 10 clear
1 0.41 20 open structure cl: name 'tti_run:client'
15 0.06 30 extract structure cl
14 0.00 include cl(state) = 'CA'
8 0.00 exclude cl(phone)[1:3] = '619'
2 0.00 sort descending by cl(last)
14 0.00 end extract
3 0.00 40 for each cl
2 0.01 print cl(id); tab(12); cl(last); ' '; cl(f
irst), cl(city); ' '; &
cl(state), cl(phone)
2 0.00 next cl
1 0.01 50 close structure cl
1 0.01 60 end
INTOUCH
|
11.4 Modifying Code at Runtime
If you want to interrupt your program at various points to add/check
code or variables and do NOT want to get into the DEBUG system, you can
use HALT statements. The HALT
statement works like the BREAK statement except that:
Both statements keep all channels open and allow you to modify any of the code in your program.
INTOUCH's Help System allows you to create informational help text that can be displayed when a user enters HELP or presses the [Help] key at an input prompt.
The actual help text is contained in records in a file. When you want your program to display some help information for a specific prompt, you simply identify which help text file record to use. The Help System will automatically display the help text if the user requests help.
This chapter explains how to create the help text and how to include and invoke the HELP.INC routine.
12.1 Creating the Help Text File
The INTOUCH help text maintenance program
HELP_MAINT.INT allows you to create help text. To run
the program, enter the following command in upper or lowercase:
INTOUCH/SOURCE TTI_RUN:HELP_MAINT
The help maintenance screen will be displayed and you will be asked for a help text file name.
30-Apr-1997 Help File Maintenance Help text file? application_help EXIT = Exit \ = Back HELP = Help |
The help text file name can be any valid file specification. That is, you can use device and directory or logical names to place the file in any directory location. When naming a help file, a common convention is to use the system or program name followed by _HELP. For example:
Help text file? application_help
Help text file? testdisk:[tester]application_help
Help text file? tti_run:application_help
|
At any prompt in the HELP_MAINT program, you can enter HELP or press the [Help] key to get helpful information about the prompt. |
Help text files have the extension of .DAT. When you enter a file name, you can optionally use the .DAT extension.
The first time you enter the help text file name, the message:
File not found for help_text_file_name.DAT
will be displayed and you will be asked:
Create this help file (Y/N)?
Enter Yes to create the help text file and a message will be displayed that tells you that the file is being created.
Once the help file is created, whenever you want to add, change, inquire or delete help text information in the help file, the HELP_MAINT program will simply open the file and allow you to proceed.
A single help text file can be used by any number of INTOUCH programs. For example, if you had a payroll system which consisted of several programs, all of the programs could use the same help text file. |
After you enter the help text file name, the help file maintenance procedures menu will be displayed.
12.2 The Help Maintenance Procedures
The HELP_MAINT program allows you to perform various maintenance
procedures on your help text file. You can add, change, inquire and
delete records in your help file and perform other functions.
The HELP_MAINT program displays a menu of procedures.
| Example 12-1 Help Maintenance Procedures |
|---|
30-Apr-1997 Maintain: APPLICATION_HELP.DAT
+--------------------Procedures--------------------+
| |
| Topic Maintenance |
| ADD Add topics |
| EDIT Edit topics |
| RENAME Change topic names |
| INQUIRE Look at topics |
| DELETE Delete topics |
| |
| Other Options |
| CREATE Create a new help text .DAT file |
| NEXT Next help text .DAT file to maintain |
| PRINT Print a HELP.LIS |
| SHOW Display a list of topics |
| RELATED Display a list of related topics |
| EXIT Exit program |
+--------------------------------------------------+
EXIT = Exit \ = Back HELP = Help
|
The name of the help file that you are maintaining is displayed in the screen frame above the procedures menu. After you select a procedure option, that option will be displayed in the upper-right corner of the screen frame. Each of the procedure options is explained in the following sections.
The records you add and maintain in your help text file are referred to as TOPICS. There is no limit to the number of topics you can have in your help file.
12.2.1 ADD - Add Topics
Select the ADD procedure to add new topics to your
help file.
You will be asked for the topic you want to add:
Topic to add? SSN
Each topic has a unique identifying name. The topic name is what you use to identify specific help text, and it is the name you use in your program to display the text when a user wants help.
The topic name can be a maximum of 32 characters in length and can consist of letters, numbers and underscore characters. If a name consists of several words, the words can be separated by either an underscore character or a space (i.e. ENTER_NAME or ENTER NAME).
After you enter the topic name, you will be placed into the editor where you can create the help text you want to display for this topic. Usually the help text includes information about the prompt and possible options that can be entered at the prompt. You can use the editor as you would on any other text file. Here is an example of some help text for SSN:
Enter a 9 digit social security number. |
When you exit out of the editor, a record will be added to the help text file for this topic. You will be asked for the next topic to add.
12.2.1.1 Related Topics
When you are in the editor, you will create the text you want to
display when help is requested. The text can include explanatory
information on what to do at the prompt. The text can also include
Related topics. "Related topics" is a list of other
topics that have something in common with the topic you are editing.
Here is an example of help text for topic LAST_NAME which includes related topics:
Enter the last name. The last name can be a maximum of 20 characters. Related topics: first_name middle_initial |
When the text is displayed for the user, it appears as follows:
LAST_NAME Enter the last name. The last name can be a maximum of 20 characters. Related topics: first_name middle_initial Topic? |
The user can then enter FIRST_NAME or MIDDLE_INITIAL at the "Topic?" prompt and get information on those topics.
To use the related topics feature, you must:
12.2.2 EDIT - EDIT Topics
Select the EDIT procedure to edit topics in your help
file.
You will be asked for the topic you want to edit:
Topic to edit? SSN
Enter the topic name you want to EDIT. The topic must exist in the help file or an error message will be displayed.
After you enter the topic, you will be placed into the editor where you can edit the text for this topic. You can add more text, make changes, add related topics, etc.
After you have exited the editor, you will be asked for the next topic to edit.
12.2.3 RENAME - Change Topic Names
The RENAME procedure allows you to change a topic name.
When you select RENAME, you are asked the following questions:
Current topic name? ADDRESS
New topic name? FULL_ADDRESS
Sure rename this topic (Y/N)? NO
After the current and new topic names are entered and if "Yes" is the response to the "Sure..." prompt, the new topic is added and the old topic is deleted. The new topic contains the same help text as was in the old topic.
The RENAME procedure does NOT change the topic name in other topics that include this topic as a related topic. Before you rename a topic, you should run the RELATED and PRINT procedures to find out if this topic is related to any other topics. Then, you will know what topics, if any, will need to be edited. Also, you must change the help topic you use in your program to match the new topic name. |
12.2.4 INQUIRE - Look at Topics
Selecting the INQUIRE menu option allows you to
display topic help text and see the text exactly as a user would see it
when they request help. This is helpful for checking your new and
edited topics.
You are asked for a topic. After you enter a topic, you are placed into the Help System module HELP.INC which performs the actual help text displays. The text for the topic you requested is displayed and then you are asked for another topic. You can inquire on as many topics in your help file as you wish. When you have completed your inquiries, press [Return] at the "Topic" prompt and you will be returned to the procedures menu.
12.2.5 DELETE - Delete Topics
The DELETE option allows you to delete topics from
your help file.
You are asked:
Topic to delete? CONTACT_ADDRESS
After you enter a topic, the first few lines of the topic text are
displayed for verification. Then, you are asked:
Sure delete topic CONTACT_ADDRESS (Y/N)? NO
If you answer "Yes", the topic will be deleted, otherwise the topic will be saved.
12.2.6 CREATE - Create a New Help Text File
If you have completed maintenance to the current help text file and
want to create and maintain a new help file, the
CREATE procedure allows you to create a new help text
file.
You are asked:
Help text file to create? CUSTOMER_HELP
Enter the name of the new help text file that you want to create. The name can be any valid file specification. You can optionally use the file extension ".DAT". If the name does not end with ".DAT", the program will append it to the name before creating the help text file.
After the new help file name is entered, you are asked:
Sure create CUSTOMER_HELP.DAT (Y/N)? NO
If you enter "Yes", the new help file will be created.
| Previous | Next | Contents | Index |