Copyright © 2000 - 2001 Christopher S. Charabaruk and Matthew R. Knight. All rights reserved. All articles, tutorials, etc. copyright © by the original authors unless otherwise noted. QB Cult Magazine is the exclusive property and copyright of Christopher Steffan Charabaruk and Matthew R. Knight.
Salutations, from another great issue of QB Cult Magazine.
Wait until you see what's been added! QBCM now features Power Coding, a column by QbProgger. There's also Demo of the Month, where we feature a really interesting demo program written in QB. If you want your demo to be featured in DotM, read the instructions there for how to enter it.
QbProgger's series on physics engines continues with it's second article, with ideas for a physics-based fighter. The serialization of BASIC Techniques and Utilities has reached chapter four, the first chapter of the second part of the book. And I've written an article with interesting little tricks you can use in your BASIC programs. Actually, starting in issue #9, BASIC Tips and Tricks returns to QBCM.
What's missing this month is Demo Coders Corner by Matt R. Knight, and Thoughts From The Darkness, by DarkDread. While we all know DarkDread is out there and has been told that TFTD is for every other month, Matt seems to have gone AWOL. Hopefully he shall return soon and continue with DCC. Also, we've dropped Ask QBCM due to lack of people sending in questions for it. Now that it's gone, just watch as a thousand people start asking questions for it. However, while Letters is just as dysmal, it's not being cancelled. I'm thinking of just putting up the spam that comes into the QBCM mailbox there.
You'll notice that this issue has no game reviews in it, nor even a section for reviews. That's because I'm focusing QB Cult Magazine on programming only. There will be reviews of programs to aid programming, and libraries, every once and a while, but game reviews are no longer a part of QBCM. If you want QB game reviews, check out V Planet! QuickBasic Magazine <www.hulla-balloo.com/vplanet/>, which focuses solely on games.
Finally, I would like to say "thank you" to Nekrophidius for the compliment towards QB Cult Magazine that he wrote in issue six of the reincarnated QB on Acid. It's nice to see that QBoA is back.
Chris Charabaruk (EvilBeaver), editor
Note: Regarding BASIC Techniques and Utilities, it was originally published by Ziff-Davis Press, producers of PC Magazine and other computer related publications. After ZD stopped printing it, they released the rights to Ethan Winer, the author. After communicating with Ethan by e-mail, he allowed me to reproduce his book, chapter by chapter, in QBCM. You can find a full text version of BASIC Techniques and Utilities at Ethan's website <www.ethanwiner.com>, or wait until the serialization is complete, when I will have an HTML version ready.
To place an ad, please e-mail <qbcm@tekscode.com>, subject QB Ads. Include your name (real or fake), e-mail address, and message. You may include HTML formatting (but risk the chance of the formatting being thrown out).
By Ethan Winer <ethan@ethanwiner.com>
There are many individual components which contribute to a completed application. The logical flow of the program must be determined, the user interface must be designed, and appropriate algorithms must be selected. But no matter how much effort you devote to the design and implementation of a program, the bottom line is it must also work correctly.
In an ideal scenario, you would begin writing a program by first jotting down some notes that describe its operation. Next, you would create an outline listing each of the program's major components. You would then determine all of the subroutines and functions that are needed, and perhaps even create a flow chart showing each of the paths that could be taken. Properly prepared for any situation that might arise, you finally write the actual code and find that it works perfectly. Now, what's wrong with this picture? Few people actually program that way!
In practice, many programmers simply start coding with little forethought and no detailed plan. They begin with the first statement and continue to the last, occasionally reworking portions into subroutines as necessary. After all, planning is not nearly as much fun as programming, and everyone knows that fun is the most important part. Believe it or not, I agree. There's nothing really wrong with plodding through a program, stabbing here and there until it works. Indeed, some great algorithms developed out of aimless doodling. I have personally never drawn a flow chart, and I have no plans to start now.
What I will address here is how to find and correct problems when they do occur. There are more things that can go wrong with a program than can go right, and tracking down an elusive "Illegal function call" error that appears only occasionally is definitely not much fun. How quickly you can solve these problems is directly related to your understanding of programming in general, and to your familiarity with the tools available.
In this chapter you will learn how to identify problems in your programs, and also how to solve them. Programming errors, or bugs, can be as simple as a misspelled variable name, and as complex and ornery as an internal flaw in BASIC itself. The BASIC editing environment provides a wealth of powerful debugging features, and understanding how to use them will help you produce programs that are reliable and error free.
There are three distinct types of programming errors: simple misspellings and other naming or syntax errors, incorrect logic such as misunderstanding or incorrectly coding an algorithm, and failing to understand some of the finer points of the BASIC language. No matter how carefully you type, no matter how much forethought you apply to a particular problem, and no matter how often you read the BASIC manuals, it is impossible to completely avoid making mistakes.
The first category includes those errors caused by simple mistakes such as misspelling a variable or procedure name. Trying to call a subprogram that doesn't exist will be immediately obvious, because BASIC gives you an error message before the program can be run. But an incorrect variable name will return the wrong results with no warning.
Passing the wrong number of arguments to a procedure may or may not be reported, depending on whether the routine has been declared. Assembly language routines in a Quick Library can be particularly pesky in this regard. Although BASIC automatically generates a DECLARE statement for BASIC subprograms and functions you have loaded in source form, it does not do this for routines in a Quick Library. If you call an assembly language routine incorrectly, you will probably crash the PC. However, it is also possible to corrupt string memory and not know it. Worse, a "String space corrupt" error is often not reported until much later in the program. If you run the short program below in the QuickBASIC 4.5 editor, it will appear to operate correctly.
X$ = SPACE$(1000) 'create a string POKE SADD(X$) - 2, 100 'corrupt string memory PRINT "Testing" X% = 1 PRINT "More testing" X% = 2 PRINT "Yet more testing" X% = 3
Here, the POKE statement is overwriting the back pointer that belongs to X$, which is one type of string corruption that can occur. But QuickBASIC doesn't know that this has happened, because it has no reason to check the integrity of its string memory until another string assignment is made. However, adding the statement PRINT FRE("") anywhere after the POKE command causes BASIC to check string memory, and report the error. Even if your program does not use POKE, calling a procedure incorrectly can cause it to overwrite memory in this fashion.
Another simple error is inadvertently using the same variable name twice, or omitting a type declaration character from a variable name. For example, if you are using a variable named Bytes& to track how many bytes of a file have been read, accidentally using Bytes later on will give the wrong results. If a DEFINT statement is in effect, then Bytes will be an integer variable. Otherwise, it will be single precision which is also incorrect. Unless you use the DIM...AS statement to declare a variable explicitly, BASIC lets you have different variables with the same name. That is, Var%, Var!, and Var# can all coexist in the same program, and each is a unique variable.
Similarly, using the wrong variable entirely will cause your program to operate incorrectly, and again with no error message displayed. More than once I have had a program with one FOR loop nested within another, and used the outer loop counter variable when I meant to use the inner one.
Another common situation is caused by changing the name of a variable during the course of writing a program. For example, you may have a variable named BPtr that tracks where you are reading within a buffer. If you later decide to change that name to BufPointer because it is more meaningful, you must also remember to change all occurrences of the name. Of course, BASIC's search and replace feature minimizes that problem. More important, though, you must make a mental note to use the new name as you continue to develop the program.
Forgetting to declare a function can also lead to incorrect results that produce no warning. If an integer function is not declared, then BASIC will dimension an array with that name if the function expects a numeric argument. When BASIC encounters the statement X = FuncName%(Y%) it assumes that FuncName% is an integer array, and create an array containing the default 11 elements. In this case X will be assigned a value of zero, or you will receive a "Subscript out of range" error if Y% is not between 0 and 11. I once observed an unexplainable "Out of string space" error that was caused by the statement Size = ScreenSize%(ULRow, ULCol, LRRow, LRCol). ScreenSize% was a function present in a Quick Library, but without a DECLARE statement BASIC created a 4-dimensional integer array.
The second cause of bugs is logic errors, and these include adding when you meant to subtract, or using the wrong variable altogether. Programs that manipulate pointers (variables that hold the addresses of other variables) are particularly prone to errors in logic. Another common logic error is forgetting to trim the leading or trailing blanks from a file or directory name before using it. If the operator enters " c:\thisfile.dat" and you try to open that file, BASIC will report a "Bad file name" error.
Another cause of logic errors is failing to consider all of the things a user may enter. An inexperienced operator is likely to enter data that you as the programmer would never consider, or select menu items in an order that makes no sense. Indeed, never underestimate the value of beta testers. After you have exhausted all of the possibilities you can think of, give the program to a 4 year old child, and ask him or her to try it while you watch. Your uncle Ernie would be a good beta tester too, and the less he knows about your program, the more valuable his contribution will be. People who know absolutely nothing about computers have an uncanny knack for creating "Illegal function call" errors in a program that you just know is perfect.
Similarly, you must consider all of the possible error conditions that could happen in a program. In an error handler that has a CASE statement for each possibility you anticipate, also include a CASE ELSE clause for those you haven't thought of. The short listing that follows shows a typical error handler that incorporates this added safety measure.
ON ERROR GOTO HandleErr
...
...
HandleErr:
SELECT CASE ERR
CASE 7, 14
PRINT "Out of memory"
CASE 24, 25, 27
PRINT "Fix the printer"
CASE 53
PRINT "File not found"
CASE ELSE
PRINT "Error number"; ERR
END SELECT
...
...
The CASE ELSE clause lets you accommodate any possibility, and your user can then at least report to you what the error number was. This simple example doesn't include all of the possibilities, but you can certainly see the general concept.
Another common logic error is using the same file number twice. When a file has been opened as #1, that number remains in use until the file is closed. This can be problematical when writing reusable modules, since there is no way to know which files may be in use by the main program. Some programmers use #99 or another unlikely number in a routine that will be reused in many programs. But even that approach is flawed, because you have to remember which numbers are used by which routines.
BASIC's FREEFILE function is intended to solve this problem, and it returns the next available file number. Be sure to save the results FREEFILE returns, however, since the value will change as soon as the next file is opened. The code below shows both the wrong and right ways to use FREEFILE.
Wrong:
OPEN "accounts.dat" FOR INPUT AS #FREEFILE INPUT #FREEFILE, X$ 'FREEFILE has changed! CLOSE #FREEFILE
Right:
FileNum = FREEFILE 'get and save the number OPEN "accounts.dat" FOR INPUT AS #FileNum INPUT #FileNum, X$ CLOSE #FileNum
In the first example if FREEFILE returns, say, a value of 2, then it will return 3 at the INPUT statement which is of course incorrect. Therefore, you must save the value FREEFILE returns, and use that for all subsequent file accesses. This situation also occurs with INKEY$, because once a character has been returned it is no longer available unless you saved it.
Two other frequent problems are attempting to use LSET to assign characters into a string that does not exist, and failing to clear a counter variable within a static subprogram or function. The second problem can be especially frustrating, because the routine will work correctly the first time it is invoked. In the function below, a counter returns the number of embedded control characters it finds in a string.
FUNCTION CtrlCount%(Work$) STATIC
FOR X% = 1 TO LEN(Work$)
IF ASC(MID$(Work$, X%, 1)) < 32 THEN
Count% = Count% + 1
END IF
NEXT
CtrlCount% = Count% 'return the count
END FUNCTION
The problem here is that Count% retains its value between function invocations. Therefore, each time CtrlCount% is used it will return ever higher values. One solution is to add the statement Count% = 0 at the beginning of the function. Another is to omit the STATIC option from the function definition.
The third type of error is caused by not understanding some of BASIC's finer points and quirks. For example, some people do not realize that omitting the third argument from MID$ causes it to return all of the remaining characters in a string. To see if a drive letter was given as part of a file name and if so extract it, you might use a statement such as IF MID$(FileName$, 2) = ":" THEN Drive$ = LEFT$(FileName$, 1). But since the number of characters was not specified to MID$, it returned all but the first character in the string. Unless the string was a drive letter and colon only ("C:"), the test for a colon could never work. The solution, of course, is to use MID$(FileName$, 2, 1).
Another instance in which an intimate knowledge of BASIC's idiosyncracies comes into play can affect the earlier example of a file name that contains leading blanks. Most programmers do not use INPUT to accept information, unless the program is very simple and it will be used only occasionally. However, asking for a file name with INPUT is one way to avoid that problem, because INPUT strips all leading and trailing blank spaces, as well as CHR$(9) tab characters. The more useful LINE INPUT, on the other hand, does not strip leading blanks and tabs. Most programmers would never be so foolish as to enter a file name with leading blanks. So this is yet another situation where it is important to consider all of the possibilities.
It is also possible to crash a program by using the ASC function when the string might be null. Again, *you* would never press Enter alone in response to a prompt for a file name or other mandatory information, but someone else might.
Another BASIC quirk is caused by rounding errors. As you saw in Chapter 2, adding or multiplying many numbers in succession can produce results that are not precisely correct. Instead of checking to see if a value is zero, it is often better to compare it to a very small number. That is, instead of IF Value# = 0 you would use IF Value# < .000001 or IF Value# < .000001 AND Value# > -.000001 or something similar. Also, some numbers simply cannot be represented at all. If you try to enter the statement X# = .00000000001 in the QuickBASIC 4.5 editor, the value will be converted to 9.999999999999999D-12 as soon as you press Enter.
Although not technically a BASIC quirk, many programmers forget that variables within a DEF FN function are by default global. Unless you include an explicit STATIC statement listing each variable that is to be local to the function, it is likely that an unexpected change will be made to a variable in the main program.
Some programming situations require that you obtain the address of a string variable using SADD. However, SADD is not legal for use with a fixed-length string or the string portion of a TYPE variable. More important, when using BASIC PDS far strings you must also remember to use SSEG to get the string's data segment. Using VARSEG will not create an error; however, the program will not work correctly.
Related to that, it is important to remember that strings and dynamic arrays move around in memory--often at unexpected times. The program below appends a zero character to one string for each zero that is found in another string. Since BASIC may move Work$ during the course of assigning Zero$, this code will fail eventually:
Address = SADD(Work$) FOR Y = Address TO Address + LEN(Work$) - 1 IF PEEK(Y) = 48 THEN Zero$ = Zero$ + "0" NEXT
Another particularly insidious bug can result if you inadvertently add parentheses around a variable that is passed to a subprogram or function. In the example below, a subprogram that intentionally modifies a parameter has been declared and is then called without the CALL keyword.
DECLARE SUB Square(Param%) Square (Value%) SUB Square(Value%) STATIC Value% = Value% * Value% END SUB
Because of the unnecessary and incorrect use of parentheses, a copy of the argument is sent to Square instead of the argument itself, with the result that Value% is never actually changed. The fix is to either remove the parentheses, or add the word CALL. Another, related issue is placing a DEFINT after DECLARE statements. In the example below, the parameters X, Y, and Z are assumed by BASIC to be single precision, even though this is clearly not what was intended.
DECLARE SUB (X, Y, Z) 'X, Y, and Z are singles! DEFINT A-Z . .
The final issue I want to address here is potential overflow errors. The statement IF IntVar% * 14 > 1000000 can never be true, because BASIC performs integer math assuming an integer range only. Unless you compile your program using the /d debug option, the error will be unreported in a compiled program. If this statement is executed within the QB environment, BASIC will report an overflow error, even though the instruction certainly appears to be legal. But since integer math assumes an integer result, the product of IntVar% times 14 will overflow the range of integer values if IntVar% is greater than 2,340.
One solution is to use a long integer for IntVar, and BASIC will then use the range of long integers for the comparison. Using a long integer wastes memory, however, and calculations on long integers are slower and require more code to implement. A much better solution is to use CLNG (Convert to Long), which tells BASIC to assume a long integer result.
The statement IF CLNG(IntVar%) * 14 > 1000000 will create a long integer version of IntVar%, and then multiply the result times 14 and use that for the subsequent comparison. Unlike the copies that BASIC makes which steal DGROUP memory, the long integer conversion in this instance is handled within the CPU's registers. CLNG when used this way is really just a compiler directive, as opposed to a called library routine. Another solution is to add an ampersand after the constant 14, thus: IF IntVar% * 14& > 1000000. Again, no additional DGROUP memory is used to handle 14 as a long integer value.
Another interesting use of CLNG and CINT--unrelated to debugging but worth mentioning none the less--is to reduce the size of comparison code. When you use a statement such as IF X% > VAL(Some$), a floating point comparison is performed even if Some$ holds an integer value. By replacing that example with IF X% > CINT(VAL(Some$)) 6 bytes of code can be saved. The CINT tells BASIC that it will not have to perform any floating point rounding when it compares the two values.
When you are developing a large application that is comprised of many individual modules, there are several useful debugging techniques you can employ. One is to create short test-bed programs that exercise each subprogram and function. Finding an error in a complex program with many interdependencies between subroutines can be a tedious prospect at best. If you instead create a small program whose sole purpose is to test a particular subprogram, you will be better able to focus on just that routine.
Another useful technique for detecting and preventing sporadic errors is to test your code on "boundary conditions". If you have a routine that reads and process a file in 4K (4096 byte) increments, test it with a file that is exactly 4096 bytes long, as well as with other test files that are 4095 and 4097 bytes long.
Perhaps nothing is more frustrating than having a program fail with the message "xxx at line No line number". This message is a throw-back to the days when all BASIC programs had to use line numbers. Now that line numbers are not required in modern compiled BASIC, most programmers do not use them, opting instead for more descriptive line labels when labels are needed at all. When an error does occur and the program has been compiled with /d, BASIC reports the number of the nearest numbered line preceding the line in which the error occurred.
A good solution to track down the cause of such errors is to use a variant on a hardware debugging technique known as the "cut in half" method. In a complex electronic circuit that does not work, using this technique means that the circuit is first checked at its mid-point for the correct signal. If the circuit tests correctly at that point, then the error is in the second half. Therefore, the test engineer would "cut in half" again, and test at a point halfway between the middle and the end. If the test fails there, then the problem must lie between the middle of the circuit and that point.
In a purely software situation, you would add a line number to a line that falls approximately half-way through the program. If that number is reported, then the problem is occurring in the second half of the program. An enhancement to this technique that I recommend is to add, say, ten line numbers in evenly spaced increments throughout the program. This will let you quickly isolate the problem to a much smaller portion of the program.
Besides the line number (or lack of line number) that BASIC reports, the segment and address at which the error occurred is also reported. This is information is frankly useless in a purely BASIC environment. You must either use CodeView to identify the line that is associated with the error, or view the assembly language output that BC can optionally generate. These will be described in the section on advanced debugging later in this chapter.
Finally, it is important to point out that you should never use ON ERROR while a program is being developed. ON ERROR can hide programming errors that you need to know about. As an example, a LOCATE statement with incorrect values will generate an "Illegal function call" error. But if ON ERROR is in effect and your program uses RESUME NEXT for errors it is not expecting, you may never even know that an error occurred. If you run the complete program below you can see that there is no indication that an error occurred at the obviously illegal LOCATE statement.
CLS ON ERROR GOTO HandleErr LOCATE 100, -90 PRINT "My program seems to work fine." END HandleErr: RESUME NEXT
The single most powerful debugging feature that is available to you is the BASIC editing environment. More than just an editor that you can use to enter program statements, the QB environment is exactly that: a complete editing environment for developing and testing BASIC programs. The BASIC editor lets you enter program statements, single-step through a program, examine variable values, and much more. Besides being able to execute commands singly and in sequence, you can also trace into subroutines and functions, and even run your program in reverse.
The primary advantage of using the QB environment instead of a separate editor is the enhanced debugging capabilities. In most high-level languages, you first write a program using an editor, and then compile and run it to see if it works correctly. If an error occurs, you must start the editor again, load your program, and study the code to see what went wrong. In contrast, QB lets you run your program at the same time it is being edited. You can even modify the program while it is running and then resume execution, view and change variable values, and change the order in which statements are executed.
Further, BASIC can be instructed to stop and return to the edit mode when the program reaches a certain statement, or when a particular logical condition becomes true. For example, you can tell BASIC to halt the program when a variable takes on a specified value. These are extremely powerful debugging tools which have no equal in any other language. In the sections that follow, I will describe each of these capabilities in detail.
Early versions of Microsoft BASIC offered a very primitive trace capability that displayed the line numbers of the currently executing statements. Although this was better than nothing, interpreting a blur of line numbers flashing by on the screen required a lot of mental effort. When Microsoft introduced QuickBASIC version 3.0 they added greatly improved debugging in the form of a step and trace feature. To activate step and trace you would enter a STOP statement at a selected point in the source code. When the program reached that point you could then execute each statement in sequence by pressing a function key. QuickBASIC 3 also provided the ability to display continuously the value of a single variable in a window at the top of the screen.
QuickBASIC 4.0 offered an improved version of this feature, using additional function keys to control how a program proceeds. This method has been continued with little change through current versions of QuickBASIC and BASIC PDS. Of course, the primary reason you would want to step through a program one statement at a time is to determine why it is not working. For example, if you have code that opens a file for output but the file is never created, you would step through that portion of the code to see which statements are being executed and which are not. In particular, stepping through a program lets you see which path an IF or CASE test is taking.
Two function keys are used to single-step through a program, and four additional options are available to assist program debugging. Each time the F10 key is pressed, the current statement is executed and the program advances to the next statement. If you have just loaded the program being tested, you will press F10 once to get to the first instruction. Pressing F10 again executes that statement, and continues to the next one. If the current statement is related to screen activity, the screen is switched momentarily to display the program's output rather than the source code. The screen is also switched during a CALL statement or function invocation, in case that routine performs screen output. You can optionally toggle between viewing the output and edit screens manually by pressing F4.
In some cases you may want to treat a subroutine as a single statement, which is what F10 does. That is, CALL MySub is handled as single statement, and all of the statements within the routine are executed as one operation. In other cases, however, you may need to trace into a subprogram, GOSUB routine, DEF FN, or function, to step through its statements as well. This is what F8 is for. When F8 is pressed at a CALL or GOSUB statement or function invocation, BASIC traces into the procedure and lets you watch as it executes each statement individually.
Two additional capabilities let you navigate a program more quickly. Pressing F7 tells BASIC to execute all of the statements up to the current cursor location. This way, you are spared from having to watch a long sequences of commands that you know are working correctly. For example, stepping through a FOR/NEXT loop that initializes 1000 elements in an array is usually pointless. Therefore, when you reach that spot in the program you would manually move the cursor to the statement following the NEXT, and press F7.
It is also possible to force execution to a particular point in the program using the "Set next statement" option of the Debug menu. Unlike F7, though, the statements that precede the selected line will not be executed. Therefore, this option is equivalent to adding a temporary GOTO to the program, causing it to jump to the specified line.
One of the most powerful features of the BASIC editor is that you can actually modify your program, then resume execution. In earlier versions of QuickBASIC, making even the slightest change to a program--even if only to a single comment--the entire program would have to be recompiled. BASIC can now preserve variable values and indeed the entire program state during most types of editing operations.
The last important step operation I want to mention now is the History feature. This too must be selected from a menu, and using it will slow your program's operation considerably. When the History option is selected from the Debug menu, BASIC remembers the last 25 program statements, and lets you step through your program in reverse. For example, if a variable has taken on an incorrect value, you can walk backwards through the program to see what statements caused that to happen. Where F8 steps forward through your program, Shift-F8 instead steps backward.
As powerful as BASIC's single-step feature is, it is only half of the story. Equally important is the Watch capability that lets you view a program's variables in real time. One or more variables may be placed into a special Watch window at the top of the editing screen, and their values will be displayed and updated after each statement is executed. Between the Step and Watch features, you can observe all aspects of your program's operation as it is executing.
Besides watching variable values, you can also monitor complex expressions and function results. For example, you could watch the value of X% * Y% + Z%, ASC(Work$), or the result of a function such as StrFunction$(Array$(), Count%). Because each variable or expression is updated after every program statement, your program will run more slowly when many items are displayed in the watch window. However, this is seldom a problem in a debugging situation, and the ability to see precisely what is happening far outweighs the minor speed penalty.
Being able to watch the results of expressions as well as simple variables offers some useful and interesting techniques. As an example, suppose you are watching a string variable named Buffer$. If Buffer$ is very long, you can use LEFT$ or MID$ to watch just a portion of the string: MID$(Buffer$, CurPointer%, 70). This expression displays the 70-character portion of Buffer$ that is currently pointed to by CurPointer% (assuming, of course, you are using variables with those names).
Likewise, if you are observing a string but nothing is showing in the watch window, you could watch "{" + Work$ + "}". This displays "{}" if the string is null, and shows if there are leading or trailing blanks or CHR$(0) bytes. Adding braces also lets you see if the string contains characters that begin past the edge of the visible window.
One particularly powerful use of BASIC's Watch capability is related to the fact that all of the expressions are evaluated anew at each statement. Earlier I mentioned how insidious "String space corrupt" errors can be, because BASIC checks the integrity of its string memory only when a string is being assigned. Therefore, watching the expression FRE(Any$) tells BASIC to evaluate string memory after every source line. Thus, as soon as string memory is corrupted it will be immediately reported. This technique can be extended to identify a "Far heap corrupt" error as well, by watching the expression FRE(-1).
Besides the Step and Watch capabilities, there are two additional features you should understand: Break Points and Watch Points. When a program is very large and complex, it becomes impractical to step and trace through every statement. Also, in some cases you may not know at which statement an error is occurring.
Pressing F9 sets up a Break Point which tells BASIC to halt when it reaches that point in the program, regardless of how it arrived there. You can have multiple break points, and the program will run normally until the specified statement is about to be executed. Simply place the cursor on the line at which the program is to stop, and press F9. That line will be highlighted to show that it is currently a Break Point. Pressing F9 again removes the Break Point.
A Watch Point tells BASIC to execute the program, until a certain condition becomes true. Some examples of Watch Points are X% = 100, ABS(Total#) > 1000, and FRE("") < 1000. In the first example you are telling BASIC to stop the program and return to the editor when X% equals 100. The second example will stop the program when the absolute value of Total# exceeds 1000, and the third halts it when there are less than 1000 bytes of string space remaining.
Considered together, these debugging features are extremely powerful. You can tell BASIC, in effect, "Run until the value of Count% hits 14; then stop the program, and let me walk backwards through the program to see how that happened."
Another very powerful debugging solution at your disposal is to compile your program with the /d debug option. When creating an .EXE file in the BASIC environment from the Run menu, you would select the "Produce debug code" option. Compiling with /d tells BC to add three important safeguards to the code it generates. Some of these debugging issues were described in Chapter 1, but they deserve elaboration here.
The first code addition is a call to a central event handler prior to every BASIC program statement, to detect if Ctrl-Break was pressed. Normally, a compiled BASIC program is immune from pressing Ctrl-Break and Ctrl-C, unless the program is processing an INPUT statement. BASIC adds break checking to let you get out of an endless loop or other similar situation, without having to reboot your computer.
The second addition is an overflow test following each integer and long integer addition, subtraction, and multiplication, to detect results that exceed the range of legal values. If you have a statement such as X% = Y% * Z% and the result after multiplying is greater than 32767, the overflow test will detect that and produce an error message. Otherwise, X% would be assigned an erroneous value and your program would have no way to detect it. Floating point operations do not need any additional testing, because overflows are detected and reported whether or not /d is used.
The last additional code that BASIC adds when /d is used is array element bounds checking. If you have dimensioned an array and attempt to assign an element that doesn't exist, a compiled BASIC program will normally ignore the error. For example, if an array has been dimensioned using DIM Array%(1 TO 100) and you then have the statement Array%(200) = 12, BASIC will store the value 12 at what would have been the 200th element. This can lead to disastrous consequences such as overwriting an element in another array, or corrupting string memory. When /d is used BASIC adds additional code to check every array element referenced, and reports an error if that element does not exist.
Because of the added checking for overflow errors and illegal element numbers, a program compiled with /d will be larger and run more slowly than one in which /d is not used. Therefore, you should not release a program for general use that has been compiled with the debug option. One exception worth noting is that QuickBASIC versions 4.0 and 4.5 contain a bug that generates incorrect code for certain long integer array operations. The only solution when that happens is to use /d. This way, the routine that calculates element addresses and checks for illegal element numbers is used, rather than the incorrect in-line code that BC produces directly.
You could also compile with the /ah (huge array) switch, which uses the same routine to calculate and check array element addresses. Using /ah has an advantage over /d in this case, because your program will not be halted if Ctrl-Break is pressed. Using /ah also avoids the extra code and time to check for overflow errors. However, /ah affects dynamic arrays only, and errors with static arrays will not be prevented.
When a program is run in the BASIC editor, the same protection that /d provides is employed. This added debug testing within the editor is one more contributor to its slowness when compared to a fully compiled program.
Although being able to step through your program and watch its variables in the BASIC editing environment is very powerful, there are still some limitations inherent in that process. For example, it is possible that a program will work perfectly in the editor, but not when it has been compiled to an .EXE program. Microsoft has tried to make the BASIC editor as compatible with BC as possible, but the editor is an interpreter and not a true compiler. There are bound to be some differences in how the program runs. Another limitation is that some programs are just too large to be run within the editor. Finally, if you receive an error message from an executable program that lists only a segment and address, there is no way to determine where the error occurred using the editor.
In these cases you will need to work with the actual compiled program. To relate an error address to the original BASIC source statement you must be able to see the assembly language code that BC generates, along with the original BASIC source. One way to do this is with the Microsoft CodeView debugger. CodeView comes with BASIC PDS [and VB/DOS Professional Edition] as well as with Microsoft's Macro Assembler. CodeView provides a debugging environment that is similar to the QB editor, except it is intended for tracing through a program that has already been compiled.
Another way is to instruct BC to generate an assembly language source listing as it compiles your program. This listing shows a mix of BASIC source statements and the resultant assembly language code and addresses. However, the listing is not as clear or easy to follow as the display that CodeView presents. But if you do not have CodeView, this is your only choice. I will describe this method first.
To create an assembly language list file you use the compiler's /a switch, and then specify a list file name. The syntax is shown below, followed by a sample list file that is generated.
You enter this:
bc program /a [/other options] , , listfile;
LISTFILE.LST contains this:
PAGE 1
25 June 91
14:28:08
Microsoft (R) QuickBASIC Compiler Version 4.50
Offset Data Source Line
0030 0006 CLS
0030 0006 INPUT Count%
0030 ** I00002: mov ax,0FFFFh
0033 ** push ax
0034 ** call B$SCLS
0039 ** mov ax,offset <const>
003C ** push ax
003D ** call 0000h
0040 ** pop ax
0041 ** add ax,000Dh
0044 ** push cs
0045 ** push ax
0046 ** call B$INPP
004B ** jmp $+04h
004D ** dw 0002h
004F ** db 00h
0050 ** db 02h
0051 ** mov bx,offset COUNT%
0054 ** push ds
0055 ** pop es
0056 ** push es
0057 ** push bx
0058 ** call B$RDI2
005D 0008 IF Count% < 100 THEN
005D 0008 Count% = 100
005D 0008 END IF
005D ** call B$PEOS
0062 ** cmp word ptr COUNT%,64h
0067 ** jl $+03h
0069 ** jmp I00003
006C ** mov COUNT%,0064h
0072 0008 PRINT Count%
0072 0008 END
0072 0008
0072 0008
0072 ** I00003: push COUNT%
0076 ** call B$PEI2
007B ** call B$CEND
0080 ** call B$CENP
0085 0008
43981 Bytes Available
43643 Bytes Free
0 Warning Error(s)
0 Severe Error(s)
Here, the list file shows the original BASIC source code, as well as the generated assembly language instructions. The column at the left holds the code addresses, and these correspond to the addresses that BASIC displays when a program crashes with an error message. Unfortunately, several BASIC statements are grouped together, so it is not immediately apparent which address goes with which source statement. For example, after the BASIC statement INPUT Count%, the earlier assembly language instructions that clear the screen are shown. Similarly, the call to B$PEOS is actually part of the INPUT code, although it is listed following the IF test.
When BASIC displays an error message and ends your program by displaying a segmented address, only the address portion is meaningful. The segment in which a program is running will depend on many factors, including the DOS version (and thus its size), the FILES= and BUFFERS= values specified in CONFIG.SYS, and whether TSR programs and device drivers are loaded. Each of these factors cause the program to be loaded at a higher segment, although the addresses within that segment never change. Also, in a multi-module program, a different segment is used for each module's source file. Therefore, if the message is "Illegal function call in module XYZ at address 3456:1234", you would compile XYZ.BAS to create a list file instead of the main program. The code in the vicinity of address 1234 will be where the error occurred.
Although compiling with the /a switch lets you view the assembly language code that BASIC creates, there is little you can actually do with that information. CodeView is a much more powerful debugging tool, and it lets you step through an .EXE file as it is running. This lets you follow the compiled program's execution path, and also view its assembly language instructions. Further, CodeView can trace into BASIC's library routines, as well as calls to C or assembly language routines that you have written.
CodeView can also be used to see how many bytes of code are generated for each BASIC statement. This is a good way to compare the relative efficiency of different programming methods, to see which ones produce less code. It is important to understand that the size of the assembly language code generated for a given BASIC statement is a combination of two factors: the number of bytes the compiler generates for each occurrence of the statement, and the size of the called routine within BASIC's runtime library. Of course, the called routine is added to your program only once. However, the code that sets up and calls the routine is added each time the statement is encountered.
Compiling a program for use with CodeView is very simple, and merely requires the addition of special compiler and linker option switches. Note that you cannot compile a program for CodeView from within the QuickBASIC editor; you must compile and link manually from the DOS command line, as shown below. Also notice that the BASIC program must be saved as ASCII text, and not with the special "Fast Load" method that QB optionally uses.
bc program /zi [/other options]; link program /co [/other options]; cv program
The /zi option tells BC to write additional information into the object file, which is used by LINK and CodeView to relate each line of BASIC source code to its resultant assembly code. The more meaningfully named /co switch is required so LINK will know to do likewise. You may be interested to know that /zi is named after Microsoft legend Mark Zibikowski, whose initials (MZ) also appear as the first two bytes in every DOS .EXE file.
Once the program has been compiled and linked, start CodeView by entering CV followed by the file's first name (that is, without the .BAS or .EXE extension). You will then be presented with a screen very similar to that of the QB editor. Most versions of CodeView initially show the BASIC source code. In other versions, you must press Alt-R-R to "restart" the program and bring it to the first source line. I should point out that CodeView is a quirky program, and it is often referred to as the program that people "love to hate". It has some glaring omissions, many aspects of its interface are inconsistent and downright obnoxious, and I personally would be lost without it.
When the BASIC source is displayed, you may press F4, F7, F8, and F10, which perform the same functions as their BASIC editor counterparts. One important difference, however, is that you may also press F3 to show a mix of BASIC and assembly language code. Stepping through the program with F8 and F10 will execute either a single BASIC statement or a single assembler command, depending on the context. That is, if you are in the BASIC view mode, then you will step through the BASIC code. If the assembly language code is being displayed, then you will step through that instead.
Figure 4-1 [not available here, sorry] shows a screen snapshot of a short sample program as displayed by CodeView when it is first started in the BASIC view mode. Figure 4-2 [also unavailable] shows the same program after pressing F10 to execute up to the first statement, followed by F3 to view a mix of BASIC and assembly language. This screen is in a 50-line mode to allow the entire program to be displayed. Although it is not shown here, CodeView can continuously display the processor's registers in a small window at the right side of the screen. The register display is alternately activated and deactivated by pressing F2.
Notice in Figure 4-2 that CodeView displays each BASIC statement indented and with a line number. This lets you identify where each BASIC command starts, and also which block of assembly language code it is associated with. The numbers at the left edge of the display show the segment and address of each instruction in hexadecimal notation. The segment value never changes within a single program module, although the addresses increase based on the number of bytes in each assembly language instruction. As you can see, some assembly language commands are as short as one byte, and others are as long as six.
In the first instruction, CLS, a value of -1 (FFFF hex) is passed to the CLS routine as a flag to show that no argument was given. Had the BASIC statement been CLS 2, then a value of 2 would have been moved into AX instead. Nine bytes of code are generated each time CLS is used, not counting the code within B$SCLS. Besides showing the B$SCLS routine name, CodeView also shows the segment and address at which B$SCLS resides. Knowing the routine's address is of little practical use in this situation, and it is displayed solely for informational purposes.
The INPUT statement is fairly complicated to set up, and I won't belabor what every assembly language instruction does. But several items are worth discussing. The first is that CodeView attempts to relate every number it encounters to a variable or procedure address. In many cases this is confusing, because some numbers are simply that, and have no relationship to a variable or procedure address.
For example, at address 39 the assembly language command MOV AX,40 is shown as MOV AX,b$STRTAB_END+10 (0040), as if there was some significance to the fact that the value 40 is an address ten bytes past the end of an internal string table. Likewise, two instructions later the value 40 is represented as being 31 bytes past the beginning of the B$LENDRW procedure. Two instructions past that the value 13 (0D hex) is added to AX, and again CodeView tries to establish a significance where none exists.
In not one of these cases are the values shown related to the named address, and you should therefore treat those named labels with skepticism. The only symbolic names that are meaningful in most cases are variable and procedure names that do not have an extra value added to them. In the instruction MOV Word Ptr [COUNT% (0036)],b$HEAP_FIRST (0064) at address 6C, the address for Count% (36) is valid, while the value 64 named b$HEAP_FIRST is meaningless. In this case, 64 hex represents the value 100 in the BASIC statement Count% = 100. Whatever b$HEAP_FIRST may represent, it has no meaning here.
I suggest that you enter this short program and then step through it one statement at a time, just to get a feel for how CodeView operates. You should also try tracing into some of the BASIC library calls, as well as into a simple subprogram or two of your own. Again, you may use either F10 or F8 to step through the code, but only F8 will trace into code that is being called. You can also use F8 to trace into some BIOS interrupts, but you should never try to trace through a DOS interrupt (21 hex). Many DOS services never return, or return in a non-standard manner, and a locked-up PC is the likely result. You will not hurt anything if you do trace into a DOS interrupt, but be prepared to press Ctrl-Alt-Del.
Besides being able to view and step through the assembly language code that BASIC creates, you can also view and modify your program's data directly. If you have pressed F2 to display the CPU's registers, CodeView will show the value currently in every memory address that is about to be accessed. For example, if the next statement to be executed is MOV Word Ptr [COUNT%],10, CodeView will show the current contents of the variable COUNT%.
A range of memory addresses may be displayed by entering commands into the immediate window at the bottom of the screen. When CodeView is first started, the cursor is placed at the bottom line in that window. As with the BASIC editor, the F6 key is used to toggle between the code output and immediate windows. Unlike the BASIC editor, however, you may type commands regardless of which window is active.
The three primary commands you will find useful are D, U, and R. The D (Dump) command tells CodeView to display a range of memory, starting at a given address. For example, D 0 means to show the 32 bytes that start at address 0 in the default data segment. Likewise, D ES:100 means to start at address 100 in the segment held in the ES register. Unfortunately, CodeView is particularly obtuse in this regard, because in some cases the numbers you enter are assumed to be decimal while in others it assumes hexadecimal. Which is which depends on your view perspective (selected with F3), and I won't even begin to offer a reason or explain the confusing rules. If you don't get what you expect, try adding an "&H" prefix to the number. And if you start by using &H and CodeView reports a syntax error, then try it without the &H.
When the contents of memory are displayed, they are shown as individual bytes, rather than as integer words which is generally more useful. In the listing below, two string constants have been displayed in response to the command D &H40. For space reasons, the segment and address which CodeView adds to the left of each row of values are instead shown above the rows.
>D &H40 5676:0040 02 00 44 00 48 69 23 00 4A 00 41 42 43 44 45 46 5676:0050 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56
As you learned in Chapter 2, BASIC near strings have a 4-byte descriptor, with the first two bytes holding the string's current length, and the second two bytes its current address. Beginning with the first two numbers displayed, the 02 00 represents the length of a 2-character string, and the 44 00 indicates the address which is 44. The data itself is a CHR$(&H48) followed by a CHR$(&H61) ("Hi"), and it immediately follows the string descriptor. When two bytes are used to store an integer word, the least significant byte is kept in the lower memory address. Therefore, the value 0002 is actually listed as 02 00 (CodeView adds an extra blank between bytes for clarity).
Immediately following the six bytes for the string "Hi" and its descriptor is another descriptor. This one shows that the string has a length of 23 Hex bytes, and its data starts at address 4A Hex. Again, the value 0023 is shown as 23 00, and the address 004A is displayed as 4A 00. This string contains the data "ABCDEFGHIJKLMNOPQRSTUV".
The U (Unassemble) command can be used to show the assembly language source code at any arbitrary segment and address. The command U 2000:1000 will unassemble the code at address 2000:1000, though again you may need to use U &H2000:&H1000 in some view modes. The U command is not used that frequently, since CodeView is used most often to step through code in sequence, rather than to examine an arbitrary block of instructions.
The R command lets you change the contents of a register, and this might be useful when debugging your own assembly language subroutines. When you type, for example, RCX and press Enter, the current value of the CX register is displayed and you are prompted for a new value. Pressing Enter alone cancels the command and leaves the current register contents intact. Otherwise, the value you enter will be assigned to CX. This is similar to BASIC's immediate window, in which you can assign new values to a variable.
The last CodeView features worth describing here are Watch Variables and Watch Points, which are similar to the same features in QB. Unlike QB, though, you cannot use an expression as the target of a Watch; it must be a simple variable name, array element, or address. Watch Variables may be added using the pull-down menu, or by pressing Alt-W and then typing the variable name. If you are in the BASIC view mode you may add only BASIC variables; in the assembly language view mode you can add only assembly language variables. To monitor the contents of a memory address requires the W command. For example, W 40 will set up address 40 as the target of a Watch.
Although CodeView does support Watch points, whereby the program will run continuously until a given expression is true, you won't want to use that feature. Asking CodeView to stop when, say, CX becomes greater than 100 will cause your program to run at less than one thousandth its normal speed. Therefore, I have never found using Watch Points effective in any situation--it is always too slow.
I have avoided discussing the latest versions of CodeView, in favor of focusing on those features which are common to all versions. CodeView 3.10 which is included with BASIC 7.1 has several new convenience features, and a few new bugs as well. Many of the commands that in earlier versions have to be entered manually are now available by simply typing new values onto the display. For instance, where older versions of CodeView required you to enter Dump commands repeatedly, the new version updates the displayed values in a range of addresses constantly. And to change the address range, you may now simply move the cursor to the segment and address numbers and type new ones. An option to display memory values as words or even single and double precision values is also present in version 3.10.
Now that you have seen what CodeView is all about and how to use it, I want to conclude this chapter with a practical example. As I mentioned in Chapter 3, the amount of stack memory that is needed in a non-static subprogram or function can be difficult to determine. The calculation itself is trivial: simply add up the number of bytes needed by every variable in the routine. Each integer requires two bytes, single precision, long integer, and string variables need four bytes, and so forth. The problem, of course, is who wants to do all that counting, especially when there may be hundreds of variables. Counting is what computers are for, no?
The solution is that BASIC knows how many bytes are needed for the subprogram, and the very first thing a subprogram does when it is invoked is to call another routine that allocates the necessary stack space. So rather than use trial and error methods to increase the stack in small increments, you can use CodeView to directly see how many bytes of stack space are being requested. Here's how that's done, using the example program shown below.
DEFINT A-Z DECLARE SUB StackTest (Dummy) Test = 10 CALL StackTest(Test) END SUB StackTest(AnyVar) X = 100 Y = 10 Z = AnyVar END SUB
Save this program as an ASCII file using the name TEST.BAS, and then compile it with the /o and /zi options. Next, link TEST.OBJ for CodeView using the /co option. Then start CodeView by entering CV TEST. Once you are in CodeView and viewing the BASIC source, press F10 to skip past BASIC's start-up code. At this point the cursor should be on the first statement, Test = 10. Finally, press F3 to show a mix of BASIC and assembly language source code. The display should look similar to that shown in Figure 4-3 [unavailable].
Notice the first statement within the TestStack subprogram at line 7, where the value 6 (erroneously labeled b$STRTAB+6) is assigned to the CX register. This is the number of bytes of stack space being requested from the B$ENRA routine which is called in the next instruction. B$ENRA is the routine that actually allocates the stack memory, and it uses the value BASIC sends in CX to know how many bytes are needed. TestStack has three local variables and each is a two-byte integer, hence six bytes are required to store them on the stack.
For a very large program, the value assigned to CX will of course be much larger. Further, if one subprogram calls another, it will be up to you to add up all of the CX values to determine the total stack memory requirements. But this is very much easier than counting variables.
In this chapter you have learned how to identify and correct common programming errors. You have also learned the importance of understanding BASIC's various quirks, and how some statements do not always do exactly what you thought they would. I have shown several debugging strategies, including a software adaptation of the "cut in half" hardware technique.
Perhaps your most powerful debugging ally is the QuickBASIC and QBX editing environments. These powerful editors let you single step through a program, monitor variable values and function results, and halt your program when a specified condition occurs.
When BASIC terminates a program prematurely with an error message and a segmented address, you can either use the BC compiler's /a option to generate a source listing, or use CodeView to see where the error occurred. CodeView can also be used to step and trace through a program at the assembly language source level, and to determine the number of bytes of stack memory a non-static procedure requires.
In Chapter 5 you will learn about compiling and linking BASIC programs. I will present a complete overview of the many BC and LINK options that are available, and discuss the relative merits of each.
By Matthew R. Knight <horizonsqb@hotmail.com>
I seriously doubt that anyone in the QB world hasn't seen some newbie making an ass of himself on the boards - or anywhere else for that matter. But have you ever stopped to think that maybe that newbie will one day become a famous and respected programmer? In the same way, have you ever wondered what todays great proggers were like when they were newbies?
Welp, DarkDread and Piptol have some confessions for ya...
Piptol: "I guess I was different to your average newbie in that I wasn't working on a huge, vastly complex RPG as a first project =) I'd first learnt BASIC on an old 8-bit Amstrad CPC computer, so I was already familiar with a lot of the simple stuff (printing text and drawing lines, etc). I just used QB the same as the Amstrad BASIC, but that meant I missed a whole load of features I didn't know about.
"In fact, one of my first QB projects was an awful 'sprite system' called QSprites v1.0.. I wrote it because I wasn't aware of QBs GET/PUT commands! And at the time I wondered why Jorden wouldn't add it to his page! (<http://qbasic.qb45.com/> -ed)
"After seeing some of the flamings people took on the boards, I often used to post questions under a false nick. That way I could get an answer, and the 'real Piptol' would emerge unscathed!
"I was just learning HTML at the same time, and once acidentally brought the Future Software board crashing down with an open HREF tag (sorry Jorden!)
"These days I'm always ready to help newbies in QBchat, or on one of the message boards, because I remember how annoying it was when people put you down just for asking stuff! I really hated the elitism of some people. It seems these days a lot of those people have (thankfully) moved on, and QB is now a safe playground for newbies, as it should be!"
DarkDread: "Well... To tell the honest truth, my habits weren't extremely different then, compared to what they are now. I suppose that, the only big difference was that I took an active part in the QB community, and I would always check out others' games... I don't do that anymore these days.
"As for funny... I dunno... I can't honestly think of anything... The closest would be that, when I first e-mailed Lith2 to a few people, I was very suprised that they even liked it... I honestly didn't think it was that big of a deal. I figured that, everyone made much better stuff than I did when it came to QB. It wasn't until a few e-mails of 'wow, this is awsome!' that I realized that my games weren't too bad."
Y'see newbies? There's hope for you yet! :)
By Christopher Charabaruk <evilbeaver@tekscode.com>
Everyone knows that you can't end a QB program with an errorlevel. Everyone knows that you can't use long file names in QuickBasic. Yeah, and everyone knows that the moon is really made of blue cheese. In other words, you can use errorlevels and long file names - there's just some tricks involved. In this article, I will show you how to pull off these amazing stunts, and I'm throwing in a few others, too. Bon appitit!
Errorlevels are nifty things. You can use them in your programs to let users know if there's a problem (using ON ERROR and exiting using ERR), or making programs that exit to run other programs and then return by batch file (like the Arachne browser for Dos). To be able to use errorlevels, you will need to use a library. I'm sure that you won't be able to run your program in the IDE if you're using errorlevels, but if you find a way, don't hesitate to tell me.
Start up QB and open your program. Now, right by the top, add the line
DECLARE SUB ExitWithErrorLevel ALIAS "_exit" (BYVAL Level%)
to be able to use errorlevels. You should all be aquainted with DECLARE SUB, but what are ALIAS and BYVAL, you might ask? Well, ALIAS means that when you call ExitWithErrorLevel, you're actually calling the _exit routine in the library. If you've made a library in C with overloaded functions, then ALIAS is what you use so that people using the library in QB can still use the overloaded functions (by giving each copy of the function a different name).
BYVAL passes the value of a variable, instead of a reference to the variable, to a function. That way, the function is unable to change the contents of the variable. Usually, when you call a SUB or FUNCTION, the variables passed are passed by reference (similar to passing a pointer, but still way different). That way, the SUB or FUNCTION has the ability to change the contents of the variable. Passing by value, means that the actual value of the variable is passed, so that the SUB or FUNCTION cannot change the value of the variable.
So, getting back to using errorlevels... To exit and pass an error code, use code like this:
Level% = 3 ' use any error level here ExitWithErrorLevel (Level%)
For reasons that elude me, you must put the errorlevel in a variable before calling ExitWithErrorLevel. I believe that it has something to do with BYVAL. Now, for some practical examples of using errorlevels. This first one lets you exit with an errorcode whenever the program has an error which cannot be trapped.
ON ERROR GOTO TrapError
' Code goes here
TrapError:
Level% = ERR
SELECT CASE Level%
' Error traps go here
CASE ELSE
PRINT "ERROR: Fatal untrapped error " + Level%
ExitWithErrorLevel(Level%)
END SELECT
The second example is for use in a batch file. It checks if the errorlevel is 128, and if so, pipes the dir output into a file called tempfile.tmp and goes to label runagain (not included).
if errorlevel 128 goto getdir goto end getdir: del tempfile.tmp dir >> tempfile.tmp goto runagain end: echo .
So now you can use errorlevels in your programs! Thanks to Robert Fortune <rfortunea@aol.com> for helping me work this all out.
Using long file names in QB means that you have to use the MbLfn library by Hans Lunsing <jlunsing@doge.nl>. Don't worry, this library is very easy to use. It even includes an example file (so I won't be showing examples here). It's included as mblfn.zip in the downloadable edition of this issue.
To begin using long file names in your program, include the mblfn.bi file, and call the EnableLfn% function. If the library can use long file names, this function returns TRUE, but if it doesn't, FALSE will be returned. Keep in mind those are constants, not strings. To terminate long file name service, call DisableLfn. It's called automatically at the end of your program, so you shouldn't have to worry about it.
If EnableLfn% did return TRUE, that means that the QB commands CHDIR, MKDIR, and RMDIR will support long file names without any problems. However, with OPEN, BLOAD, and BSAVE, long file names will be capitalized and truncated. As we all know, that's a bad thing, so the library includes the Lfn$ function. Just pass the long file name to Lfn$ function, and have it return the DOS filename to those three troublemakers. And you can even use Lfn$ with short file names, and when long file names aren't supported!
Some other QB commands don't support long file names, and so there are other routines to replace them. There are even extras (like long file name versions of CURDIR$ and DIR$ from PDS and VBDOS, and stuff replacing MS-DOS' ATTRIB.EXE). This chart shows the originals, and their long file name counterparts:
| QB | MbLfn32 | Notes |
| CURDIR$ | LfnCurDir$ | returns current path for drive drive$ (if drive$ not specified, current drive) |
| DIR$ | LfnDirFirst$ LfnDirNext$ | returns filenames matching filespec$ (wildcards allowed) |
| FILES | LfnFiles | |
| KILL | LfnKill | |
| NAME | LfnName | |
| n/a | LfnGetAttrib% | for getting file attributes |
| n/a | LfnSetAttrib | for setting file attributes |
You should all know how to use FILES, KILL, and NAME, and using their replacements is almost the same. The remainder of MbLfn I won't explain, there's just too much for a beginner's primer on QB with Lfn. Read the MbLfn manual for all the other details and everything.
Finally, if errors occur, you must check for yourself by using DOSErr or DOSErrTest. They both return the DOS error code (see Appendix A of the MbLfn manual), but DOSErrTest resets it to zero afterwards. It would be nice if MbLfn would just do errors in a way that lets you handle them like any normal ones in QB, but because of oversights in Redmond when making QB, only libraries actually written in QB can do that.
Now that you can use long file names, get rid of wierd unreadable file names in your games, utilities, and libraries!
Some people just don't like having to install the QB programs they download in a certain place. But if you know how to code, you can make it so that your programs can exist in any directory. Still, there's times that you should know what directory your program is in, and occasionally, even the program's name. By using the greatest of DOS interrupts, that's all a piece of cake.
The pathname.bas file included in the downloadable edition of this issue, written by Christy Gemmell (e-mail unknown), is all you need. Regardless of it saying VBDOS, pathname.bas will also work for QB and PDS without any modification. The PathName$ function in the file accepts one string variable, which is where the function places the filename of the program calling the function, and returns the path of that program.
Now, that wasn't so painful, was it? Well, don't figure on that being the end of tips, tricks, or code snippets! Issue #9 will see the return of QB Tricks and Tips to QB Cult Magazine! So send in your fasthacks, your workarounds, and anything else that's small and really useful to the whole community. Remember, we're here for the QB coders, by the QB coders.
By EvilGeek (e-mail withheld on request)
In this article, i'm only going to handle the 2d case of convex hull. The convex hull of a set of points is the smallest convex polygon containing all of the points. This is a helpful thing to know when creating isosurfaces, and a bunch of other shit.
Suppose we want to take the convex hull of the points in fig. 1 for a moment. How would we go about doing this? There are several algorithms for finding the convex hull, but I won't describe some of them. If you want more info, look at the bibliography at the end of this article. The slowest method (runs in n^4 time) is to test each point (n) against every single possible triangle in the data (n^3). If the point is interior to any of the triangles, we discard it (testing interiority by using the walk-north algorithm).
Needless to say, we don't have time for n^4 operations to find the convex hull of something (the convex hull of just 20 points would be 20^4 = 160000 tests), so nerds have developed more efficient algorithms. There's an n^3 algorithm which is very similar to the n^4 algorithm described above. If you want an n^3 algorithm too badly, look in the biblio. The gift-wrapping algorithm is the next one I will discuss here, and I believe it runs in n^2 time. Basically, the principle of this algorithm is that you take the lowest point, then you find the line with the lowest angle (closest to horizontal), repeat (except you find the closest to the last angle), until you end up at the first point again.
Wow, that's a significant improvement, from n^4 to n^2, but we can do better. We can use the quickhull algorithm, which takes the highest, lowest, leftmost, and rightmost points as a guess polygon, and checks each point to see if it is interior. If not, we add it to the convex hull. One thing that you can easily fuck up with this algorithm is testing to see if formerly exterior points are now interior, and if so, removing them.
And here's our convex hull:
By QbProgger <qbprogger@tekscode.com>
[Editor's Note: Sorry this is incredibly small. QbProgger put this together really quickly, since he was quite busy in December.]
Simple enough, eh? :)
Next QBCM will feature a demo of this fighting game structure as well as an explanation of how to make a sidescroller with a physics engine!
Welcome to the first Demo of the Month column. Every month, QBCM will spotlight a different demo, from sound to graphics, to anything else done in QuickBasic. If you want your demo to be demo of the month, just e-mail it to <qbcm@tekscode.com> with subject "Demo of the Month" (without the quotes).
The first demo of the month is Crack, which was coded by Lithium <lithium@lithiumdex.com>. It features a really cool flame effect, with text bouncing up and down the screen continously. The image doesn't really give Crack the good look it actually has, since I took it in a hurry. Source is available, so you can find out just how Lithium did all this neat stuff. Crack is available as crack.zip in the downloadable edition of this issue.
Future Software, which recently underwent a facelift, is one of the largest QB resources on the net. With over a thousand files available, a very active webboard, and a new tutorials section (the site formerly known as Alternate Logic), Future Software should be a staple of any QB programmer. And it doesn't end there - Future Software is home to the excellent Future.Library, Arrakis, and also has sections on C/C++, Perl, and even Half-Life and Diablo 2! It's clear that Future Software is one the sites of QB.
Is Nekrophidius right in his comment in QB on Acid issue #6? Is QB Cult Magazine really the best QB e-zine since the late great QB: the Magazine? We went to the people to put this to the test, and here's what we found:
Thanks to everyone who participated in this issue's poll. Now go vote on next issue's!
By QbProgger <qbprogger@tekscode.com>
Ever wanted to learn the secrets of a power programmer? Yes of course!
This column is an introduction to power coding, and it covers making your code just a little bit cleaner for everyone to understand and read. After all, the most important thing about a program is that the function is understandable not only to the programmer, but the user as well!
The only thing you should have in your main module are SUB Declarations, an init call, a simple game loop, and then a deinit call.
For example:
DECLARE SUB blalbhalh
DECLARE SUB blalbhalh
DECLARE SUB blalbhalh
DECLARE SUB blalbhalh
DECLARE SUB blalbhalh
Init
DO
UpdateObjects
UpdateKEyboardstuff
WAIT &H3da,8
Display
LOOP UNTIL GameQuit = 1
Deinit
SYSTEM
This makes your main module readable and understandable. You should never bloat up your main module with arrays and data filling. Do that in Init fer chrissakes. Also, with this setup, you need not modify the main module, only the subs called from the main module.
Don't make a SUB with a useless function. Make SUBs that explain what they do jsut by the name.
For example:
Sub ConvertXYToVector End Sub
You can understand what that SUB does without even looking at it. Don't make a SUB called ConvertZtoTheta and then it just prints out a menu. This is confusing and makes it hard for people to read and understand your code! Make your code readable at all costs!
Next issue sees yet another chapter of Basic Techniques and Utilities, the 5th, "Compiling and Linking". Also, our imfamous columnists shall write more material that deserves a Pulitzer, you'll just how popular each version of QB is in the CultPoll, and last but not least, you shall revel in more great programming articles.
Until next issue!
Chris Charabaruk (EvilBeaver), editor