Cross-reference your program- save hours of debugging time with XREF.ARC on your START disk!

Buying GFA BASIC made me think of all the BASIC programming utilities I've used over the years-some good, some not so good. I think the two programs I found the most useful were a line renumbering utility and a variable-and-label cross-reference program. With GFA BASIC, the first program was obsolete, but I could certainly use the second. I quickly discovered that a cross-reference program did not exist for GFA BASIC, so I decided to write my own. Thus Xref was born.

Xref reads a copy of your BASIC program from disk and compiles a listing of the program's variables, labels and procedure names, along with the line numbers on which they appear. The program is GEM-based and was written using GFA BASIC. It runs in either medium or high resolution.

Preparing Your File for Xref
Xref can only cross-reference a file properly if it's a text file with the BASIC commands in all uppercase and everything else in upper and lower case. Run GFA and load your program. Press the Escape key to go to direct mode and then type DEFLIST0 and press Return. Press the Escape key again and then press Return to get back to the GFA edit screen. Select SAVE,A (Shift F2) and save the file with the extender .LST.

Xref can cross-reference BASIC files as large as 3,500 lines. If you happen to have a file that exceeds this limit or if you run out of memory you'll need to divide your program into two or more separate files. To do this, first load your program into GFA BASIC. Next, mark a big block of text with the BLK STA (Shift-F5) and BLK END (F5) commands, then save it using the BLOCK (F4) "W" command. Finally, mark the remainder of the program and save it to a separate file.

Xref's split-screen display lets you examine
and search through your variables, procedure
names and labels in the upper window, and study
exactly how they are used in the numbered listing
of your BASIC program below.

Running Xref
To run Xref, copy the files XREF.ARC and ARCX.TTP onto a blank, formatted disk and un-ARC the file, following the Disk Instructions elsewhere in this issue. Double-click on XREF.PRG to run the program (the file XREF.RSC must be in the same directory). Xref will come up with a file-selector box; select the file you wish to cross-reference.

Xref will then read and cross-reference the file. It also will provide you with a dialog box to show what percentage of the file has been read. Xref will then sort the cross-referenced listing and open two GEM windows, one above the other.

The top window displays the cross-reference listing and the bottom window shows the BASIC program with line numbers added. Both windows have vertical sliders and arrow buttons. The program window also has a horizontal slider with arrow buttons for lines longer than 80 characters.

The cross-referenced listing is broken down into three parts. The first shows all your variable names, the second the procedure names and the third the labels. After each name is a list of the line numbers of the program which reference that name.

The program shows the type of variable-either "%", "!" or "$" - and uses an open parenthesis "(" to indicate an array. A procedure or label's line number of origin is marked in the listing with an asterisk ("*").

The Menu Bar
All of the drop-down menu bar commands can be accessed with either the mouse or control-key combinations.

File
Select Open File. . . (Control O) to choose a new file to be cross-referenced. The previous file and its cross-reference listing will be lost if a new file is selected and cross-referencing has begun.

Select Save All of Xref. . . (Control V) and Save Block of Xref. . . (Control F) to save all or part of a cross-reference listing to disk. The listing is saved as a standard ASCII text file that can be loaded with a word processor It can also be either viewed or printed from the Desktop.

Search
You can scan the cross-reference listing for a particular name or section with the Search. . . (Control S) command. The dialog box that appears will accept a search string up to 30 characters long. A complete name is not required to find a match. For example. you can enter "long" to find "longname" or "t" to find the beginning of the "t" listings. (Note that the search is case sensitive; thus entering an uppercase T, for instance, would not find a lowercase t.)
 

What do you mean you can't use XREF because you don't have a copy of the GFA BASIC interpreter? You do if you have a START disk! Don't miss out! Call (800) 234-7001 to order START's XREF and GFA BASIC ver. 2.0.

The search begins at the second line in the cross-reference window and works forward. A dialog box informs you which section of the listing is currently being searched -variables. procedures or labels-and the number remaining to be checked.

If the search is successful an alert box will appear telling you where the string was found. The second window is then reset to display the line with the matching string at the top of the window. If the search fails you'll be told in an alert box.

To move the display to a specific line in the program window, use the Goto Line. . . (Control G) command. Answer the dialog box that appears with a line number and the program listing will be re-displayed with that line at the top of the window. Like the search command, if there aren't enough lines following to fill the window, then the line will be displayed at the bottom of the window

Print Your Cross Reference
You can send all or part of the cross-reference listing to the printer with the All of Xref (Control P) or Block of Xref (Control B) commands. All of Xref will print the entire listing and Block of Xref will print only a marked section. All or part of the program file can be sent to the printer with the All of File (Control A) and Block of File (Control K) commands.

All of the Print commands have the same output format. A six-line header is printed on the first page in which the first two and last two lines are left blank. The third line has the path and file name of the BASIC program and the fourth line has the date and time of printing. The cross-reference and program listings are printed exactly as they appear in their windows.

Block Commands
To mark a single line, click twice with the left mouse button on the desired line. To mark a block of lines, click on the first line of the block with the cursor anywhere on the line and that line will be highlighted. Now point the mouse at the last line of the block and click again. The first line, the last line, and all of the lines between will be highlighted. You can mark as many lines as you like but you can have only one block per window.

To unmark a block, select Unmark Block (Control U) from the drop-down menu. If you have lines marked in both windows, only the block in the active window will be unmarked. Using the Save or Print Block commands will also unmark a block for that window.

An Excellent Reference
Ambitious programming is a complicated process-it's easy to add variables early on and then forget exactly where or even if they're being used several versions later. Also, bugs can easily crop up when the same variable name is used in more than one section of the program. Xref isn't a tool you'll use every day but when you do use it you'll thank it for taking the drudgery out of debugging.

David Archibald lives in Flint, Michigan where he is on educational leave from General Motors. His CompuServe ID. is 73256,2640.