Q L H A C K E R ' S J O U R N A L =========================================== Supporting All QL Programmers =========================================== #28 July 1998 The QL Hacker's Journal (QHJ) is published by Tim Swenson as a service to the QL Community. The QHJ is freely distributable. Past issues are available on disk, via e-mail, or via the Anon-FTP server, garbo.uwasa.fi. The QHJ is always on the look out for article submissions. QL Hacker's Journal c/o Tim Swenson 2455 Medallion Dr. Union City, CA 94587 swensontc@geocities.com http://www.geocities.com/SilconValley/Pines/5865/ ****** Note New Mailing Address ******** EDITORS' FORUMN I have not received much feedback on the Qliberator Source Book idea I mentioned in the last issue, and I have received basically no "helpfull hints". So, my plan is to write what I can, put it out on the Net, and see what feedback comes from it. If I make any mistakes, I'm sure there are many willing to point out my failings :-). Sometimes the best way to get an answer to a question is to give a wrong answer, then many will pop up to give the real answer. I'll probably put in questions that I have in the hope that they too will get answered. A part of the material going into the Source Book is coming from stuff I'm writing for this newsletter. I have taken the article on adding Config Blocks to Qlib program and expanded it quite a bit. A couple of articles from this issue will also go in. I also plan to have sections that touch on the various SuperBasic extentions and programming aids available to the SuperBasic programmers. In other news, besides having past issues of the QHJ available on my web page, I've added a number of articles that I've written for other newsletters. Check the link from the main page. STRUCTURED SUPERBASIC 2.6 Structured SuperBasic is a utility that has been printed a couple of times in this newsletter. I have recently dusted the program off and completed a new version. SSB 2.6 has all of the functionality of SSB 2.5, but I have added a lot of error checking, fixed a few bugs, added Config Block support, Command Line support, Environment Variable support, and compiled it with Qliberator. The manual has been expanded from 5 pages to 16 pages. The whole package has been zipped and should be available your local QL BBS and the Internet. It can be downloaded off my web page at http://www.geocities.com/SiliconValley/Pines/5865/. For those that don't remember what SSB is, it is a filter program that takes SuperBasic code, written in the form for SSB and converts it to full SuperBasic code. SSB allows for no line numbers, blank lines between code segments, conditional compilation, Include files, and other features. SSB allows for more readable and maintainable code. Download the package, unzip it, and give it a try. REVISION CONTROL SYSTEM (RCS) Whether it's source code or system configuration files, it's nice to be able to keep track of changes made to files over time. The Revision Control System is a collection of programs that keep track of different versions (revisions) of text files. A special file is created by RCS that contains information about the changes in a file and allow the user to get back to any revision of the file. RCS was designed primarily for programmers to keep track of what changes were made to various source files. It was derived from an earlier Source Code Control System (SCCS) and was first developed for the UNIX operating system. Since RCS came from a UNIX background, it understands the concepts of different users accessing the same files and allows "checking out" files and locking them from being changed by other users. RCS can be used by a number of programmers all working on the same code. It keeps track of who has what file "checked out" and who makes what changes. Although most QL programmers program by themselves, RCS can help the QL programmer bring a form of discipline to their programming. This is especially usefull for what can be called "full production" programs; commercial or freeware. Given the long life of QL programs (I'm still using programs written more than 10 years ago), RCS can keep track of what changes were made from revision to revision and why. A programmer can keep make a rule that each RCS revision be a bug fix and the reasons for the fix can be logged as part of the revision history. Enough blathering on, now to jump right into what RCS is and how it works. Original File - This is the text or source code file that you want to keep track of. It can be any text file. Revision File - This is a single file that contains the original text/source file and all of the revision history. It has the same name as the original file except that a ',v' is appended to the end. If the original file is 'test_c', then the revision file is called 'test_c,v'. A revision file keeps track of only one original test/source file. If you have 3 source code files that make up a single executable, then RCS will have three revision fills. Check-In - All revisions to a file are put into the revision file by checking them in. The program 'ci' is used to do this. 'ci' is used to either create a new revision file or to check-in a new revision into an existing revision file. Once a file has been checked into the revision file, it is deleted. Check-Out - When you want to edit a text/source file that has been checked in to the revision file, you use 'co' (check-out) to extract the text/source file from the revision file. The whole process of using RCS is basically checking-in and checking-out the same file. RCS is not aware of time, so there is no need to check-in a text file when you have finished a programming session. You really only need to check-in a file when you have made all of the edits you need. If you are fixing a bug in a program, you would only check-in the file when you have fixed it. No need to keep track of working copies of the files. To show you how RCS is used, I've written a short Structured SuperBasic program: OPEN #3,con_100x100a100x100 CLS #3 INPUT "Enter The Name of a File :";file$ OPEN_IN #4,file$ REPeat loop INPUT #4,in$ IF EOF(#4) THEN EXIT loop PRINT #3,in$ END REPeat loop CLOSE #4 CLOSE #3 I stored this program in the file 'readfile_ssb'. I then checked it in to RCS using the following command: exec ci;"readfile_ssb" 'ci' then asks me for my initials. Since the QL does not have the concept of multiple users (and therefore user names), a persons initials are used to keep track of who has checked out a file and who has made what changes to that file. 'ci' then asks for a Description. The Description is where the "why" of the file change is kept track of. If you are using RCS to keep track of bug fixs for a program, the Description section would be used to mention the bug, what caused it, and how it was fixed. I do not believe there is a limit on how long the description can be. The Description is ended by a line with just a period on it. 'readfile_ssb' is now checked-in to the RCS revision file and is deleted. Now to get the file back to edit it, I ran the following command: exec co;"-l readfile_ssb" I need to tell 'co' what file I want, but I also have to tell 'co' that I want to edit the file. If I ran 'co' without the "-l" option, 'readfile_ssb' would have been created, but it would not have been "checked-out" from the revision file, and when I went to check it in, RCS would not have allowed it. Under UNIX, 'co' would create a 'read-only' copy of the file. 'co' asked for my initials. Since the same person who checks out a file is the only person the can check in a file, be sure to remember what initials you used. 'readfile_ssb' is now extracted from the RCS file and the revision file is changed to show that the file is checked out. Once I am done editing the file, I can then check in the file using 'ci'. Again I am asked for my initials. The file is now checked back into the revision file and deleted. If you copied the file before checking it back in and you have edited this file, you can not incorporate those changes into the revsion file since the file is 'officially' checked in and can not be edited. RCS uses revsion numbers to keep track of the different times a file is checked-in. The first revision is 1.1, then 1.2, then 1.3 and so on. Let's say that I have edited my file 4 times, I'm now at revision 1.5 and want to recall revision 1.3. I would run the following command: exec co;"-r 1.3 readfile_ssb" 'co' would then dig though the revision history and generate version 1.3 of 'readfile_ssb'. RCS comes with more than just the 'ci' and 'co' programs. 'rcsdiff' is used to compare a working "checked-out" file with the version still in the revision file. 'rlog' is used to view the revision file. Below is the output of 'rlog' from my example session: RCS file: readfile_ssb,v Working file: readfile_ssb head: 1.2 branch: locks: strict access list: symbolic names: comment leader: "# " keyword substitution: kv total revisions: 2;selected revisions: 2 description: Creation of RCS Archive ---------------------------- revision 1.2 date: 1998/06/11 20:41:01; author: tcs; state: Exp; lines: +2 -2 This is a second version of this program. ---------------------------- revision 1.1 date: 1998/06/11 20:19:34; author: tcs; state: Exp; Initial revision ============================================================ RCS is a lot more complicated that I've mentioned here. It, and SCCS, is fully documented in the book "Applying RCS and SCCS" by Bolinger & Bronson, published by O'Reilly & Associates. RCS for the QL is available from most freeware sources. The QL RCS distribution does not come with the 'diff' program which it requires. 'diff' is available as part of the C68 distribution. RCS can not be used with regular SuperBasic programming, as RCS would see any new line numbers as a change in the file. If you loaded a file into SuperBasic, did only a line renumber, saved it, and then check it back into RCS, RCS would any line with new line number as having changed. RCS works well with Structured SuperBasic as it has no line numbers. It also works well with C, Forth, Pascal, etc. ENVIRONMENT VARIABLES The concept of Environment Variables comes from the Unix world. They are used slightly in MS-DOS, but not at all to the same extent as UNIX. For the QDOS world, the file ENV_BIN provides a number of extensions that allow the use of Environment Variables. Essentially an environment variable is a variable that can be "seen" by exectuable programs. In SuperBasic we can set up all kinds of variables, but if we execute a program from SuperBasic, these programs can not "see" these variables and get data from them. The purpose of environment variables is to change the configuration of a program. They function like Config Blocks, but don't require running a program to make the change. Let's take a quick look at how we can change the behavior of programs. There are five different ways of doing this: 1] User Intervention. This is where the user uses a menu or answers queries from the program. 2] Config Blocks. This feature is pretty unique to QDOS, but it allows the user to change default options without having to know how to edit a binary file. 3] Configuration File. This is a separate file that the program reads to determine how to set defaults and run. 4] Command line Arguments. Instead of the program querying the user for information, the user types it in when they execute the program. 5] Environment Variables. The user sets a variable that is then read by the program and changes its default settings. Each of the options have their own place and their own benefits and faults. Some are more permanent, like Config Blocks and Config files, while some are very short lived, like User Intervention and Command line Arguments. Enviroment Variables are in between as they can be set in a BOOT program, but they can be changed by just typing in a new command. The ENV_BIN file comes with 4 extensions. They are: SETENV - Defines an environment variable. ENV_LIST - Lists all defined environment variables. ENV_DEL - Deletes an environment variable. GETENV$ - Gets the value of an environment variable. The two key commands are SETENV and GETENV$. SETENV is used like this: SETENV "VARIABLE=value" SETENV takes a string argument of the type "XXXXX=YYYYY" where XXXXX and YYYYY are two strings separated by an equal sign. Any space before the equal sign is treated as a part of XXXXX and any space after the equal sign is treated as a part of YYYYY. The case of each string is important as "VARIABLE" is different from "variable". By convention, upper case is used for variables. The SETENV is done either in a BOOT or setup program or by the user. The command for an executable to get the contents of an environment variable is GETENV$. The command is used like this: a$ = GETENV$("VARIABLE") In this case a$ will be assigned the value of "value". This comes from our previous SETENV command above. If the Environment Variable "VARIABLE" is not set (does not exist) then the GETENV$ would return a Null string ( "" ). Now I did say that executables use GETENV$ and not SuperBasic programs. Since variables are already used in SuperBasic, we would not gain much in using environment variables. There the commands are use is in compiled SuperBasic programs, which are executables. I see the purpose of using Environment Variables as adding to the flexibility of programs that use Config Blocks. Both Config Blocks and Environment Variables are really designed to change default program settings. User Intervention and Command Line Arguments are designed to tell the program what the data is. Using environment variables allows the user the ability of making a temporary change to the default options of a program, without having to go through the trouble of using "config". Environment variables would be used to change a setting for a single session and that's it. Getting Config Blocks and Environment Variables to work together is not difficult. The program would first get it's default settings from the Config Block. It would then check to see if there are any Environment Variables set. If there are, then the Environment Variable settings would override the Config Block settings. WORKING DIRECTORY As we all know, QDOS did not come with the concept of directories and subdirectories. A number of extensions to QDOS are available to help create the working concepts of directories. When using ED drives, I found the Path (PTH) extensions usefull because they would search a list of subdirectories looking for a particular exectuable. Now, I've never used a QL with a hard disk, so I'm not too experienced with using the tools for handling directories, plus my copies of some of the good articles dealing with this subject are not available to me. So, I've been doing some thinking on the matter, especially since I have been writing a freeware program and I want to make it as versatile as possible. The one issue that I've been pondering over is telling a program where there data file are at. This is called a Working Directory. It is a directory where the data files are at and any newly created files will also go. I know that DATA_USE is designed for this purpose, but I do not want to type in a new DATA_USE before each program I execute. I could set up a short little SuperBasic program to set up everything, but I want to EXEC a program not LRUN it. Of course, using a front end like QASCADE, this point is mute, since the user is removed from the details of executing the program. With PTH_ setup, I don't need to set PROG_USE, because PTH_ finds the executable. I was looking a way of having the executable know where the Working Directory is. What I came up with is this: Have an item in the Config Block for Working Directory. The contents would be something like this, "WIN1_PROG_DATA_". This string would be appended to the front of each file name used in the program. This does mean that the user would not be able to type in a new device name, such as "FLP1_FILE_EXT". Initally, the Config Block entry for Working Directory would be the null string (empty), so that a user would enter "FLP1_FILE_EXT". Once the user has created a working environment, the Config Block can be changed to what the user wants. If this feature is linked to Environment Variables, it would become more powerfull. By setting an Environment Variable for the program, the user could temporarily override the Config Block and change the Working Directory. If the Config Block was changed to a Working Directory and the user needed to use the floppy for a few times, the user would set the Environment Variable to "flp1_" or to the null string ("") and then set DATA_USE to flp1_. If they did not want to change the default Config Block, a BOOT program could set the Environment Variable and it would be active during the whole computing session. If different programs used different Environment Variable names for their Working Directory, then all Working Directories could be set up in the BOOT program. Something that could not be accomplished with just DATA_USE. Since my experience in this area is kind of light, the more experienced QLers may want to take this all with a grain of salt. I prefer to think of it as a way that I would prefer to organize things and others may have a different way. The reason I am bringing up this idea is for programmers to consider the concept and add it to their programs. The option is not very difficult to implement, but it would a nice feature to the program. The whole feature would take up no more than 10-20 extra lines of code to a program. By setting the default value of Working Directory to nothing, the feature is essentially turned off and it does not impede the user that does not want use a Working Directory. CASE STATEMENT IMPLEMTATION When I recently was working on SSB 2.6, I was using a SuperBasic implemtation of a CASE structure for the core of the program. The deeper the structure got, the harder it was to read and understand. I starting thinking of using another way of implementing a CASE structure. For those that don't know what a CASE structure or statement is, it is essentually the same structure as a SuperBasic SELECT ON statement, but it is not limited to numbers. Plus the general idea of a CASE structure is to have a number of possible logic statements with an action for all cases that do not fit one of the logic statements. In a generalized CASE structure not all of the comparisons must be based on the same data (string, number, etc), but can vary. Traditionaly, a way of creating the CASE structure is to have a number of nested IF..THEN..ELSE statements, with the final ELSE handling the default value. An example would be something like this: you are reading in text from a file. You want to handle the following cases: a line starts with a ##, or a line starts with a **, a line starts with a period (.). If none of these cases, then the line is passed to the output file. Using nested IF..THEN..ELSE statements the pseudo code would look something like this: IF line starts with ## THEN ...... ELSE IF line starts with ** THEN ...... ELSE IF line starts with a period THEN ....... ELSE pass to output file END IF END IF END IF If you start having more than just a hand full of possible cases, the structure can get long and difficult to read. SuperBasic allows the use of NEXT in conjunction with a REPEAT statement. This means that when the NEXT is reached, the rest of the REPEAT loop is skipped and the processing goes onto the next interation of the REPEAT loop. Using NEXT in this manner allows for the creation of a different implementation of a CASE structure. Below is an example of the two implementatios listed side-by-side. REPeat loop REPeat loop IF .... THEN IF .... THEN .... .... ELSE NEXT loop IF .... THEN END IF .... IF .... THEN ELSE .... IF .... THEN NEXT loop .... END IF ELSE IF .... THEN default .... END IF NEXT loop END IF END IF END IF default END REPeat loop END REPeat loop Using the REPEAT..NEXT..END version may not seem as clean as the "classical" IF..THEN..ELSE structure, but I think it is cleaner when it come to reading and debugging. What I am looking for from readers is to ponder over any downsides from using the REPEAT..NEXT structure. I can't think of any logical problems with using this structure over the classical one. If you know of any, please send me a note. I'll add the productive comments in the next issue. CREATING LOADABLE EXTENSIONS USING QLIB One of the things that has always amazed me about the QL was the ability to load a binary file and have a bunch of new keyboards available in SuperBasic. In most computers that had Basic built in, the language was static and had no way to extend itself. Other languages (like C, Fortran, or Pascal) used libraries of functions and procedures to extend the capability of the library. The first major loadable extention to the QL was ToolKit. From then on the term toolkit has been used in reference to loadable extensions. Popular toolkits are ToolKitII (TKII), DIY ToolKit, and DJToolKit. I knew that the first of these toolkits were written in Assembly, but I did not know that they could be created by Qliberator. It seems that QDOS executables and extensions are real close in format and when compiled right, they can be interchangable. This means that an executable can also be loaded as an extension. To figure out how to create a toolkit, I grabbed a simple function, Qliberator, and gave it a try. The function is included below: 10 REMark $$external 100 DEFine FuNction upper$(up$) 110 LOCal x, temp 120 FOR x = 1 TO LEN(up$) 130 temp = CODE(up$(x)) 140 IF temp > 96 AND temp < 123 THEN up$(x)=CHR$(temp-32) 150 NEXT x 160 RETurn up$ 170 END DEFine The function takes any string and converts it to all upper case letters. The $$external is a compiler directive to Qliberator that tells it that the next function or procedure needs to be available outside of the executable. For each procedure or function that you want to turn into an extension, you would have to put the $$external directive in front of it. If I was to put an additional line in the program, 180 PRINT upper$("This is a test") then when I executed the program, line 180 would be executed. If I LRESPRed the program, the keyword upper$ would be made available. When compiling the program it is a good idea to turn WINDS off, since the extension will have no channels open. Otherwise 3 channels will be opened for it, wasting them. To lower the size of the binary file, turning off NAMES and LINES might be a good idea. Note that the case of the function or procedure will be maintained in the extension. In my example, the name that will show up when entering EXTRAS is "upper$" (all lower case). If I defined the function a UPPER$, then "UPPER$" would show up in the EXTRAS command. By convention, extensions should be done in all upper case. If you will be running the extension on a system that already has the Qlib runtimes loaded, then compile the program without runtimes. If you don't know if the Qlib runtimes will be available, compile it with the runtimes included. It is a good idea to compile both ways and let the user decide which one they need. The example program when compiled without the Qlib runtimes was 594 bytes. With the Qlib runtimes it was 11,146 bytes. The runtimes take up a fair bit of space. If you load an extension that does not have the Qlib runtimes on a system where the Qlib runtimes are not loaded, you will not get an error message when you LRESPR the extension. When you call the extention is when the error will occur. The exact error message is: Error "Runtimes Missing !" Once you have compiled an extension, all that is needed is to LREPSR it and test it out. Remember that you can't LRESPR while any jobs, other than Job 0 (SuperBasic), is running.