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 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. ==============================================================================