In the first episode of this exciting serial I showed you how to structure a simple program so that it could easily be expanded and improved without loosing track of where you are. All we have to do is to consider a statement, think how it might be improved, write the improvement as a FuNction or PROCedure and call it by name from the original statement. The program was one to print the directory of a storage device (disk or mdv cartridge) onto paper that had appeared in an earlier issue of Sinc-Link. The first modification we made was to give the user the option of either accepting program’s suggestion for the source of the directory or putting in one of your own without having to stop the program and EDIT a line.
I left you with the problem of altering the program so that the default offered doesn’t always revert to the one built into the program in the PROCedure “Set_up”, but uses whatever device you used last time. There are two ways to do this, one is to modify line 220 (not 210 – my mistake) as follows:
220 dev$=Get_dev$(dev$):DIR#3,dev$
The first statement can change the value of the global variable dev$, which couldn’t happen in the earlier version. The other way would be to change the dv$ variable to df$ throughout the FuNction Get_Dev$, this means that df$, an alias (formal variable) for dev$ within the function, could be altered and dev$ along with it. But I don’t favour this way of doing it, it’s a bit too mysterious!
Another point struck me while re-reading what I wrote last time: some beginners might be puzzled about the use of CHR$(10) and CHR(12) in the program. These are ASCII control codes which cannot usually be typed in from the keyboard; CHR$(10) is an exception, it’s the <ENTER> key, also known as line feed (LF), since that’s what it does both on the screen and on the printer. (You can also generate it with <CTRL J> – try it!). CHR$(12) is form feed (FF) and does nothing on the QL screen, but has a noticeable effect on the printer – it moves to a new sheet of paper at the end of the run. (On some micros it cle[ars] the screen – but not this one!) One other code worth mentioning here is CHR$(13), carriage return (CR), which on the QL screen is implied in the LF, and probably on your printer if you have set the DIP switches to their most useful settings.
If you have tried our program as it stands you will probably have noticed that it only prints one name on each line, and since file names are generally rather short this is a shocking waste of trees. Wouldn’t it be nice to print it in several columns across the page, like, for example, Quill does on the screen when you ask for a list of your _docs? That is what we are going to look at in this episode. The first thing we have to do is to identify the line that we need to alter, i.e. the one that actually instructs the computer to send the directory from the mdv tape or floppy to the printer. We have to look no further than line 220; it is the DIR#3 command that does it. We have [to] intercept the stream of file names tha[t] this command spews straight down the serial port. This is where the QL’s flexible handling of channels come in handy.
Aside on channels.
A computer would be useless unless you could put information into it and get something back out – it needs to be able to communicate. Information can be put into the computer from the keyboard, from a file on tape or disk, via the net etc. Output can be obtained on the screen, on a printer or it can be put into a file. Some computers have different commands for dealing with different kinds of devices (e.g. PRINT to the screen, but LPRINT to a printer), but to the QL they are all just numbered channels. The commands you use are the same irrespective of the device at the other end of the channel. (Although some are inappropriate – like CLS to a printer channel.) When you open a channel you have to tell QDOS what kin[d] of input/output device it is, and it sets up the appropriate “driver” to look after the details for you.
Back to our columns.
The DIR command directs the list of file names to a numbered channel, so we can intercept it if we make the channel a file rather the printer. Then we can read it back from the file into an array, and get full control of the list of file names as we print them out. Printing them out at regular intervals across the page is easy, but proper printing in columns involves going down each columns in turn from left to right; and that is what we shall do – phone book order is what I am aiming at.
The listing contains all the lines you will have to alter or add to Prt_dir2 to upgrade it to Prt_dir3. It is not a complete program in itself; it will not run by itself. Type in the listing, and save it under some temporary name (e.g. mdv1_Prt_dir_UG). Then load Prt_dir2 and MERGE in the upgrade. You must do it in this order since lines with the same line number are overwritten during a MERGEr, and we want the later versions to stand. This assumes you have the same line numbers as the listing published in part one; if you have RENUMbered, then you will have to be very careful and make the alterations by hand.
Upgrade Listing
When merged with Prt_dir2 these lines convert it to version 3, do not try to RUN them on their own!
100 nm$ = "Prt_dir3"
110 REMark hjc 1991.03.13 Ver 0.33
162 temp$='ram1_temp_dir'
164 chars%=80: REMark output line
166 cols%=4
220 Col_dir 3,Get_Dev$(dev$)
630 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^
640 DEFine PROCedure Col_dir(ch%,dv$)
650 LOCal a$,nl%,i,n%,st$(2,30),rows%
660 n%=0: nl%=chars% DIV cols%-1
670 Make_array dv$
680 PRINT#ch%,st$
690 PRINT#ch%: FOR i=1 TO rows%
700 FOR j=0TO cols%-1
710 a$=ddir$(i+j*rows%)
720 PRINT#ch%,!Procrust$(a$,nl%);
730 END FOR j: PRINT#ch%: END FOR i
740 END DEFine
750 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^
760 DEFine PROCedure Make_array(dv$)
770 LOCal a$,c%,i: c%=ch%+1
780 REMark Put directory into file
790 DELETE temp$: OPEN_NEW#c%,temp$
800 DIR#c%,dv$: CLOSE#c%
810 n%=Line_count(c%,temp$)-2
820 rows%=n%/cols%+.499
830 n%=cols%*rows%
840 DIM ddir$(n%,nl%)
850 OPEN_IN#c%,temp$
860 FOR i =1,2:INPUT#c%,st$(i)
870 FOR i=1 TO n%
880 IF EOF(#c%): EXIT i
890 INPUT#c%,ddir$(i)
900 END FOR i
910 CLOSE#c%: DELETE temp$
920 END DEFine
930 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^
940 DEFine FuNction Line_count(ch%,f$)
950 LOCal a$,ct,n%:n%=0
960 REMark Count no. of lines in file
970 OPEN_IN#ch%,f$
980 REPeat ct
990 IF EOF(#ch%): EXIT ct
1000 INPUT#ch%,a$: n%=n%+1
1010 END REPeat ct
1020 CLOSE#ch%
1030 RETurn n%: END DEFine
1040 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^
1050 DEFine FuNction Procrust$(r$,p%)
1060 LOCal l%: l%=LEN(r$)
1070 IF l%>p%
1080 r$=r$(1TO p%)
1090 ELSE r$=r$&FILL$(" ",p%-l%)
1100 END IF
1110 RETurn r$: END DEFine
First we need to bring the version info up to date (100 & 110). Before we get to the main additions it is necessary to define a few more global variables, and the best place to put these is into the PROCedure Set_up (lines 162, 164 & 166).
Temp$ is the temporary file we shall have to set up to hold the directory. If you have ramdisk use it here, if not replace ram1_ with any device (flp or mdv) that will have a bit of space on it. Using a variable in this way means that you only have to alter the name once to change it thoughout the program.
Chars% is the number of characters in the line of the output device; this is normally 80, but to save paper while I am testing the program I use a screen for channel #3 which is only 37 characters wide. (This is an example of the usefulness of the QL’s channels; all I have to do is to alter the definition of channel #3 in line 160 to switch from screen to printer.) Cols% is the number of columns required, you can set it to whatever suits you. Later we might add a procedure to enable the user to chose the number required while the program is running.
I’ve designed my new PROCedure to look as much like the QDOS PROCedure it replaces as possible, so it requires the same two parameters, a channel number and a device name (or, in this case, a function that returns one). (You cannot use the # notation for your own superbasic PROCedures; it has to be replaced with a space.) The main change to the original listing occurs in line 220. (You can use either version – see above) This change leads into the sequence of two new PROCedures and two new FuNctions that follows.
Col_dir is the PROCedure that deals with printing in columns, but there are a few preliminaries to go through first. Make_array puts the directory into an array, ddir$. Lines 790 & 800 OPEN a new file as channel #c%, and puts the directory of your chosen device into it. Not surprisingly QDOS objects if you try to OPEN_NEW a file with a name that alredy exists, and the program would stop with a QDOS error message if it were not for the protective DELETE statement – luckily QDOS does not object to deleting a file that doesn’t exist! DIR produces a series of ASCII text ‘lines’ each followed by a LF characte[r] (CHR$(10)), so that is what the temporary file consists of. The first two lines of the directory of a formated device are always the device name and the sector statistics. (Well not quite always, I have a version (2.02) of Toolkit 2 with a bug in it so that it fails to produce these two lines from an empty mdv tape, and the program as written stops here if there are no files on the tape. It will, of course always stop if the tape is not formatted.) The rest of the file is a list of the names of the files on the tape or disk. Since there may be anything from 0 to about 450 we have to count them. This is done at line 810, n% is the actual number of files – two less than the number of lines found by function Line_count, which I’ll explain later.
Then follows a bit of fudging. Since I want to print in proper columns the array has to be exactly the product of the numbers of rows and columns. Suppose there were 98 files and we ask[ed] for four columns, we can only print rows, so the first line would have to consist of files number 1,26,51 and 76 and so on, but when we get to the last row but one we should run out in the last column if we had only dimensioned our array to 98, generating an “out of range” error. Line 820 calculates the number of rows – the .499 makes sure it rounds up not down – 830 adjusts the value of n%, and 840 dimensions the array ddir$() to n% strings of maximum length nl%. This length was calculated at line 660 – the -1 ensuring at least one space between the columns.
Dimensioning Arrays
Because of the way it was dimensioned ddir$ is a global array. I should have preferred to make it LOCal to Col_dir, but this couldn’t be done since we don’t know how big it has to be when we enter the procedure. Variable arrays have to be dimensioned to help QDOS organise t[he] memory. Since it is a string array yo[u] have to tell it how many elements (file names) and the maximum number of characters you want in each – if you try to assign a longer name then only the first nl% will go into the array. A LOCal array is declared by putting the dimensions in brackets after the variable name in the LOCal statement, which must be the first line in the array or function. The variable st$ declared in line 650 is an example of a LOCal array, this is to hold the device name and the sector statistics. Since we know in advance what size this has to be there is no problem, but we cannot dimension ddir$ until we know how many file names there are, and it has to be done with a DIM statement. SuperBASIC is more flexible than most BASICs in that you can re-dimension an array to be larger than it was before, so there is no problem with the fact that it will be re-dimensioned each time you print a directory.
Having dimensioned our array we have to fill it with the file names. Line 850 re-OPENs our file for INPUT to the computer as channel #c% again. (The OPEN command also allows you to alter or add to the file, but we don’t need to do that.) The short form FOR loop at line 860 puts the drive name and stats into st$. I could have just used the first two elements of ddir$, but I didn’t want them to be truncated. Note that the INPUT command – with the appropriate channel number – is used, the same command you use to get input from the keyboard. Then we move to a long FOR loop which reads the file names from the temporary file and puts them into the array. Because we may have increased the value of n% to be greater than the actual number of names we have to allow for getting to the end of the file before we get to the end of the loop; this is done at line 880. The last few arrayelements may remain empty. Then we’ve finished with the file and can dispose of it (910).
We now return to line 680, which demonstrates a useful trick. If you want to print a whole array you do not have to write your own loops, PRINT array_name will print out the whole thing. If you follow the array_name with one of the formatting “punctuation marks” (, ; !) it is printed as though each printed element is followed by the mark; a comma will tab each element – try the effect of the others for yourself. Since there is nothing in line 680 the two entries are printed as separate lines. Then we move to the main double loop (690 – 720). The outer (i) loop controls the rows and the inner (j) loop picks out the entry for each column as we go across the row. The ! puts a space before each column except the first, and the procrustean FuNction ensures that each is exactly the right length. (The formatting mark ! is not used often enough by amateur programmers, as well as the above role it will not print at the end of a line if there is not enough room for the whole string, but starts a new line – no split words.) The PRINT statement between the two END FORs makes sure that there is a new line after each row, it is redundant if you have got the characters per line right in Set_up, but helps keep things tidy if you haven’t.
There are still two FuNctions left unexplained. Line_count just returns the number of lines in an ASCII text file, you can use it, for example on a basic file – try:
PRINT Line_count(4,"mdv2_Prt_dir3")
(you must have prt_dir3 loaded at the time – or Line_count at least, and don’t forget the quotes!. It won’t work on a Quill file they are not ASCII.) Note in particular line 990. Whenever you use a loop to run through a file, since you do not usually know the length in advance you have to use a REPeat loop rather than a FOR loop, and you must test for end-of-file right at the beginning – it might be an empty file. Nothing happens to a$ here, it’s just somewhere to put each line while you count it. You could easily adapt this FuNction to find the length of the longest file name in the list as well as count them couldn’t you? (This month’s assignment, you might also try to adapt it to find the length of a file in bytes – hint use INKEY$). The other FuNction, Procrust$, either truncates (1070/80) or pads out with spaces (1090) the string r$ to make its length exactly p%.
If there is anything I have not explained in enough detail please write to me. Next time Afferbeck Lauder.
(This series will be continued in the next issue)
(c) 1991 H.J.Clase
Howard Clase
Box 9947, Station B,
St John’s, Nfld, A1A 4L4
Media
Note: Type-in program listings on this website use ZMAKEBAS notation for graphics characters.