I am one of those people who cannot see a bit of code, in SuperBASIC at any rate, without wanting to improve it. This happened most recently when I looked at a few lines by Butch Weinberg called Pri_dir in the Sept/Oct issue of SincLink. It struck me that it might make the starting point for a series of articles on how I go about writing a SuperBASIC program. The program as it stands works, despite an error, and does a useful job, but has lots of scope for improvement; it makes an excellent nucleus for a really useful program. The original listing was:
10 OPEN#3,ser1
20 DIR#3,flp1_
30 PRINT#3
40 PRINT#0,'More?'
50 more$=INKEY$(-1)
60 IF more$='y' OR more$='Y'
THEN GO TO 20: ELSE
70 PRINT#3,CHR$(12);: CLOSE#3: STOP
There were three things that I wanted to alter right away, since while they worked they were hang overs from lesser BASICs, and didn’t take full advantage of the Super variety. To avoid confusion the BASIC statements I am discussing are given in bold type, to distinguish them from the discussion itself.
1. The condition more$==”Y” tests both cases at once, and is more efficient than more$=”Y” OR more$=”y”.
2. In this instance it isn’t really necessary to assign the value of INKEY$ to an intermediate variable, you can use it just as it comes, so the two lines 50 and 60 can be replaced by:
IF INKEY$(-1)==”Y”: ….
This waits until you press a key before evaluating the IF.
3. The use of GOTO. GOTO and GOSUB are quite unnecessary in SuperBASIC, and are generally considered “bad form” – even though they work! In this instance the GOTO is creating a loop, and this is better done using the REPeat … END REPeat structure. The way to break out of a loop is via an EXIT statement, and in order to use this we actually have to reverse the IF statement I derived above i.e. we want to stay in the loop if the answer is “Y”. There are several ways to deal with this: we could change the question to “Finished?”, we could change the line to IF INKEY$(-1)==”N” or do what I have done stick a NOT in front of the condition. This may seem the most complicated solution – but it is one that is generally available and it may come in useful when there is no alternative. Note that it gets around the absence of a not-equal test that covers both cases at once; k$<><>”Y” DOES NOT WORK! The error is the floating ELSE at the end of line 60; it serves no purpose at all.
Incorporating these ideas the program becomes:
10 OPEN#3,ser1
15 REPeat loop
20 DIR#3,flp1_
30 PRINT#3
40 PRINT#0,'More?'
50 IF NOT INKEY$(-1)=='y':EXIT loop
60 END REPeat loop
70 PRINT#3,CHR$(12);: CLOSE#3: STOP
Structured Programming – Clase’s Rules
But I am still unsatisfied; it is not properly structured. Most programs can be divided into three parts: set up – in which the initial conditions are determined (windows, devices etc), main – where the main action takes place, and finish – which tidies up at the end and restores your QL to its normal state. (As you may have noticed many commercial programs leave out the finish section!) Accordingly my own programs generally consist of a single line:
100 Set_up: Main: Finish: STOP
(the STOP is optional.) The rest is all PROCedures and FuNctions. In these I try to keep to the following self imposed rules:
1. Each PROCedure and FuNction should be no longer than one screenful (i.e. 20 lines). Anything longer than this almost certainly involves more than one procedure.
2. PROC/FN names have an initial capital and variable names are all lower case. This distinguishes them from each other and SuperBASIC commands and machine code extensions.
3. Global variables – those few required to be used generally throughout the program – should have meaningful names, but wherever possible variables should be LOCAL to their PROC/FN. LOCAL variables can be abbreviated to two or three letters, since rule 1. means that their role should be easy to discern. As well as variables defined as LOCAL, this includes formal variable names from the DEFinition line. Each PROC/FN should be as general and self-contained as possible making it easy to reuse in other programs.
4. I also like to have a clear demarcation between PROC/FNs, and put their names in a prominent place to make it easy to find them in the listing.
Although I have largely evolved these rules myself they are similar to the way ‘C’ programmers work and Mike Lloyd in QL World recommends something similar.
Rewriting our program according to Clase’s rules we have:
100 nm$ = "Prt_dir1"
110 REMark hjc 1990.11.03 Ver 0.1
120 Set_up: Main: Finish: STOP
130 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
140 DEFine PROCedure Set_up
150 OPEN#3,ser1
160 dev$="flp1_"
170 END DEFine
180 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
190 DEFine PROCedure Main
200 LOCal lp
210 REPeat lp
220 DIR#3,dev$
230 PRINT#0,"More?"
240 IF NOT INKEY$(-1)=="y":EXIT lp
250 PRINT#3
260 END REPeat lp
270 END DEFine
280 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
290 DEFine PROCedure Finish
300 PRINT#3,CHR$(12): CLOSE#3
310 END DEFine
Great! We now have 22 lines where we had 7 doing exactly the same job! But to me it is a working skeleton that we can flesh out into a much more versatile program. What we have to do is to look at each statement in turn, and where it can be improved replace it with a call to a PROC/FN that incorporates the improvement. The basic structure we have above will remain, although the statements will be altered and many more PROC/FNs added.
Actually I have already altered it slightly by introducing the global variable dev$. This is assigned the value ‘flp1_’ in Set_up, and it is the first statement I want to expand. There is also a programming variable nm$ which contains the name and current version of the program to make it easy to save the various versions as I go along. I use an ALTKEY definition available from toolkit II, but if you don’t have it you can add a PROCedure such as the following (adapted to your own favorite device):
DEF PROC Sv
Delete 'mdv1_'&nm$: SAVE 'mdv1_'&nm$
END DEF
Enter sv at the keyboard to save the current version. This can be removed from the final version of the program.
Returning to dev$, to change the device using the original you would have to EDIT the code. Wouldn’t it be nice if the program gave you a choice of device, or even better offered you a default, but gave you the option to change it? We should also include code so that only legitimate device names are accepted. This calls for a FuNction rather than a PROCedure, since we want it to come up with a device name or “return a string value” in computerese.
From now on I shall not reprint the entire program each time, but just the lines that have to be altered and the aditional PROC/FNs.
For obvious reasons I’ve decided to call the FuNction Get_Dev$ (it has to end in $ since it returns a string.) My original idea was to insert a call to Get_dev$ at line 160, but this fixes the device for the duration of the program, putting it into the Main loop means that you can get directories from different devices in the same run. I’ve therefore put it in line 210, as part of the DIR statement. This means that each time this line is reached you are asked the name of the device. This works because Get_Dev$ is a string FuNction and can be used anywhere that a statement expects a string. Get_Dev$ expects one parameter, the name of the default device, which is defined in line 160. So change line 210 to:
210 DIR#3,Get_Dev$(dev$)
and add these two FuNctions to the end of your listing:
320 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
330 DEFine FuNction Get_Dev$(df$)
340 LOCal dv$,k$,j$,lp
350 CLS: PRINT"Directory of ";df$;" ?"
360 PRINT "Enter, or type new name."
370 REPeat lp
380 k$=INKEY$(-1)
390 IF k$=CHR$(10)
400 dv$=df$
410 ELSE
420 PRINT k$;: INPUT j$: dv$=k$&j$
430 END IF
440 IF True_dev(dv$): EXIT lp
450 BEEP 3000,25: REMark bad name!
460 END REPeat lp
470 RETurn dv$: END DEFine
500 REMark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
510 DEFine FuNction True_dev(d$)
520 LOCal l%,n$,p$,ok%: ok%=0
530 p$="mdv/flp/fdk/ram/hdk"
535 n$="12345678"
540 l%=LEN(d$)
550 IF l%=4: d$=d$&"_": l%=5
560 IF l%=5
570 IF d$(1 TO 3)INSTR(p$)
580 IF d$(4)INSTR n$ AND d$(5)="_"
590 ok%=1
600 END IF: END IF: END IF
610 RETurn ok%: END DEFine
One parameter, dev$, is passed to the FuNction Get_dev$, QDOS requires brackets for a FuNction, but not for a PROCedure! This is received by the FuNction as df$ (the default); df$ is used as an alias for dev$ within the function. The advantage of this is that you could use the same FuNction for programs using more than one device e.g. a file copying program. NOTE any changes made to df$ within the FuNction will actually happen to dev$ – although nothing can happen to it here.
Get_Dev$ first prints the default (350) and then examines the next character typed (k$). If this is <ENTER> then dv$ is given the name of the default (390,400) otherwise k$ becomes the first letter of the name, and the rest is added to it and assigned to dv$ (420). Either way you can only get out of the loop (lp) if dv$ is a proper device name (440). If it fails the test then you get a raspberry and another go (450,460). Finally dv$ is the value RETurned by the FuNction (470).
True_dev is another FuNction which checks the device name and returns the value 1 (=true) or 0 (=false). The condition which follows an IF is always evaluated by QDOS as true or false in this way. (Try PRINT 2+2=4 and PRINT 2+2=5 directly from the keyboard.) This function first adds the trailing underscore if only four characters are present (550). Then, only if the name has five characters, it checks that the first three form an acceptable device name, that the device number is in the range 1-8, and that the underscore is present by a sequence of long **IF**s (570-610). You cannot do it all in one go, linking the conditions with **AND**s because of a bug in SuperBASIC: it should stop checking as soon as it finds a false condition, but it actually goes on to check them all. So, for example, if d$ had only two characters an error would be found when it tried to check the characters beyond 2. Putting them in a cascade avoids this problem, each condition is only evaluated if the previous ones are true.



That is more than I intended for one episode. Next time we will look at how to save paper. The program as written lists the names in a single column down the left side of the paper, it would be much more efficient if we could use three or four columns. It would also be nice to have the option of putting them into alphabetical order. You might like to think about how to do this – hint: it involves OPEN_NEWing a temporary file.
This month’s assignment is to see if you can modify line 210 so that the default is whatever device the program used last, rather than always reverting to the original one from line 160. It only requires a small change!
In the meantime I’d be happy to hear from anyone with comments, suggestions or requests for more information.
Howard Clase, Tel [phone number omitted]
Box 9947, Station B,
St John’s, Nfld
Canada, A1A 4L4
email: [e-mail address omitted]
(c)1990 H.J.Clase
Media
Note: Type-in program listings on this website use ZMAKEBAS notation for graphics characters.