Tutorial Subroutines

by Ian Finlayson


Issue 28

Jul/Aug 87

Next Article >>

<< Prev Article



Start of a new series in which Ian Finlayson presents short subroutines which are highly documented to allow you to understand exactly what is going on.


There are many programs around which will list the contents of your disk to the screen or to a printer, but all of them have a common disadvantage if you have a very large number of files per disk you have to scan several pages of disk contents and watch the list scroll away or print it out as hard copy. This situation can easily arise if you write many short letters using a word processor making it difficult to keep track of all your correspondence. I find AtariWriter very frustrating in this respect as the list of files scrolls rapidly and the 'Control 1' interrupt does not freeze it. Printing out the contents results in a long narrow list of the filenames which is not ideal for retaining with the disk.

Here then is a short program which will list 64 file names to a single screen that is as many as are possible under DOS 2 although some other forms of DOS can accommodate more. The program is intended to provide a tutorial and to provide a useful subroutine at the same time. It can be readily modified for other purposes and will give a neat printout if you change all the ? commands to LP.


AtariLister - requires Java


Here then is a full breakdown of the program which I hope will help you understand and use the techniques in your own programs.

Line 30999 This REM statement is merely an identifier. I find such reminders most important when keeping small bits of program or subroutine for later use, otherwise things get lost. By putting it on line 30999 I can delete it, to save memory if required, when incorporating it into a larger program and still GO SUB to a round line number.

Line 31000 Dimensions the string TT1A$. For use in subroutines it is as well to avoid the more common names for strings or variables as they can clash with the main program. The disk directory files we are going to recover are of the form "* FILENAMEEXT XXX" 17 characters each. The * shows locked or unlocked, then there is a space followed by the filename and extender (without a stop between them), a second space and then the number of sectors the file occupies.

Next we open IOCB #3 to the disk directory (as signified by the 6 in the open command. Using the two * wild cards in the "D:*.*" name will access all the filenames on the disk. This can be changed to suit your needs, for instance if you only wish to list picture files from a disk you could use "D:*.PIC" and any file without the PIC extender will be ignored (such as DOS.SYS for example).

The first print statement clears the screen and puts a heading in the top line. The technique is not difficult to use and is very much the same as cursor movements around the screen except that to stop them taking effect immediately each Control key sequence is prefixed by Escape. In this instance the first three characters in the quotation marks are obtained as follows:

Esc Ctrl-Clear (Clear screen)
Esc Ctrl-Tab (Tab right)
Esc Ctrl-Rt.arrow (Cursor right one space)

Next we initialise the variable TT1 to 1 This is the line we wish to print directory information on. (The title is on line zero). It would be nice to leave a blank line between the title and file listing but with a possible 64 files to list and only enough width for 3 on a line we could need 21 lines, so there are none to spare in a 24 line Graphics 0 screen.

Last a non-zero poke to 752 turns the cursor off.

Line 31010 TT2 is the column in which the file name will go (0 to 2). INPUT gets a string from the open IOCB #3. Next we check to see if we have reached the end of the disk contents. The last string recovered from the directory is of the form "XXX FREE SECTORS", and we look for a match with " FREE".

Line 31020 Positions the (invisible) cursor. Each column is 13 characters wide including a trailing space in the form "FILENAME.EXT ".I have split the FILENAMEEXT with a period for clarity. Once the filename is displayed we go back to the next of the 3 columns and when all three are done move down a row before printing the next 3 file names.

Line 31030 This is the bottom line of the display, printed after finding the free sector count in line 31010. The ; at the end of the print statement is important as it stops the cursor from moving to the next line which would cause the screen to scroll up if you have a full 64 files present.

Next we set up to receive an input from the keyboard. The GET waits for a keypress, the variable is a dummy for which I have reused TT2 for economy as we don't need it any more.

Line 31040 After the keypress close the IOCB, turn the cursor back on and clear the screen, this is good housekeeping. When this is used as a subroutine the Return Statement goes here also.