Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / SNOBOL / SNOBOL_A.ZIP / UTILSDOC.PRT < prev

Wrap

Text File | 1988-05-24 | 501.5 KB | 8,094 lines

GORDON PETERSON'S SNOBOL4+ UTILITIES Users' Guide Version 1.012 May 24, 1988 Noah Systems P. 0. Box 40476 San Antonio, TX 78229-1476 U. S. A. page i Table of Contents 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Printing this User's Guide . . . . . . . . . . . . . . . 1 1.2 Overall Format . . . . . . . . . . . . . . . . . . . . . 2 1.3 About Public Domain and Shareware Distribution . . . . . 2 1.4 What is SNORUN.EXE? . . . . . . . . . . . . . . . . . . . 3 1.4.1 SNORUN version 2.0 for Public Domain Distribution . 4 1.4.2 SNORUN versions for Registered Users . . . . . . . . 4 2. ABOUT SHAREWARE, FREEWARE, AND PUBLIC DOMAIN SOFTWARE . . . . 6 2.1 Public Domain Software . . . . . . . . . . . . . . . . . 6 2.2 Freeware . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3 Shareware . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4 Distribution Channels . . . . . . . . . . . . . . . . . . 8 2.5 But the Terms Do Vary . . . . . . . . . . . . . . . . . . 9 2.6 License to Distribute . . . . . . . . . . . . . . . . . . 9 3. ANGLICIZ -- "ANGLICIZE" FOREIGN CHARACTER SET . . . . . . . 12 4. ASMGEN2 -- DISASSEMBLY SUPERVISOR . . . . . . . . . . . . . 14 5. ASMRECOV -- RECOVER ASSEMBLER SOURCE FROM LISTING FILE . . 15 6. ASMSTAT -- GENERATE ASSEMBLER PROGRAM STATISTICS . . . . . 18 7. CASE -- CASE CONVERSION AND FOLDING . . . . . . . . . . . . 19 8. CHARDF -- CHARACTERIZE A DELIMITED FILE . . . . . . . . . . 22 9. CHOPUP -- CHOP UP A FILE FOR TRANSMISSION . . . . . . . . . 26 10. CISSTRIP -- STRIP JUNK FROM COMPUSERVE CAPTURE FILES . . . 28 11. COMBINE -- COMBINE FILES AND ELIMINATE DUPLICATES . . . . 34 page ii 12. COPYSEG -- COPY A FILE TO MULTIPLE SEGMENTS . . . . . . . 37 13. CPRANGE -- COPY RANGES OF RECORDS . . . . . . . . . . . . 40 14. DELALL -- DELETE ALL MATCHING FILES . . . . . . . . . . . 45 15. DELIEOF -- FIND AND DELETE INTERNAL EOF MARKS . . . . . . 47 16. DIFFER -- FIND DIFFERENCES IN TWO TEXT FILES . . . . . . . 50 17. DIRCMP2 -- COMPARE FILES IN DIFFERENT SUBDIRECTORIES . . . 52 18. DIRTREE -- MAKE FILE OF SUBDIRECTORIES PRESENT . . . . . . 54 19. EXPTAB -- TAB CHARACTER EXPANSION . . . . . . . . . . . . 57 20. EXTEND -- EXTEND A FILE (RECOVER LOST DATA) . . . . . . . 59 21. FILEDUMP -- HEXADECIMAL FILE DUMP . . . . . . . . . . . . 63 22. FMTHDLL -- FORMAT HARD DISK, LOW LEVEL . . . . . . . . . . 65 23. GENTBLS -- GENERATE PROGRAM SOURCE CODE TABLES . . . . . . 69 24. LASERPG -- MULTIPAGE OUTPUT TO LANDSCAPE MODE PRINTER . . 74 25. LINEAN1 -- SERIAL COMMUNICATIONS ANALYSIS AID . . . . . . 76 26. LIST -- (YES, ANOTHER) TEXT FILE LISTER . . . . . . . . . 78 27. MAKASEQ -- DISASSEMBLY AID (USED WITH ASMGEN2) . . . . . . 80 28. MAKDUMMY -- MAKE DUMMY FILES FOR ARC'D FILES . . . . . . . 82 29. MAKEALL -- CONVERT A MAKE FILE TO "ALL" BATCH FILE . . . . 84 30. MAKEMAKE -- BUILD A MAKE FILE BASED ON INCLUSIONS . . . . 90 page iii 31. MAKERMAK -- BUILD A RAW MAKE FILE . . . . . . . . . . . . 95 32. MELIZA -- PSYCHOANALYSIS PROGRAM (FAMOUS EARLY AI EFFORT) 98 33. MERGECMP -- MERGE WORD'S .CMP USER DICTIONARY FILES . . . 99 34. MSCRIBE -- DOCUMENT FORMATTING AND ENTRY PROGRAM . . . . . 101 35. OVER -- SHIFT A PRINT FILE OVER TO THE RIGHT . . . . . . . 104 36. PADREC -- PAD RECORDS TO A FIXED SIZE . . . . . . . . . . 105 37. PLAYCVMS -- SUPERKEY TO DRVSPKR FORMAT CONVERTER . . . . . 107 38. PLAYCVT -- PLAY FILE TO DRVSPKR FORMAT CONVERTER . . . . . 110 39. PMUSCVT -- PIANOMAN .MUS TO DRVSPKR FORMAT CONVERTER . . . 114 40. PUBLBL -- PUBLIC LABEL INCLUSION GENERATOR . . . . . . . . 116 41. REPAGIN8 -- INTELLIGENT DOCUMENT PAGINATION AND TOC . . . 120 42. SAPPREF -- APPEND ASSEMBLER CROSS-REFERENCE TO LISTING . . 126 43. SPACE -- DISK SPACE MANAGEMENT AND RECOVERY UTILITY . . . 129 44. STRIPBS -- STRIP BACKSPACE CHARACTERS FROM TEXT FILE . . . 135 45. TITLGEN -- GENERATE A TITLE PAGE . . . . . . . . . . . . . 137 46. TOTSIZ -- TOTAL SIZE OF SUBDIRECTORIES . . . . . . . . . . 142 47. TP -- WIPE CLEAN THE TAIL END OF A FILE . . . . . . . . . 144 48. TRUNCATE -- REDUCE THE SIZE OF A FILE . . . . . . . . . . 147 49. TSELIM -- TRAILING SPACE ELIMINATION . . . . . . . . . . . 149 page iv 50. TYPEOF -- CHARACTERIZE AN ASCII TEXT FILE . . . . . . . . 151 51. UNBACK -- RECOVER BACKUP FILES THAT RESTORE WON'T . . . . 153 52. UNOVER -- DELETE LEADING SPACES IN TEXT FILE . . . . . . . 154 53. WC -- WORD COUNT . . . . . . . . . . . . . . . . . . . . . 157 54. WFREQ -- WORD FREQUENCY . . . . . . . . . . . . . . . . . 160 55. XTRCOMS -- EXTRACT COMMENTS FROM ASSEMBLER PROGRAMS . . . 163 56. SETTING UPPER AND LOWER CASE CHARACTER SETS . . . . . . . . 164 57. HOW TO GET MORE . . . . . . . . . . . . . . . . . . . . . . 166 58. COMMON QUESTIONS AND ANSWERS . . . . . . . . . . . . . . . . 167 59. ABOUT SNOBOL4 VERSIONS FOR MS-DOS . . . . . . . . . . . . . 174 59.1 What Does SNOBOL Stand For? . . . . . . . . . . . . . . 174 59.2 About the SNOBOL4 Language . . . . . . . . . . . . . . . 174 59.3 Implementations for MS-DOS . . . . . . . . . . . . . . . 175 59.3.1 Minnesota SNOBOL4.2 by Viktors Berstis . . . . . . 176 59.3.2 Macro SPITBOL by Robert B. K. Dewar . . . . . . . . 177 59.3.3 Vanilla SNOBOL4 by Mark B. Emmer . . . . . . . . . 179 59.3.4 Catspaw SNOBOL4+ by Mark B. Emmer . . . . . . . . . 181 59.4 Recommendation . . . . . . . . . . . . . . . . . . . . . 183 60. LEGALITIES . . . . . . . . . . . . . . . . . . . . . . . . . 186 60.1 License to Distribute . . . . . . . . . . . . . . . . . 186 60.2 Disclaimer of Liability . . . . . . . . . . . . . . . . 186 60.3 Trademark and Product Acknowledgements . . . . . . . . . 187 61. MACRO SPITBOL ERROR CODE NUMBERS . . . . . . . . . . . . . . 189 62. ABOUT THE AUTHOR . . . . . . . . . . . . . . . . . . . . . . 197 63. LATEST VERSIONS OF THESE SNOBOL4+ UTILITIES . . . . . . . . 200 page 1 1. INTRODUCTION The document you are reading describes a variety of interesting and hopefully useful utilities and other programs, most of which are being distributed as shareware. Some of the utilities are very simple (but still useful!), others are quite sophisticated. Many of them provide simple but useful functions which are not adequately addressed by any widely available shareware (and sometimes even commercially available) software package. It is virtually certain that one or more of the utilities in this package will solve a problem, or improve the operation of your MS-DOS system. Note too that most, if not all, of the utilities described herein will work on network volumes (which is important if you are using a local area network); most of these utilities will also work on non-PC-compatibles, as long as they are running MS-DOS version 2.0 or above. 1.1 Printing this User's Guide In most distributions, this document has been formatted with the intention that it be printed in condensed-print mode on an 80-column (or wider) printer. Short pages (about 42 lines or so) have been used so that the resulting printed copy can be bound and trimmed to a nice, convenient size, about eight inches high and about six inches wide. It has also been shifted over so that, once bound, the left-hand edge is not buried in the staples, punched holes, Velobind strip, or whatever else you might have used to hold your printed copy together. The number of columns shifted over, normally twenty, was chosen to make it easier to read through the ".PRT" file using the popular shareware interactive text file listing program "LIST", written by Vernon D. Buerg, (not to be confused with the SNOBOL4+ "LIST" program described herein). Other distributions of this document may have been formatted differently, either by the author or by subsequent people who modified it before you got your copy (such changes by others are NAUGHTY! and are discouraged by the author). page 2 1.2 Overall Format Most of the following chapters each describe one utility or program of interest. Each includes a basic description of what the program does, one or more sample command lines which one might use to invoke the program, and a description of how you would specify any required file names. Each chapter also contains a thorough description of the available options provided by the utility or program. Constructive suggestions for improvements to this document are always welcome and should be sent directly to the author. 1.3 About Public Domain and Shareware Distribution Depending upon where you found this document, you probably got it along with one or more of the utilities described herein. Like most public domain and shareware software, there have been numerous distributions of this package over time. Different distributions have incorporated, where appropriate, updated versions of some of the included programs. Note that this document describes the NEWEST versions of these programs, as of the date this document was generated. (Depending upon how you actually got this document, the original date stamped on this document file may have been changed during one or more intermediate transfers). These newest versions described herein may not necessarily reflect the versions of the software that you happen to have concurrently received. (In some cases, this document explicitly mentions restrictions that may have been applicable to some older versions.) Public domain distribution is by its nature relatively unstructured. Old versions of programs do float around nearly forever. The diskette which the author releases, containing this document, is not large enough to contain all of the utilities described herein. Therefore, each distribution contains some subset of these described utilities. In some cases, public domain distributors, bulletin board SYSOPs, and the like may have re-packaged useful utilities from prior distributions along with utilities selected from the newer distribution to result in the package you have received. These things are obviously out of the control of the program author. page 3 If you find that some of the utilities described herein are of interest to you, but are not part of the package you have received, you are encouraged to contact the author directly. This is also obviously the only way to ensure that you have the newest revisions of each of the utilities you are interested in. Registered users (those who have registered as users of the package with the author) are notified periodically of updated versions of this package. Note that distributions of the current shareware version of these utilities, direct from the author, are made subject to a nominal charge for diskettes, postage and handling charges. In any package of utilities as diverse as this one is, there are bound to be some utilities described herein whose usage is complicated or whose usefulness you might not understand. Some of the utilities in this set are quite straightforward, others are quite complex and sophisticated. If you get bogged down while reading the description of some utility in this document, don't just put the whole document aside. Just skip to the next chapter! Chances are good that you'll find at least a few "must have" utilities among this set. One thing is for sure, you'll find utilities here that are not available anywhere else. At least one of the programs described herein, "SPACE", is considered to be a "program product" and is not distributed in the public domain. This program is, rather, offered on an individual sale basis only. SPACE is priced at $30 (and is well worth it!). The $30 charge gets you your own, personalized, non-copy-protected copy of the program. (Liberal quantity discounts apply to multiple-processor, network, or commercial users). 1.4 What is SNORUN.EXE? Virtually all of these utilities have been written in the SNOBOL4+ language. This language is supported by a public-domain run-time called SNORUN, which is needed to execute any of the programs you find in this package with the extension ".SAV". The use of the public domain run-time makes the individual ".SAV" files much smaller than they would be if they page 4 each had to include all of the common routines used by virtually every SNOBOL4+ program. Whether you transmit the ".SAV" files via some kind of communications line or via copies on diskette, this reduced size is a real advantage over programs written in other languages which require that each utility include a duplicate copy of the full runtime library. There is, however, a corollary disadvantage: ".SAV" files have to be executed with the version of SNORUN which matches the version of the SNOBOL4+ compiler which originally produced the ".SAV" file. This sounds more complicated than it really is: all it means is that you can't freely mix-and-match different versions of SNORUN with different versions of ".SAV" files. 1.4.1 SNORUN version 2.0 for Public Domain Distribution To help eliminate confusion, the author has thus far (at least as of this writing, in April 1987) distributed all shareware distributions of this software using one single version of the SNOBOL4+ system, namely version 2.0. This ensures that the version of SNORUN which people find in public domain distribution is likely to match the ".SAV" files which they also find in public domain distribution. However, there is a known bug in version 2.0 of the SNOBOL4+ system. This bug does not occur frequently, and it is data-sensitive. The bug generally causes the executing program to hang in what appears to be a loop. Since the bug occurs so rarely, the author's judgement call is that the chances of you being inconvenienced by it are probably less than, especially for casual users, your likelihood of being confused by having non-matching SNORUNs and ".SAV" files. (The bug has been fixed in version 2.03, which as of this writing is the newest version of SNOBOL4+). If it turns out that the bug actually impacts you users out there more than I expect it will, then this decision is certainly subject to change. 1.4.2 SNORUN versions for Registered Users In the meantime, those users who use one or more of the programs from this package a lot will probably want to register with the author for the newest versions of these utilities. I assume that those users who page 5 choose to register with the author, and therefore receive a complete distribution, are using the utilities more heavily than those users who get the distribution through public domain and shareware channels and use these programs infrequently. Registered users are assumed to be both more likely to encounter the bug, and simultaneously less likely to be confused by having a newer version of SNORUN. Registered users will therefore normally be sent a distribution with ".SAV" files compiled by the newest available version of the SNOBOL4+ system. page 6 2. ABOUT SHAREWARE, FREEWARE, AND PUBLIC DOMAIN SOFTWARE There seems to be a great deal of confusion regarding the terms "public domain", "freeware", and "shareware". In this chapter, I'll try to explain the differences and what it means to you as a computer user. 2.1 Public Domain Software Public domain software is software which has been literally placed into the public domain, meaning that it is freely available. Such software may be changed, improved, chopped up, or whatever else anyone wants to do with it. Public domain software tends to be rather chaotic, especially when the original source is distributed as well. Such programs get modified by "compulsive tinkerers", sometimes for the better and sometimes for the worse. Often the executable version of the program shows no obvious signs of these "modifications". No two versions of such programs are ever quite alike. Now that this phenomenon is well known, most responsible authors are no longer releasing their worthwhile and significant programs into the true "public domain". Much true "public domain" software is anonymously written... if you find a bug or have any problems, the author doesn't want to hear about it. Even worse, unscrupulous "diskette sellers" can package and sell public domain software at uncontrolled prices, and the author will receive no payment for his program, and has no control over selling price or marketing practices. 2.2 Freeware Freeware is a step above public domain software. Software which is freeware is generally protected by an author's copyright notice, which implies that the author is taking a continuing interest in his program and specifically intends to keep it from diverging off in many diverse and incompatible directions. This also usually suggests some measure of periodic, coordinated improvements and enhancements. Such software, without the intervening hands of many "helpful tinkerers", tends to be more consistent and error-free than true public domain software. page 7 Freeware differs from Shareware (described below) in that the author of software described as freeware generally expects no financial rewards from the users of his package. 2.3 Shareware Shareware is a "different animal" from the others. Shareware is actually often commercial-grade software (or better), where the author has been frustrated by attempts to pursue commercial distribution. Instead, in a variation on the old "chain letter" scheme, the idea is to simply give the software to one's friends, and ask them to give copies to their friends, and so on. People receiving the software can thoroughly test the software to decide whether it is suitable for their needs. If not, they can just pass the diskette on to a friend who they think might be more interested. If they do decide to use the software, the Shareware author requests that the user "register" with the author, and pay a nominal registration fee. When you receive a piece of shareware, the people you've received it from as a rule pay nothing to the shareware's author. You've merely bought the diskette or communications line time used for the transfer. You win in this scheme. Unlike your local computer store, where they ask you to part with considerable sums of money for a "professional" software package that may or may not be quite what you want, (and how to decide which one of the ten on their shelf is the best for you?), with shareware you can try the software yourself just as long as you like, in the comfort of your own home or office. Only after you've decided that you like it, do you actually pay for the right to use it on an ongoing basis. Even then, you win again. The distribution system for shareware is less costly than that for commercial software, so that as a user you have access to a very diverse array of software, at a lower price than you would have to pay for the same software if you had bought it in the normal way. This system also works well for the Shareware author. He has the satisfaction of knowing who his users are (if they register), and he (or she, of course) actually receives a much higher percentage of the money paid than would be the case for regular commercial distribution. These funds support additional work on both the software being registered, and further products that are made available later. page 8 Of course, this system breaks down if none of the package's users decide to register their software and support its author. In this case, the real loser is the software's user, because its author will eventually lose interest and stop supporting the existing software products, and turn back to the more expensive and less interesting retail computer software channels. Normal retail software marketing, where they try to force EVERY user of a software package to pay for it (and usually up-front), has other disadvantages as well, painfully evident to anyone who has been inconvenienced by the continuing Gestapo-like tactics of copy-protected commercial software. Your support of shareware is your way to reward the first major about-face from the idea of software copy protection, and to support a genuine alternative. The moral of the story is this: if you have received shareware software, and find that you never use it, don't feel guilty about having it and not paying for it. Just remember that you've got it, and pass along a copy to a friend who might have more use for it later. If, on the other hand, you've got a shareware software package which you've ended up using regularly, it makes sense for you to register it and pay the requested fee to its author. In so doing, you ensure its continued support and development. Besides, when somebody does something nice for you, it just simply feels good when you can return the favor... and even better when you know that it's going directly to the person who actually designed and wrote the software you've decided you like, and not disappearing into a faceless bureaucratic organization somewhere. 2.4 Distribution Channels Shareware, freeware, and public domain software are all typically distributed in the same manner: through computer clubs, users groups, bulletin boards, and diskette copying services. Since much of this deluge of software is "true public domain software", in this document I've decided to simply refer to the collection of friends, bulletin boards, and all the rest as simply "public domain distribution channels". page 9 If you've looked at much of the stuff that gets distributed this way, you've no doubt seen that some of it is very good, some is average, and much of it is simply garbage. Typically, the software which is "shareware" IS actually worth paying for: the author has gone to the trouble of polishing the program(s), providing carefully considered options and extra features, and expended the considerable effort of preparing thorough documentation. In many cases, those users who register their shareware get first-rate printed documentation, telephone or online support, and automatic free or reduced-priced software updates as new and improved versions get released. 2.5 But the Terms Do Vary Some authors still interpret the terms "shareware", "freeware", and "public domain" differently than I do here. However, usually they will explain their interpretation along with their product, and give some indication of their intentions regarding usage, distribution, and registration. Please respect their wishes. If you have already sent in shareware registrations for one or more of the shareware packages you already have that you find of value to you, I'm sure I can speak for the programmer responsible as well as the rest of us programmers dedicated to this new method of software distribution, in saying a sincere, "Thank you for supporting the free enterprise system." 2.6 License to Distribute Anyone having a copy of this package of shareware utilities is welcome (even encouraged!) to give copies of it to their friends, business associates, computer club members, or the like. It may be freely loaded onto bulletin board services for downloading. However, there are a few restrictions which must be observed: The registered version of these utilities uses a different version of the "SNORUN" runtime package. To prevent confusion, the registered version may not be distributed without express written permission from the author. page 10 Some programs as specified herein (such as SPACE) are program products and are not for general distribution. If this package is to be copied for distribution, it must be complete and unmodified. Specifically, no files part of the original distribution package may be modified or appended to in any way whatsoever. Additional files MAY BE ADDED to the package as long as they are clearly and centrally indicated as additions, and as long as those added files are placed under the identical distribution license as described in this section. Any such additions must clearly identify who added them, and when. It is specifically prohibited from adding any copyrighted additional files, unless the copyright of such added material is thereby assigned to this package's author. Any for-profit organization wishing to distribute this package may charge a reasonable fee, not exceeding six U.S. dollars per diskette or twelve U.S. dollars for the complete shareware package, or its equivalent in local currency, to cover diskette duplication and handling costs, as long as they strictly adhere to the other requirements of this license. Furthermore, such organizations must advise me of their intention to distribute the package, so that I may ensure that they have the most recent shareware distribution. Anyone charging any fee for distributing this package must clearly indicate that "shareware" is NOT "free software", but that the user is expected to register the software with the author if any or all of the software is to be used on an ongoing basis. They must also explain that the fee charged by the distributor does not constitute "registration", and is not being paid to the author. Distribution rights to this package and any other software copyright by me, Gordon Peterson II, are specifically denied to Nelson Ford and/or "The Public (Software) Library" until further notice. This unusual and unfortunate step has been taken because of his inflexible policy of adding separately copyrighted material to authors' disks in an attempt to impede their further distribution, and his policy of modifying author's documentation files. page 11 Any other commercial distribution of these programs is the exclusive right of the author. Contact me for further details. Since programs and packages distributed under public domain type distribution channels are not under the author's direct control, note that this license agreement is subject to change without prior notice. page 12 3. ANGLICIZ -- "ANGLICIZE" FOREIGN CHARACTER SET Many files, especially those originating in foreign countries, contain many characters which are part of the "IBM extended ASCII character set", but are not part of the "normal" 96-character ASCII character set. Such characters might include letters with diacritical marks, fractions, foreign punctuation, and various currency symbols. It is often necessary to convert such files to their 96-character-ASCII equivalent. In some cases, such as the "upside down question mark" used in Spanish, the special characters may simply be discarded. In other cases, the diacritical mark accompanying the character must be deleted. A more complicated case occurs when a single character must be replaced by several, especially if one wishes the replacement characters to correspond correctly with the upper/lower case indicated by the character replaced and those following it. ANGLICIZ performs all these conversions quickly and conveniently. Users involved in international operations will find it to be extremely useful. For example, assume that one has the German surname "Hübner". (Note: the quoted word should contain a "u" with two dots over it. If your printer did not print that letter, or printed it as something strange, this shows why you need a utility like this one). ANGLICIZ will change this name to its Anglicized equivalent "Huebner". The phrase "¼ cup" will be changed to "1/4 cup". And so forth. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. It also should be pointed out that the program automatically deletes trailing spaces at the end of each record, and that input records are assumed to be less than 4000 characters long. page 13 The program is invoked with a command line of the form: snorun angliciz [<iooptions>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. page 14 4. ASMGEN2 -- DISASSEMBLY SUPERVISOR This program works in conjunction with the public domain program ASMGEN to generate disassemblies of .COM and/or .EXE program files. One of ASMGEN's biggest problems is that it does not recognize character string constants and obvious data areas (blocks of binary zeros or hex FF's, for example). It does, however, support an auxiliary input file (the .SEQ file), which allows the user to tell it where it is to generate ASCII strings, data bytes, and the like. Unfortunately, making the .SEQ file is usually a tedious manual process. ASMGEN2 automates this process. It supervises ASMGEN while it performs the first pass over the executable file and generates a "first stab" at a decent source file output. ASMGEN2 next invokes the utility MAKASEQ, which examines the first pass output from ASMGEN and figures out where character strings and data areas are likely. MAKASEQ outputs a .SEQ file suitable for input to ASMGEN. ASMGEN2 finally invokes ASMGEN for a third pass, which generates a considerably cleaner output source file. Note that early versions of this system do not support object files larger than 32K bytes, due to a limitation in MAKASEQ version 1.0. Using versions of MAKASEQ 1.1 or above, the limit is 64K. This 64K limitation is imposed by the public domain ASMGEN program. Note that ASMGEN2 must be run from a disk containing DOS, ASMGEN, and MAKASEQ. To disassemble the executable file "MYPROG.EXE", the command line would look like: snorun asmgen2 ;MYPROG.EXE ASMGEN2 generates appropriate error messages if it detects that any of the processes it supervises have not been successful. It may be interesting that the MAKASEQ program is also written in the SNOBOL4 language. It was compiled using an alternate SNOBOL4 system (called Macro Spitbol). page 15 5. ASMRECOV -- RECOVER ASSEMBLER SOURCE FROM LISTING FILE This utility program uses the print file on your disk from a (hopefully recent) assembly, and uses it to recover the source file. This makes it much less painful when you have accidentally deleted or overwritten your original source file. ASMRECOV is designed to work with listing files produced by Microsoft Macro Assembler version 4.0, but the output from other versions will probably work just as well. The current version of ASMRECOV does not attempt to strip out any inclusions or macro expansions which might have appeared in your listing. Therefore, there may be some manual editing to do to "clean up" the output file produced by ASMRECOV. However, this should be in all cases less than the work it would take to key the program back in from the same listing!! Likewise, note that sometimes (due to the way MASM handles tab characters) it may be necessary to add or remove a tab character here or there from the resulting output file. One thing you might need to watch out for are some of the bugs which Microsoft's Macro Assembler is so famous for. Just one, of special concern to us here, causes a line such as: NAME DD 0,0 to appear twice in your listing, once where it belongs and again right below it where it doesn't belong. The current version of ASMRECOV does not attempt to suppress this (although it will usually be apparent when you later try to re-assemble your file; if you have a label on the line, you'll get a "duplicate definition" error message for the label. If not, you will just have to find it on your own!) and you'll get both of the two lines written to the ASMRECOV output file. page 16 ASMRECOV assumes that listing file lines are never more than 300 characters wide, and also automatically deletes trailing spaces from the records it writes to standard output. Note that this program can operate as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. The program is invoked with a command line of the form: snorun asmrecov [<iooptions>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the listing file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or even the console (although why you would want ASMRECOV to read from the console is beyond me!) ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. This file is the reconstructed assembler source file. page 17 Example command lines would look like: snorun asmrecov <program.lst >program.asm snorun asmrecov /5:program.lst /6:prog.asm page 18 6. ASMSTAT -- GENERATE ASSEMBLER PROGRAM STATISTICS This utility program compiles some interesting statistics about assembly language programs. It reads in assembly language programs (formatted according to the rules for Microsoft's MS-DOS assembler, although it would probably work with most compatible-format assembly languages) and produces statistics indicating the ratio of comment keystrokes to program keystrokes, and many other interesting statistics. It is surprising to see how closely an individual programmer's statistics end up being, even in quite different programs. This program can also be used to "screen" a series of programs, to see which might need be checked for adequate commenting. The program is invoked with a command line of the form: snorun asmstat <<inputfilespec> Note that the first of the left-pointy-brackets above is used in the actual command line to redirect the input to the program from the file indicated by <inputfilespec>. Alternatively, this first "<" character may be replaced by "/5:" or "/5=". (These are generally the three ways to redirect the input file to any program based on SNORUN). Example command lines would look like: snorun asmstat <c:\asm\prog1.asm snorun asmstat <myprog.asm page 19 7. CASE -- CASE CONVERSION AND FOLDING This utility program converts files containing upper and lower case alphabetic characters to all upper or all lower case, depending upon the option entered on the command line. Options may be entered in either upper or lower case. If both /U and /L options are specified, the program will invert the case of all alphabetic characters. If no option is specified, the program displays an example command line with a list of available options and terminates, without processing the input file. CASE can also optionally fold the 256-character IBM extended ASCII character set into a 128-character set, by forcing the high order bit to a zero. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. It also should be pointed out that the program automatically deletes trailing spaces at the end of each record, and that input records are assumed to be less than 4000 characters long. (The limit was 1000 for earlier versions of this program). The program is invoked with a command line of the form: snorun case [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. page 20 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /L or /l This option specifies that any input file characters found in upper case are to be converted to lower case. /U or /u This option specifies that any input file characters found in lower case are to be converted to upper case. As mentioned before, note that if both /U and /L are specified, the case of the file is inverted (i.e. upper case input characters are converted to lower case and lower case input characters are converted to upper case). /F or /f This option specifies that any character greater than hex 7F is to have its high order bit set to zero. This "folds" the character set into a normal 128-character ASCII set. This option can be useful when dealing with WORDSTAR files, or those which have been received using certain communications packages. If other options are also active, note that they effectively are performed after the case-folding takes place. page 21 Example command lines would look like: snorun case <infile.txt >outfile.txt ;/U snorun case <c:\mixfile.txt >c:\lower\mixfile.txt ;/L snorun case /5=d:\insd\tempfile.asm /6:c:\outsd\uprcase.asm;/u snorun case /5:flipinp.txt;/L /U page 22 8. CHARDF -- CHARACTERIZE A DELIMITED FILE This utility program is a terrific aid if you've received a delimited ASCII file which you wish to manipulate or convert to a normal ASCII text file containing fixed-length-records and fixed-length-fields. The program will read one or more input files, carefully examining all the records. Upon completion of each file, statistics including the number of records in the file, and how many records for each given number of fields were found, is displayed. When all the input files have been examined, CHARDF will output the total number of records examined. It also displays the minimum size possible for each of the fields, maximum number of fields found in any record, and (therefore) the minimum record size sufficient to contain all data from the original delimited files, without truncation. If the memory capacity is sufficient, an option is available which causes CHARDF to create an output file containing the data from the delimited records found in all of the input files. The output file records are fixed length records, containing fixed length fields. The data from the corresponding input file fields are left-justified in the output file fields, and padded on the right with spaces within each field. What is a delimited ASCII file? It is simply a standard ASCII file. Each line of the file corresponds to a single record. Within that line, there may be one or more "fields", or data items. Data items may consist of numbers, character strings, or any ASCII text. Individual data items within a line are separated by commas or "tab" characters (the ASCII "tab" character has the decimal value 9). If a data item is contained within double quotes, then that data item may contain commas. (It is not a good idea to use tab characters within quoted strings, since it is not clear where the "tab stops" are intended). Quoted strings may also be used where leading or trailing blanks must be retained. In non- quoted fields, leading and/or trailing blanks are eliminated. page 23 For example, the following lines each contain six fields and are exactly equivalent: Mr. Thomas,3, 4.7, " yes, really!",,Jeffries "Mr. Thomas","3","4.7"," yes, really!", "" ,"Jeffries" Delimited ASCII files are often used as a standard method of transfer of multi-field data files between programs. Delimited files are often used for mail-merge files within word processors, produced by dBase III or other database managers, and are easily handled by programs written in BASIC. On the other hand, delimited files are not easily dealt with by other languages, mainframes, and many utilities. Most "serious" programs expect data to be represented in fixed-size fields within fixed-length records. CHARDF, therefore, allows you to take one or more delimited files and find out rapidly: 1. How many records are present? 2. Do all records contain the same number of fields? 3. What is the maximum number of fields in any record? 4. What is the size required for each field to avoid data loss? 5. What is the total maximum record size needed? Having found out the above, CHARDF can create a fixed-length, field- oriented ASCII text file which combines the data from all the input files. One possible example of the use of CHARDF is the following: you have produced a form letter using Microsoft WORD and wish to add all the addressees you've sent it to to your mainframe system's data files. You have produced a simple delimited file (with WORD's formatting removed) containing all of the names and addresses, but you're not sure which records have the longest data for each field and what the required format needs to be for input to your mainframe. You also would like to then convert the file to a form the mainframe can handle. page 24 CHARDF will work with multiple input files. Each input file record (i.e. each single line) is limited to no more than 4000 characters long. If the creation of a fixed-length record, field-structured output file is requested, the current version of CHARDF buffers the input file data in memory until it has decided what the field and record sizes need to be. This eliminates the need to reread and re-parse the input files, but does limit the amount of data that can be written to the field- structured output file if memory overflow is to be avoided. Typically the CHARDF program permits output files up to 300K bytes or so, but this number will vary according to how many records, how many fields, and the like, are to be handled. An important benefit of SNOBOL4's very sophisticated memory management is that fields which contain identical values are stored only once in memory, regardless of how many records or fields contain that same value. In some cases, therefore, output files of quite large final size may be buffered without running out of memory. To invoke the CHARDF program, use a command line like the following: snorun chardf [<iooptions>] ;<options> <iooptions>:: /4=<fieldfile> or /4:<fieldfile> This item allows specification of a file (or device) to which the field-oriented, fixed-length-record version of the combined input file data is to be written. If output to this file is desired, the /W option should also be specified (see below). <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. Note that this input file (unit five) is the FIRST input file. page 25 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the standard output is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. WARNING: CHARDF can produce several different output files. The output file referred to by this item is the one which normally is directed to the screen, and NOT the one containing the fixed-length, field- oriented data file. /8=<inputfile> or /8:<inputfile> This item allows specification of a file (or device) from which the second input file is to be read, if any. /9=<inputfile> or /9:<inputfile> This item allows specification of a file (or device) from which the third input file is to be read, if any, and so forth, up through unit number 14 (although typically less than eight input files will be possible due to limitations on command line length). <options>:: /W or /w This option specifies "write", and tells CHARDF that a fixed-length record data file (with fixed-length fields) is to be written to the output file defined in the "/4:" description. NOTE that the semicolon before the /w option is important (see the example command line, above)! page 26 9. CHOPUP -- CHOP UP A FILE FOR TRANSMISSION Sometimes it is desirable to be able to send a file by electronic mail, but some electronic mail systems (notably CompuServe's EMAIL) cannot deal with message files over 10K bytes in length. If you have a file you need to transmit more than 10K bytes long, the obvious approach is to chop it into pieces that you can send, and allow the recipient to simply put them back together at the receiving end. Unfortunately, there are no standard utilities available to facilitate the process of chopping up a file. Text files can sometimes be divided by a good editor, but what could one do with a big archive or other binary file? The CHOPUP utility takes an input file, whether text, binary, or whatever, and divides it up into pieces of 9600 bytes each. This value is comfortably under CompuServe's 10K byte message size limit. In addition, some communications packages pad XMODEM-protocol transmissions to 128-byte multiples. By using a 9600 byte message, the 128 byte multiple will not pose any problem (other than perhaps at the very last piece of the file, but this is usually not critical regardless). To facilitate its use in a batch or MAKE file, CHOPUP will automatically increment the name of its output file to produce as many names as are needed to contain the (subdivided) input file. It first tries to increment a number it finds in the extension of the file, and if that doesn't work it tries to increment the first number it finds in the filename. NOTE THAT CHOPUP EXPECTS TO SEE A NUMBER EITHER AS PART OF THE OUTPUT FILE'S EXTENSION OR NAME. If CHOPUP cannot figure out how to increment the output file name, it will abort. When the output files arrive at the destination end, it is a simple matter to append them together using the MS-DOS "COPY" command, as follows: COPY A.TX1+A.TX2+A.TX3+A.TX4 A.TXT Please refer to your MS-DOS User's Guide for more information on the use of COPY. page 27 To invoke the CHOPUP program, use a command line like the following: snorun chopup [<iooptions>] ;<options> <iooptions>:: /4=<inputfile> or /4:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. /8=<outputfile> or /8:<outputfile> This item allows specification of a file to which the first piece of the input file is to be written. This name should have a number either in the extension or in the filename that CHOPUP can increment on subsequent output files. <options>:: /=nnnn This option specifies a different output file size to use. The number can be any decimal value up to 32767. NOTE: It is a good idea to use only values which are multiples of 128. NOTE that the semicolon before the /= option is important (see the example command line, above)! An example of a typical command line for the use of CHOPUP might look like: snorun chopup /4=datafile.arc /8=datafile.a1 ;/=9728 page 28 10. CISSTRIP -- STRIP JUNK FROM COMPUSERVE CAPTURE FILES Users of CompuServe who make a habit of saving their CompuServe (or other communications systems) sessions to a disk capture file may notice that a lot of space is wasted in such capture files with repetitive junk. Such junk might include common prompt lines, such as: Press <ENTER> to continue: Another common space waster in capture files are those "helpful" menus that get displayed all the time. Although these menus can be helpful while you are online, they are generally not at all helpful when enshrined forever in your retained capture files. The CISSTRIP utility allows you to strip the most commonly occurring junk from your capture files in a painless way. This reduces the size of your capture files, saving space on disk and making it easier and faster to find messages or conversations you might wish to later find in them. CISSTRIP reads an editable file which contains exact copies of all the lines you wish stripped from your capture files. In addition, CISSTRIP will also remove consecutive blank lines (i.e. four consecutive blank lines will be reduced to one), trailing spaces, and backspaces that your communications program is not smart enough to remove before writing its capture file to disk. CISSTRIP's operation can be summarized in the following steps: 1. The file containing the "junk lines" to be stripped is read. A sample CISSTRIP.TXT file is probably included on the distribution diskette, but you are encouraged to modify this file according to your own requirements. (There is nothing "magic" about it, you can modify it using your favorite text editor). This file will typically be several hundred lines long. page 29 2. If the "junk lines" file contains duplicate lines (i.e. lines which are EXACT duplicates of each other), or null lines, the "junk lines" file is automatically updated to remove the null or duplicate records. 3. If an output file is specified, that file is used. If not, CISSTRIP will attempt to create a temporary work file on a user-specified path. (If you have a RAM drive, for example, it is usually a good idea to place the work file there). If a work file is used, CISSTRIP will copy the stripped work file back over the original input file upon completion. 4. The input file (the capture file) is read and any record in it which EXACTLY matches a record in the "junk lines" file is discarded. Multiple consecutive null lines are reduced to one blank line, and backspaces are removed by eliminating each one with the preceding character on the line, if any. Remaining records are written to the output file. 5. When all the input records have been processed, the input and output files are closed. If a temporary work file was used, CISSTRIP then copies the work file back over the original input file. 6. If you have a program which will reset your DOS clock (e.g. many multifunction boards having a clock/calendar come with such a utility, often called something like "getclock"), you can specify its name as an option. If you do so, CISSTRIP will retain the original input file's date and timestamp for the output file. Note: CISSTRIP does not attempt to determine the context of the lines it is told to strip; i.e. a prompt line that you tell it to remove will be removed, even if it is in the middle of a message you have received and was not intended by its author as a prompt. Successful use of CISSTRIP is dependent upon how well you set up the "junk lines" file based upon your own personal usage patterns and requirements. Although CISSTRIP was developed by the author for the specific purpose of cleaning up CompuServe capture files, it is by no means limited to that use. The program can actually remove any specified matching lines from almost any kind of file. With a little imagination you can probably come up with a number of other fascinating ways to use it. I'd be interested in hearing what you come up with. page 30 To run CISSTRIP, the basic command line is of the form: snorun cisstrip <iooptions>[;<options>] (The "<iooptions>" and "<options>" fields will be described below). CISSTRIP is also designed so that it can easily handle a number of capture files at once. For example, the author's capture files have file names of the form: "CPSVmmdd.txt", where "mm" is the month and "dd" is the day of the month. A simple batch command line such as the following: for %i in (cpsv*.txt) do snorun cisstrip /5:%i ;wpath=d: /t=getclock.exe will automatically strip the junk from all the CompuServe capture files and update them in place. Note that the command line specifies that drive "D:" (which could be a RAM drive) is used for the temporary output file(s), and that the "getclock" command will be used for resetting the system clock. For more information on the use of such batch file commands, you should refer to your DOS User's Guide; note in particular that if you put this line into a batch file, you need TWO "%" characters for each occurrence of the character in the line above. One thing users of CISSTRIP need to be careful of: many communications programs can occasionally leave hex "1A" (DOS end of file) characters in the middle of their capture files. When such a character is encountered by CISSTRIP (as is true for most of the programs in this package), they sincerely believe that the end of the input file has been reached and all following data is therefore ignored. THIS CAN RESULT IN LOSING ALL FOLLOWING DATA FROM YOUR CAPTURE FILES. Perhaps your communications software never writes embedded hex "1A" characters into your capture file (count yourself lucky!). If you're not sure, it is safest to make sure that any such characters are first eliminated from your communications capture files (see the DELIEOF utility, described elsewhere in this document) before running CISSTRIP. Note that, effective beginning with version 1.02, CISSTRIP will bypass embedded end-of-file marks contained within the input file. This makes page 31 it less likely that important capture file data will be lost. The "bypass internal end-of-file mark" feature can be disabled, if desired, by specifying the /X1A option (see below). When the hexadecimal "1A" character is skipped, note that it is not copied to the output file; an informational message is also written to the screen indicating that an internal EOF mark was skipped and its offset within the input file. CISSTRIP assumes that the system file "COMMAND.COM" is available on your disk(s) under your current directory, or in your path string (see your DOS User's Guide's description of the PATH command for more information). In the option descriptions which follow, note that you may use either upper or lower case. It makes no difference. <iooptions>:: /4=<junkfile> or /4:<junkfile> This item allows specification of a file (or device) from which the "junk" file is to be read. This is the file which contains examples of all the lines which you wish to be removed from the capture file(s). If you do not specify this option, CISSTRIP will look for a file named "CISSTRIP.TXT" in the current directory. Note that many communications services send lines with one or more leading line feeds. These are considered by DOS to be part of the following record, so these linefeed characters MUST be included in the "junkfile" lines if the corresponding lines in the capture file are to "match" and be stripped. /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. This is the file which contains your captured communications session from which junk lines are to be stripped. This is the only one of the <iooptions> which you MUST specify. (If you do not, the program will attempt to read from the console, and this will cause the program to fail since the console is not a repositionable device). page 32 /8=<outputfile> or /8:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. If this item is not specified at all, the program will attempt to modify the input file name (the one specified for unit 5, above) by using the "work file path" option (see below), and use that as the name of the output file. <options>:: /wpath:<pathname> or /wpath=<pathname> or /w:<pathname> or /w=<pathname> This option is used to specify the path on which the temporary output work file is to be placed. If you have specified the name of a specific output file (using the /8: option as described above), and that file can be opened, then this option is ignored. See the example command lines below for specific ways this option can be used. You may use either a colon or an equals sign to separate the option name from the path name. (The path name given will be put at the BEGINNING of the "base portion" of the input file name and the resultant string will be the name of the temporary output file). If you specify this option, it is important to make sure that it will in fact place the work file somewhere different than the drive and subdirectory containing the input file. IF NOT, YOU MAY INADVERTENTLY OVERWRITE THE INPUT FILE DIRECTLY, WHICH MAY RESULT IN THE TOTAL LOSS OF YOUR CAPTURE FILE. CISSTRIP tries to prevent this from occurring, but it can be fooled by names which appear to be different but in fact end up referencing the exact same file. BE CAREFUL! /time:<progname> or /time=<progname> or /t:<progname> or page 33 /t=<progname> This option specifies the name of your program which can reset your DOS clock from your battery-backed-up system clock. If this option is specified, CISSTRIP will be able to retain the same date and time stamp on its output file as there was on the input file. If you have no such program, or don't understand the need for this option, you can safely ignore it. /x1A This option specifies that the presence of a hexadecimal "1A" character in the input file is to be taken as a genuine end-of-file mark, even if the MS-DOS directory entry for the input file indicates that there is supposed to be additional file data following it. Specifying this option could result in the loss of data if a communications line error results in a hex "1A" character being captured into your capture file. This option (and the ability to bypass embedded EOF mark bytes) only applies to the input file specified as unit 5 (i.e. the file from which the "junk" lines are to be stripped) and not the file defining which lines are "junk", i.e. unit 4. NOTE: If any of the above options are specified, don't forget the semicolons separating them from the <iooptions>. The semicolon IS important. Example command lines might look like: snorun cisstrip /4:c:\junkfile.txt /5:c:\modem\comm.cap /6:a:comms.cap snorun cisstrip /5:cpsv0104.txt ;/w=d: /t=c:\mfcard\getclock snorun cisstrip /5:received.txt ; wpath:c:\scratch NOTE: CISSTRIP is being distributed in different versions. The shareware version includes a shareware information screen, and may be freely distributed. The version for registered users is personalized and must not be distributed to anyone other than the user to which it is personally registered. page 34 11. COMBINE -- COMBINE FILES AND ELIMINATE DUPLICATES This program combines two to four files, eliminating in the process all records which are EXACT duplicates of another. In other words, if all of the input files, together, contain four records consisting of simply "**", the output file produced by COMBINE will contain just one such record. As an example, suppose that you have a name and address file which contains one record for each of your friends. You have copies of this file on your personal computer at home, as well as your computer at the office. Occasionally, you make additions to the file, and don't always remember to update the other copy right away. After several additions in each place, as well as perhaps some changes to existing records, it is difficult to combine the two files, ensuring that all additions to any of its separate copies are reflected in the new, consolidated file. With COMBINE, you can handle such problems with ease. It is important to recognize that COMBINE does not attempt to discern whether or not two records, which originally were identical, are now different because of a change made to one of the copies. It simply observes that they are now different. Therefore, the output file of COMBINE can of course contain records which reflect multiple generations of the same input record. Even if it could detect that the almost- duplicate records were modified copies of the same record, it would certainly be impossible to determine automatically which is the "newest" and which data in which copy of the record might be outdated. The easiest way to deal with such problems is to use the "sort" option, described below. Use of this option causes records which start out the same, at least, to group together where they can be visually checked for similarity. This program requires that the output file (after elimination of duplicates) is small enough to be kept in available memory... usually around 300K or so. Most files applicable to this sort of processing are smaller than that size. COMBINE has several other characteristics which might affect some users: it eliminates trailing blanks, if any, at the end of each record; it assumes that input records are 4000 characters (or less) each; and it removes null lines in addition to duplicates. page 35 To use COMBINE, enter a command line like: snorun combine /1=<infile> ... /4=<infile> /6=<outfile> ;<options> You are allowed up to four input files, numbered one to four. The separator after each input file number may be a ":", a "=", or omitted entirely if you prefer. In the resulting output file, the input records (those which are not duplicates) appear in sequence: 1) records from input file 1 2) records from input file 2 3) records from input file 3 4) records from input file 4 Records (unless the SORT option is specified) are not sorted or otherwise reordered during the COMBINE operation. Note that duplicates are removed even if they occur within one input file. They do not have to be adjacent for COMBINE to find and remove the multiple copies. In order to be considered "duplicates", records (after trailing blanks have been removed) must match exactly, character for character. Upper and lower case characters are considered different during this comparison. Likewise, tab characters are treated just as any other character, and must match exactly in order for two records to be treated as identical. <options>::= /S or /s This option specifies that the output file, once duplicates have been removed, is to be sorted alphabetically (according to the ASCII collating sequence). This can sometimes help to locate "almost-duplicate" records that have been modified in only one of the several copies of a file, by bringing them together in the output file. Note that, as mentioned above, this will typically not help unless the first part of each record is the same; otherwise, they will generally sort "apart" rather than together. NOTE: If you use the /s option, be careful to include the ";" before the /s. It IS important. page 36 Typical command lines for COMBINE might look like: snorun combine /1:input1.fil /2:input2.fil /6:output.fil snorun combine /2:a.txt /3:b.txt /4:c.txt /6=abc.txt ;/s page 37 12. COPYSEG -- COPY A FILE TO MULTIPLE SEGMENTS If you've ever had a big file you needed to put onto floppy disks or other such "small" devices, you probably have wondered how one goes about transferring a file which is too big to fit on a single floppy disk. The answer to the problem: use COPYSEG. COPYSEG will copy either an ASCII text or binary input file to one or more output files. If there is not enough space on the output volume to copy the entire input file, COPYSEG will copy as much as will fit, then increment the file name, and continue copying to the new file, and so on, until the entire input file has been copied. When an output file must be written as multiple segments, COPYSEG will propose an incremented file name for each additional segment. File names are incremented by incrementing the first number COPYSEG finds in the extension part of the file name, if any. If there is no numeric part in the extension, then COPYSEG will try to increment the first numeric part it finds in the file name. (The user is responsible to make sure that there is enough space in the extension or name for the number to be incremented as many times as necessary). For example, here are some possible file names and the corresponding incremented names that would be generated: JUNK.TX1 JUNK.TX2 JUNK1.TX4 JUNK1.TX5 J1NK2.TXT J2NK2.TXT JUNK9A.TXT JUNK10A.TXT When COPYSEG proposes the incremented file name for an additional output file segment, the user may accept the suggestion (this is a good time to change the floppy disk if needed), give the program a different output drive and/or file name if desired, or can terminate the program. If COPYSEG cannot increment the file name (generally this is because neither the file name or extension contain any numbers), the user is given the chance to tell COPYSEG what drive and filename are to be used for the next segment to be written. page 38 COPYSEG is designed to be interactive, and it continually advises the operator of its assumptions and activity during the operation. If the file being copied seems to be an ASCII text file, COPYSEG will try to copy only complete text records to each output segment. If the file being copied appears to be a binary file, COPYSEG will copy as much of the input file to each output segment as it possibly can. COPYSEG decides whether the input file is an ASCII text file or a binary file by reading the first portion of the input file and performing a character occurrence analysis. This usually is reliable. However, for unusual cases, this can be overriden by a command line option when necessary. To use COPYSEG, the command line is of the form: snorun copyseg <iooptions> [;<options>] <iooptions>:: /3=<inputfile> or /3:<inputfile> This item allows specification of the input file which is to be copied. Note that this must be a file, not a device, since it must be positionable: COPYSEG processes this file using random access. /4=<outputfile> or /4:<outputfile> This item allows specification of the first file to which the output of COPYSEG is to be written. Don't forget to include the drive specification if necessary. WARNING: Be careful to make sure that the output file specified (and any incrementation of that name that COPYSEG may perform) will not end up being the same file as the input file. If this occurs, it can cause the input file to be overwritten and possibly destroyed. <options>:: /B or /b page 39 This option is used to specify that the file is to be treated as a binary file, regardless of whether it appears to be an ASCII text file or not. NOTE: Don't forget the semicolon on the command line between the <iooptions> and the regular options. It IS important. As a few examples, typical command lines to COPYSEG might look like: snorun copyseg /3=c:\prtfiles\report.prt /4=a:report.pr1 snorun copyseg /3:utilsdoc.prt /4:a:utilsdoc.p1 snorun copyseg /3=bigarc.arc /4=a:bigarc.ar0 ;/b page 40 13. CPRANGE -- COPY RANGES OF RECORDS This utility program is useful when you want to extract one or more series of records from one file and place them into another file. This is especially useful when the input file is large, or contains long records, and doing the extraction with a normal editor would be tedious or impossible. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. CPRANGE will work with files containing arbitrary numbers of records. Each record may be up to 4000 bytes long. Note: all trailing spaces are removed from input records before they are written to the output file. If this is undesirable, (typically when the records are supposed to be a fixed, known length) the output file records may be repadded to the desired length (see the PADREC utility). (Note that the record size limit was 1000 for some older versions of this program). The ranges of records which are copied by CPRANGE are determined by giving a starting key string and an ending key string. In this way, the starting and ending records of each sequence to be copied are determined by context and not by something artificial such as a line number. CPRANGE will find the key string anywhere in the input records, (it does not have to be field-aligned). However, note that the key string IS case-sensitive; a specified key string of "ABC" will NOT match a record containing the string "Abc". The CPRANGE program is normally in one of two modes: it is scanning, looking for the start of a sequence of records to be copied; or, it is copying, looking for the end of the current sequence. The program is invoked with a command line of the form: snorun cprange [<iooptions>];<options> page 41 <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /S:<key> or /S=<key> or /s:<key> or /s=<key> This option specifies the starting pattern. The starting pattern is the pattern which, when found in an incoming record, causes that record (and the ones following) to be copied to the output file. The format of the <key> item is described below. If no starting key is specified, the program will go immediately into copy mode and copy until a record containing the ending key is copied. /E:<key> or /E=<key> or page 42 /e:<key> or /e=<key> This option specifies the ending pattern. The ending pattern is the pattern which, when found in a record of a sequence being copied to the output file, causes the program to revert to scan mode (looking for the starting pattern), beginning with the next record of the input file. The format of the <key> item is described below. If no ending key is specified, the program, once it begins to copy records of a sequence, will copy all remaining input records until the end of the input file is reached. /R or /r This option specifies "repeat". It causes the same set of starting and ending keys to be used again and again, until the input file has reached end of file. If this option is NOT specified, CPRANGE will (when it has completed copying a sequence of records as specified) look on the command line for another set of starting and ending keys, and continue operation (from the current location in the input file) using the new starting and ending keys. NOTE: If the /R option has been specified anywhere on the command line, then only the first starting and ending keys found on the command line will be used. <key>:: "string" or 'string' or string The key may be specified as a simple string of characters, if it contains no commas or spaces. In this case, the key string (which must be found exactly in a record to start or end a sequence of records to be copied) begins with the character immediately following the ":" or "=", and continues up to (but not including) the next space or comma, or to the end of the entered command line. If the key to be searched for contains commas or spaces, then it page 43 must be surrounded by quotation marks. Either single or double quotes may be used; if your key string contains one or more double quote characters, then surround it with single quotes. If your key string contains one or more single quote characters, then surround it with double quotes. If your key string has to contain both single and double quotes, then eliminate the spaces and commas and use the form which does not require surrounding quote marks. The CPRANGE program is normally in one of two modes: it is scanning, looking for the start of a sequence of records to be copied; or, it is copying, looking for the end of the current sequence. For example, if you had an assembly language source file and you wanted to extract all the subroutines, you could use a command line like the following: snorun cprange <input.asm >inputsr.asm;/s=proc /e=endp /r Note that "proc" will match any appearance of the four letters "proc", even if they are contained completely within another word. As another example, suppose that you had been printing a file when the printer jammed, and the last third of the file printed onto the same single (by now very black!) line. You notice that the first line of the page on which the printer jammed had a page heading that included the exact character string "PAGE 1776". You can restart your printing there by using the command line: snorun cprange <myfile.prt >prn;/s="PAGE 1776" NOTE: Each time that CPRANGE looks for starting and ending keys to define a sequence of records, it takes the NEXT starting and the NEXT ending key that it finds on the command line. The order in which they appear on the command line is not significant. Therefore, the command line: snorun cprange <input.txt >a:output.txt;/E:ABC,S:/DEF,/E:GHI page 44 will NOT copy the sequence starting from the first record through the record containing "ABC", followed by the sequence beginning with a record containing "DEF" through a record containing "GHI". Instead, what the above command line will actually do is to copy a sequence of records beginning with a record containing "DEF" through a record containing "ABC", and then additionally copy the following records, until it finally has copied a record containing "GHI". If your key string includes spaces, note that spaces and space produced by tab characters are not the same (although they typically look the same on the screen or on a printer). page 45 14. DELALL -- DELETE ALL MATCHING FILES This utility program searches through the indicated path and deletes all files from it that match the indicated skeleton. Intended for use in batch and "make" files, the command DOES NOT ASK FOR CONFIRMATION. DELALL will optionally list the path and name of each file as it is deleted. Due to the danger inherent in deleting files, a command line option must be present in order for the automatic deletion to take place. If that option is not present, DELALL simply lists those files which match the indicated path and would (therefore) be deleted if the option had been specified. Due to the same danger, DELALL will not delete files outside of the single subdirectory specified. To use the DELALL program, enter the command line: snorun delall <iooptions>[;<options>] Options, as usual, may be entered in either upper or lower case. <iooptions>:: ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This option allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. This file is the output which would ordinarily be written on the screen. You might wish to keep this file as a record of which files were deleted. <options>:: path=<pathname> or /p=<pathname> page 46 This option allows specification of the path name and skeleton file spec that describes the files to be deleted. Examples are: c:\asm\lst\ <--- all files in the subdirectory c:\asm\lst\*.lst <--- only those files ending in .LST c:\asm\xyz. <--- only a single file (not subdir) Note that you can also specify the prefix part of a file name as well as the name of a subdirectory. In this case, DELALL will delete all files beginning with the given prefix part. An example of using DELALL to delete all files beginning with CL in a given subdirectory (DOS) might be something like: snorun delall ;path=c:\dos\cl /f /d This example would delete, for example, c:\dos\clock.exe c:\dos\clearmem.com c:\dos\clubroll.txt /dpo This option causes no file deletion, but merely displays the effective path name that would be used for the lookup. This is NOT a particularly useful option. file or /f This option causes the output to include an entry for each file that is (or would have been) deleted. /k or killem This option specifies that any files matching the path name and file skeleton given in the PATH option are really and truly to be deleted. NOTE: DELALL makes no attempt to delete subdirectory files, volume names, or files with the HIDDEN, SYSTEM, or READ- ONLY attributes (see your DOS User's Guide for more details on the meaning of these attributes if this is unfamiliar to you). page 47 15. DELIEOF -- FIND AND DELETE INTERNAL EOF MARKS Occasionally when one appends text files (usually occurring as the result of the capture of a communications session) the text files will contain hex "1A" characters, either as a result of the closing of the communications session or as the result of noisy communications lines. (It would be nice if the communications program would make sure these don't find their way into capture files, but many communications programs are evidently not that clever). This is serious only because DOS takes those characters to indicate the end of the file. Many DOS utilities, including many of those in this package, will stop processing their input file upon reaching a hex "1A" character, and anything occurring after that (which might include a subsequent communications session) can get lost in the process. Although such lost capture data can usually be recovered (if you notice it often enough) using the EXTEND utility (described elsewhere in this package), the safer alternative is to process files prone to contain such erroneous characters, and remove them, prior to handling the files with other programs. DELIEOF is an interactive program which allows you to search for internal EOF mark characters that might be placed in a text file. Upon finding each one, DELIEOF gives the operator the choice of whether to retain it, replace it with an ASCII space, or exit the program. A command line option allows the operator to pre-answer all the questions for a session, if desired. WARNING: Executable or other binary files will often happen to contain hex "1A" characters as instructions or other binary data. Such files, if processed by DELIEOF, can be irreparably damaged. Use DELIEOF only on files which contain editable ASCII text data. To use the DELIEOF utility program, use a command line of the form: snorun delieof <iooptions>[;<options>] page 48 <iooptions>:: /4=<filespec> or /4:<filespec> This option allows specification of the disk file which is to be searched for internal end-of-file mark characters. Make certain that any file specified be an EDITABLE ASCII TEXT FILE. Other types of files, especially .EXE or .COM files, can be damaged irreparably by DELIEOF. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. NOTE: This option should normally only be used if the /Y or /N option is specified, see below. <options>:: /Y This option allows the processing of the specified file without further operator intervention. All hex "1A" bytes found in the file will be changed to ASCII spaces. This option may appear in either upper or lower case, but note that the semicolon before the option on the command line IS important. /N This option allows the processing of the specified file without further operator intervention. All hex "1A" bytes found in the file will be commented on but left "as is". The file will not be changed. This option may appear in either upper or lower case, but note that the semicolon before the option on the command line IS important. page 49 Some typical DELIEOF command lines might look like: snorun delieof /4:cpsv0101.txt ;/y snorun delieof /4=e:\tempdir\capture.txt page 50 16. DIFFER -- FIND DIFFERENCES IN TWO TEXT FILES This utility program compares two text files and indicates how many areas in the file have been changed. A report is produced to compare the changed areas. The program is basically the work of P.R. Tallett, Datacall Ltd, Kirkstall Rd., Leeds, England. It has been elaborated somewhat by A. P. McCann. Inclusion of line numbers and slight rework for the IBM PC version has been done by David Shields and Robert Dewar. Several bugs in command line scanning and end-of-file handling have been corrected by Gordon Peterson II. The program is invoked by a command line of the form: differ <file1> <file2> <outfile> [<options>] The first two file specs define the two input files to be compared, and these two must be present. The third file spec, if present, defines where the output file is to go. This can be either a disk file or a device (such as CON, PRN, or LPTn). If no output file is specified, the console is assumed. (Note that if the /W format is being routed to the console, it is much more readable if /W39 is specified). <options>:: /M This option forces blank lines to match in compared files. The default is that blank lines are ignored during the matching process. /L[n][+] This option specifies that "n" lines must be found identical before the program can assume the files are again in parallel. The default is 3. If the + is found, then the listing includes the n lines which were the same. The default is that only the first such line matching gets included in the listing. page 51 /Rc Normally, any character found in either input file less than 20H is replaced by a "?" character in the output report. If this option is specified, the character specified as "c" specifies an alternate replacement character to use instead. /X This option prevents the replacement of characters less than 20H in the output report. (They are retained and output as found in the input files). /W[n][-] This option specifies that a double column listing format is to be used. Use of this option is recommended. The first "n" characters of each line (one from file1, one from file2) are printed side by side, making the comparison easier. The total line length is 2n + 2 including the separator characters. Default is 65. The "-" sign, if present, reduces the length of the line of asterisks separating the blocks of different code. The "-" option, which might be useful on slow printers, is not really recommended. Example: To compare "OLDVER.TXT" with "NEWVER.TXT" and print a file of the changes, the suggested command line would be: differ oldver.txt newver.txt prn /W page 52 17. DIRCMP2 -- COMPARE FILES IN DIFFERENT SUBDIRECTORIES This utility program allows comparing the files within specified directories. The directories may be on the same or different disk volumes, and may also be network volumes running within, for example, PC network. The program is invoked with a command line of the form: snorun dircmp2 [<iooptions>];CMDFILE=<cmdfile>[,BATFILE=<outputfile>] <iooptions>:: ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. The CMDFILE contains entries of the form: MATCH C:\,D:\ MATCH D:\ASM\SRCPROG F:\ASM\SRCPROG MATCH D:\PROG, D:\PROG\BACKUP Each of these entries define a pair of subdirectories (and the drives on which they are located) which are to be compared. NOTE: In version 1.01 of DIRCMP2, the command lines must be in upper case as shown. In later versions, these command file lines are case-insensitive. The separator between the two subdirectories may include an optional comma, followed by zero or more spaces, as long as some such separator obviously divides the two subdirectories. ASCII tab characters are also legal; they are treated as spaces. page 53 There are three output streams from the program: Display output (written to SCREEN) includes progress messages which are displayed on the screen as each new directory is read from the specified drive. This output stream cannot normally be redirected. Standard output (written to OUTPUT) includes an echo of each entered command received. This is followed by a listing of all files in the two subdirectories which are of different age or size, as well as those which are missing from one or the other of the directories. Note that the program will not process MATCH commands where one or the other of the two subdirectories is missing or contains no files (and lower- level subdirectories do not count as a file for the purpose of this test!) This stream is normally redirected (see the discussion of I/O options above) to either the printer or an output file for subsequent analysis. Batch output (written if the BATFILE= option is specified) consists of a batch file which includes COPY commands which update older versions of files from the newer versions, and copies over files which previously were missing from one or the other of the corresponding subdirectories. DIRCMP2 is a very useful tool for maintaining, for example, a series of subdirectories which include files being maintained by separate programmers. It also is very useful if a programmer is maintaining a file server subdirectory, but updates his own personal copy on his own machine and then periodically wants to update the later versions to the generally-available copies on the file server. Another good use for DIRCMP2 is when one receives a software update for some package, and is interested in finding out which of the many files on the update disk are unchanged from the previous version. page 54 18. DIRTREE -- MAKE FILE OF SUBDIRECTORIES PRESENT This utility program allows listing subdirectory information on either an entire volume or within any specified subdirectory of a volume. All options may be entered in either upper or lower case. The output file may be redirected in the same way one would redirect any other output file produced via SNORUN. The program works fine on local drives, or on remote drives under many available networking systems. This is not true for commercially available programs such as PCTOOLS or Norton Utilities, which will not generally work on network drives. The TREE option (described below) assumes that your output device (normally the display or printer) supports the IBM extended ASCII character set (specifically, the line-drawing graphics characters). snorun dirtree [<iooptions>][;<options>] <iooptions>:: /6=<outputspec> This option allows putting the output of DIRTREE to a disk file or to the printer. Either the equal sign (as shown) or a colon are equally valid delimiters for this option. Example command lines are: snorun dirtree /6=lpt1: ;path=c: snorun dirtree /6=c:\prt\mydirs.prt ;path=d: ><outputspec> The output of DIRTREE may also be routed to a disk file or a device by simple redirection. Example command lines are: snorun dirtree >mydirs.prt ;path=d: list >><outputspec> The output of DIRTREE may be appended to a disk file. To create a disk file containing the listings of all valid paths for hard drives C: and D:, the command lines might be: snorun dirtree >mydirs.txt ;path=c: list snorun dirtree >>mydirs.txt ;path=d: list page 55 <options>:: path=<pathname> or /p=<pathname> This option allows specification of the path name to be used for the subdirectory lookup. Example pathnames are: c: a:ms* d:ms?as* etc. The default path name is "\". As in the output file options, you may use either a "=" or a ":" in the option specification, whichever you prefer. /dpo This option causes no subdirectory scanning, but merely displays the effective path name that would be used for the lookup. list or /l This option causes all subdirectories to be written to the output file. They are output as FULL PATH NAMES, in sorted, interleaved sequence. indent or /i This option causes all subdirectories to be written to the output file. They are output as FULL PATH NAMES, in sorted, interleaved sequence, just as for the "list" form, except that nested subdirectories are indented. stair or step or /s This option causes all subdirectories to be written to the output file. They are output, one subdirectory to a line (with higher levels of each path name suppressed), in sorted, interleaved sequence. The left end of each nested subdirectory is lined up under the right hand end of the name of the containing (sub)- directory above. page 56 tree or /t This option causes all subdirectories to be written to the output file in the style used by PCTOOLS, except in a continuous format (PCTOOLS displays them one screenful at a time, making it incon- venient to print them). nohdr or /nh This option suppresses the heading from being written to the output file. The heading contains the path name used, the date and time, and the volume name (unless suppressed). novol or /nv This option suppresses the volume name from being accessed. If not suppressed, the volume name is read and placed in the heading (which could also be suppressed). /lej This option causes a page eject to be sent to the output at the beginning of the output. The mnemonic means "leading page eject". /tej This option causes a page eject to be sent to the output at the end of the output. The mnemonic means "trailing page eject". page 57 19. EXPTAB -- TAB CHARACTER EXPANSION This utility program expands the tab characters found in its input file to the appropriate number of ASCII space characters. A command line option allows the user to specify how many columns wide each tab zone is to be. The command line values (including the options) are not case-sensitive. If no explicit tab zone width is specified, EXPTAB assumes the normal DOS eight-character-wide zones. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. It also should be pointed out that the program automatically deletes trailing spaces at the end of each record, and that input records are assumed to be less than 4000 characters long. The program is invoked with a command line of the form: snorun exptab [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> page 58 This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /t<number> or /T<number> This option specifies how many characters wide the tab zones are to be. If this option is not specified, the default is the same as DOS uses, which is eight. You may use a ":" or "=" between the "T" and the number if you prefer. NOTE: Even if you want the default eight-character-wide tab zones, specifying the option (or at least the semicolon) will suppress the help message from being displayed when the program runs. Example command lines would look like: snorun exptab <infile.txt >outfile.txt ;/T7 snorun exptab <c:\mixfile.txt >c:\retabbed\mixfile.txt ;/T=9 snorun exptab /5=d:\insd\tempfile.asm /6:c:\outsd\tempfile.asm; page 59 20. EXTEND -- EXTEND A FILE (RECOVER LOST DATA) When MS-DOS appends to the end of a file, it writes the information being appended into an area of the disk which is in something of a "limbo" state. It is the intention of MS-DOS to make this information a part of the file being appended to; however, the actual change to the file being appended to is postponed until the file is finally closed. Actually, even when you are writing to a completely new file, MS-DOS treats it as if you had created an empty file, and then started appending to it. You've probably found files on your disk that are zero bytes long. These are usually files that have been created, often even written to, but then not closed before the system went down. Imagine, for example, that you are online to some communications service, perhaps doing a database search. The entire session is being faithfully recorded by your favorite communications program, and as the desired information is received by your system, it is reassuring to see the hard disk "blink" at you periodically as the data you have been seeking is recorded on disk. After several lengthy (and costly!) hours, it is time to log off of the service and start your offline examination of the information you've found. But, Murphy's Law strikes, and some gremlin in your system causes your computer to die just as you're trying to get back to MS-DOS. After rebooting, you discover that all of the information you've been downloading has evaporated. If this has never happened to you, consider yourself lucky (so far). If it has, I'll bet you wished you had a program like EXTEND. The frustrating part about problems like this is that the data you've lost is there, on your hard disk, the whole time. If you've got a good disk dump program, you can even go and look at it, and see it there, staring forlornly back at you. Fortunately, MS-DOS usually thinks that the area of the disk that your "lost" data is stored in is still unused (this means that page 60 the disk sectors themselves are not "lost", as a rule). The next time that a program asks MS-DOS for disk space, they'll probably get the same sectors that you've written your valuable data into. What you need, then, is just a way to tell MS-DOS to take some of its free disk sectors, (including... cross your fingers... the ones containing your missing data) and stick them on to the end of the file you originally wanted them written into to begin with. This is just what EXTEND does. It is important, after such a loss of information, that nothing be written to the disk in question until you've retrieved your lost data: anything else written to the same drive will quite likely overwrite the stuff you're trying to recover. You will need to have some vague idea of how much stuff you've lost, because you'll need to tell EXTEND how much of the free space on your disk you want to "corral" and add to your existing file. If you're not sure, just specify extra, to be safe. Always specify more, rather than less. It is easy to release the excess later. After you've recovered the lost data, it is a good idea to examine your file with a file listing or dumping utility (my FILEDUMP is not a bad choice, although Vernon Buerg's excellent LIST utility is ideal for this use, especially in its hexadecimal mode). This will show you the data you've recovered, along with any other random junk that MS-DOS may have given you. Once you've found the byte location of the last of the useful stuff you want to retain, you're ready to use TRUNCATE, described later in this User's Guide, to give the rest of the real garbage back to MS-DOS. This utility is (hopefully!) not something you'll need to use often, but when you do need it, you'll need it BAD. Depending upon what your system was doing when it went down, it MAY have invalidated other system tables on the disk. It is usually a good idea to run CHKDSK on the drive in question before running EXTEND. Letting it correct any problems it finds (see your DOS User's Manual for details) will usually not interfere with your recovering your lost data using EXTEND. page 61 Note that some systems treat their disk files in unusual ways, and in such cases the data may not have physically been written to the disk before the system went down. But, typically, if you saw the data being written, EXTEND will get it back for you. There are, of course, no guarantees. To use the EXTEND program, the command line looks like: snorun extend <iooptions> ;<options> <iooptions>:: /2=<file> or /2:<file> This item allows specification of the file to which the "lost" data is to be appended. Usually, best results are obtained if this is the same as the data the file was originally being written to. However, if necessary, you can append the data to another file, as long as it is on the same physical disk. Note that if you append to a different file, you are likely to lose as much as one full cluster of your "lost" data... this is the portion that was written between the "logical" end of file and the end of the dos cluster (the cluster is MS-DOS's unit of disk space allocation). NOTE that EXTEND uses unit 2 rather than the customary unit 5. The purpose of the change is to enable EXTEND to extend binary files. NOTE: Although EXTEND will extend files of any type, the odds of getting your data back in some semblance of its former self is much better for simple text files. <options>:: /=filesize or /=filesizeH This option specifies that the file is to be extended until it is "filesize" bytes long. If "filesize" is followed immediately by an H (upper or lower case, EXTEND doesn't care), then the filesize is assumed to be in hexadecimal. If "filesize" is not followed by an H, then the value is assumed to be in decimal. page 62 This numeric value specifies the size you want to make the file. The amount of data that will be found on the disk and added to your file is equal to the size specified with this option MINUS the current size of the file. Note that this option MUST BE SPECIFIED. Also, don't forget the ";" between the file spec and the file size option, it is important. Typical command lines might look like: snorun extend /2:comm.cap ;/=734512 -or- snorun extend /2:c:\importnt.vry ;/=34A7Bh page 63 21. FILEDUMP -- HEXADECIMAL FILE DUMP It is sometimes useful to be able to carefully examine a file on a detailed, record-by-record basis. When this is necessary, there are few tools as handy as a program to dump the records of the file in hexadecimal and printable ASCII characters. FILEDUMP will dump the file either as logical records or as physical sectors. This program dumps each record of the input file separately, with its record number and length. NOTE: FILEDUMP limits records in the input file to no more than 4000 bytes each, and deletes trailing ASCII spaces from each record before computing its length (which therefore does not include existing trailing spaces, if any) or the dumping of the record to the output file. (If the file is dumped in physical sector mode, each 512-byte sector is dumped individually and no trailing spaces are deleted). Each record is then dumped to hexadecimal and printable ASCII characters. All ASCII characters between 020H (ASCII space) up to 07EH (just below ASCII DEL) are output as is. All others are converted to a "." character. Note that no expansion of tab characters, if any, takes place in the input records: TAB characters are treated like any other. The current version of the program formats its output records such that they can be shown on an 80-column display, or printed on an 80- column wide printer in non-condensed mode. To use the FILEDUMP utility, the command line looks like: snorun filedump <iooptions>[;<options>] <iooptions>:: /2=<inputfile> or /2:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. NOTE that FILEDUMP uses unit 2 rather than the customary unit 5. The purpose of the change is to enable FILEDUMP to support an optional sector mode, which requires binary access to the input file. page 64 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /S or /s This option specifies that the file is to be dumped in sector mode rather than in record mode. When the file is dumped in sector mode, the file is accessed as a binary file and all 256 possible characters are permitted in each sector. In this mode, no trailing space suppression takes place. All sectors (except for the usually only partially used last sector of each file) are 512 bytes long. page 65 22. FMTHDLL -- FORMAT HARD DISK, LOW LEVEL This program is used to perform a low-level format of the hard disk drive on XT- and AT-compatible computers. It performs basically the same function as that performed by the program supplied on the IBM XT or AT Advanced Diagnostics diskette. Often, this low-level format operation will have already been performed on a new hard drive by either the manufacturer or your dealer before you receive the drive. If you have just received and installed a new hard drive, however, and the drive doesn't seem to work at all, it might well need to be low-level formatted. Typical symptoms include the system taking a long time to boot, even from diskette, often eventually giving an error message about some kind of a hard disk failure. If you are certain that you've never written anything on the hard drive, you've got nothing to lose by performing a low-level format on it, so it's certainly worth a try! Another case where a hard drive might need to have a low-level format performed is the case where the drive had been previously formatted using a different type of hard disk controller. For example, a drive which had previously been used on an XT-compatible using an RLL-type controller and which is now to be used on an AT-compatible using a non-RLL-type disk controller will have to be low-level formatted again, using the new non-RLL-type controller. WARNING: Do NOT assume that the low-level format operation CONVERTS RLL-type formatted drives leaving their contents intact. After a low-level format the drive will be EMPTY. You can think of the low-level format operation as being like that performed during an early stage of creating a housing subdivision. When the surveyors go through the future streets-to-be, measuring the size of each lot, driving stakes and posting little signs indicating the "street number" of each lot, they are performing a "low-level format" by identifying the exact location where each home will eventually be built, and what its house number will be. page 66 Similarly, the low-level format operation writes "markers" on the disk indicating where every sector of every track of every cylinder will eventually be written, and what the exact address of each one will be. During the operation, blank data sectors are also written following each "marker". This implies that the entire disk is overwritten, and data that had previously been written on it, if any, IS NOT RECOVERABLE, even by programs which claim to "unformat" a hard drive. The program is interactive and basically self-explanatory. The only information the operator needs to know (and respond when asked) is which hard drive is to be low-level-formatted, either the primary one (unit 0, which is usually drive C:) or the secondary one (unit 1, which is usually drive D:). You may be interested to know that, unlike most of the other utilities described in this document, FMTHDLL is written in assembly language. IF YOU HAVE AN AT-COMPATIBLE: Before using FMTHDLL, you need to run SETUP on your computer (on many AT-compatibles, this can be done without a diskette, since the SETUP function is often contained in the BIOS ROM and can be accessed during the power-on-self-test procedure) to tell the AT what type of hard disk drive you have. This is important because FMTHDLL asks the AT's BIOS what the characteristics are of your hard drive, such as the number of cylinders and heads the drive contains. IF YOU HAVE AN XT-COMPATIBLE: Before using FMTHDLL, you need to make sure that your controller is correctly set for the type of disk drive that you have attached. The way to do this will vary depending upon your specific controller, but often requires the setting of straps or a "DIP" switch. This is important because FMTHDLL asks the hard disk controller's BIOS what the characteristics are of your hard drive, such as the number of cylinders and heads the drive contains. The current version of FMTHDLL always formats disks using 17 sectors per track and an interleave factor of four. Note that this setting is usually okay for hard drives, unless you are using an RLL controller. RLL controllers allow one to put more than the "normal" amount of data on a disk, usually putting 25 or more sectors on each track. page 67 Also note that the current version of FMTHDLL does not accept the user entry of a "bad sector map". Therefore, it is a good idea after running FMTHDLL to also run a program (there are several fine ones available from various public domain distribution channels) to test the disk and lock out any sectors which may be marginal. To use the FMTHDLL utility, it is simply invoked on the command line: FMTHDLL After the FMTHDLL utility has completed, you need to perform several more steps before your hard disk is ready for use: 1. Use FDISK (on your DOS diskette) to create a DOS partition. Note that some versions of FDISK do not always seem to work successfully if you answer "Y" to the question "Use entire disk for DOS?". It seems to be more reliable if you answer "N", and then use the default responses to the partition size questions. After creating the DOS partition, be sure to set the DOS partition active before returning to DOS. (NOTE: Any disk partition modified using FDISK generally loses its entire contents in the process, and this loss is generally not reversible. FDISK is a very powerful utility, and deserves to be used with great respect.) 2. Run the DOS FORMAT command on your hard drive. The DOS format, unlike the low-level format, READS the entire hard disk (it does NOT overwrite it) and then writes the basic DOS tables onto the drive, such as the boot sector, the File Allocation Table, the root directory, and so forth. The DOS FORMAT command also confines itself to the DOS partition, as set previously by FDISK, and does not interfere with any other partitions that may be present on the same hard drive. NOTE: It is always better to be safe than sorry. Your DOS FORMAT command may differ. Be sure to check the relevant documentation before using any FORMAT command. 3. Usually the next step is to put a copy of DOS onto the drive using the DOS SYS command. Alternatively, you can ask DOS FORMAT to do this by specifying the /S option. page 68 Now your hard disk is ready for use. For more information on the use of the DOS FDISK and FORMAT commands, please refer to your DOS User's Manual. page 69 23. GENTBLS -- GENERATE PROGRAM SOURCE CODE TABLES A frequent problem for a programmer is to associate each of a series of textual messages with one or perhaps a range of numeric values. A typical example, given a numeric return code, is to look up the corresponding error message. The fact that there are many possible ways to arrange such a table, along with the desire to minimize the effort to handle ranges of return codes and still allow for easy program maintenance, usually results in a table storage and lookup method being chosen at an early stage of program design, and a corresponding lookup routine written for each such table. Subsequent changes to program requirements can often change the contents or the table lookup method of choice, but by this time there is usually an understandable reluctance to restructure the lookup table until "later when I have the time". The GENTBLS utility is designed to read a simplified text file which contains the (possibly range of) numeric value(s) that are to be associated with a given string of text, followed by the text itself. GENTBLS then produces a commented assembler language inclusion file, suitable for most 8088-family assemblers, which defines the text of each message, along with a complete lookup table to facilitate the conversion from return code to text message. The lookup table even generates commonly needed equates typically used by lookup routines (the length of each entry, a pointer past the last byte of the table, and the number of entries in the table). If a range of numeric values correspond to the same message, note that only one copy of the message text will be generated. A separate entry in the table will be generated for each of the values in the range. The table may be sparse; i.e. there may be many numeric values for which no corresponding entry appears in the table. Of course, the use of GENTBLS can be specified in a MAKE file, such that a change of the original, plain-text file can cause a subsequent MAKE to automatically regenerate the suitable inclusion file, re-assemble the relevant portions of the program, and re-link the resulting program. page 70 A single input file can specify lists of entries for several different tables to be generated by a single run of the GENTBLS program. If multiple tables are to be processed in a single input file, they should be separated by the "-GROUP" control statement (described in greater detail below). It is anticipated that future versions of this program will provide considerably enhanced capabilities, including support for generating tables suitable for lookup by other languages. Another strong possibility would be to allow the user to specify which of several different lookup strategies are to be used, with GENTBLS automatically modifying the structure and layout of the generated tables appropriately. It is intended that a future version also be able to produce, upon request, a fully documented lookup subroutine, customized based upon the particular programming language, lookup strategy, and table organization that is most appropriate to solving the given problem. Features such as this will ultimately help to bring a measure of DBMS-like storage structure independence to applications programs, without the serious run-time performance penalty or program maintenance costs usually associated with such flexibility. To use the GENTBLS utility, the command line looks like: snorun gentbls <iooptions> <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. The format of the input file is described below. ><outputfile> or >><outputfile> or page 71 /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. The input file consists of a series of lines of different types: 1. Comment lines. Any line in the input file which starts with an "*" in column 1 is considered to be a comment line and is discarded by GENTBLS. 2. Control commands. Any line with a "-" in column 1 is considered to be a control command. These provide information which GENTBLS uses in order to decide what kind of tables are to be produced. A. "-GROUP" control statements are used to specify that the end of one table's entries has been reached. The word GROUP is not case- sensitive. A "-GROUP" control statement is assumed at end of file, so it is not normally necessary to specify one there explicitly. If you are using multiple groups in a single input file, the "-GROUP" control statement is usually followed by a "-NAMES" control statement, (see below). The "-GROUP" control statement looks simply like: -GROUP B. "-NAMES" control statements are used to specify how the generated labels and text associated with the table are to be constructed. Like all control statements, the word "NAMES" is not case-sensitive. A "-NAMES" control statement must appear before the first table data record. page 72 The record looks like: -NAMES <ilpfx>,<tbllabel>[,<strpfx>] The fields are: <ilpfx> is the prefix to be used to generate the labels for individual text strings. The actual label consists of the specified prefix, followed by the decimal numeric lookup value. <tbllabel> is the name of the beginning of the lookup table which the program generates. This is also used as the first part of the names of the relevant equates which are generated corresponding to the table: ....S length of each entry, in number of bytes ....E offset past the last byte of the table ....N number of entries in the lookup table <strpfx> is a string which is appended to the beginning of each text message, followed by a ":" and a space. This field is optional. If no value for it is specified, then the text messages are not prefixed by a constant string. NOTE: It is not illegal to also have NAMES control statements embedded within the lines which define a single table. This can be useful if you wish to change the constant text prefix in mid-table. However, if this is done, it is strongly recommended that the values of the other fields on the NAMES command line not be changed from their value at the beginning of the given table. 3. Table data records. Any line which is neither a comment line nor a control command is assumed to be a table data record. These records simply consist of a numeric value, followed by a comma, followed by the text of the corresponding message. page 73 The number is assumed be hexadecimal if it is terminated with an "X" or an "H" (and these are case-insensitive), or if it contains any of the characters "A" through "F" (also case-insensitive). Otherwise, it is assumed to be decimal. Note that, if you have a constant prefix which you wish to appear at the beginning of each message, you can also specify that on the NAMES control statement (see above) and need not key it manually at the beginning of each line of text. Typical table data records might be: 0,Normal completion 1f,Name table is full f0-ff,Fatal internal error The easiest way to figure out how GENTBLS works is to look at a specific example. The GENTBLS utility should be accompanied by an example text file called "GENTBLS.SMP", which shows two tables. The first is a list of error messages corresponding to various return codes provided by the IBM PC Network Adapter's NETBIOS routines. The second table is a much simpler one which shows messages corresponding to a simple trio of hypothetical return codes. To generate the assembly language inclusion file corresponding to this sample pair of tables, key in the command line: snorun gentbls /5:gentbls.smp /6:gentbls.asm Then use your favorite file listing program to examine the input and output files, and you will appreciate how much work the use of a tool such as GENTBLS can truly save. page 74 24. LASERPG -- MULTIPAGE OUTPUT TO LANDSCAPE MODE PRINTER This program is useful if you have a printer able to print landscape mode pages each of which can contain two printed pages. (Many laser printers and some wide-carriage dot matrix printers can do this well). LASERPG will scan through your print file, (which should not contain escape sequences, tab characters, or the like, but should contain page ejects at the start of each new page) and will then print the document, two pages per physical sheet. The order in which the pages are printed is such that one can take the resulting stack of paper, cut the sheets in half, stack the two halves on top of each other, and the document is ready for binding. Note that the commands to put a printer into landscape mode, and compressed print mode, vary widely. LASERPG does not attempt to do this. You need to ensure that the printer is in the desired mode before you run LASERPG. To bring up LASERPG, the command line is of the form: snorun laserpg <ioptions> <iooptions>:: /5=<inputfile> or /5:<inputfile> This item allows specification of a file from which the input file is to be read. Note that since LASERPG reads the file twice, this file must be repositionable (i.e. don't use "standard input", the console, or any non-repositionable device). The file should contain page ejects at the start of each page, but should not contain escape sequences, backspace characters, or other embedded control information. It should not contain any tab characters either; expand them first using EXPTAB. ><outputfile> or /6=<outputfile> or page 75 /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. An example of a LASERPG command line might look like: snorun laserpg /5=c:\project\document.prt /6=lpt1 page 76 25. LINEAN1 -- SERIAL COMMUNICATIONS ANALYSIS AID This special-purpose program can be of help in analyzing communications line behavior. If one is looking at asynchronous hexadecimal characters arriving on a communications line, it is sometimes useful to know how the bit stream is actually being sent on the line. This allows one, for example, to look at the actual bit stream as it appears on the line and attempt to figure out why the data is not being received as expected. This program is generally not useful to persons without a fairly good low-level understanding of serial communications. However, for such persons this program can save a great deal of mechanical bit fiddling! To use LINEAN1, the command line would look like: snorun linean1 >lpt1 The program will prompt for the entry of strings of received hexadecimal bytes. It assumes that the hex bytes received represent asynchronous, eight bit data with no parity bit, one start bit and one stop bit. If you are entering a byte which was received with a framing error, follow the entry of its two hex digits with an "x". For example, a typical line you might enter could look like: 00,46x,3f,7ex,55x,02,42,47,5c You then have the option to enter a comment describing the conditions under which this data was observed, if you like. If not, just press the Enter key. This field, if entered, is simply printed as annotation on the output listing. The program will then compute the bit pattern that this would represent on the line and send it to the printer. In the output, the line time (which may be a non-integral number of bit times on asynchronous serial transmission) is represented by a "." character. (This period generally represents zero or more non-start-bits). The hex character representing the bit pattern appears centered under its corresponding data bits. page 77 The program will also show the way the same data would appear on the line for eight-bit synchronous format as well. (Because of the nature of this program and the complexity of the topic it deals with, the author would rather not enter into lengthy correspondence about the use of this program or interpretation of its output). I've considered simply removing it from the Utilities but have decided for the time being to leave it in, since it is unusual and might be useful or interesting to somebody out there. page 78 26. LIST -- (YES, ANOTHER) TEXT FILE LISTER This utility program allows listing a text file with a variety of options. Note that you may have LIST in either of two forms, the SNOBOL4+ form (with the extension .SAV) or the SPITBOL form (with the extension .EXE). The command lines are slightly different between the two forms: If you have LIST.SAV, use the "snorun" form of the command line; if you have LIST.EXE, use the "list" form of the command line instead. snorun list ;<inputfile>[,<outputfile>][<options>] OR: list <inputfilespec>[,<outputfile>][<options>] <outputfile>:: This item specifies the name of a file to which output is to be written. If no file name is specified, default is to output to PRN: (the printer). <options>:: /f This option specifies that the file being listed is already in print file format. No headings are added, and no numbering of lines is done. The file is assumed to contain no tab characters. /n<integer> This option allows specifying how many input record lines are to be printed on each page. The default is 55. /p This option causes a print file to be generated. This file is formatted for being output to a printer, including page headings. The extension defaults to ".LST" if none is specified. /q This option causes the output to be appended to the end of the output file, if it already exists. If the output file is empty or does not already exist, this option has no effect. page 79 /t<integer> This option causes any tab characters encountered to be expanded so that tabs occur every <integer> columns. The default is to tab every eight columns. /x This option causes numbering of the lines to be suppressed. The default is to number the input records. The first record number is 1. page 80 27. MAKASEQ -- DISASSEMBLY AID (USED WITH ASMGEN2) This program is generally used as a companion program to ASMGEN2, which is described earlier. However, it might also be desirable to use it individually on some occasions, so its separate usage will also be described. MAKASEQ reads through the disassembled source file produced by the public domain program ASMGEN and attempts to locate areas that look like character string constants or obvious data areas. It then creates a .SEQ file which can be used as input to a subsequent invocation of ASMGEN, which will yield a cleaner disassembled source file. MAKASEQ version 1.0 can only process object files which are less than 32K bytes in size. Starting with version 1.1 of MAKASEQ, it can now process 64K byte object files. This is also a limitation of the public- domain ASMGEN program. If an object file exceeding 64K bytes in size is given, MAKASEQ does not bomb, but merely does not process (or make .SEQ file entries for) that part of the program past 64K. If the output from ASMGEN is in a file named JUNK.ASM (note that the extension must be .ASM), then the command line to execute MAKASEQ and create the file JUNK.SEQ would look like: makaseq junk Upon completion, you might want to examine the .SEQ file (use LIST or your favorite file listing utility). It will indicate where each apparently separate character string constant begins, and includes the first portion (if long) of that constant. It also indicates where obvious data areas (those containing blocks of binary zeros or hex "FF") begin. The basic format of each output line is: addr type [;string] where: addr is the hexadecimal starting address of the memory area found, page 81 type is the apparent type of the area: B data bytes C code S character string constant string is the beginning portion of the character string constant in the area described. Note: MAKASEQ expects to see a "raw" file from ASMGEN, i.e. one generated in the absence of a .SEQ file. If you already have a .SEQ file for the indicated executable file, rename or delete the .SEQ file before generating the .ASM file which MAKASEQ is to process. page 82 28. MAKDUMMY -- MAKE DUMMY FILES FOR ARC'D FILES This utility program generates dummy files on a diskette with the same names as the corresponding files in a ".ARC" archive file. The shareware utilities ARC and PKARC are extremely useful for compressing a number of files down into a much smaller single file that can be stored (and transported) easily on a single diskette. The only problem is that diskette cataloguing programs (such as the shareware DBS-KAT system) will then catalog the ".ARC" file but not the individual files therein. This means possibly hunting through a large number of diskettes, each having a big (and very opaque) ".ARC" file on it, to find the ones that have copies of the file(s) you are looking for. What MAKDUMMY does is to create dummy files, usually on the same diskette as the ".ARC" file, of the same names as the files that are archived. Each dummy file simply contains a text record which directs the reader's attention to the ".ARC" file, giving its name, in which the correspondingly-named file can be found. If the diskette gets too full to write the dummy files, MAKDUMMY will continue to write directory entries (for empty files) having the appropriate names as long as space remains in the directory to hold the file name entries. Assume that you are using MAKDUMMY to make dummy files for the archive file named "TEST.ARC" on diskette drive A. You will need to have the SNORUN run-time package somewhere within your environment's PATH, of course. You must also have the PKARC utility (early versions of MAKDUMMY used ARC 5.12 instead) also accessible. You should be in the subdirectory where your archive file exists. Unless the MAKDUMMY.SAV file is in that same place (which is unlikely), you will need to include a path name so that SNORUN can find it. The command line to run MAKDUMMY, in general, would look like (you may use either upper or lower case as you wish): snorun c:makdummy;<arcfile>,<drivespec> OR FOR EXAMPLE: snorun c:makdummy;myfiles,a: <arcfile>:: This item specifies the name of the archive file which contains the members you want to create dummy files for. This file must page 83 have the extension ".ARC". You need not specify the extension on the command line (".ARC" is supplied by default). <drivespec>:: This item specifies the drive spec on which the dummy files are to be created. Note that the comma between <arcfile> and <drivespec> is optional. You may in fact use a comma or any combination of ASCII blanks and tab characters. However, the drive spec must be terminated with the colon as shown. page 84 29. MAKEALL -- CONVERT A MAKE FILE TO "ALL" BATCH FILE The original idea for a MAKE utility apparently originated somewhere deep in Bell Labs, and I believe was generated for use with UNIX and related software. Unlike many simple programs, complex systems of software (especially those comprising many different modules, multiple inclusions, different languages which must be combined, and the like) often require a very carefully choreographed (and often delicate) sequence of operations to prepare before the software is ready for testing, use, or distribution. MAKE is an attempt to allow the programmer to define (once, in theory) which modules depend upon which others, so that the system can decide for itself just which of the steps are necessary to repeat following some program modification. The MAKE utility then carries out only those steps of the entire procedure which are necessitated by the changes it figures out have been made. It judges that a module (which it refers to as the "target" file) needs to be remade if it is older than one or more of the other files which it depends on (these other files are hence called "dependent" files). It is outside the scope of this document to fully describe the usage of the normal MAKE command and the format of a MAKE file. This is fully described in the document accompanying Microsoft MAKE (or Borland MAKE) and will not be repeated here. It is assumed that the reader is familiar with the basic concepts of the MAKE utility. It occasionally turns out that you need to reperform more parts of your system generation process than you had originally planned, (a modification to your make file itself, for example, often suggests a major regeneration and the make file itself is rarely included in the list of dependent files for a given target) and it is sometimes difficult to get MAKE to do things that you really do want it to do, regardless of what the file date stamps say. This utility program reads a MAKE file and converts it to a batch file which will perform all the steps, regardless of the date and time stamp on each of the originally specified target files. page 85 The version of MAKE supported by this utility is the current version of Microsoft MAKE (my copy is version 4.02). It is believed, but cannot be promised, that MAKEALL will work for other versions of MAKE as well... such things tend to be reasonably standardized. Converting a MAKE file to a batch file has several consequences. Among these are the fact that batch files do not understand the inference rules or the macro substitutions supported by MAKE. Therefore, MAKEALL has to expand both the macros and the inference rules. The current version has a few minor implementation restrictions which mean it is not quite like Microsoft MAKE: 1. MAKE's command line options are not supported (but macros MAY have their values defined on the command line). Macro replacement values which are defined on the command line override any values which may appear in the make file, even if the macro replacement item is redefined in the make file several times. 2. Reading of inference rules from TOOLS.INI is not supported. 3. I have decided to not duplicate in MAKEALL the numerous bugs that are present in Microsoft MAKE. These include bugs regarding the handling of comment lines and the handling of inference rules when the target file is outside of the current subdirectory. 4. I have decided to follow Borland's example and treat a "#" and everything after it on each input line as a comment, even on command lines. This implies that one cannot use MAKEALL to generate a command line which contains a "#" character. (Microsoft avoids this problem by requiring that the "#" be the first character on a command line in order to be taken as a comment... but then, they don't handle such comment lines correctly anyhow). The current version, however, includes several enhancements not supported by Microsoft MAKE. Some of these are taken from Borland's MAKE. page 86 1. The macro replacement item "$<" is replaced with the full target name, including path and extension. 2. The macro replacment item "$:" is replaced with the target's path (only), not including the file name itself or extension. 3. The macro replacement item "$." is replaced with the target's file name and extension, not including the path. 4. The macro replacement item "$&" is replaced with the target's file name (only), not including the path or extension. 5. Note that the macro replacement item "$**" is replaced by the complete list of dependent files, like in Microsoft MAKE (but this feature is not supported by Borland's MAKE). 6. Note also that Microsoft and Borland disagree on the meaning of the "$*" macro replacement operator. Borland considers that this is replaced with the target file's path and filename (but not extension), while Microsoft considers that the "$*" should be replaced with the filename only (neither path nor extension). Since Borland's MAKE provides an operator ("$&") which works like Microsoft's "$*", I've decided to make "$*" work according to either Borland's convention or Microsoft's, according to a command line option. 7. Trying to use the "$**" replacement item (which in Microsoft's MAKE is replaced by a list of the dependent files) within the dependent file list itself generates an error message and causes the related command block to be skipped. 8. MAKEALL is smart enough to not go into a hard loop if looping or recursive macro replacement items are defined. MAKEALL will only perform 100 macro replacements on any given line, and then it simply continues and processes the line as it is at the point when it gives up. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. page 87 It also should be pointed out that the program automatically deletes trailing spaces at the end of each record, and that input records are assumed to be less than 4000 characters long. NOTE: The fact that MAKEALL deletes trailing spaces at the end of each record can cause problems in certain cases. MAKE assumes that some characters (such as the "\") have special meanings if they are the very last character on a given line. If a programmer needs to have such a character as the last character on a line, a common trick to "fake out" MAKE is to put a space or something after the special character so MAKE will ignore it. MAKEALL deletes this blank, so "caveat emptor". To use the MAKEALL program, the command line looks like: snorun makeall [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. By convention, MAKE files usually have blank extensions, but MAKEALL doesn't care if you follow the convention or not. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. I suggest that the extension for output files from MAKEALL use either ".ALL" or ".BAT", but you are free to choose other conventions if you prefer. page 88 <options>:: /borl This option causes the "$*" macro replacment item to be replaced by the target file's path name AND file name (but not extension). If this option is not specified, the "$*" macro replacement item is replaced by the target file's file name (only), including neither the path name nor extension, as per Microsoft's convention. /cs This option makes macro replacement items case sensitive. If this option is specified, "name=replace" will not replace $(NAME). Note that the case sensitivity option does not affect inference rule extensions (these are always case insensitive, since DOS treats file names as case insensitive anyhow). It also does not affect the macros whose values are taken from MS-DOS environment variables. MS-DOS environment variable names are ALWAYS in upper case; using macro replacement items in lower case will ensure that they are never supplied from the MS-DOS environment variables. The default is that macro replacement items' names are not case-sensitive (they are in the default case converted internally to upper case by MAKEALL). /einp This option specifies that the input make file is to be echoed to the console as it is being read. This permits one to watch the input of make file lines and observe how each one is modified to batch file output records. This option can also be useful in tracking down discrepancies or problems during the MAKEALL process. /dirt This option causes the inference rules table (containing all the inference rules known to MAKEALL) to be dumped to the screen upon completion of reading the input make file. This is sometimes useful in trying to track down problems. /dmrt This option causes the table containing all known macro replacement items and their final values to be dumped to the screen upon completion of reading the input make file. NOTE: This table does NOT contain those values which have been specified on the command line, as these are kept in a different, higher-priority table. page 89 Example command lines would look like: snorun makeall <inmake >outmake.bat snorun makeall <c:\mymake.mak >c:\mymake.all snorun makeall /5=d:\source\payrsys /6:c:\source\payrsys.all;/einp page 90 30. MAKEMAKE -- BUILD A MAKE FILE BASED ON INCLUSIONS One of the other problems involved with using MAKE files is that one is rarely really certain that all the files upon which a given source module depends are included in its list of dependencies in its MAKE file. MAKEMAKE reads through a make file. For each MAKE file target/dependency line encountered, the first dependency item is presumed to be a source file (if its extension is either .SNO, .C, .ASM, or .H). This file is read, as are any inclusion files it requires, any inclusion files those require, and so forth. (NOTE: .ASM files are only processed if the /A option has been specified, see below). If you do not yet have a MAKE file for your programs, you may wish to use the separate MAKERMAK program, described below, which will construct a raw MAKE file from the entries it finds in one or more of your directories. The output file from MAKEMAKE is basically the same as the input make file, except that: 1) The new "dependency list" includes all referenced inclusion files, as well as all inclusions of inclusions, as well as any dependency files that were contained in the original make file; 2) The new "dependency list" will have the path names associated with inclusion files that have been located based on default paths (described below). When looking for inclusion files which do not contain an explicit drive or path specification, MAKEMAKE looks both in the "current directory" as well as in all the directories indicated by the enviroment strings "SNOLIB=", "INCLUDE=", and "LIB=" (as set up using the DOS "SET" command, see the MS-DOS User's Guide). If an inclusion request in a file contains any kind of a explicit path specification (either a drive specifier or a subdirectory name of any kind), then MAKEMAKE will not attempt to search other paths to find that inclusion file. page 91 WARNING: "current directory" above refers to the directory in which MAKEMAKE is being run, which may not be the same as the directory in which the "subject file", or the file it has included, is in. Although this could be changed in MAKEMAKE, note that most MAKE programs running through the same MAKE file would have the same problem! MAKEMAKE, if you use it in conjunction with the DRVSPKR Speaker Device Driver, will give a distinctive audible alert to notify you of any referenced inclusion files which MAKEMAKE is unable to find. MAKEMAKE will allow inclusion files to be nested to essentially arbitrary depth. It can handle continuation lines on the input MAKE file (lines can be up to 400 characters wide) and will generate continuation lines as appropriate to the output MAKE file. The current version of MAKEMAKE does not attempt to perform any macro substitutions, either when processing the dependency items from the input make file or when processing the INCLUDE statements in the source program files. MAKEMAKE also supports many different options which allow the user quite a bit of control over the degree of output produced by MAKEMAKE. See the options as described below for more details. All options may appear in either upper or lower case. Don't forget the semicolon which must precede any options you specify... it is important. If you are an international user of MAKEMAKE, note that MAKEMAKE will support the proper case conversion of your national character set if you specify the correct corresponding upper and lower case characters using the environment option as described elsewhere in this document. To use the MAKEMAKE utility program, the command line is of the form: snorun makemake [<iooptions>][;<options>] <iooptions>:: /5=<inputfile> or /5:<inputfile> page 92 This item allows specification of a file from which the input make file is to be read. This file contains lines in the "usual" MAKE file format (see the documentation of your MAKE program for more details). ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. It is usually a good idea to examine the output make file from MAKEMAKE, to ensure that MAKEMAKE has done what you intended, before you blindly try to use it! <options>:: /a This option causes MAKEMAKE to also scan .ASM source files. The support for .ASM source files has been made optional, since this form of source files requires more complex scanning and I didn't want to force SNOBOL4+ and C users to have to do the more complex scanning unless it was really required. /d This option causes MAKEMAKE to display the target and dependency file name, as it has parsed them off, to be displayed. Note that only the inclusions required for the FIRST DEPENDENCY ITEM SPECIFIED (which MAKEMAKE refers to as the Subject) will be searched by MAKEMAKE. /f This option causes MAKEMAKE to display messages on the screen page 93 telling the user exactly which files are being processed at all times. This output may be useful if MAKEMAKE is having trouble locating one or more inclusion files and the user would like additional information to figure out why this might be happening. /i This option causes MAKEMAKE to display a message on the console as it finds each request for an inclusion. The message includes the name of the file being read, and the name of the file which the inclusion has requested. /o This option causes the output target/dependency header (as written to the output make file) to also be echoed to the screen. This might be desirable if the user wishes to follow on the console the progress of the MAKEMAKE program. /p This option causes MAKEMAKE to display on the screen, at the start of execution, the total list of paths through which it will automatically search for inclusion files which do not contain a specific drive or path specification and which are not found in the current directory. /sa This option causes MAKEMAKE to summarize, after it has processed each MAKE file target/dependency item, the names of all the inclusions which have been referenced (both directly and indirectly). /sd This option causes MAKEMAKE to summarize, after it has processed each MAKE file target/dependency item, the names of all the inclusions which have been DIRECTLY referenced by the "subject" source file (the first dependency item in the group). /sk This option causes MAKEMAKE to summarize, when it has nearly completed execution, the names of all the source files and inclusion files which it has processed. page 94 Example command lines would look like: snorun makemake /5:inmake. /6=outmake.mak snorun makemake 5=c:\mymake.txt /6=c:\mymake2.txt ;/i /sa page 95 31. MAKERMAK -- BUILD A RAW MAKE FILE This is another useful utility if you use MAKE files for major projects. This utility will go through one (or more) subdirectories, find all the .ASM, .C, .SNO and .SPT programs, and automatically build a MAKE file to compile or assemble each of them to the corresponding .REL, .SAV, or .EXE files, as appropriate. The output of this program is suitable for input to the MAKEMAKE program, described earlier. (In fact, you can even "pipe" the output of MAKERMAK directly to MAKEMAKE... how to do this will be described a little later). Please see the warning in the description of the MAKEMAKE program, described earlier, regarding the context in which MAKEMAKE searches by default for any referenced inclusion files. The command line to invoke MAKERMAK is of the form: snorun makermak <iooptions>[;<options>] <iooptions>:: ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. It is usually a good idea to examine the output make file from MAKERMAK, to ensure that MAKERMAK has done what you intended, before you blindly try to use it! page 96 <options>:: path=<pathname> or /p=<pathname> This option allows specification of the path name to be used for the subdirectory and file lookup. Example pathnames are: c: a:ms* d:ms?as* etc. The default path name is "\". As in the output file options, you may use either a "=" or a ":" in the option specification, whichever you prefer. If you are only going to specify a subdirectory, and wish MAKERMAK to process all the files in that subdirectory, you should terminate the name of the subdirectory with a "\" character. For example, if you want to build a MAKE file to compile all the programs in your directory SNOPLUS, your path option might look like: /p=c:\snoplus\ Note that you can also specify the prefix part of a file name as well as the name of a subdirectory. In this case, MAKERMAK will find all files beginning with the given prefix part. If the pathname also matches a subdirectory name, then MAKERMAK will also operate on that subdirectory as well IF the "/R" option has been specified (see below). An example of using MAKERMAK to build a MAKE file for all ".C" files beginning with "CL" in a given subdirectory might be something like: snorun makermak /6:clc.mak ;path=c:\cprog\cl*.c This example would build a MAKE file to compile, for example, c:\cprog\clock.c c:\cprog\clearmem.c c:\cprog\clubroll.c /r This option causes MAKERMAK to also scan any lower-level subdirectories (and so on) corresponding to the path indicated. In this way, one could conceivably create a MAKE file which would assemble or compile, as appropriate, everything containined on an entire volume. page 97 NOTE: The use of this option, especially when using MAKERMAK in conjunction with MAKEMAKE, has a minor "trap" in that inclusion files that MAKEMAKE finds referenced will be assumed (first) to be in the same directory that MAKEMAKE is being run in, which may not be the same directory as the source file being read (the one that contains the inclusion) is in. This could be changed in a future version of MAKEMAKE; however, note that if you tried to run the resulting MAKE file from the same directory you were in when you built it, you would have the same problem finding the inclusions anyhow. If you have the DRVSPKR Speaker Device Driver installed, MAKEMAKE will give a distinctive audible warning for any referenced inclusion files it cannot find. NOTE: The output of MAKERMAK is suitable for input to the previously described MAKEMAKE program. The "piping" facility is described further in your MS-DOS User's Guide. However, just as an example, if you wanted to create a MAKE file for all the .C, .ASM, and .SNO programs contained in your entire tree of directories starting at C:\ASM, and wish at the same time for MAKEMAKE to find all their dependencies based upon any inclusions they might have, you could achieve this by use of the single command line: snorun makermak ;path=c:\asm\ /r | snorun makemake /6:hugemake. ;/a page 98 32. MELIZA -- PSYCHOANALYSIS PROGRAM (FAMOUS EARLY AI EFFORT) This is a version of the famous "ELIZA" psychoanalysis program, one of the earliest famous attempts at "artificial intelligence". Although this program is relatively straightforward, if the subject is persistent for a while, and attempts to converse seriously, the program can occasionally produce some rather startling insights and is sometimes terribly funny. (ELIZA is the happiest when you talk to her using complete sentences and don't ask too many questions.) This program has been around for quite some time, in many different forms. I don't know who the original authors were. The version described here is a consolidation of several SNOBOL4 efforts, apparently beginning with a version in the December 1970 issue of SIGPLAN, page 50, by Robert T. Duquet. This in turn was modified by Mike Alexander and Viktors Berstis, and finally by Gordon E. Peterson II. To start your appointment with ELIZA, simply enter the command line: snorun meliza and then take your place on the couch, and relax. The doctor will be with you shortly. page 99 33. MERGECMP -- MERGE WORD'S .CMP USER DICTIONARY FILES This utility program is especially useful if you use Microsoft WORD. Microsoft WORD's user spelling dictionaries are sequential text files which are used by the spelling checker. WORD version 2, although not documented (in classic Microsoft style!), keeps a default user dictionary under the name of "SPECIALS.CMP". When the user adds a word (not found in the normal dictionary) to his user dictionary, this is where WORD ordinarily places it. (Microsoft finally got around to documenting this feature, I am told, in version 3.) If you have several such .CMP files, and wish to combine them, the MERGECMP program will help you to do this. It takes two text files, sorted into ascending or descending sequence, and merges them into a single output file. Options allow you to decide how you want to handle records which are identical in both the two input files: you may output them both, or only once, or delete them entirely if you choose. Although this program was written specifically to process Microsoft WORD's user dictionary files, it can also merge any other combination of sorted text files, as long as the "sort key field" starts in the first byte of the record and continues for the duration of the record. Note that multiple identical input records within a SINGLE input file are not deleted by MERGECMP. Input records are assumed to be less than 4000 characters long. (This limit was 1000 characters for some earlier versions of this program). Any trailing spaces are removed from records processed by MERGECMP. Options can be entered in either upper or lower case, and are normally separated somehow. Also note that the entire input record is compared, starting with the first column. The command line to invoke MERGECMP looks like: snorun mergecmp;<inputfile1>,<inputfile2>,<outputfile>[,<options>] <inputfile1> page 100 <inputfile2> <outputfile>:: These are the file specifications for the two input files and the output file. They should adhere to normal MS-DOS file naming conventions. Path names are, of course, permitted. If no file extensions are supplied for any file, ".CMP" is assumed. If no output file is specified, it will default to the console. File specifications can be separated by commas or spaces. Note in particular, however, that all three file specifications must be present: it is not permissible to omit, say, inputfile2 and assume that the two commas are sufficient to indicate it as a null file. (Of course, this would be pointless on a merge program, anyway!). <options>:: /D This option specifies that the output file is to be produced in descending sequence. In this case, note that the input files supplied should also be sorted in descending sequence. If this option is not specified, ascending sequence is assumed, and in this case the input files should likewise be in ascending sequence. /B This option specifies that, in the event of the same record being found in both input files, both copies are to be written to the output file. The default, if neither the /B or /X option are specified, is to write identical input records to the output file only once. /X This option specifies that, in the event of the same record being found in both input files, neither copy is to be written to the output file. This provides an "XOR" type feature for sorted text files. The default, if neither the /B or /X option are specified, is to write identical input records to the output file only once. page 101 34. MSCRIBE -- DOCUMENT FORMATTING AND ENTRY PROGRAM This utility program is similar to the Datapoint MSCRIBE program. It reads in a simply formatted text file, and ends up producing a nicely formatted version of the documentation, according to a standard format. This is suitable for product specifications, user's guides, and such. MSCRIBE works in conjunction with the Borland program SUPERKEY and the word processing program WORDSTAR 2000+. The output macro files are kept smaller than 8K bytes, by segmenting them into multiple files (the extension of the macro file name is incremented for additional macro files, which are automatically linked). WORDSTAR 2000 should be con- figured to support document histories. Also, before running the "key" command below, it is assumed that a format file (same name as the input file, but with extension .FRM) exists for the document body, and that the format file MSCRIBET.FRM exists (which is used for the title page and preface). The final document is to be found in the resulting files with extensions .TIT, .TOC, and .BOD, which are then printed by WORDSTAR. Note that you may have MSCRIBE in either of two forms, the SNOBOL4+ form (with the extension .SAV) or the SPITBOL form (with the extension .EXE). The command lines are slightly different between the two forms: If you have MSCRIBE.SAV, use the "snorun" form of the command line; if you have MSCRIBE.EXE, use the "mscribe" form of the command line instead. snorun mscribe /5:<inputfilespec> /6:<macrofilespec> OR: mscribe /5:<inputfilespec> /6:<macrofilespec> key <macrofilespec> /ml The input file contains text with embedded formatting commands. These commands are all beginning in column one of their record. Within the input file, the following formatting commands are used: +m1 <projectname> This command furnishes the project name for the document. +m2 <title> This command furnishes the title of the document. page 102 +m3 <documenttype> This command furnishes the type of document ("User's Guide", "Prelimin- ary Specification", or the like). +m4 <date> This command supplies the version date of the document. +m5 This command indicates that the following text (beginning with the next record) is the Preface for the document. +m6 <docdescription> This command indicates the end of the Preface and supplies the name for the Body file (this is keyed into the Document History kept by Wordstar for the main part of the document). It also indicates where the Table of Contents is to be inserted. +m7 0. <chapterheading> This command supplies the heading for each chapter. The "0" is auto- matically replaced by MSCRIBE with the chapter number. +m8 0.0[[.0].0] <sectionheading> This command supplies the heading for each section, subsection, etc. The zeros are automatically replaced by MSCRIBE with the appropriate numbers for the given section, subsection, or sub-subsection. Four levels of section numbers are presently supported (more could be supported on request, but Wordstar 2000+ only supports four levels in its table of contents, hence the restriction). The number of zeros indicate the nesting level. +pp<n> (e.g. +pp0, +pp1, etc.) This command causes the text following to be the start of a new para- graph. You may start the new paragraph either on the following line or on the same line as the +pp<n>, as long as at least one space follows the command (and optional number). New paragraphs are automatically assumed after any +m<n> heading command which is followed by text. page 103 +sl<n> (e.g. +sl0, +sl1, etc.) This command causes the text following (beginning on the following line) to be the start of a new paragraph. You may start the new paragraph either on the following line or on the same line as the +sl<n>, as long as at least one space follows the command (and optional number). The only difference between this command and the +pp command is that using this command keeps the new paragraph from being indented. +turnoff This causes text following it to be ignored, including any +m<n> commands that might be encountered, until a +turnon command is encountered. page 104 35. OVER -- SHIFT A PRINT FILE OVER TO THE RIGHT This utility program is used to shift print files right by a specified number of columns. It is useful, for example, to get a listing of a program documentation file which can be put into a binder without the leftmost characters of each line becoming buried in the binding. If one or more nonprinting printer control characters are at the beginning of each record, they are kept at the beginning and the padding characters are inserted following those control characters. Note that this program, since it is compiled by the SPITBOL implementation of the SNOBOL4 language to produce a true .EXE file, does not use the SNORUN runtime module. To use the OVER utility, the command line is of the form: over <inputfilespec> <outputfilespec> [/n<integer>] <inputfilespec>:: file name and extension, with optional drive spec and/or path name, defining where the input is to come from. <outputfilespec>:: file name and extension, with optional drive spec and/or path name, or device name, where the output file is to be placed. It may also be written to a specified device. /n<integer>:: This option specifies by how many columns the input file is to be shifted to the right. The default is twenty columns. The option letter "n" may be either upper or lower case. Examples for this option would look like: /N16 /n7 Therefore, example command lines might be: over file1 file1ovr /n5 over a:docfile.txt c:\docfiles\over\docfileo.txt page 105 36. PADREC -- PAD RECORDS TO A FIXED SIZE This utility program copies the standard input file to the standard output file. While doing so, it converts all records to a fixed size. This fixed record size, specified, may be as large as 5000 characters. Each input record longer than the fixed size is truncated. Each input record shorter than the size indicated will have spaces added to the right-hand side of the record until it is the length desired. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. The program is invoked with a command line of the form: snorun padrec [<iooptions>];<options> <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. page 106 <options>:: /S=<recsize> This option specifies the fixed size of the records desired. The record size can contain embedded commas if you prefer: specifying "/S=2,048" is exactly the same as specifying "/S=2048". The option may be specified in upper case or lower case, and the delimiter between the "S" and the record size may be an "=", a ":", or may be omitted entirely if you prefer. /T=<tabwidth> or This option specifies that the input records may contain tab characters, and that, if so, they should be expanded before padding or truncating the record to the fixed size desired. If this option is specified, the output records will contain zero or more spaces where the tab characters had been in the input records. (Zero spaces would only apply at the end of the record if truncation had taken place). The option may be specified in upper or lower case, and the delimiter between the "T" and the tab column width may be an "=", a ":", or may be omitted entirely if you prefer. NOTE: If the "/T" option is not specified, any tab characters that might appear in the input records are treated as any ordinary character. If the "/T" option is specified, but no tab width is explicitly specified, tab characters will be expanded to the DOS default spacing (which is eight columns). A typical command line would look like: snorun padrec <infile.txt >outfile.txt;/s=325 page 107 37. PLAYCVMS -- SUPERKEY TO DRVSPKR FORMAT CONVERTER The shareware music editing and generation system "Pianoman", by Neil Rubenking, is capable of generating delightful music and melodies. It allows for interactively entering and editing these melodies, and can perform in up to four-part harmony on a standard PC-compatible. (The PIANOMAN software is by a different author, but may be available from the same place you got your shareware copy of these SNOBOL4+ utilities). My loudspeaker device driver makes it possible to "queue up" lengthy musical selections (or any sequence of tones, for that matter) and then proceed to do other things while they are produced. The PLAYCVMS utility provides part of a "gateway" between PIANOMAN and the DRVSPKR.SYS loudspeaker device driver. (The loudspeaker device driver is also available through many bulletin boards, users groups, CompuServe, all decent shareware diskette distributors, or directly from me if you prefer). A normal part of the PIANOMAN package is a conversion utility called PLAYRPNO. This utility can take PIANOMAN music files (which typically have extensions ".MUS") and convert these into ASCII text files suitable for loading by Borland's SUPERKEY utility (although larger musical selections typically don't work this way because they tend to exceed SUPERKEY's macro memory capacity). In any case, the PLAYCVMS utility can take these SUPERKEY macro files and convert them to the format suitable for use by the DRVSPKR.SYS loudspeaker device driver. NOTE: The PLAYRPNO utility generates a rather specific form of Superkey macro file. The PLAYCVMS utility has been tailored to this specific format. The output file from PLAYCVT (normally with extension .SPK, by convention) can be routed directly to the speaker (SPKR:) or can be saved in a disk file and copied to the speaker later, using COPY or any other program. page 108 Note that the speaker device driver is somewhat limited by its interrupt-driven mode of operation to a "granularity" of something like eighteen different tones (corresponding to "timer ticks") per second. On some PIANOMAN music, typically those with multiple voices and very rapidly changing notes, the PLAYCVMS utility has to slow the piece down by a factor of two or more to avoid losing notes. On single- voice selections, this problem rarely occurs. A special option to PLAYCVMS permits one to request that PLAYCVMS attempt to "shrink" excess slowness out of the piece by dropping every "n-th" (very) short note. This is most successful when the piece has multiple voices and the notes are typically rather long. It is less successful on rapidly moving pieces, where its "sampling" technique can result in the occasional loss of musically necessary notes. If in doubt, try it and see how the results are. Note that PLAYCVMS does not require you to give it the name of an output file. The SUPERKEY macro files generated by PLAYRPNO contain a "<TITLE>" phrase which PLAYCVMS uses to find the name of the macro file (it is generally has a ".mac" extension). PLAYCVMS uses the same name, only changing the extension to ".spk". To prevent confusion, PLAYCVMS displays the name of the output file it is writing to. To use the PLAYCVMS program, the command line format is: snorun playcvt <iooptions>[;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. <options>:: /s:<number> or /s=<number> page 109 This option allows requesting that the output file (the one formatted for the speaker device driver) be "shrunk" by dropping every "n-th" note, if and only if that is a "very short" note. Generally, for a good speedup and minimum loss of musically significant material, I suggest a value of one less than the number of voices present. In other words, for a four-voice musical selection, one might try specifying a command line like: snorun playcvms /5:mntpythn.mac /6:mntpythn.spk ;/s=3 Note that the option can be specified in either upper or lower case, and the separator may be either ":" or "=" (or omitted altogether, if you prefer something like "/S3"). /x This option specifies that the extra spaces normally added to the output file (separating notes from each other, for the sake of readability) be omitted to make the output file smaller. The file will play just the same as normal, but will be perhaps 15% smaller. Note that the option may be specified, as normal, in either upper or lower case. page 110 38. PLAYCVT -- PLAY FILE TO DRVSPKR FORMAT CONVERTER This utility program converts a file containing BASIC-format "PLAY" strings into a format suitable for the loudspeaker device driver DRVSPKR.SYS. The loudspeaker device driver is another shareware software product from this author. Many BASIC programs which play music can be relatively easily changed to write their "PLAY" strings to a file by changing their PLAY statements to PRINT statements. For example, the following statements in a BASIC program: PLAY "abc#" PLAY "o3deg" Could be changed to: OPEN "xxx.tun" FOR OUTPUT AS #1 PRINT #1,"abc#" PRINT #1,"o3deg" The resulting output file (in this case, "xxx.tun") would then be suitable for input to the PLAYCVT program. The output file from PLAYCVT (normally with extension .SPK, although this is simply a convention and does not represent a default) can be routed directly to the speaker (SPKR:) or can be saved in a disk file and copied to the speaker later, using COPY or any other program. Note that you need not use BASIC to generate a file in "PLAY string" format. This can be generated using any program you like (even an editor or the DOS COPY command can be used!). The actual format of PLAY strings is described in the relevant BASIC User's Guide and is outside the scope of this document. Input to the PLAYCVT program can come directly from another program using the MS-DOS "pipe" facility. See your DOS User's Guide for further information. page 111 Note that the BASIC "PLAY" facility, in all of its capabilities, requires a much more frequent and intensive use of your computer's resources than the DRVSPKR device driver does. As a result, some things with are possible with BASIC's "PLAY" command are not fully "do-able" by the speaker device driver. For example, the "music normal" and "music staccato" features of the BASIC "PLAY" command can only be supported by the speaker device driver on relatively long notes. This is because DRVSPKR has at most about eighteen "uses" of the processor per second. In each case, the PLAYCVT program attempts to come as close as DRVSPKR can to the intent of the original PLAY command. This coarser granularity also comes into play on very short or irregularly sized notes. Relatively subtle changes in tempo, note duration or the like which are below the resolution of DRVSPKR will generally not be translatable. Since the loudspeaker device driver is buffered and interrupt- driven, the "music foreground" and "music background" commands to the BASIC "play" statement are irrelevant to DRVSPKR and are discarded by PLAYCVT. A more serious problem concerns BASIC's ability to embed variables in its PLAY strings by variable name. Since those variables are of course long gone by the time PLAYCVT is running, it cannot replace such variables with their then-current string values. These embedded variable commands are not supported by PLAYCVT. These commands usually look like: Xa$; or =name; or some reference to VARPTR$(name) Such references in PLAY statements must be changed, either by manually inserting the variable's value or by dividing the PLAY string into several concatenated strings or possibly multiple PLAY statements. This is sometimes trivial, and sometimes a real pain. It's too bad that the design of BASIC incorporates such a screwball feature in a way so contrary to the design of the rest of the language. But, as in many things with BASIC, that's just the way it is. page 112 There is another program which I have used to aid in such conversions, which finds such items and replaces them with the last-seen string constants assigned to the variable each refers to. However, the program is not really general, since it reads the BASIC program sequentially rather than executing it, and I'm disinclined to offer it as part of this package of utilities. Typically, BASIC music programs (with some notable exceptions) are very straightforward and are amenable to such a simpleminded tool. If you are interested in the program (it's named PLAYREP), please contact me directly. At the end of the output file, the PLAYCVT program automatically sends commands to the speaker device driver to reset its parameters to their normal values (gap size, duration, and tempo) and also sends a suitable inter-selection pause of several seconds' duration. Version 1.1 of PLAYCVT has fixed a problem that caused the notes played to be one octave high, improved the timings (it was playing too fast), and added the IN= option (see below). To use the PLAYCVT program, the command line format is: snorun playcvt <iooptions>[;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. page 113 Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. By convention, the extension ".SPK" is used for files formatted for the speaker device driver. You can also use "SPKR" (or "SPKR:") as the output file name, in which case the output is sent directly to the loudspeaker and is not saved to disk. <options>:: IN=<filename> This option specifies the name of the input file (which must have an extension of .TUN) and the PLAYCVT program will put the output in a file of the same name and path but with extension .SPK (this option makes it easier to use PLAYCVT automatically from a batch file). The option may appear in upper or lower case. page 114 39. PMUSCVT -- PIANOMAN .MUS TO DRVSPKR FORMAT CONVERTER This utility program converts a Pianoman binary ".MUS" file into a format suitable for the loudspeaker device driver DRVSPKR.SYS. The loudspeaker device driver is another shareware software product from this author. One of the most spectacular features of the shareware Pianoman program is its ability to rapidly switch between several different frequencies, in effect "time-slicing" the PC's limited sound-generation capability, in order to produce a good simulation of multiple voices. Unfortunately, the low rate of MS-DOS timer interrupts prevents the Speaker Device Driver from playing more than about eighteen notes per second. In order to not miss any notes, this means that some multi- voiced Pianoman music files will play more slowly than usual. PMUSCVT will generally, however, play single-voiced music files very successfully and sometimes do surprisingly well on multi-voiced music files. The output from PMUSCVT (normally with extension .SPK, although this is simply a convention and does not represent a default) can be routed directly to the speaker (SPKR:) or can be saved in a disk file and copied to the speaker later, using COPY or any other program. At the end of the output file, the PMUSCVT program automatically sends commands to the speaker device driver to reset its parameters to their normal values (gap size, duration, and tempo) and also sends a suitable inter-selection pause of several seconds' duration. To use the PMUSCVT program, the command line format is: snorun pmuscvt <iooptions>[;<options>] <iooptions>:: /2=<inputfile> or /2:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. NOTE: This program reads from unit 2 rather than from the standard unit 5. (This is because the program reads the .MUS file as a binary file.) page 115 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. By convention, the extension ".SPK" is used for files formatted for the speaker device driver. You can also use "SPKR" (or "SPKR:") as the output file name, in which case the output is sent directly to the loudspeaker and is not saved to disk. <options>:: IN=<filename> This option specifies the name of the input file (which must have an extension of .MUS) and the PLAYCVT program will put the output in a file of the same name and path but with extension .SPK (this option makes it easier to use PLAYCVT automatically from a batch file). The option may appear in upper or lower case. page 116 40. PUBLBL -- PUBLIC LABEL INCLUSION GENERATOR When one is debugging assembly language programs with a symbolic debugger (such as Microsoft's SYMDEB), the debugger generally will let one reference program locations by name if the name corresponds with a label which has been declared "public". Typically, however, programs contain many more labels than those which need to be known outside of the containing module, and good programming practice keeps these known only within their local module. Unfortunately, this means that such symbols cannot be referenced symbolically while debugging. The PUBLBL program aids symbolic debugging of assembly language programs by rapidly and automatically generating an inclusion file which contains "public" statements which make all source file labels and procedure names known to the "outside world", including the symbolic debugger. This inclusion file can then be included into a subsequent assembly of the assembly language program. NOTE: Labels and procedure names which are not normally intended to be declared as "public" may not be unique when thrust into the world of other public names. The PUBLBL program does not make any attempt to leave private those names which can or do conflict with the same name which may be declared in other modules. In this case, the name in the assembly language program to be debugged should be changed and PUBLBL rerun, or the output file from PUBLBL can be edited to manually remove the conflicting public label declaration. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. NOTE: This paragraph only applies to the ".SAV" file form of PUBLBL. page 117 Note that there are two different versions of this utility, one of which (the .SAV file form) uses SNORUN, and the other (the .EXE file form, compiled with SPITBOL) which does not require SNORUN. Use only the example command lines and options descriptions below which correspond to the version of PUBLBL which you have. The following section describes the use of the PUBLBL.SAV version of the PUBLBL utility. The PUBLBL.SAV program is invoked with a command line of the form: snorun publbl [<iooptions>][;<options>] (PUBLBL.SAV version only) <iooptions>:: (PUBLBL.SAV version only) <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. This file normally contains an assembly language source program. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. This file will contain a series of "public" declarations for suitable labels and procedure names which were found in the source file. page 118 Example command lines would look like: snorun publbl /5:myprog.asm /6:myprog.pub snorun publbl /5=c:\asm\src\test.asm /6=a:\testinc.pub The following section describes the PUBLBL.EXE version of the PUBLBL utility. Effective with version 1.5, PUBLBL now recognizes two special lines contained within the assembler source program file: ;publbl -1 and ;publbl +1 The first of these turns "off" the PUBLBL processing of labels for subsequent lines, and the second turn PUBLBL processing back "on". These may be nested: initially the "publbl" tag has a value of one (any value greater than zero turns on label scanning). Note that this means you can negate a subsequent "-1" by preceding it in the text file with a "+1" line. Likewise, you can turn it "on" (+1) twice, then turn it off (-1) once, and it will stay on until you turn it off (-1) again. These special lines must appear -exactly- as indicated, (the semicolon must be in column one), and are most useful for preventing PUBLBL from trying to make public any local labels that may appear in macro definitions. The PUBLBL.EXE program is invoked with a command line of the form: publbl <inputfile>[,<outputfile>][;<options>] (PUBLBL.EXE version) <inputfile> (PUBLBL.EXE version only) This is the specification of the input file which contains the assembler language source code to be processed. If no extension is given, the default is ".ASM". <outputfile> (PUBLBL.EXE version only) This is the specification of the output file which is to receive page 119 the assembler language inclusion file, containing the "public" definitions that the PUBLBL utility has generated. If no output file spec is given at all, the same name and path as for the input file is assumed. If no extension is specified, the default extension of ".PUB" is supplied automatically. <options>:: (PUBLBL.EXE version only) /q This option tells PUBLBL that it should append its output to the existing contents of the indicated output file, rather than overwriting the output file from the beginning (which is the normal case). Example command lines would look like: (PUBLBL.EXE version only) publbl myprog.asm,myprog.pub ) these two are exactly equivalent publbl myprog ) publbl c:\asm\src\myprog.asm,c:\asm\inc\myprog publbl myprog,appendit.txt ;/q page 120 41. REPAGIN8 -- INTELLIGENT DOCUMENT PAGINATION AND TOC This utility program repaginates documentation files and processes them to create more satisfactory printed copies. Those who get a lot of public domain software, for example, often get documentation files which are simple, 80-column wide text files. Sometimes these files have been paginated in their past, but subsequent revisions may have resulted in all pagination having been lost. Often, the original, numbered chapter and section headings remain, and even an outdated index and/or table of contents. When such files are printed, there is also often not enough space to the left of column one to permit binding or punching of the printout without punching through the leftmost columns of text, or burying the leftmost columns into the deep crevasses of the binding. This problem is made especially acute when the files are printed in condensed print mode. The REPAGIN8 utility repaginates such text files, restoring them to a goodlooking format, suitable for punching or binding. It eliminates existing page eject control characters, adds page headings with optional page numbers, and shifts the text some specified number of columns to the right to leave space for binding. Rather than just printing so-many lines per page (although a nominal value can be specified), the program attempts to "intelligently" paginate the file. It looks for chapter and section headings, and paginates appropriately: chapters always start on a new page, and section headings are bumped to the following page if they are close to the end of the previous one. REPAGIN8 also takes into account widow/orphan control, attempting to keep paragraphs together when it seems practical and reasonable to do so. It also partially centers "short" pages vertically, so that a page with just a few lines on it will not hug the top of the page quite so tightly. The shift-right logic should work correctly, even if the line contains overprinted characters. Implementing this feature is less trivial than it would seem. page 121 A related program, called TITLGEN, has been written which is useful to automatically create title pages for documents. This program is especially useful in conjunction with REPAGIN8. See the TITLGEN chapter for further details. REPAGIN8, if it finds numbered chapter and section headings, will automatically generate a new table of contents, which it will print at the end of the document. Paginated like the rest of the document, the table of contents pages are numbered (if page numbering is in effect) using the standard, lower-case roman numerals, beginning with "i". Typically, this new table of contents will be removed after printing and moved to the front of the document. An option also exists, if preferred, (starting with version 1.4) which will cause the table of contents to be written to a different file. This file has the same name and extension as the original output file, but the extension is changed to ".TOC". This permits a batch or MAKE file to automatically append the table of contents file and the paginated output file, eliminating the need to move the table of contents to the beginning of the file. Another option, beginning with version 1.6, allows you to specify the nominal page width. This has no effect on most lines in the file (REPAGIN8 does not attempt to word-wrap or otherwise modify how the data is broken up into lines), but does affect the way that the page headings and table of contents pages are generated (i.e. it affects those lines that REPAGIN8 itself has added to the file). If you like, REPAGIN8 also offers an option to renumber the chapter and section headings. This is especially useful if you have combined several documentation files, or rearranged their sections. In this case, chapter and section heading numbers will be used only to indicate the appropriate level. If renumbering is in effect, all chapter headings will be forced to upper case. (NOTE: In the conversion to upper case characters, foreign users can specify the suitable upper and lower case character sets. See the chapter titled "Setting Upper and Lower Case Character Sets" elsewhere in this document for further details). page 122 Note that, if you want chapter headings to begin on a new page, REPAGIN8 requires that they be preceded by at least two blank lines, and followed by one. This helps to prevent its triggering a new page when it hasn't got a real chapter heading. The user's guide you are presently reading has been processed through the REPAGIN8 utility program. Looking at its format carefully will give you a good idea of what REPAGIN8 does. Note that page breaks generally take place in reasonable places. The heuristics are complicated, but fortunately, like many good programs, you don't have to understand how most of them work to use and appreciate them. You might be interested to learn that REPAGIN8 was originally written to fix up the received (and sorta garbled) documentation for the public domain program "MSKERMIT", although REPAGIN8 has been used since then on a large amount of public domain and shareware software documentation. REPAGIN8 assumes that each input record is less than 300 bytes long (these are, after all, normally expected to be print lines!). Trailing spaces, if any, are removed (as is true for most of these SNOBOL4+ utilities). In the REPAGIN8 command line, note that any items may be specified in either upper or lower case. The separator between option values and the corresponding numbers (if any) may be either ":", "=", or omitted altogether if you prefer. Options may be separated by spaces or commas or whatever, if you prefer, but do not require separators. (However, don't forget the ";"!) The command line to REPAGIN8 looks like: snorun repagin8 [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. page 123 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. <options>:: /h:<nn> or /h=<nn> or /h<nn> This option allows specifying the number of lines of header to be placed at the top of each page (minimum is one) before the first line of text is printed. (Note that the header will often be larger than specified based on a variety of factors designed to put the text on the page in a more pleasing way.) The default for this value, if not explicitly specified, is currently three. /l:<nn> or /l=<nn> or /l<nn> This option allows specification of the nominal number of lines to print on the body of the page (note that this is NOT the same as the number of print lines per page, normally 66). This is the approximate number of lines to print per page, following the header and before however many blank lines may appear at the bottom of each page. An example value might be "/L50". The default for this value, if not explicitly specified, is currently 55. /n This option specifies that REPAGIN8 is to add page numbers at the top of each page. The new table of contents, if generated, will be numbered using lower case roman numerals. The page numbers are approximately vertically centered within the specified header. page 124 /o:<nn> or /o=<nn> or /o<nn> or /o This option specifies that the file is to be printed further over on the printed page than it would otherwise. If the option does not appear at all, then the file is not shifted over at all. If the option is given without a value, then the default value (twenty columns) is used. If a numeric value is specified, then the input file is shifted to the right by that number of columns. /r This option specifies that chapter and section headings are to be renumbered. The existing numbers are used to indicate the level only. Chapter headings are forced to upper case if this option is in effect. /t This option specifies that the table of contents, if any, is to be written to a different output file than the main output file. The table of contents file is given the same name as the main output file, but with the extension "TOC". If this option is not specified and a table of contents is produced, it is written at the end of the main output file. Having the table of contents written to a different file makes it possible to simply use COPY to append those two files, producing a third: copy outfile.toc+outfile.doc outfile.prt As an example, the exact command lines which were used to format this User's Guide are as follows (the first three lines are used to append the list of most current versions of each utility): snobol4 bldverl /5:utilsdoc.txt /6:f:utilsdoc.tx2 copy utilsdoc.txt+f:utilsdoc.tx2 utilsdoc.doc del f:utilsdoc.tx2 snorun repagin8 /5:utilsdoc.doc /6:utilsdoc.do2;/l42 /n /o20 /r /t copy utilsdoc.toc+utilsdoc.do2 utilsdoc.prt del utilsdoc.toc del utilsdoc.do2 page 125 /w:<nn> or /w=<nn> or /w<nn> This option allows specifying the nominal page width, or the maximum number of columns that are normally expected to appear on a given line. This value only affects page headings and table of contents lines actually generated by REPAGIN8, and DOES NOT OTHERWISE AFFECT LINES FROM THE USER'S FILE. REPAGIN8 DOES NOT REARRANGE PARAGRAPHS OR OTHER ORIGINAL TEXT. The default for this value, if not explicitly specified, is currently 78. page 126 42. SAPPREF -- APPEND ASSEMBLER CROSS-REFERENCE TO LISTING If you use Microsoft's Macro Assembler very much, one real annoyance (of the many, ahem!) is the fact that its cross references, prepared with the companion program CREF, are written into a separate print file. This is less serious if you are printing direct to a printer, but is a royal pain if you are running on a network or use some other kind of spooling to a shared printer... it often means that your program listing and cross-reference arrive in two separate parts, with burst pages, blank sheets, and/or someone else's listings in between. It is also a pain that Microsoft apparently provides no mechanism to suppress the CREF cross-referencing of local labels used within macros. Having these in the cross-reference makes it bigger than it needs to be (by a LOT if you are using a lot of macros!) and is dumb anyway since (unless your macros are really humongous): 1) you can immediately see all the references to the label (if your macros are expanded in your listing... they are, after all, local) or 2) you can't see the references to the label anyhow (if your macros aren't expanded in your listing): in this case, the cross-reference will show all the references as being on the same one line. The SAPPREF program takes the output file from Microsoft's CREF program and removes references to macro local symbols (those which begin with "??") and others to be suppressed (those which begin with a single "$"... I use these for general equates and the like, such as extended instruction mnemonics). It then repaginates the resulting print file (using Microsoft's existing page headings), renumbers the pages and tacks the final product onto the end of the source listing print file. The result is a single print file, with local symbols suppressed, just like a decent assembler would have provided to begin with. Except for the often-considerable reduction in the size of your cross- reference, the only other indication from the listing that SAPPREF has been used is the recomputed symbol count at the end of the cross-reference and a new line following it that shows the number of local symbols that have been suppressed. page 127 SAPPREF is fully suitable for use in MAKE files. (MAKE is a useful utility which helps to automate the sometimes-complex system generation process for programs or large systems). SAPPREF is written in SPITBOL (see the discussion on the various implementations of SNOBOL4 later in this document), so it is FAST. It typically takes a small fraction of the time CREF requires (to generate the ".REF" file) to fully process it and append it to MASM's ".LST" file. The program is invoked by a command line of the form: sappref <infile> <outfile> [<options>] The first file spec defines the output file previously produced by Microsoft's CREF. If you do not specify an extension for this file, the normal CREF output-file extension of ".REF" is assumed as a default. If you want a blank extension, simply use a trailing "." at the end of the file name, as per MS-DOS conventions. Drive specifiers and path names may be used as necessary. This file represents the input file to SAPPREF. The second file spec defines the output file from SAPPREF, and normally is the listing file that has been output from Microsoft's MASM. If you do not specify an output file, a file of the same name as the input file will be assumed (see the /Q option below for further details on defaults). Note that the options listed below may be entered in either upper or lower case. <options>:: /q This option causes the resulting output to be appended to the output file. IF THIS OPTION IS NOT SPECIFIED, THE OUTPUT OF SAPPREF WILL OVERWRITE THE OUTPUT FILE STARTING AT THE BEGINNING. If this option is specified, the output file extension will default to ".LST". If not, the output file extension defaults to ".RF2". page 128 /n<integer> This option allows specifying how many lines are to be printed on each page. The default is 58 (the same as CREF uses). If you prefer, you can optionally put either an "=" or ":" after the "/n". /sfs This option causes the program to display to the console the name of the output file which will be written to. This option is not terribly useful, but is documented for the sake of completeness. The display also indicates whether SAPPREF is using APPEND or (over)WRITE mode. Invoking the SAPPREF program with no command line file specs or options will cause it to display a help screen with the available options. Examples: To suppress the local symbols in "TEST.REF" and append the result to the MASM source listing file "TEST.LST", the suggested command line would be: sappref test /q The above command line is exactly equivalent to a command line (not taking advantages of the defaults) looking like: sappref test.ref test.lst /q If you just wanted to remove the local symbols from "TEST.REF" and produce a new file named "TEST.RF2", without modifying MASM's ".LST" file, one possible command line might be simply: sappref test The above command line is exactly equivalent to a command line (not taking advantages of the defaults) looking like: sappref test.ref test.rf2 page 129 43. SPACE -- DISK SPACE MANAGEMENT AND RECOVERY UTILITY If you have a hard disk on your PC-compatible, you need the SPACE program. This program helps you to manage your hard disk space better, and find space consumed by files you either don't need any more, or can move offline to floppies. This utility program is an enhanced version of DIRTREE (shown above). Like DIRTREE, it allows listing subdirectory information on either an entire volume or within any specified subdirectory of a volume. Also like DIRTREE (and unlike PCTOOLS or Norton Utilities), the SPACE utility works fine on remote volumes under most local area networking systems. However, SPACE also optionally displays the number of files and sectors contained within each subdirectory, broken down by file extension within that subdirectory, and for the entire volume (or highest level path as specified on the command line). These space utilization reports may be ordered either alphabetically by extension, or by descending order of space used by files of each extension. The report can also optionally compute the percentage represented by files of each extension. The SPACE program can also find likely duplicate files which have been copied to various hiding places on your hard disk and then forgotten about, even if the name or extension has been changed, or if the files which are duplicates of each other are in different subdirectories. It does this, without having to read the actual file data, by finding files anywhere within the paths searched which have exactly the same file size, creation date, and creation time. NOTE: This does not guarantee that the files are indeed the same, or that any such duplicates found may be freely deleted. The responsibility for such determination rests, of course, on each individual user. However, most users will find that this option will help them to recover a surprising amount of space on their hard disk. So, if you've a hard disk, and it always seems to be too close to full for comfort, you'd probably be surprised how many sectors you can free up using the information supplied by SPACE. You'll wonder how you got along without it. page 130 NOTE: SPACE (as of this writing) is NOT being distributed as shareware. It is a separate product, which must be registered individually with the author. SPACE is priced at $30 US, and is well worth that price. A special reduction applies to users who are registered users of these SNOBOL4+ utilities or who register the rest of this package concurrently. Prices are subject to change without notice. Write the author for current prices and ordering information. The TREE option (described below) assumes that your output device (normally the display or printer) supports the IBM extended ASCII character set (specifically, the line-drawing graphics characters). (Note that, throughout the options descriptions that follow, ":" and "=" are both equally acceptable between an option keyword and its specified value.) Also, all options may be entered in either upper or lower case. snorun space [<iooptions>][;<options>] <iooptions>:: ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This option allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. <options>:: path=<pathname> or /p=<pathname> This option allows specification of the path name to be used for the subdirectory lookup. Example pathnames are: c: a:ms* d:ms?as* etc. The default path name is "\". As in the output file options, you may use either a "=" or a ":" in the option specification, whichever you prefer. page 131 alloc or /a This option causes the output of space utilization reports which are sorted in descending order by amount of space used for files of each given extension. /dpo This option causes no subdirectory scanning, but merely displays the effective path name that would be used for the lookup. This is NOT a particularly useful option. dup or /d This option causes an analysis and report of possible duplicate files. A report is generated of all files of the exact same length and generation time for the specified path(s). Although the data in the files is not actually checked, use of this option will generally turn up several files which are needlessly wasting space on your hard disk by existing in several places at the same time. Note that it is not necessary that the file name or extensions be the same for them to turn up on this report. ext or /x This option causes the output of space utilization reports which are sorted in alphabetic order of file extension. This option takes precedence over the "alloc" and "/a" options, should both be specified. list or /l This option causes all subdirectories to be written to the output file. They are output as FULL PATH NAMES, in sorted, interleaved sequence. indent or /i This option causes all subdirectories to be written to the output file. They are output as FULL PATH NAMES, in sorted, interleaved sequence, just as for the "list" form, except that nested subdirectories are indented. page 132 stair or step or /s This option causes all subdirectories to be written to the output file. They are output, one subdirectory to a line (with higher levels of each path name suppressed), in sorted, interleaved sequence. The left end of each nested subdirectory is lined up under the right hand end of the name of the containing (sub)- directory above. tree or /t This option causes all subdirectories to be written to the output file in the style used by PCTOOLS, except in a continuous format (PCTOOLS displays them one screenful at a time, making it incon- venient to print them). util or /u This option causes the output of space utilization reports. These reports break down the number of files and number of bytes allocated per file extension, per subdirectory. If more than one space utilization report is produced, a summary report is also provided at the end which consolidates all of the previously produced space utilization reports. Note that the number of bytes allocated as shown in these reports does not include the additional unused bytes normally found at the end of each file. The default ordering of these reports is in alphabetic order by file extension. width=<integer> or /w=<integer> This option sets the width of the output lines to the indicated maximum width. The default maximum width is 80. If the usage option is in effect, setting the maximum width to 132 (or some value bigger than 80) may result in more columns being able to fit per output line. page 133 nohdr or /nh This option suppresses the heading from being written to the output file. The heading contains the path name used, the date and time, and the volume name (unless suppressed). novol or /nv This option suppresses the volume name from being accessed. If not suppressed, the volume name is read and placed in the heading (which could also be suppressed). per or /p This option adds an additional figure to each file extension's entry within the space allocation reports. This percentage figure represents the percentage of the total space allocation, for that report, which is represented by files with the indicated extension. Specifying this option also implicitly specifies the /u option. /lej This option causes a page eject to be sent to the output at the beginning of the output. The mnemonic means "leading page eject". /tej This option causes a page eject to be sent to the output at the end of the output. The mnemonic means "trailing page eject". POSTSCRIPT: It should be pointed out that the SPACE utility keeps a lot of information in memory. Although this is organized quite efficiently, as hard disk drives get larger and contain more files, it becomes harder for SPACE to deal with the large numbers of files. If you receive some kind of an error message, perhaps an "overflow" message of some kind (the exact message will differ depending upon what the program was in the process of doing when it ran out of memory), there page 134 are several things you might try. First is to reduce the number of options you are using all in the same run. For example, if you are requesting the duplicate file analysis (which uses a lot of memory), it will help to not also request other options at the same time. Of course, you should also try to maximize the available DOS memory space. You might try, for example, to run SPACE with fewer memory- resident utilities (such as Sidekick, Superkey, or PC-Tools) loaded. This will maximize the amount of memory that SPACE can use. The actual limits are widely variable depending upon how your disk is organized, but on the author's hard disk, SPACE tends to exceed its available memory (using the /d option) at around 2700 files. page 135 44. STRIPBS -- STRIP BACKSPACE CHARACTERS FROM TEXT FILE This utility program eliminates backspace characters from records read from standard input and copies the rest to standard output. Some communications software, such as BITCOM when talking online to CompuServe, simply stores backspace characters into its capture files: this program gets rid of them. Backspace characters at the beginning of each record are simply discarded. Backspace characters which are preceded by some other character are eliminated along with the previous character. STRIPBS also eliminates trailing spaces that may be at the end of each input record. Input records may be up to 4000 bytes long. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. The program is invoked with a command line of the form: snorun stripbs [<iooptions>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or page 136 /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. A typical command line would look like: snorun stripbs <infile.txt >outfile.txt page 137 45. TITLGEN -- GENERATE A TITLE PAGE This utility program reads a parameter file containing a title, subtitle, version and release number, date of preparation, and an author name. TITLGEN then formats this information in a standardized manner and creates a title page for the corresponding document. The user can specify the desired maximum width of the printing on the page, the nominal page length, and how many bytes the information on the page is to be shifted over (to the right) in order to allow space for binding. Note that this program is intended for use as a companion program to REPAGIN8, described in an earlier chapter. The program is also designed to be easily used within a MAKE file. To use TITLGEN, you must first prepare a file containing various lines of information which will be placed on the title page. This is a simple text file which looks as follows (each record begins in column 1): Document title Document subtitle Document version and release number Document date Author Name and address block (optional, up to five lines) The following would be an example of a suitable input file to TITLGEN: Data Entry System Program Operations Manual Version 1.0 March 14, 1987 XYZ Software Company 123 Main Street Anywhereville, XX 98765-4321 U. S. A. (900) 555-1212 page 138 Some items of interest about the above records in the input file: Each line will be centered horizontally within the specified-width printing area on the title page, and the printing area is shifted a specified number of spaces to the right to allow for binding. The lines are spaced proportionately down the page according to the nominal number of lines that could be placed on the page. The document title will be forced to upper case automatically when it is placed on the title page. If the document title is much narrower than the printed area on the page, it will automatically be spread out (by placing a space between each character) to give it a more pleasant appearance. NOTE: In the conversion to upper case characters, foreign users can specify the suitable upper and lower case character sets. See the chapter titled "Setting Upper and Lower Case Character Sets" elsewhere in this document for further details. The document subtitle is centered and placed below the document title. The release number (that portion of the number to the right of the decimal point) is automatically incremented by TITLGEN each time a title page is created from the given parameter file. It does this by actually updating the parameters file on disk. Note that TITLGEN always creates a three-digit release number, which is padded if necessary on the left with zeros. This update also leaves the parameters file tagged with not only the last version and release of the given title page that has been generated (in the file itself), but also the date and time when that version and release was put together (via the time and date fields kept in MS-DOS's directory entry for the parameters file). The date line normally looks as shown in the example above. This allows one to hard-specify a date for the title page. If you prefer, however, you can leave this line blank (i.e. don't just omit it, it must still be there but can be empty) and TITLGEN will automatically supply today's date for the title page. Following the date line, one can place up to five lines of author name and address information, telephone numbers, or whatever else might be desired. This information is placed in a block towards the bottom of the page, under the line with the date. You do not have to supply an author block unless you want to. page 139 In the TITLGEN command line, note that any items may be specified in either upper or lower case. The separator between option values and the corresponding numbers (if any) may be either ":", "=", or omitted altogether if you prefer. Options may be separated by spaces or commas or whatever, if you prefer, but do not require separators. (However, don't forget the ";"!). To use TITLGEN, the command line looks like: snorun titlgen [<iooptions>][;<options>] <iooptions>:: /4=<parameterfile> or /4:<parameterfile> This item allows specification of the disk file from which the file containing the information for the title page is to be read. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the title page is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. <options>:: /l:<nn> or /l=<nn> or /l<nn> This option allows specification of the nominal number of lines that are physically present on each page. Note that this option differs from the corresponding usage in REPAGIN8. The default for this value, if not explicitly specified, is currently 66. /o:<nn> or /o=<nn> or page 140 /o<nn> This option specifies that the title page is to be printed further over on the printed page than it would otherwise. This is to allow space for binding. If the option is not specified, the default shift is five columns. The number given with the option specifies how many columns towards the right the page is to be shifted over. NOTE: The page width (see below) does not assume any specific "left margin", i.e. the "printed page width" is assumed to start at column 1 of the printed page. If you wish a "left margin" on the title page (even though this IS largely meaningless on a page where everything is centered), you should increase the value specified for this parameter to allow for both the "left margin" and the number of columns to shift to allow for binding. /w:<nn> or /w=<nn> or /w<nn> This option specifies the nominal maximum width of the area to be printed on each page, measured in terms of the number of "space" characters wide the printable area is. This value is used when deciding how to center the title page lines on the page, and to decide whether or not the document title should be "spread". If this option is not specified, it currently defaults to the value of 55. /lej This option causes a page eject to be sent to the output at the beginning of the title page. The mnemonic means "leading page eject". /tej This option causes a page eject to be sent at the end of the title page. This option is usually not needed if the title page is to be appended to a table of contents and/or document processed by REPAGIN8, but can be handy for laser printer users who wish to print just the single title page by itself. The mnemonic means "trailing page eject". page 141 An example of the way in which the TITLGEN utility might be used in conjunction with the REPAGIN8 utility, described elsewhere, is the following series of command lines, which are similar to those that were used to create the document you are reading: snorun repagin8 /5:utilsdoc.doc /6:utilsdoc.do2;/l42 /n /o20 /r /t snorun titlgen /4:utilsdoc.tid /6:utilsdoc.tit;/L56 /o20 copy utilsdoc.tit+utilsdoc.toc+utilsdoc.do2 utilsdoc.prt del utilsdoc.tit del utilsdoc.toc del utilsdoc.do2 page 142 46. TOTSIZ -- TOTAL SIZE OF SUBDIRECTORIES This utility program searches through one or more subdirectories and provides the total number of allocated bytes for each subdirectory, and the total number of files in that subdirectory. Optionally, it will also list all of the files in each subdirectory (including hidden files and "subdirectory pseudo-files"). It automatically searches all lower level subdirectories, and also gives a summary report at the end of the run (if necessary) which gives the grand totals if more than one subdirectory was listed above. Since one can redirect the program's output, this also makes it possible to capture the displayed information for input to some other program, if desired. To do this, the output from the program could either be redirected to a file or "piped" directly into the other program using the appropriate DOS facilities (see the DOS User's Guide for details). Note that the allocation number displayed is the number of bytes used according to the directory entry, and does not take into account the number of bytes that are unused at the end of the last sector of the file. (Note that the average DOS file wastes, typically, half of its last sector. DOS only allocates whole sectors to files, even if the last sector is only needed to hold one single byte). This phenomenon, known as "granularity", can affect you more or less depending upon the specific sector (and allocation cluster) size in use on your particular disk. When the minimum allocation is bigger than a single sector, the average amount wasted is half a cluster. To use the TOTSIZ program, enter the command line: snorun totsiz <iooptions>[;<options>] Options, as usual, may be entered in either upper or lower case. <iooptions>:: ><outputfile> or >><outputfile> or page 143 /6=<outputfile> or /6:<outputfile> This option allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. <options>:: path=<pathname> or /p=<pathname> This option allows specification of the path name to be used for the subdirectory lookup. Example pathnames are: c: a:ms* d:ms?as* etc. The default path name is "\". As in the output file options, you may use either a "=" or a ":" in the option specification, whichever you prefer. Note that you can also specify the prefix part of a file name as well as the name of a subdirectory. In this case, TOTSIZ will find all files beginning with the given prefix part. If the pathname also matches a subdirectory name, then TOTSIZ will also operate on that subdirectory as well. An example of using TOTSIZ to total the sizes of all files beginning with "CL" in a given subdirectory might be something like: snorun totsiz ;path=c:\dos\cl /f This example would total the sizes of, for example, c:\dos\clock.exe c:\dos\clearmem.com c:\dos\clubroll.txt /dpo This option causes no subdirectory scanning, but merely displays the effective path name that would be used for the lookup. This is NOT a particularly useful option. file or /f This option causes the output to include an entry for each file found in each subdirectory processed. The output includes records for hidden files and "subdirectory pseudo-files". page 144 47. TP -- WIPE CLEAN THE TAIL END OF A FILE Most people do not realize that almost every disk file on every disk, both theirs and the ones they have received from others, contain two different information-carrying regions. The first is the area used by the real file, and its contents are usually as expected. The other region is the area past the end of the real file, and its contents are generally unexpected and sometimes a real surprise. The reason there IS anything "past the end of the real file" is that DOS always allocates space in terms of clusters, and these clusters contain anything from one to as many as four (even more in some older versions of DOS) disk sectors. DOS is incapable of allocating space in anything less than cluster increments. Therefore, if you have a file which requires "n" clusters, plus one byte, then there will exist at the end of that file a "second information-carrying region" which is one cluster (minus one byte) long. If your cluster size is 2048 bytes (which is typically true for hard disks), this frequently overlooked region will contain almost an entire screenful of bytes! Persons and companies which prepare disks for distribution, although they usually go to great pains to ensure the correctness and propriety of the information contained in their files they are going to distribute, generally do not at all consider this "second" information-carrying region. Generally one discovers that this second region contains information not at all intended for distribution. Although generally one finds random bits of object code, or fragments of old directory sectors, one also can occasionally find hunks of source code, pieces of word processing documents, old letters, pieces of spreadsheets, or other more interesting stuff. Systems which are used for communications, for example, might easily have pieces of dialing directories, user login codes, passwords, (even old CompuServe CB conversations!) and the like floating around in the pool of unused sectors, and occasionally these sectors turn up on diskettes which that system prepares for distribution. page 145 The TP utility is a tool which concerned computer users will want to use often. It "wipes" clean the "tail end" of the specified file, clearing everything in this second information-carrying region to binary zeros. It does not modify the data file itself, so TP is safe to use on any kind of file I know of. (Of course, before changing ANY critical files with ANY program, one should ALWAYS make sure there is a backup copy. This is just good common sense). TP, of course, requires that the file it is to wipe is not write- protected. It may also terminate abnormally if the disk containing the file to be wiped is full. To use TP, the command line looks like: snorun tp /2:<filespec>[;<options>] The "<filespec>" item is replaced by the name of the file (including, as always, optional drive specifications and/or path names) which is to have its tail end wiped. For example, one might enter the command line: snorun tp /2:a:read.me As always, the ":" character between the "/2" and the file specification can be either a ":" or a "=", whichever you prefer. NOTE that the "tp" command (by default) assumes that your DOS uses clusters of 2K bytes (usually as four 512-byte sectors) or smaller. If your system uses a larger cluster size, you should specify the Cluster Size option. Failure to do so will mean that your "tail end" could still contain some unintended information. For example: snorun tp /2:myfile.txt ;/c=4096 If you have a lot of files which you wish to wipe using TP, a handy feature of DOS allows you specify multiple files with a single command line, by specifying a file spec "skeleton". For example, if you are going to give a diskette with a bunch of files on it to a friend, or to send it off for public distribution, you could first stick the diskette in your A: diskette drive and enter the command line: for %i in (a:*.*) do snorun tp /2=%i page 146 The above command line will "wipe the tail end" of every normal, non- protected file in the diskette's current directory. (Of course, if the diskette has multiple subdirectories, you will have to repeat the above command line separately for each one. The "skeleton" command line shown above does not cross subdirectory boundaries.) Now that you know about this second information-carrying region, there are those among you that will spend a cozy evening at home on some nasty winter night checking out a bunch of your diskettes to see what secrets you might find on them. (I sure hope there isn't anything embarassing on any of the ones I've previously distributed!) If you DO find anything unusually interesting on any of your acquired diskettes, especially those distributed by major companies, I'd be interested in hearing what you found. My address is at the end of this document; drop me a line! page 147 48. TRUNCATE -- REDUCE THE SIZE OF A FILE This utility reduces the size of a file by discarding characters that are at the end of the file. This is most useful for returning excess disk space to MS-DOS that was captured using the EXTEND utility, described earlier. Refer to the EXTEND chapter for further details. In order to use TRUNCATE, you first need to decide just how much of the existing data in the file you wish to retain, and you need to know this to the exact number of bytes. There are many programs that you can use to establish such information, but perhaps the most simple and useful is Vernon Buerg's excellent LIST utility. Find where you want the end of file to be, switch to hexadecimal mode, and figure out its byte number. Next you call up TRUNCATE with a command line that looks like: snorun truncate /2:<file> ;<options> WARNING: Since this program's function is to carve a piece off of an existing file, it must be used with some care. The program requires that you confirm what it is about to do by entering the password PROCEED in response to its confirmation request. /2=<file> or /2:<file> This item allows specification of the file which is to be shortened. Note that unit number 2 is used, instead of the customary unit 5. This permits binary file mode access to be used. As usual, either ':' or '=' may be used following the unit number. <options>:: /=newsizeH or /=newsize page 148 This option (misnamed, since it MUST be specified) tells TRUNCATE how long you want this file to be. You can specify the number in either hexadecimal (with a trailing H) or in decimal (no trailing H). When TRUNCATE is finished, you can look at the file's entry in the directory (use DIR) and it should be exactly the size you've specified. This number must be smaller than the file's current size (actually, the same size is legal too, but pointless). A typical command line would look like: snorun truncate /2:d:\myfiles\comm\capture.txt ;/=64365 -or- snorun truncate /2:myfile.prt ;/=23a0fh page 149 49. TSELIM -- TRAILING SPACE ELIMINATION This utility program eliminates trailing spaces from the end of each input record and copies it to standard output. This can often improve the speed of some types of printers, and can reduce line costs on communications lines. Note that this program operates as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. It also should be pointed out that input records are assumed to be less than 4000 characters long, and that the program deletes any trailing spaces that may be found at the end of each record. The program is invoked with a command line of the form: snorun tselim [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer page 150 or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /? or /H or /h This option causes an example command line to be displayed to the screen. The program then terminates without processing the input file. A typical command line would look like: snorun tselim <infile.txt >outfile.txt page 151 50. TYPEOF -- CHARACTERIZE AN ASCII TEXT FILE This utility is useful for examining ASCII files to determine their characteristics that are not obvious by a quick inspection with a file listing program. The TYPEOF utility not only counts the number of records in the file, but also indicates maximum and minimum record lengths, average record length, and mean length. It outputs a distribution table of how many records of each length are found. It checks to see if any records contain tab characters. If so, it reports on the maximum and minimum number of tabs found in a single record, and outputs a distribution chart. TYPEOF also examines records for any possible non-printing characters that may be present (including TAB characters), and if it finds any it provides a count of how many of each are found. It is intended that a future enhancement of the program will be to perform a zone analysis of each record, if the records appear to be columnar, indicating the type and length of each field. Input records are assumed to be less than 4000 characters long. Note that TYPEOF deletes trailing blanks from each record upon input, (so, records which end in variable-length alphanumeric fields may appear to be variable in length, even though they could be considered fixed-length). TYPEOF is useful for performing confidence checks on data files with known characteristics, verifying the validity of ASCII text files, and many other general uses. To use the TYPEOF utility, the command line looks like: snorun typeof <iooptions> <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. page 152 ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. page 153 51. UNBACK -- RECOVER BACKUP FILES THAT RESTORE WON'T This utility program allows you to restore files that have been placed on a diskette using the DOS BACKUP utility. Ordinarily, RESTORE requires that the file BACKUPID.@@@ exist on the backup diskette, and that it be a perfect match for the files on the diskette. If that special file is missing or invalid for some other reason, it normally is not possible to restore the data file. The normal RESTORE command will not process it, and just COPYing the data file gives an invalid version of the file that was originally backed up. This utility will read the file placed onto the diskette by BACKUP, remove the control information, and copy it to another disk so it may be used. UNBACK does not work just like RESTORE: it has some limitations. First, UNBACK does not restore the originally backed-up file's original time and date. Secondly, UNBACK does not restore files which are not entirely contained on one diskette. However, it can be a lifesaver when you need it! snorun unback The UNBACK program will prompt you for each input file and corresponding output file in turn. The prompts should be self-explanatory. When you are finished, simply enter a null record (just press ENTER) in response to the keyin prompt. page 154 52. UNOVER -- DELETE LEADING SPACES IN TEXT FILE Sometimes one has a file which contains a number of leading spaces at the beginning of each record. These may have been added to make the file print in a more attractive manner on one kind of printer, but might adversely affect the printing on some other printer, for example. In such cases, the UNOVER utility can be used to remove the first run of "some number" of blanks from each record in the input file. UNOVER therefore can be used to "undo" a previous "OVER" operation. (OVER is another utility program in this package, described in an earlier chapter). Note that control characters, escape sequences, or any other text which might precede the run of spaces, if any, do not interfere with their removal. For example, this document is formatted with a number of leading spaces at the start of each record, and is intended to be printed in "compressed print" mode. The use of the leading spaces prevents the document text from squeezing so tightly against the left margin that it interferes with binding the printed document. If one only has an eighty column printer with no ability to print in compressed mode (such as perhaps a daisy wheel or older-style printer), the printer might not be able to deal with the longer records. UNOVER allows you to specify how many consecutive blanks to remove. If there are more than the specified number, only the number specified will be removed. For example, one could reduce the left margin of this document, without eliminating it entirely, by removing ten of the twenty blanks from each record. Note that this program can operate as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. page 155 To invoke the UNOVER utility, use a command line of the form: snorun unover <iooptions>[;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /N=<number> or /n:<number> or /n<number> This option allows the user to specify how many blanks are to be removed from each record. The first run of the specified number of consecutive ASCII spaces (NOT including tab characters or their expansion!) found in each record of the input file will be removed. Note that the option may appear in upper or lower case, and the option letter may be separated from the number, if desired, with either a colon or an equals sign. If this option is not specified, the default number of spaces to remove is 20 (the same as the default number inserted by the OVER utility). NOTE: Don't forget the semicolon before the option. It IS important. page 156 Some typical command lines would look like: snorun unover <utilsdoc.prt >utilsdoc.pr2 snorun unover /5:somefile.txt /6:revised.txt;/n=18 snorun unover <\print\prtfile.prt /6=\print\prtfile2.prt;/n10 page 157 53. WC -- WORD COUNT This simple but useful utility program counts the number of words in an input file and displays the total. (Simple is not an exaggeration... the SNOBOL4+ source program for this utility is only four source statements long, including the "END" statement!) As a bonus, it also displays a count of the number of source lines in the file. There is no universal agreement as to what constitutes a "word". This program considers a word as anything starting with a alphabetic character or a numeric digit, and containing only alphabetic characters or digits. WC counts hyphenated words and contractions (joined by an apostrophe) as a single word, if they appear on the same line. Unlike other word counting programs, this one allows the user to specify that other characters are legal in words as well. This feature is especially helpful for users writing in foreign languages. For example, "P. O. Box 40476" counts as four words. "SNOBOL4" counts as one word. "MS/DOS" counts as two words (unless the character "/" is specified as legal, in which case "MS/DOS" would count as one word). Some text editors produce text files which have very long individual records. Microsoft WORD, for example, writes each entire paragraph as one (long!) line in its unformatted output text files. WC allows each input record to be up to 30,000 characters long. Note that using WC on "formatted"-type (counts as two words, due to the quotes) files produced by some word processors can cause erroneous counts because the formatting information may sometimes look like "words" and be included in the count. Note that this program can operate as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. Note, however, that only the final lines (containing the word count and the total number of input records read) are written to standard output. The program signon is written to the console, even if standard output has been redirected to a disk file or elsewhere (see below). page 158 The program is invoked with a command line of the form: snorun wc [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. <options>:: /L="<legal chars>" or /l:"<legal chars>" This option allows the user to specify that other characters are also to be allowed as starting or intermediate characters in "words". Using this option allows foreign language users to get accurate word counts too! Note that the option can appear in either upper or lower case, and either "=" or ":" is a legal separator. The double quotes around the string of legal characters are required. NOTE: Don't forget the ";" that separates the I/O options from the regular options! It IS important. page 159 NOTE: In the example below that demonstrates the use of this option, a number of IBM Extended ASCII characters are used which may cause your printer to do "strange things". If these characters cause problems on your printer, (there should be fourteen characters between the double quotes), you might want to modify the example so you can print it correctly. Note also that not all keyboards generate the foreign character sets easily (and sometimes not at all). Some typical command lines would look like: snorun wc <infile.txt >infile.wct snorun wc /6:infile.txt;/L="ÇéàçêÉôòûùáíóú" page 160 54. WFREQ -- WORD FREQUENCY This program reads an input file and counts how many times each specific word in the file is used. This can be of use to writers, for example, to point out words that they may be over-using. On the other hand, words that appear only one time in a lengthy document are more likely to be misspelled than words which appear more than once. It is also interesting to analyze a document to see what the "working vocabulary" is, i.e. how many different words are contained in the document. There is no universal agreement as to what constitutes a "word". This program considers a word as anything starting with a alphabetic character or a numeric digit, and containing only alphabetic characters or digits. WFREQ considers hyphenated words and contractions (joined by an apostrophe) as a single word, if they appear on the same line. Unlike other word frequency programs, this one allows the user to specify that other characters are legal in words as well. This feature is especially helpful for users writing in foreign languages. For example, "P. O. Box 40476" is four different words. "SNOBOL4" is a single word. "MS/DOS" is treated as two different words (unless the character "/" is specified as legal, in which case "MS/DOS" would be considered to be one word). Some text editors produce text files which have very long individual records. Microsoft WORD, for example, writes each entire paragraph as one (long!) line in its unformatted output text files. WFREQ allows each input record to be up to 30,000 characters long. Note that using WFREQ on "formatted"-type (counts as two words, due to the quotes) files produced by some word processors can cause erroneous counts because the formatting information may sometimes look like "words" and be included in the count. Upon conclusion, the program prints a multi-column report of the words and their usage counts, and finally a report with other useful counts, such as the number of source lines, the average word length in the file, number of different words, and the like. The number of columns in the word frequency report is chosen at run-time according to the longest "words" found. page 161 Note that this program can operate as a "filter", much the same way as the DOS "MORE" command. It reads from standard input and writes to standard output. Therefore, its input and/or output can be "piped" the same way as any other DOS filter. See the DOS User's Guide for more details on filters and "piping" of standard input and standard output. Note, however, that the program signon is written specifically to the console, not to standard output. Therefore, the signon will still appear on the screen, as usual, even if the remainder of the program output has been redirected to a disk file or elsewhere (see below). The program is invoked with a command line of the form: snorun wfreq [<iooptions>][;<options>] <iooptions>:: <<inputfile> or /5=<inputfile> or /5:<inputfile> This item allows specification of a file (or device) from which the input file is to be read. If this item is not specified at all, the program reads from "default standard input", which may be a piped input file, or the console. ><outputfile> or >><outputfile> or /6=<outputfile> or /6:<outputfile> This item allows specification of a file (or device) to which the output file is to be written. This can be either a printer or a disk file, or in general any MS-DOS sequential output device. Note that the ">>" form appends the output to the end of the existing contents of the specified file, if any. If this item is not specified at all, the program writes to the "default standard output", which may likewise be piped into another program or by default will appear upon the console. page 162 <options>:: /L="<legal chars>" or /l:"<legal chars>" This option allows the user to specify that other characters are also to be allowed as starting or intermediate characters in "words". Using this option allows foreign language users to use WORDFREQ as well! Note that the option can appear in either upper or lower case, and either "=" or ":" is a legal separator. The double quotes around the string of legal characters are required. NOTE: Don't forget the ";" that separates the I/O options from the regular options! It IS important. NOTE: In the example below that demonstrates the use of this option, I have used "normal" ASCII characters that one might want to be included within words (the example above being MS/DOS). Foreign users whose keyboards and printers support foreign characters in the "extended ASCII character set" can key their characters here as well. Some typical command lines would look like: snorun wfreq <infile.txt >infile.wfq snorun wfreq /6:infile.txt;/L="/$" You might be surprised to learn that the entire WFREQ program (excluding only the standard columnar print subroutine inclusion) is only five executable statements long (and one of those five is the "END" statement!) If the output were to be printed in single-column form instead (one word per line), the program would still only be five executable statements, total, including the "END" statement. page 163 55. XTRCOMS -- EXTRACT COMMENTS FROM ASSEMBLER PROGRAMS This utility program extracts blocks of comments from assembly language source files. Specifically, it looks for blocks which contain a comment line whose first two bytes are upper case alphabetic characters, and which is followed by a non-null comment line. Such blocks are usually the comment blocks preceding a program subroutine. Once triggering on such a comment block, the remainder of the block is written to standard output (the block is not considered terminated by a null comment line). Therefore, the typical command line would look like: snorun xtrcoms <asmfile.ASM >asmfile.CMT [/S] A typical comment block of the form that XTRCOMS looks for might look like: ; ; MYSUB -- Title of My Subroutine ; This routine does nothing other than to demonstrate the kind of ; comment blocks which the XTRCOMS programs looks for, and to give ; an example of a fairly typical subroutine header. ; On entry, AX = whatever parameters might be in it ; On exit, AX = unchanged ; All other registers unchanged ; Normally, the output of XTRCOMS would be written to a disk file (where, for example, it could be referenced by some kind of an on-line aid facility or the like). However, one could also redirect this output to a printer, if one wanted to get a listing of the internal subroutine documentation. The /S option, if specified, causes the various comment blocks to be sorted and output in sorted sequence instead of the order in which they appear in the file. They are sorted into sequence based upon the name of the comment block, which is defined to be the first word (in upper- case ASCII characters) at the beginning of the comment block. page 164 56. SETTING UPPER AND LOWER CASE CHARACTER SETS Many of the utilities in this package convert alphabetic characters from upper to lower case or vice-versa. With most programs, this poses a problem for international (especially European) users, whose character sets include a number of special characters which most programs ignore when doing case conversion. (If you are in the United States and never need to use international character sets, you may safely ignore this chapter). In order to help resolve that problem, many of the utilities in this program which assume a knowledge of the upper and lower case character sets have been designed to allow the user to specify which additional characters (other than the normal ASCII "A" through "Z" and "a" through "z") are legal in "words" and how the different cases of those characters correspond to each other. This is done by placing two strings in the DOS environment area by using the MS-DOS "SET" command, typically in one's AUTOEXEC.BAT file, so that the configuration is done automatically each time the system reboots. For example, a user in France might want to enter the following two lines into the machine's AUTOEXEC.BAT file (these two lines may not print correctly if your printer does not correctly handle the IBM Extended ASCII character set): SET UCASE=ÇÉè SET LCASE=çéè Note especially that one can enter the same character in corresponding positions on both the upper and lower case character definitions. This tells the programs which support this facility that the characters are legal in "words" but that they are not to be changed during case conversions. This facility is useful, for example, for users needing or wishing to use other international character sets, such as Hebrew, in which the concept of "case" is not meaningful. page 165 You must always have exactly the same number of characters in both the UCASE and LCASE strings. If the number of characters in the two strings are different, they will generally be ignored. In exceptional cases, your version of MS-DOS may not have enough room in its environment area to allow you to enter the above-described SET commands. In this case, you should either carefully examine your MS-DOS documentation to see if it describes how to increase the size of the MS-DOS environment area, or else contact the person who you usually go to for MS-DOS technical support. You might also check with some of your friendly local hackers at either your local computer store, or a nearby computer club or bulletin board service, for help. page 166 57. HOW TO GET MORE Note that not all of the utilities described in this document are being distributed as "ShareWare". In particular, I feel that the SPACE utility is well worth my asking price of $30. Any utilities described in this document which are not part of the distribution package you received are available separately upon request from the author. Please write for price and availability information. Also, please note that programs in this package are subject to periodic improvement and updating. The public domain distribution system inevitably results in old or obsolete copies of programs floating around nearly forever. The only way to ensure that you have the latest versions of these programs is to register as a user directly with the author. The contribution you make when you register will help to defray the cost of sending you update and latest-version information from time to time. Also, due to the vagaries of public domain distribution and the low price of these utilities, note that I cannot accept any liability for any damages or claims whatsoever that may result from the use, or inability to use, any of these programs. The user must accept any and all responsibility regarding this software. Your acceptance and use of these programs constitute your acceptance of this responsibility. page 167 58. COMMON QUESTIONS AND ANSWERS Q. I am having trouble getting the "append" feature to work when I try to append output from a program to the end of an existing file. What am I doing wrong? A. Probably nothing. As of this writing, SNORUN version 2.03 (at least) seems to have trouble appending to existing files. I understand that the problem can be bypassed by using units other than 6 (standard output), but this also would prevent one from simply redirecting SNOBOL4+'s standard output using the ">" and ">>" command line options. I understand that Mr. Emmer is looking into the problem, but this one apparently will be challenging to correct since apparently the problem is caused by a "feature" of MS-DOS. In the mean time, you can get around the problem by writing the output to a new file, then combining the old and the new files with a command sequence like: copy oldfile.ext+newfile.ext scratch.txt copy scratch.txt oldfile.ext del scratch.txt Q. I've been using the XXXX program for quite some time and had no problems. Suddenly today it seemed to just hang in a hard loop or something. What happened? A. Hard to say for sure. If you are running the ShareWare version of these utilities, you are probably using version 2.0 of the SNORUN run-time package (the version number is in the signon message). Version 2.0 infrequently has a problem which causes it to hang up. This problem is discussed in the Introduction. If you are running a registered version (version 2.03 of the SNORUN run-time, as of this writing), this problem should have been fixed. Please report it. Q. Okay, I've found a bug in one of your programs. What do I do now? page 168 A. First of all, please make sure it is a bug and not just a "feature". Double-check the description in this user's guide to make sure you haven't overlooked something. If it is a bona-fide bug (and you can get it to happen again... if you can't reproduce it, chances are I can't either), please send me a diskette containing any relevant programs or data files necessary to demonstrate the problem. I cannot guarantee that these programs are completely error-free (even though this is the intention!). In any case, I can't fix a bug which I don't know about. NOTE: As of this writing, in August 1987, I am not equipped to handle diskettes other than 5-1/4 inch. Sorry. Send the diskette, and a complete description of the bug, direct to me. My address is located towards the end of this user's guide. If you are not a registered user, this would be an excellent opportunity for you to register! If you are a registered user (or register when you report the bug), you can be assured of a reply, and most likely a fix. If you are using the ShareWare version, the bug may have been fixed already in a newer version than the one you have, but I'd still appreciate your report. Your ideas for improvements in these programs, or ideas for other useful utilities, are of course always welcome as well. Q. Can I give a copy of your utilities to a friend? A. The ShareWare version of these utilities is distributable completely freely, which means that you are welcome to give away copies. All such copies must be complete and unmodified. If you intend to sell the copies, you must charge no more than a nominal fee for diskette duplication and handling. In all cases, you must include this user's guide in its entirety. If you have a registered copy, those should not be given out, as registered copies have a SNORUN (and .SAV files) which are different from (and incompatible with) those in the ShareWare versions. The SPACE utility is a program product, and must not be given away to others. For more details, refer to the license agreement which appears towards the beginning of this user's guide. page 169 Q. I want to use one or more of your programs within my company. Any restrictions? A. If you are a business, you really should register your copies. This ensures you with technical support and the most reliable versions of these programs. The SPACE program is a program product, but very attractive site licensing terms are available. I'm also available for consulting or custom programming projects, please write for details. Q. You keep saying "as of this writing", but every time you give a different date. Which one is right? A. All of them. Like most documents in these days of automated document preparation, this one is added to and revised periodically. Such notes which you'll find scattered through the User's Guide reflect the time that the containing section was written, or last revised. If you find something that's obviously inconsistent or in error, please let me know so I can correct it in the next revision. Q. I am curious about why I have to use "5" so often for input files and "6" so often for output files. A. Good question. The direct answer is "for historical reasons". The original version of SNOBOL4 was written for the IBM 360 (the most popular mainframe at the time) and, as an expedient, the developers "borrowed" the Fortran language's I/O package. Fortran uses "unit numbers" to internally reference specific "files", sort of like the "file numbers" that one refers to in BASIC. By longstanding convention (in the IBM world, at least, I can't vouch for others), unit 5 is the standard "input file" and unit 6 is the standard "output file". Subsequent versions of SNOBOL4 (which have, by and large, thankfully eliminated the Fortran I/O nonsense), have generally opted to retain the unit number, both as a convenient internal "file handle" and to retain maximum possible compatibility with existing SNOBOL4 programs. My personal convention is to use "standard input" (i.e. unit 5) and "standard output" (unit 6) as much as possible. I page 170 use other unit numbers when I have to do binary input/output, for example, or if I have to open multiple input or output files at the same time. Just why the original Fortran developers chose 5 and 6, I'm not sure anyone still remembers. More likely than not, even their answer today would also be "for historical reasons"! Q. SNOBOL4 sounds like the language I need for things I occasionally would like to do. I've never seen it in any of my local computer or software stores. Where can I get a copy? A. This is a question I hear all the time. Unfortunately, most computer stores only know about the products that they see big ads for in the magazines that they read, or that everybody comes in asking about. Even when a language is as good as SNOBOL4 is, it's hard to get any of the "big guys" interested in it. You could try going to your local computer stores and simply insisting that they special-order you a copy. There are at least a few enlightened mail-order software companies that carry it. If neither of those ideas work, (which too often seems to be the case), I have decided (of necessity!) to process orders personally for the benefit of my clients. You should find a price list elsewhere on the diskette containing this manual. If you are in Europe, you will probably find that ordering your SNOBOL4 and related products from me directly will be less expensive than special-ordering them through your local computer store, some of which seem to have simply outrageous markup and pricing structures. Q. Why don't the developers of SNOBOL4 promote this exciting product? A. The original development, done at Bell Labs, was a "by-product" of another project. Bell Labs (for legal reasons) at the time was prevented from selling any of their products directly to the public. Fortunately for the rest of us, they decided to put the source for SNOBOL4 into the public domain, guaranteeing its continued widespread availability, for any system anyone wishes to "port" it to. Meanwhile, the primary developer (Ralph Griswold) has moved from Bell Labs to the University of Arizona. Continuing research there has produced page 171 another fascinating language (ICON), again as a by-product of other research. Again, the funding body insists that their research funds not be used to finance any commercial or for-profit organization. Typically, the individuals who port SNOBOL4 to a given system do it primarily for their own interests and few of these have the money or inclination to pursue a costly nationwide distribution campaign. Q. One of the utilities you have here looks like just what I need... almost. Can I get you to make "just one small change"? A. Suggestions for improvements are always welcome. Often, these are relatively simple to implement. If they are of the sort that will continue to be of general interest, I may simply incorporate your ideas in the next release. I may even make such changes at no cost to you whatsoever. Changes which are more specialized are also possible, but are usually billable. Please contact me with your requirements and we'll see if we can't reach a suitable arrangement. Q. Reading through this User's Guide gave me a great idea for a program I'd like to have. It's real specific to my needs, and I would not want it to "get out" to others. I've never seen anything like it on the market. Could you make it for me? A. Probably! I offer comprehensive product design, software engineering, and systems consulting services. This includes custom programming of systems and applications software in numerous languages, running the gamut from Assembler and C to SNOBOL4 and ICON. I am willing to sign non-disclosure agreements if you need them. I am also willing to travel worldwide should your needs require. Please contact me with your ideas and requirements for details and a fee schedule. In the "About the Author" chapter elsewhere in this User's Guide you will find a description of some the diverse areas I've already been involved with. Q. I live overseas and it's really complicated to send shareware payments in dollars to American shareware authors. My bank charges outrageous fees for checks in dollars, and I don't want to send cash. Isn't there some other way I can register shareware packages? page 172 A. One good way to send money to shareware authors in the United States is to purchase American Express traveller's cheques. Most major cities worldwide have American Express representatives who will sell you traveller's cheques, in US dollars, at a much smaller surcharge than a bank would charge for a foreign-currency check. (Unfortunately, you may not be able to get these in denominations smaller than $20, or in less than a minimum quantity of $100 worth). Make sure, before you mail the cheque, that you have signed it in BOTH the required places and that you have written in the name of the person to whom you are making the payment. It is also a good idea to keep a record of the serial number(s) of the cheque(s) you send, so that you can claim a refund from American Express if the cheques are lost or stolen in the mail. Q. Is it okay if I upload the shareware versions of one or more of these utilities to my local bulletin board? I'm sure there are other users who would enjoy being able to use them too. A. You are encouraged to upload the shareware versions of these utilities to any local bulletin board services you may frequent. If you do so, however, please note that under the license agreement described elsewhere in this document, you must upload a COMPLETE and UNMODIFIED copy of these utilities, INCLUDING this documentation print file. You are not allowed to upload any versions of this software (existing as .SAV files) which use other than version 2.0 of the SNORUN run-time package. In fact, if you DO upload a copy of this package to a local bulletin board, and send me proof of having done so (this might consist of a copy of the "capture" file, or "log", that most communications programs allow you to record), I will send you in return a diskette containing the latest version of this manual, and a registered copy of your choice of any of my programs described herein. (Please specify which program you wish to receive, and give the name, access telephone number, and sysop's name and address (if you have it) for the bulletin board you uploaded to). (Of course, you don't have to include any log data which would reveal your password or other secret information!) I reserve the right to limit this offer to a reasonable number of free registered programs per person, or to withdraw it, if necessary, at any time without prior notice. page 173 Q. I've heard a lot of talk about "computer viruses" lately, and I'm not sure that shareware programs are safe to use. A. Virtually all programs leave their authors "virus free". Although the whole issue of computer viruses has thus far been overblown, there is genuine reason for caution to be exercised. Of course, once a program is released, it may pass through many hands before it gets to you and this means there is at least the opportunity for mischief. It is safest to use programs acquired directly from their author, or from a disk vendor or BBS which specifically certifies that the specific package in question was received DIRECTLY FROM ITS AUTHOR. This ensures that the software you receive and use is of "known pedigree". To minimize your chances of getting "infected" software from a disk vendor, you should only deal with disk vendors who DO NOT MODIFY OR ADD TO THE DISKS THEY DISTRIBUTE IN ANY WAY. If the disk vendor's system is infected, ANY change or rearranging that they perform on the author's release package could result in a virus already present in the disk vendor's system being transferred to the package in question. Quality software and packages carefully prepared by their responsible authors do not need the dubious "improvements" that some disk vendors try to add. If you get copies of this or any other package which contain files clearly NOT part of the author's original distribution, COMPLAIN TO YOUR SOURCE and tell them you don't want or need their dubious "improvements". The closer you can get to the original author's distribution disk, the safer you are. page 174 59. ABOUT SNOBOL4 VERSIONS FOR MS-DOS By the time you have read this far through this document, you are perhaps interested in finding out more about the SNOBOL4 language which has been used for nearly all the utility programs in this package. Many users either haven't ever heard of SNOBOL4, had no idea what it could be useful for, or did not know that it was available in a version to run on their own PC-compatible. 59.1 What Does SNOBOL Stand For? The name SNOBOL, which was given to the language after its implementation, stands for StriNg Oriented symBOlic Language. The language, although planned from the beginning for algebraic manipulations, is not really at its best on heavily numerical computations. If what you really need to do is high speed matrix transforms or lots of gaussian quadrature, SNOBOL4 is not probably the language you should be using. However, if you are reading or writing ASCII (or EBCDIC!) files, processing character strings or information structures, performing conversions or formatting, parsing, matching, or replacement, then SNOBOL4 is probably the language for you. It is tremendous for list processing, and is most likely better than LISP for AI applications. 59.2 About the SNOBOL4 Language The SNOBOL series of languages originated during the 1960s at Bell Labs. In the beginning, SNOBOL was a rather simple-minded language designed to perform symbolic algebraic manipulations such as factoring multivariate polynomials and symbolic integration. During the next few years, its capabilities were greatly extended, resulting in SNOBOL4, which was finally completed in 1969. SNOBOL4 was implemented in a macro assembly language for an abstract machine, so that it could more easily be ported to different processor architectures and instruction sets. (Contrary to popular belief, portable programming did not begin with C! It is interesting to note, however, that both C and SNOBOL originated at Bell Labs). SNOBOL4, with perhaps only the exception of its successor ICON, is today probably the most powerful and highest-level general-purpose programming page 175 language that has become widely available. The full implementation of SNOBOL4 is sufficiently difficult that only maybe three or four from-scratch implementations have ever been finished. The hundreds of different versions that exist for different machines and diverse operating systems all derive from one of these few original efforts. (This also explains their typically considerable compatibility with each other!) It is quite remarkable that progress in hardware has made it possible to finally port a full-blown implementation of SNOBOL4 onto hardware affordable by anyone. Not at all a "micro" language, SNOBOL4 for MS-DOS is fully equivalent to the mainframe version, with all the mainframe bells and whistles one could ask for. (The biggest change, and a welcome one too, is the elimination of the anachronistic FORTRAN I/O package with which the original was afflicted.) There are many other "interesting" programming languages, including many which are much better known than SNOBOL4. However, regarding many of them, skeptics are well positioned to ask "but what can you really do with the language?" SNOBOL4 is unusually rich in its features, extraordinarily powerful, easy to learn and to use (even for beginners!) and applicable (as you have seen by the diverse areas covered by these utilities) to a very wide range of real-world applications. To anyone who has thus far been limited in their programming experience to the primitive "knit-one-purl-two" mentality of traditional so-called "high-level" programming languages, such as BASIC, PASCAL, C, MODULA-2, or FORTRAN, it comes as somewhat of a revelation to discover SNOBOL4. 59.3 Implementations for MS-DOS At the moment there seem to be four different implementations of SNOBOL4 that are available for MS-DOS machines. I have (and have used) all four. If you are interested in getting a copy of SNOBOL4 for yourself (and I think it belongs on every PC and compatible), here are my remarks on the different versions. page 176 59.3.1 Minnesota SNOBOL4.2 by Viktors Berstis This version of SNOBOL4 is the closest to the pure, unadorned mainframe version of SNOBOL4. It is derived from the macro implementation of SNOBOL4 done at Bell Labs. Of the three versions of SNOBOL4 for MS-DOS machines, this one is the only one which directly supports 32-bit integers. It permits a very large combined program and data area, over 500K bytes. It is also the least expensively priced version available for the PC, other than the freeware "Vanilla SNOBOL4" from Catspaw (described later). The newest version of Minnesota SNOBOL4, which Mr. Berstis refers to as Minnesota SNOBOL4.2, has a number of improvements and additions, including support for path names (finally!), new functions including SORT, the ability to generate "save" files, increased execution speed, and other enhancements. He has also added the optional use of Fortran-formatted I/O, primarily to further augment his compatibility with the original mainframe implementation of SNOBOL4. SNOBOL4.2 now supports PEEK() and POKE() (really!), as well as loadable assembler functions. It also now provides (optionally) the automatic expansion and compression of tab characters, as well as allowing variable-length input records without requiring the truncation of trailing spaces. There are, however, a variety of reasons that Minnesota SNOBOL4.2 is still not the version of choice, in my opinion. First of all, and most importantly, there are still some hassles in the design of its I/O package. Even with the new enhancements that have been made in this area, it is still too complicated, in my opinion, to check for the existence of a file, and to handle a "file not found" condition. In the case where a program needs a detailed explanation of just why the file could not be opened, SNOBOL4.2 apparently shines, but the need for such information is rare in any case. Secondly, Minnesota SNOBOL4 requires an 8087 numeric coprocessor if you want to do any floating point operations. If you have only a small amount of such floating point work to do, it is annoying to be forced to buy a relatively expensive piece of hardware just for that purpose alone. (At least, however, floating point is supported). page 177 Third, Minnesota SNOBOL4 does not include many of the useful language extensions provided by the other two "main" versions. These include the very handy features originally introduced in Macro Spitbol: imbedded assignment, alternative evaluation, and imbedded pattern matching. (It is, of course, only fair to point out that these features are also lacking from Vanilla SNOBOL4). These three features, although they sound unimportant, really do change the character of the SNOBOL4 language considerably and are extremely useful in the other implementations which support them. I certainly applaud the new upgrade to SNOBOL4.2. This clearly represents a substantial effort on the part of Mr. Berstis, and is most likely quite worthwhile. In some cases, the changes may make SNOBOL4.2 worth another look. If you are already using Minnesota SNOBOL4, you certainly could not go wrong by upgrading to Minnesota SNOBOL4.2. I personally have now been using SNOBOL4+ for over a year, however, and have not seen anything sufficiently interesting in SNOBOL4.2 to justify returning to its use (given its continuing deficiencies) as a primary development tool. 59.3.2 Macro SPITBOL by Robert B. K. Dewar Macro SPITBOL is in many ways a very interesting version of SNOBOL4. It is the only one of those for MS-DOS which does not derive directly from the Bell Labs macro implementation. As such, it has a variety of nice added features, which make it easier to write and debug programs under than Minnesota SNOBOL4. Many of the extensions originally provided by SPITBOL have become "industry standard" for SNOBOL4 systems, and are to be found, as an example, in Catspaw SNOBOL4+. Macro SPITBOL is fast. Depending upon the language features you use, and how you use them, I've found its execution speed to be from five to forty times faster than the other versions. This makes it especially useful for production programs or programs whose running time might otherwise be excessive. Compilation speed is equally impressive. Macro SPITBOL can generate .EXE files. This means you can distribute the programs you write in SPITBOL in directly executable form, and the people you give them to may not even be aware that the program is written originally page 178 in the SNOBOL4 language. (The DVED full-screen editor, in many public- domain distribution libraries, is an example. It was written using Macro SPITBOL. This helps to explain the positively miraculous way in which the DVED editor can crank out its own documentation file... and the documentation file, which comes out of the editor, is by itself bigger than the entire editor file). Given the ease of doing so many incredible things in SNOBOL4, a programmer must use caution lest programming near-miracles performed using it become expected every time! There is a minor disadvantage: the .EXE files, since they contain the complete runtime system, are individually (as a rule) quite a bit larger than either the source or .SAV files would be. One special consideration pointing to Macro SPITBOL: it uses the same Realia Record Manager as Realia COBOL apparently does. Therefore, if you use Realia COBOL, and any of its proprietary data file formats, you should find that your data files will be easily and naturally accessed by Macro SPITBOL as well, perhaps making it therefore your version of choice. Macro SPITBOL, as with all other current SNOBOL4 releases for the PC, supports path names and subdirectories. Unfortunately, there are a variety of problems with Macro SPITBOL too. Among these are the following: There is no floating point whatsoever, whether you have an 8087 or not. This is a potentially significant problem for some applications since Macro SPITBOL supports only 16-bit integers. Macro SPITBOL uses a small memory model, which limits the size of combined program and data space to 64K. Since SNOBOL4 can make such effective use of large data storage, this is truly a limitation. This problem, for example, makes it (unfortunately) impractical to run the SPACE utility under Macro SPITBOL. To save on memory space, run-time error messages consist of a cryptic three-digit number which requires the manual to decode. This is doubly inappropriate now that memory costs so little, and since Macro SPITBOL, with its small memory model organization, doesn't let you use all that extra memory for data or program code anyway. It does, however, help reduce the size of the .EXE files. page 179 Macro SPITBOL is somewhat buggy. In particular, there seem to be problems with the way it handles end-of-record marks on output files (it doesn't always seem to include the line feed, which causes problems when its output is directed to the screen). Finally, technical support with Macro SPITBOL seems to be nonexistent. Bugs (as mentioned above) that I've reported have never been fixed, and I've never even received responses to my letters. (But then, the first time I tried to buy the software, my letter was returned by the post office). Macro SPITBOL does not seem to be very actively supported. This is especially disappointing, since it is the most expensive implementation of the three MS-DOS versions. It appears that Macro SPITBOL is a product of the same people that do REALIA COBOL (which is also an expensive commercial product). Can anyone report whether their technical support for COBOL is better than what they provide for Macro SPITBOL? I am told that a revision to Macro Spitbol will be released in late 1987 or early 1988, and hopefully it will resolve some of the above problems. As of this writing, I have not seen the revision and so must reserve comment. 59.3.3 Vanilla SNOBOL4 by Mark B. Emmer Vanilla SNOBOL4 is a simplified, "freeware" version of Catspaw SNOBOL4+ as described below. "Freeware" means that you can freely give (complete) copies of Vanilla SNOBOL4 to anybody you like. There is no requested "registration fee" for your continued use of Vanilla SNOBOL4. Vanilla SNOBOL4 is primarily being offered to give interested programmers (and even non-programmers!) a chance to play with and learn this fascinating language. It comes with a comprehensive 150+ page User's Guide on the diskette, with both tutorial and reference sections. Even if you are not a programmer, you will most likely find that Vanilla SNOBOL4 is easier to learn -- and use effectively -- than BASIC, C, Pascal, Modula-2, or other primitive languages. The tutorial and user's guide (actually a subset of the excellent manual which is delivered with SNOBOL4+) is the best-written SNOBOL4 tutorial I've yet seen, which makes the package worth getting even if you end up using something else. page 180 This version is great for things like simple file conversion programs and the like. Many users will probably find that this version does most of what they need to do with SNOBOL4, and you can't beat the price. This version is basically similar to SNOBOL4+, but with a feature set closer to that of Minnesota SNOBOL4. Program and data space is limited to 30K (even smaller than SPITBOL's). Integers are 16-bits, and real (fractional) numbers are not supported. SPITBOL extended operators are not included. There is no support for random-access or binary files, no ability to generate .SAV object files, and no built-in SORT function. Likewise, loadable assembler functions are not supported. So what is included? Basically all of "green book" (classic) SNOBOL4, except for LOAD/UNLOAD, BACKSPACE, (thankfully) Fortran I/O, 32-bit integers and real numbers. Paths and subdirectories in file names are included. Execution speed is generally comparable to SNOBOL4+. Vanilla SNOBOL4 does not require PC compatibility, which should be very good news indeed for users of non-PC- compatible MS-DOS machines. Vanilla SNOBOL, like SNOBOL4+, comes with a sizeable collection of sample source programs to get you started. The 30K limitation is not necessarily a serious problem, for most users, since many SNOBOL4 programs tend to be quite small anyway. (It does, of course, affect you if you need large arrays or tables). The major advantage of this version is its availability and its price: anyone who has it can give you a copy, and it costs you nothing to try it out. Any programs you write with it will upgrade easily to SNOBOL4+ when you decide you're ready for the more advanced features. Meanwhile, you get a tool you'll be able to use to whip out amazing things, and quickly. You risk nothing other than addiction! (However, that, it must be said, is a very real risk indeed!). The main nice things about there being a completely freeware version of SNOBOL4 are that: 1) If you are a consultant, you can give the complete system to your clients, along with your own source programs, which they will therefore be be able to make minor changes to and recompile if needed, and completely without language royalties or licensing hassles; page 181 2) You can share your SNOBOL4 programs with your friends, in source form, so they can actually see how fiendishly clever you really are; 3) If you're just interested in learning SNOBOL4, or even just in learning something about how to program, you can get a copy of Vanilla SNOBOL4, with its over 150 pages of first-class documentation on the disk, for essentially free. You are encouraged to give copies to your friends at work, school, the country club or your computer club. Whatever. (If you give a copy to the folks at your local computer store, you might just be able to convince them to carry SNOBOL4+!). 59.3.4 Catspaw SNOBOL4+ by Mark B. Emmer Catspaw SNOBOL4+, like Minnesota SNOBOL4, originated from Bell Labs' macro implementation of SNOBOL4. However, SNOBOL4+ has been very well adapted to the MS-DOS environment. It has been significantly extended, and includes most of the language extensions and features found in Macro SPITBOL, both in terms of additional built-in functions and additional language operators and constructs. SNOBOL4+ fully supports path names and subdirectories. The speed of SNOBOL4+, while substantially slower than Macro SPITBOL, is thirty to fifty percent faster than Minnesota SNOBOL4. (I have not run significant benchmarks as yet using Minnesota SNOBOL4.2, which is supposed to be faster than its previous version). SNOBOL4+ permits very large program and data area, up to a combined total of around 300K bytes. This is in addition to SNOBOL4+ and MS-DOS's own code requirements, meaning that SNOBOL4+ can effectively use most of the memory available in even a 640K processor, especially if you have some memory-resident spoolers or whatever running concurrently. SNOBOL4+ supports only 16-bit integers, but supports floating point with or without the presence of an 8087 (it uses the 8087 if present). The available precision allows up to 15 decimal digits of precision in floating point numbers, if necessary, largely alleviating any problems of 16-bit integer size. A special option allows integers to automatically be converted to real upon overflow. page 182 SNOBOL4+ will generally run fine even on non-100%-compatibles. If your machine runs any version of MS-DOS or PC-DOS, it will probably run Catspaw SNOBOL4+ without any problems, even if you have had difficulties running other software designed for PC-compatibles. SNOBOL4+ can generate .SAV files which run under a public-domain runtime package (SNORUN.EXE, distributed with these utilities). The .SAV files cannot be readily turned back into source code, so distributed software can be protected. The resulting programs (in .SAV file format) can be sold or distributed without royalty or other licensing hassles. SNOBOL4+ can handle binary files, meaning that it is not limited to handling purely text files. Its files can contain any characters, including binary zeros or anything else. SNOBOL4+ allows executing of any DOS commands as a subroutine. This permits the writing of "smart" supervisors, which can intelligently control a "batch file" of other programs. Input and Output files may be piped or redirected using standard MS-DOS techniques, permitting the writing of "filters" using SNOBOL4+. For those with more intensive data file problems (which require access to ISAM files, for example) an interface to the well-regarded BTRIEVE file management package is available for SNOBOL4+. SNOBOL4+ permits access to MS-DOS environment strings. Another exciting feature is a highly unusual, remarkable and intriguing "fuzzy match" capability, implemented with the aid of special hardware support (the board is optional at extra cost). SNOBOL4+ is under active development and nearly constant improvement, by its author, Mark B. Emmer, who derives his entire income from SNOBOL4+ and related products. This means that technical support is outstanding, his commitment is total, and any bugs that have turned up are fixed immediately. The current version is exceedingly robust and as bug-free as almost anything I've ever used. page 183 SNOBOL4+ comes with an extremely fine tutorial and reference manual, and a very large collection of something like sixty demonstration and example programs and utility subroutines. These cover a very wide range, but include a set of basic windowing routines and a routine which gives access to nearly any MS-DOS function desired. Assembly language routines for other functions may be loaded dynamically at run-time and may be included in the .SAV files created for distribution. (My DIRTREE utility, for example, as included in this set, contains an assembler-language module I use to access the disk directory entries). In addition to SNOBOL4+, Catspaw distributes a number of other good items of interest to SNOBOL4 programmers, including books and other material. They have even gone to the trouble to have one of the classic (and remarkable!) SNOBOL4 books, "Algorithms in SNOBOL4," by Gimpel, reprinted (it has been out of print for several years). They also sell ICON material (ICON is a descendant language of SNOBOL4, also developed by Ralph E. Griswold, one of the original developers of SNOBOL). Catspaw even has SNOBOL4+ and ICON T-shirts! Of course, Catspaw is also the source for Vanilla SNOBOL4, described earlier. Recent additions to the Catspaw stable of "power tools for programming" include a 68000/UNIX version of Macro Spitbol, (presumably without the frustrating bugs which afflict MS-DOS Macro Spitbol's file system), and a Macintosh version (expected in Fall 1987). Atari and Amiga versions are expected to follow. Catspaw SNOBOL4+ is definitely on the leading edge, the emerging SNOBOL4 standard-setter for MS-DOS. 59.4 Recommendation Anyone who has had a PC or compatible for any length of time either has encountered (or will) a case where they need to make some changes to a text file, (which might be data, a program, a batch file, a "make" file, or anything like that) and where those changes are too complicated to do page 184 automatically with their editor's "Search and Replace" function. These are the frustrating times when you look at the problem, and think, "I really ought to write a program to do this," but end up spending several tedious hours with the editor, making the change manually, instead. Having a good version of SNOBOL4 at your disposal will go a long way to making these painful manual editing sessions a thing of the past. It would be hard to imagine a more useful and powerful tool for general-purpose file manipulation. It is truly hard to imagine how I got along without it. Now that you've decided that you, too, need to have SNOBOL4, which one to buy? I bought, and have used, all four of the implementations I've reviewed above. The Minnesota SNOBOL4, by Viktors Berstis, is certainly usable but its numerous faults, despite its low cost, prevent me from recommending it. It, in all fairness, would be a terrific product in the absence of the better ones being available. Vanilla SNOBOL4 is a mixed bag. It doesn't have all the nice support features of SNOBOL4+, but is a great low-risk way to decide if you like the kind of features that SNOBOL4 has to offer. Even if you want to spend little or no money, it's hard not to imagine Vanilla SNOBOL4, at least, being worth having. If you are a teacher, the advanced features you can teach with SNOBOL4 (including trees, lists and recursion), along with the freely reproducible manual and the lack of royalties or licensing, regardless of how many machines your school has, are a relief for tight budgets. Catspaw SNOBOL4+, by Mark B. Emmer, is definitely the class act among the four versions I've used. It is solid, well-suited to MS-DOS use, and very capable. It is very well supported, and comes with first-class documentation. His included tutorial is usable by anyone familiar with programming concepts: if you can write simple programs in BASIC, you can learn to use SNOBOL4+. This version is highly recommended. (Note: make sure you get version 2.0 or above. Earlier versions did not have path support or provision for .SAV files). If you have a PC or compatible and do anything with it, you should have SNOBOL4+ in your toolbox. SNOBOL4+ lists, in the United States, for around $100. page 185 Macro SPITBOL, by Robert B. K. Dewar, is a mixed blessing. Its speed is certainly nice. It is expensive, however; it costs around $200. Technical support is spotty at best, which would be less serious if the product were less buggy. When Macro SPITBOL programs work, (and with some tinkering, they can usually be made to work) they generally work extremely well. The speed increase, for programs that fit within its limited program and data space, is exhilarating. But, not all programs will port gracefully to Macro SPITBOL. My recommendation is Catspaw SNOBOL4+. This offers a tremendous balance of power, features, reliability, support, and a reasonable price. Once you buy SNOBOL4+, and use it for a while, you might be ready to experiment with Macro SPITBOL. If you end up using SNOBOL4+ a lot, it would probably be worth your time and money invested in a copy of Macro SPITBOL as well. But, don't expect a lot of hand-holding, or expect Macro SPITBOL to completely replace Catspaw SNOBOL4+ for you. It probably won't. If you can't get your friendly local computer dealer to get SNOBOL4+ for you, join the club. It's amazing how many unenlightened dealers seem content to try to constrain their customers to "stone-age" software tools ("...but everyone else seems to like 'xxxx'." GRRRR!). I will be glad to get a copy of SNOBOL4+ to you. Please write for my current price list. page 186 60. LEGALITIES This chapter covers some of those legalities that always seem to appear in software documentation: 60.1 License to Distribute Basically, anyone having the shareware copy of this package is encouraged to give away complete and unmodified copies to their friends and business associates. The registered copy uses a different version of the SNOBOL4+ runtime package and is not to be given out, to avoid confusion. For the complete details on permission being granted to redistribute this product, please see the license agreement found towards the beginning of this document. 60.2 Disclaimer of Liability In consideration of the vagaries of shareware distribution and the low price of these utilities, the author disclaims any and all responsibility for damages resulting from their use, or inability to use, and/or for any other reason whatsoever. The author has used each of these utilities and believes each one to operate reliably as described in this document, (and would sincerely appreciate that any problems encountered be reported to him) but the sole responsibility for the selection and use of these utilities must rest with the user. In particular, one should never modify or overwrite any critical file unless it has been backed up somewhere. This precaution is for your own protection, and is always a good habit to get into with any software product. page 187 60.3 Trademark and Product Acknowledgements This section acknowledges the names and trademarks of various companies as mentioned in assorted places throughout this document. AMIGA is a trademark of Commodore International. AMPEX is a trademark of Ampex Corporation. ARC, MSCRIBE and DATAPOINT are trademarks of Datapoint Corporation. BITCOM is a product of BIT Software, Inc. BTRIEVE is a product of Softcraft, Inc., a Novell Company. C, SNOBOL, SNOBOL4, and UNIX are trademarks and/or products of AT&T. COMPUSERVE and EMAIL are products and/or services of CompuServe Information Services, Inc. CREF, MASM, MICROSOFT, MS-DOS, MS/DOS, SYMDEB and MICROSOFT WORD refer to trademarks and/or products of Microsoft Corporation. DBASE III is a trademark of Ashton-Tate. DBS-KAT is a product of Applied Foresight, Inc. DRVSPKR and SPACE are products of Noah Systems. DVED and SPITBOL are trademarks and/or products of Dewar Information Systems. ICON is a product of the University of Arizona. Macintosh is a product of Apple Computers, Inc. MINNESOTA SNOBOL4 is a product of Berstis International. page 188 PC, XT, AT, PL/1, and IBM are trademarks and/or products of International Business Machines Corporation. PC-TOOLS is a product of Central Point Software, Inc. PIANOMAN and PLAYRPNO are products of Neil Rubenking. PKARC and PKXARC are products of PKWARE, Inc. REALIA COBOL is a product of Realia Corporation. SIDEKICK, SUPERKEY are trademarks and/or products of Borland International. SNOBOL4+ is a product of Catspaw, Inc. WORDSTAR and WORDSTAR 2000 are trademarks and/or products of MicroPro International Corporation. POSTSCRIPT and VELOBIND are also trademarks of their respective owning corporations. page 189 61. MACRO SPITBOL ERROR CODE NUMBERS Those SNOBOL4 programs contained within this package in the form of .EXE files (DIFFER.EXE, for example, but not of course SNORUN.EXE) produce error numbers rather than complete error messages. This decision, though regrettable, is understandable in light of the desire to reduce the size of the .EXE files produced by Macro SPITBOL. If you should happen to receive one of these numbered error codes, you will find the following table handy. For each possible error code number, it lists the matching error message. Most of these error messages are unlikely to turn up, and are more applicable to compile-time problems, but are listed here regardless for the sake of completeness. 1 Addition left operand is not numeric 2 Addition right operand is not numeric 3 Addition caused integer overflow 4 Affirmation operand is not numeric 5 Alternation right operand is not pattern 6 Alternation left operand is not pattern 7 Compilation error encountered during execution 8 Concatenation left opnd is not string or pattern 9 Concatenation right opnd is not string or pattern 10 Complementation operand is not numeric 11 Complementation caused integer overflow 12 Division left operand is not numeric 13 Division right operand is not numeric 14 Division caused integer overflow 15 Exponentiation right operand is not numeric 16 Exponentiation left operand is not numeric 17 Exponentiation caused integer overflow 18 Exponentiation result is undefined 19 Exponentiation right operand is negative 20 Goto evaluation failure 21 Function called by name returned a value 22 Undefined function called page 190 23 Goto operand is not a natural variable 24 Goto operand in direct goto is not code 25 Immediate assignment left operand is not pattern 26 Multiplication left operand is not numeric 27 Multiplication right operand is not numeric 28 Multiplication caused integer overflow 29 Undefined operator referenced 30 Pattern assignment left operand is not pattern 31 Pattern assignment right operand is not string 32 Subtraction left operand is not numeric 33 Subtraction right operand is not numeric 34 Subtraction caused integer overflow 35 Unexpected failure in -NOFAIL mode 36 Goto abort with no preceding error 37 Goto continue with no preceding error 38 Goto undefined label 39 External function argument is not string 40 External function argument is not integer 41 Field function argument is wrong datatype 42 Attempt to change value of protected variable 43 ANY evaluated argument is not string 44 BREAK evaluated argument is not string 45 BREAKX evaluated argument is not string 46 Expression does not evaluate to pattern 47 LEN evaluated argument is not integer 48 LEN evaluated argument is negative or too large 49 NOTANY evaluated argument is not string 50 POS evaluated argument is not integer 51 POS evaluated argument is negative or too large 52 RPOS evaluated argument is not integer 53 RPOS evaluated argument is negative or too large 54 RTAB evaluated argument is not integer 55 RTAB evaluated argument is negative or too large 56 SPAN evaluated argument is not string 57 TAB evaluated argument is not integer 58 TAB evaluated argument is negative or too large 59 ANY argument is not string or expression page 191 60 APPLY first arg is not natural variable name 61 ARBNO argument is not pattern 62 ARG second argument is not integer 63 ARG first argument is not program function name 64 ARRAY first argument is not integer or string 65 ARRAY first argument lower bound is not integer 66 ARRAY first argument upper bound is not integer 67 ARRAY dimension is zero, negative or out of range 68 ARRAY size exceeds maximum permitted 69 BREAK argument is not string or expression 70 BREAKX argument is not string or expression 71 CLEAR argument is not string 72 CLEAR argument has null variable name 73 COLLECT argument is not integer 74 CONVERT second argument is not string 75 DATA argument is not string 76 DATA argument is null 77 DATA argument is missing a left paren 78 DATA argument has null datatype name 79 DATA argument is missing a right paren 80 DATA argument has null field name 81 DEFINE first argument is not string 82 DEFINE first argument is null 83 DEFINE first argument is missing a left paren 84 DEFINE first argument has null function name 85 Null arg name or missing ) in DEFINE first arg. 86 DEFINE function entry point is not defined label 87 DETACH argument is not appropriate name 88 DUMP argument is not integer 89 DUMP argument is negative or too large 90 DUPL second argument is not integer 91 DUPL first argument is not string or pattern 92 EJECT argument is not a suitable name 93 EJECT file does not exist 94 EJECT file does not permit page eject 95 EJECT caused non-recoverable output error 96 ENDFILE argument is not a suitable name page 192 97 ENDFILE argument is null 98 ENDFILE file does not exist 99 ENDFILE file does not permit endfile 100 ENDFILE caused non-recoverable output error 101 EQ first argument is not numeric 102 EQ second argument is not numeric 103 EVAL argument is not expression 104 EXIT argument is not suitable integer or string 105 EXIT action not available in this implementation 106 EXIT action caused irrecoverable error 107 FIELD second argument is not integer 108 FIELD first argument is not datatype name 109 GE first argument is not numeric 110 GE second argument is not numeric 111 GT first argument is not numeric 112 GT second argument is not numeric 113 INPUT third argument is not a string 114 Inappropriate second argument for INPUT 115 Inappropriate first argument for INPUT 116 Inappropriate file specification for INPUT 117 Input file cannot be read 118 LE first argument is not numeric 119 LE second argument is not numeric 120 LEN argument is not integer or expression 121 LEN argument is negative or too large 122 LEQ first argument is not string 123 LEQ second argument is not string 124 LGE first argument is not string 125 LGE second argument is not string 126 LGT first argument is not string 127 LGT second argument is not string 128 LLE first argument is not string 129 LLE second argument is not string 130 LLT first argument is not string 131 LLT second argument is not string 132 LNE first argument is not string 133 LNE second argument is not string page 193 134 LOCAL second argument is not integer 135 LOCAL second argument is not a program function name 136 LOAD second argument is not string 137 LOAD first argument is not string 138 LOAD first argument is null 139 LOAD first argument is missing a left paren 140 LOAD first argument has null function name 141 LOAD first argument is missing a right paren 142 LOAD function does not exist 143 LOAD function caused input error during load 144 LPAD third agument not a string 145 LPAD second argument is not integer 146 LPAD first argument is not string 147 LT first argument is not numeric 148 LT second argument is not numeric 149 NE first argument is not numeric 150 NE second argument is not numeric 151 NOTANY argument is not string or expression 152 OPSYN third argument is not integer 153 OPSYN third argument is negative or too large 154 OPSYN second argument is not natural variable name 155 OPSYN first argument is not natural variable name 156 OPSYN first argument is not correct operator name 157 OUTPUT third argument is not a string 158 Inappropriate second argument for OUTPUT 159 Inappropriate first argument for OUTPUT 160 Inappropriate file specification for OUTPUT 161 Output file cannot be written to 162 POS argument is not integer or expression 163 POS argument is negative or too large 164 PROTOTYPE argument is not valid object 165 REMDR second argument is not integer 166 REMDR first argument is not integer 167 REMDR caused integer overflow 168 REPLACE third argument is not a string 169 REPLACE second argument is not string 170 REPLACE first argument is not string page 194 171 Null or unequally long 2nd, 3rd args to REPLACE 172 REWIND argument is not a suitable name 173 REWIND argument is null 174 REWIND file does not exist 175 REWIND file does not permit rewind 176 REWIND caused non-recoverable error 177 REVERSE argument is not string 178 RPAD third argument is not string 179 RPAD second argument is not integer 180 RPAD first argument is not string 181 RTAB argument is not integer or expression 182 RTAB argument is negative or too large 183 TAB argument is not integer or expression 184 TAB argument is negative or too large 185 RPOS argument is not integer or expression 186 RPOS argument is negative or too large 187 SETEXIT argument is not label name or null 188 SPAN argument is not string or expression 189 SIZE argument is not string 190 STOPTR first argument is not appropriate name 191 STOPTR second argument is not trace type 192 SUBSTR third argument is not integer 193 SUBSTR second argument is not integer 194 SUBSTR first argument is not string 195 TABLE argument is not integer 196 TABLE argument is out of range 197 TRACE fourth argument is not function name or null 198 TRACE first argument is not appropriate name 199 TRACE second argument is not trace type 200 TRIM argument is not string 201 UNLOAD argument is not natural variable name 202 Input from file caused non-recoverable error 203 Input file record has incorrect format 204 Memory overflow 205 String length exceeds value of MAXLNGTH keyword 206 Output caused file overflow 207 Output caused non-recoverable error page 195 208 Keyword value assigned is not integer 209 Keyword in assignment is protected 210 Keyword value assigned is negative or too large 211 Value assigned to keyword ERRTEXT not a string 212 Syntax error. Value used where name is required. 213 Syntax error. Statement is too complicated. 214 Bad label or misplaced continuation line. 215 Syntax error. Undefined or erroneous entry label 216 Syntax error. Missing end line 217 Syntax error. Duplicate label 218 Syntax error. Duplicated goto field 219 Syntax error. Empty goto field 220 Syntax error. Missing operator 221 Syntax error. Missing operand 222 Syntax error. Invalid use of left bracket 223 Syntax error. Invalid use of comma 224 Syntax error. Unbalanced right parenthesis 225 Syntax error. Unbalanced right bracket 226 Syntax error. Missing right paren 227 Syntax error. Right paren missing from goto 228 Syntax error. Right bracket missing from goto 229 Syntax error. Missing right array bracket 230 Syntax error. Illegal character 231 Syntax error. Invalid numeric item 232 Syntax error. Unmatched string quote 233 Syntax error. Invalid use of operator 234 Syntax error. Goto field incorrect 235 Subscripted operand is not table or array 236 Array referenced with wrong number of subscripts 237 Table referenced with more than one subscript 238 Array subscript is not integer 239 Indirection operand is not name 240 Pattern match right operand is not pattern 241 Pattern match left operand is not string 242 Pattern return from level zero 243 Function result in NRETURN is not name 244 Statement count exceeds value of STLIMIT keyword page 196 245 Translation/execution time expired 246 Stack overflow 247 Invalid control line 248 Attempted redefinition of system function 249 Expression evaluated by name returned value 250 Insufficient memory to complete dump 251 Keyword operand is not name of defined keyword 252 Error on printing to interactive channel 253 Print limit exceeded on standard output channel 254 Erroneous argument for HOST 255 Error during execution of HOST 256 SORT/RSORT 1st arg not suitable ARRAY or TABLE 257 Erroneous 2nd arg in SORT/RSORT of vector 258 SORT/RSORT 2nd arg out of range or non-integer 259 FENCE argument is not pattern 281 CHAR argument not integer 282 CHAR argument not in range 291 SET first argument is not a suitable name 292 SET first argument is null 293 Inappropriate second argument to SET 294 Inappropriate third argument to SET 295 SET file does not exist 296 SET file does not permit setting file pointer 297 SET caused non-recoverable I/O error 298 External function argument is not file 299 Internal logic error (unexpected PPM branch) page 197 62. ABOUT THE AUTHOR I think it is important for those of us in the computing profession to get to know each other. Just as "ShareWare" software can help to extend the reach of the programs we write, hopefully this concept will help to extend our interpersonal network of contacts as well. It is not necessary that software authors be condemned to a life of anonymity! I encourage other authors of "ShareWare" products to further this personal and professional networking by telling us about themselves as well. The utility programs in this package have been written during 1986, 1987 and 1988 by Gordon E. Peterson II (except as noted, when they have been adapted from the works of other, sometimes anonymous, authors. Thanks to all!). They represent some of the results on ongoing development efforts in many diverse areas. I have been writing computer system software in assembly language since about 1970, starting as a Computer Science major at the University of Illinois in Champaign-Urbana. This was my first exposure to IBM equipment, learning on their 360/75 system (a BIG computer at the time, with a million bytes of main memory and two megabytes more of slow Ampex bulk core memory. It is astonishing to realize that I have nearly that much memory, and much faster too, on the machine on the table in front of me). This is also when I got my first exposure to PL/1, and SNOBOL4. Along with many interesting PL/1 programs, (some quite large!), I also wrote a very good SPITBOL program to convert Fortran source programs to PL/1. During a little over nine years after getting my degree, I worked in Advanced Product Development at Datapoint Corporation. On the off chance that you might be familiar with Datapoint, I was the developer of the "Dot-Series" disk operating systems there, being responsible for DOS.A, DOS.B, DOS.C, DOS.D, and DOS.E. I was the author of their high-speed disk BACKUP and COPY programs, the REFORMAT utility, and their DUMP utility, among others. I wrote their Multi-Partition Virtual Machine facility, called PS (for Partition Supervisor), and their high-performance print unspooler (called UNSPOOL). My most notable software product I created there was the DOS ARC System, which was the world's first commercially successful local area network. This product eventually sold over a billion dollars' worth of hardware for Datapoint. page 198 At various other stages of my career, I have worked with quite a variety of machines and equipment, ranging from several different kinds of mainframes to microprocessor control software for a very sophisticated discotheque lighting control system; an advanced credit card telephone; a museum exhibit controller running four stereo tape decks, thirty loudspeakers and a similar number of spotlights; to the development of least-cost-routing software controlling telephone central office switching equipment, to name just a few. As of this writing in August 1987, I am doing contract consulting work for a San Antonio based company, on assignment in Europe. I'm presently involved with industrial automation systems and local area networks. Besides computers, my other interests include video, stereo equipment, (and in fact most kinds of home electronics), massage, travel (especially interested in ocean liners and trains), Citroens (a French automobile), and meeting people. If you're ever on a cruise somewhere, and meet a longhaired, moustached, bearded and gregarious computer programmer, it might well be me. If you find these utilities to be useful for you, and decide to continue using one or more of them, please register as an official user. The price is inexpensive, just $35, which is less than one dollar for each of the utilities described herein. Your registration payment will get you a complete set of the utilities described above (other than those clearly indicated as program products, such as the SPACE utility, which are available as separate products), and will allow me to offer you periodic revisions and reduced-price upgrades to this package, which is under continually ongoing development. If you feel that these utilities are useful to you, but not -that- useful, please send a smaller amount, whatever you feel is right and just. (I hate to think, on the other hand, how many videogame cartridges I've bought for $35 each and never played more than once or twice). If you find that even one of these utilities is useful for you, $35 should not be unreasonable. Of course, if you feel they are worth more, greater amounts will certainly be gratefully received. (Don't be afraid to send a small amount! After all, money is still money). page 199 If you have systems or applications software design, development, evaluation or analysis needs, perhaps you might also be interested in my consulting services. Please contact me with your interests. Also, if you would just like to write, that is certainly welcome too! Perhaps I will reconnect with some old friends, and make some new ones too, this way. You can write to me at: Gordon E. Peterson II Noah Systems P.O. Box 40476 San Antonio, Texas 78229-1476 You can also reach me through CompuServe EMAIL. My CompuServe User ID is 75116,3524. (This is generally quicker than the post office, especially since, as of this writing in mid-1987, I am spending most of my time outside of the United States, and mail must be forwarded to me). I'm looking forward to hearing from you! page 200 63. LATEST VERSIONS OF THESE SNOBOL4+ UTILITIES Many of these utilities are under continuing development as ideas and the opportunities to improve them arise. In many cases, the shareware versions of the utilities lag behind the newest versions developed by the author. As mentioned earlier in this document, the only way to ensure that you have the newest and most useful versions of these utilities is to register with the author. This approach also has the advantage that it usually works out less expensive than having to download a revised version of the utilities from your local BBS, or to buy the diskettes again and again from your favorite shareware dealer. You also will have the advantage of direct support in your use of these utilities by their author. This chapter contains the version and release number of the most recent edition, as of the date this document was processed, of each program. In those cases where the program exists both as an .EXE file (generally produced by Macro SPITBOL) and as a .SAV file (produced by SNOBOL4+), the latest revision of each version is listed. NOTE: please note the time and date stamp on this print file. If it is not within the last few months from the date you are reading this, it is virtually certain that this document has been augmented and improved since the version you are reading. You might be interested to know that the listing in this chapter is automatically produced by yet another SNOBOL4+ utility, called BLDVERL. It reads through this users' guide, and finds the name of each utility documented herein. It then looks up the source file for each of the utilities, and scans through it to find the signon message containing the relevant version and release number. These are then summarized and written to a file, which is then appended to this document. The resulting document is processed with the REPAGIN8 utility, which intelligently paginates it, numbers the pages, formats and numbers the chapter and section headings, shifts the document over 20 columns to provide a left margin, and produces an (also paginated and page numbered) table of contents file. That table of contents file, followed by the main REPAGIN8 output file, are then appended with the MS-DOS COPY command, to produce the print file you received. page 201 If a version and release number in the listing below shows up as question marks, it indicates that the related program is generated somewhat differently from the others and was not located by the automated system which produces the version and release number listing. Please contact the author directly for the latest version and release information for such program(s). The following is the list of current versions of these utilities. This listing is current as of 05-24-88 15:14:16. ANGLICIZ.SAV 1.03 "Anglicize" Foreign Character Set ASMGEN2.SAV 1.1 Disassembly Supervisor ASMRECOV.SAV 1.2 Recover Assembler Source from Listing File ASMSTAT.SAV 1.2 Generate Assembler Program Statistics CASE.SAV 1.2 Case Conversion and Folding CHARDF.SAV 1.2 Characterize a Delimited File CHOPUP.SAV 1.00 Chop Up a File for Transmission CISSTRIP.SAV 1.04 Strip Junk from CompuServe Capture Files COMBINE.SAV 1.0 Combine Files and Eliminate Duplicates COPYSEG.SAV 1.01 Copy a File to Multiple Segments CPRANGE.SAV 1.2 Copy Ranges of Records DELALL.SAV 1.01 Delete All Matching Files DELIEOF.SAV 1.01 Find and Delete Internal EOF Marks DIFFER.EXE 1.01 Find Differences in Two Text Files DIRCMP2.SAV 1.02 Compare Files in Different Subdirectories DIRTREE.SAV 1.05 Make File of Subdirectories Present EXPTAB.SAV 1.01 Tab Character Expansion EXTEND.SAV 1.1 Extend a File (Recover Lost Data) FILEDUMP.SAV 1.1 Hexadecimal File Dump FMTHDLL ?.?? Format Hard Disk, Low Level GENTBLS.SAV 1.01 Generate Program Source Code Tables LASERPG.SAV 1.00 Multipage Output to Landscape Mode Printer LINEAN1.SAV 1.01 Serial Communications Analysis Aid LIST.EXE 1.03 (Yes, Another) Text File Lister LIST.SAV 1.04 (Yes, Another) Text File Lister MAKASEQ.EXE 1.1 Disassembly Aid (used with ASMGEN2) MAKDUMMY.SAV 1.4 Make Dummy Files for ARC'd Files MAKEALL.SAV 1.1 Convert a MAKE File to "ALL" Batch File page 202 MAKEMAKE.SAV 1.01 Build a Make File Based on Inclusions MAKERMAK.SAV 1.00 Build a Raw MAKE File MELIZA.SAV 1.05 Psychoanalysis Program (Famous Early AI Effort) MERGECMP.SAV 1.1 Merge WORD's .CMP User Dictionary Files MSCRIBE.EXE 1.04 Document Formatting and Entry Program OVER.EXE 1.03 Shift a Print File Over to the Right PADREC.SAV 1.03 Pad Records to a Fixed Size PLAYCVMS.SAV 1.1 SUPERKEY to DRVSPKR Format Converter PLAYCVT.SAV 1.1 PLAY file to DRVSPKR Format Converter PMUSCVT.SAV 1.1 Pianoman .MUS to DRVSPKR Format Converter PUBLBL.EXE 1.2 Public Label Inclusion Generator PUBLBL.SAV 1.3 Public Label Inclusion Generator REPAGIN8.SAV 1.7 Intelligent Document Pagination and TOC SAPPREF.EXE 1.1 Append Assembler Cross-Reference to Listing SPACE.SAV 1.15 Disk Space Management and Recovery Utility STRIPBS.SAV 1.1 Strip Backspace Characters from Text File TITLGEN.SAV 1.00 Generate a Title Page TOTSIZ.SAV 1.03 Total Size of Subdirectories TP.SAV 1.03 Wipe Clean the Tail End of a File TRUNCATE.SAV 1.1 Reduce the Size of a File TSELIM.SAV 1.1 Trailing Space Elimination TYPEOF.SAV 1.2 Characterize an ASCII Text File UNBACK.SAV 1.1 Recover BACKUP Files that RESTORE Won't UNOVER.SAV 1.03 Delete Leading Spaces in Text File WC.SAV 1.0 Word Count WFREQ.SAV 1.0 Word Frequency XTRCOMS.SAV 1.01 Extract Comments From Assembler Programs