TECHNICAL BULLETIN #178 - Rev 1.10 (9/03/96)
==============================================================================
TITLE : ASPECT Compiler Options and Programming Hints
PRODUCT : Procomm Plus 4.x, 3.x
==============================================================================
The Procomm plus ASPECT Compiler comes with several useful features designed
to help programmers minimize coding and debugging time. This document will
highlight some of the more useful features of the compiler and provide some
other tips and tricks for creating and debugging ASPECT Scripts.
COMPILER OPTIONS
WARNING LEVEL
This setting determines whether the compiler reports warnings, in addition to
any syntax errors encountered while compiling a script. It's a good idea to
leave Warning Level set to 2. This makes the compiler report any variables,
labels, or procedures that have been defined, but not referenced within the
script. To set the Warning Level, click Tools | Compiler Options from the
ASPECT Editor Main Menu, select the appropriate radio button, and click OK.
THE ASPECT RUN-TIME DEBUGGER
The Run-Time Debugger is a very useful tool that, among other things, allows
you monitor which commands have produced run-time errors, step through scripts
one command at a time, and check values of variables during script execution.
INVOKING THE DEBUGGER
In order to use the Run-Time Debugger, you'll need to turn Compile for debug
ON. To do this, click Tools | Compiler Options from the ASPECT Editor Main
Menu, check the box labeled Compile for debug, and click OK. Now, recompile
the script. When the script encounters any run-time errors, the Debugger will
now automatically pop up. There are a couple of ways to pop up the Debugger
when you haven't encountered a run-time error:
1. Press <Ctrl> <Break> during the execution of a script that was compiled
for debug. (If the script is currently executing a command that can be
exited with Ctrl-Break, it will be canceled when script execution
resumes.)
2. Use the breakpoint command to open the Debugger before the problem occurs.
If you have a procedure that seems to be working incorrectly and you want
to watch it. Simply add the BREAKPOINT command as the first line of code
in the procedure, recompile, and run the script. When the script comes to
that line, the Debugger will pop up.
CHECKING VALUES OF VARIABLED DURING EXECUTION
When the Debugger is displayed you can check the value of any variable at that
point in the script. All you have to do is click on the drop-down box labeled
"Variable" and select the variable you want to see from the list. Initially,
the Variable listbox shows Predefined variables. If the variable you want to
see is Global, select [Global] from the list. If the variable is local, select
[Local] from the list. Once you select the variable to be shown, it's current
contents will be shown in the field immediately to the right of the drop-down
box.
If the variable you select is an array, the Debugger will allow you to see the
values of all of the elements in the array. The index of the array will be
shown in the Array Offset field and you can click Next or Previous to scroll
through the other elements.
STEPPING THROUGH A SCRIPT
Sometimes, it can be useful to watch your script execute line by line. Once
the Debugger is displayed, it's easy to step through a script in this manner.
Simply click Step. Note the Source Line Text field. It always shows the line
of code that will be executed next. Stepping through a script in this manner
while monitoring the contents of a particular variable can be a very effective
troubleshooting method.
GENERAL ASPECT PROGRAMMING TIPS AND TRICKS
MAKE A PLAN
You wouldn't build a house without a blueprint. Likewise, it's not a very good
idea to start coding a script without a good idea of where you are going. When
you build a script from the ground up, starting with a blueprint, you'll find
things go much quicker and easier. Some people use flowcharts to build their
blueprint. Others simply write down the steps involved in outline form.
However you decide to do it, make sure and have a clear picture of what you
are trying to accomplish before you start coding.
COMMENT AS YOU GO
Code isn't very "English-looking". You may have a very clear picture of what
each line of your script does right now. But tomorrow or next month (or next
year) when you look at your script, it probably won't seem so clear. If you
comment a script well enough, you may be able to re-aquaint yourself with it
later on without struggling through the code at all, but simply by reading the
comments. Consider the following ASPECT script. Without the comments, it would
be much more difficult to follow.
proc main
string DataFile="C:\FRIENDS.TXT" ;Filename of my friends list
string FriendsList[100] ;array to hold all of my friends' names
string Line ;variable to hold lines as they're read
; from the file.
integer Counter=0 ;variable to hold the current index of
;the array
if fopen 0 DataFile READ TEXT ;open the file for Read Only
while not feof 0 ;while we're not at the end of
; the file...
fgets 0 Line ;grab a line from the file
FriendsList[Counter]=Line ;add it to the array
Counter++ ;increment the array index
endwhile
else ;File couldn't be opened...
usermsg "Couldn't open File!" ;output an error message
endif
breakpoint ;invoke the Debugger (only if
; I've compiled for debug)
endproc ;that's it...
USE MODULAR PROGRAMMING (AND RE-USE CODE)
Modular programming is breaking code up into logical sub-tasks (procedures and
functions). When you use modular programming, reading through a script is much
easier. For a script that logs on to the Quarterdeck BBS and gets a file, you
might have the following main procedure:
proc main
when Problem call BailOut ;if a procedure reports a
; problem, get out...
DialBBS(WhoToDial,&Problem) ;dial the BBS
LogOn(MyName,PassCode&Problem) ;Log onto the BBS
GetTheFile(FileToGet,&Problem) ;download the file
LogOffAndHangUp() ;log off and hang up
endproc
Notice that the commands in the main procedure don't contain very code,
they're more like a simple list of tasks. This accomplishes two things:
1. It makes it easier to track down logic problems that occur during
run-time.
2. It makes much of your code reusable. Later, if you write a script to log
onto your favorite local BBS, you can re-use the procedure called
"DialBBS" (just copy and paste the procedure into the new script and
invoke it with a different Dialing Directory Entry Name).
TIPS AND TRICKS
Use those User Messages When programming in ASPECT, there are lots of points
in the script where you'll want to know how things are going. By using the
USERMSG command extensively, you can know during the execution of the script
exactly what's going on. Some examples are as follows:
usermsg "Entering procedure GetTheFile."
usermsg "FileToGet=%s" FileToGet
usermsg "Starting Download"
usermsg "Download is over"
usermsg "Done with procedure GetTheFile"
This helps narrow down where problems are occurring. Also, it keeps script
execution slowed down enough to follow along during run-time.
IF DEBUG...
One problem with using all those USERMSG commands is that when the script is
done and the USERMSG commands are no longer needed, it's tedious to go in and
get rid of them. Besides, what if a problem is encountered later on and you
need to add them back in? Try surrounding all of the USERMSG commands with a
conditional expression based on a global variable called "Debug". The first
USERMSG above would become:
if debug
usermsg "Entering procedure GetTheFile."
endif
This way, while you code and test a script, you can simply set "Debug" equal
to 1. When coding is finished, set it equal to 0 and the USERMSG commands no
longer fire.
USE METAKEYS TO EDIT AND RUN SCRIPTS, ETC.
Let's say you're working on a script that will sort your list of friends
(C:\FRIENDS.TXT) and place the output in a file called C:\FRIENDS.SRT. Each
time you run the script, you want to go and look at C:\FRIENDS.SRT to see if
it worked correctly. You can use three Meta Keys to accomplish this.
The first MetaKey might run a script called SORT.WAS. (if you specify a .WAS
file to be run, it will automatically be compiled). The second MetaKey invokes
the ASPECT Editor with SORT.WAS as a parameter so that you can edit the script
file if neccassary. The Third MetaKey runs NOTEPAD.EXE with a parameter of
"C:\FRIENDS.SRT".
Now you have MetaKeys to do all of these tasks without having to leave the
comfort of the PROCOMM PLUS 3.0 Terminal screen. You could even set up a
MetaKey to delete the Output file. Just write a tiny script to delete
"C:\FRIENDS.SRT" and link a MetaKey to that script.
GO TO WORK
ASPECT is a powerful programming language. You'll find that almost anything
that can be done with Procomm Plus can be automated with ASPECT. So it's
time to put your creativity to the test. Try to stay organized and follow
good programming habits. You'll find many of your own tips and tricks as you
go along.
==============================================================================
To ensure that you have the latest version of this document, compare its
revision number to that of the same document on any of our support sites.
This technical bulletin may be copied and distributed freely as long as it
is distributed in its entirety and it is not distributed for profit.
Copyright (c) 1996 Quarterdeck All rights reserved.
==============================================================================
|