============================================================================= >>> DRAFT <<< This document will eventually be expanded to provide detailed "how-to" for using swapdisks to advantage. INPUT FROM YOU, THE USERS, COULD HELP US A LOT. If you have suggestions, or if you know of ways to improve on the methods here described, please let us know! Michael Markov, P.O. Box 17, Lockwood, New York 14859 U.S.A. ============================================================================= HOW TO MAKE A SWAP PROGRAM WORK FOR YOU - by Michael Markov The following material is intended to provide "HOW-TO" information that could make future swapdisks at least as useful as a printed journal such as the CHHU Chronicle. Specifically, all users should be able to scan through a swap disk or tape almost as easily as he could scan a printed journal. This degree of convenience should be within the reach of HP-41/HP-75/HP-71 users who own or or have access to HP-IL mass storage and to an 80 column printer. The key to such ease of use is the consistant use of an agreed-upon format for both documentation and software contributed to future swapdisks. This proposed format is constrained by the equipment available to the end users of future swapdisks. After this standard is adopted, a few utility programs would allow users to scan through a table of contents, and view or print whatever may grab their interest. Please note that most of the needed utilities already exist, if only in prototype form. Why not put them to good use? Briefly -- to the extent possible, all material should be in the form of TEXT (ASCII, or LIF1) files. Furthermore, these files should have a maximum of 80 characters per line, and all such characters should be printable, ie., with a value between 32 and 126 inclusive. In other words, series 70 files should be changed into TEXT / ASCII / LIF1 files with the TRANSFORM command, and source code should be provided for all contributed BIN or LEX files... In fact, contributors probably should provide BOTH a "TEXT" version and a compiled (assembled) version. This would help users avoid most problems associated with resource allocations, while also allowing other folks to view (print) the file. Effectively, this provides us with an "image" that can be viewed or printed without further processing. With HP-IL peripherals, this also means that the text can be transfered directly from the mass storage unit to the selected printer or display device, without copying the entire file into often inadequate RAM. The programs that allow you to print TEXT files, irregardless of memory limitations are all available on CHHU03 or SWAP08. See HP-41 : CPMM, CPMM2, CP21, CPDEVIL, CPDEV2, CP75 or HP-75 : PRTEXT75, or HP-71 : PRINTEXT, READ75T. Minor modifications would readily slow down the output to allow you to view the file(s) on a video monitor at a comfortable rate, minimizing the use of expensive paper. NOTE: The files on SWAP08 are improved versions, with documentation available on SWAP08. See file INDCP for further details. Since series 70 users usually also own HP-41 machines, they should not run into difficulty with HP-41 files -- sorry, the convenient TRANSFORM command is not implemented on the HP-41. However, series 70 users who do not have HP-41 machines CAN print out HP-41 PRogram files with the help of existing software. See TAPE41 by W.C. Wickes (HP-71 User Lib. program #03193-71-7), and TPRP41D (HP-75, on swadisk CHHU03). FORMAT SELECTION CRITERIA : It is important to realize that the vast majority of handheld users own a bare minimum of equipment. Typically, this consists of EITHER an HP-41 OR an HP-75 OR an HP-71. Information and programs are usually saved on magnetic cards. Expensive HP-IL modules and peripherals, if available, are shared between several people. Also, in the past year I have noticed that there is a growing number of users who use IBM PC clones as a low cost alternative to expensive HP-IL peripherals. We shall assume that the end user(s) of the swapdisks have access to an HP-IL mass storage device and to an 80 column printer. This should be all you need to print the documentation provided on the disk, and to copy selected software to magnetic cards. This time consuming process would presumably be a group activity carried out at local user group meetings. Here we may need to deal with any HP-IL mass storage device (CMT RAMDISK, or HP-9114, or cassette drive) The 80 column printer may be any HP-IL printer, or possibly some other printer connected to the loop using some interface, including IBM clones with an HP-82973 HP-IL interface card; running Southern Software's LINK1.02. See EduCalc catalog #35 pg. 94 & 95, items #82973 at $124.95 and S-785 at $75.95. CHHU member can get a nice discount by ordering directly from Southern Link, I believe the price for members is $60.00. This wide variety of printer / display devices precludes embedding printer control characters, escape sequences, or formatter commands. For much the same reasons, contributors are asked to try to make sure that the "images" they provide meet the above criteria. The important benefits of the proposed format are that people will be able to produce legible printed copies of swapdisk material far faster than is possible with text formatters, and it eliminates the need for a formatter. This means that HP-41 owners can enjoy swapdisks as much as series 70 owners. MASS STORAGE SELECTION CRITERIA: The primary reason for selecting HP-9114 drives and DOUBLE SIDED, DOUBLE SIDED (DSDD) 3.5" disks as the medium of choice for swapdisk distribution is storage capacity and the fact that we can make multiple copies of entire DSDD disks in approximately 5 minutes, as compared to 20 or more minutes to make copies of cassette tapes. In practical terms, this means that I can easily make 5 copies of a disk in about 1/2 hour, using the two HP9114 drives I own, while copying an equivalent amount of data on on cassettes would take some 10 hours (6*5*20 minutes). Please note the emphasis on Double Sided, Double Density -- this is very important. People on the lookout for low cost disks will find amazing bargains, only to find out later that the disks in question are either single density or single-sided... The storage capacity of such disks can be as low as 40% of the standard DSDD HP disk. Needless to say, such disks must be specially formatted. In some cases, the disks are not compatible with the HP9114 drives. So, what does happen when I get a strange disk in the mail? Well, I assume that folks will alway be kind enough to send DSDD disks. When I (ususally) find out that the disk has not been formatted, I use the INITIALIZE command to rectify the matter. This is a relatively unsophisticated command - the HP-71 does not seem to have any means of determining what kind of disk you feed the HP9114, so, usually, you get no error messages. Next, I try to use MCOPY71 to make the copy. Since the MCOPY71 routines trigger a direct device to device transfer with NO testing, again, there are no error messages. All that happens is that the destination drive stops storing information when the non-standard disk is full. So, if I went to the kitchen for a cup of coffee, everything looks great -- but the disk returned is definitly NOT safe to use. If I happen to see that the destination disk stopped early, I then would have to attempt to format the disk single-sided, and then use BCOPY to transfer the information to the disk, which is MUCH slower. Here, I am often tempted to just return the disk as is, with an explanation of the problem. The above paragraph should not be misunderstood. I do not care whether you use HP, SONY, MAXWELL or any other brand, as long as it is compatible with the HP9114 and the HP-71, and has the standard 630K storage capacity. This is also the reason I ask people to send FORMATTED disks - preferably used ones of known capacity. The major disadvantage of Hewlett-Packard's HP-IL disk drives is that the power supplies cannot sustain continuous use, even when plugged into an AC source. Reserve power packs, HP's recommended solution, are not satisfactory, especially when using MCOPY -- if we assume fully recharged battery packs, you SHOULD be able to carry out 5 MCOPY cycles. In the real world, batteries are rarely above 80% charge, and it would be nice if you could use your drives for normal file COPY operations after making a few MCOPYies.. The solution is a battery eliminator. These are available for both the cassette drive and the HP-9114. See CHHU V2N3P32 for the "Octopus" system, by LF Consulting, P.O. Box 20201, Orlando, Florida 32814 USA. You may want to get the "HP-9114 Empowerer" ($145/$199) from Personalized Software, P.O. Box 869, Fairfield, Iowa 52556. Personally, I use a much less espensive "home-made" power supply built by a friend. See schematic by RJN, enclosed. (Copies available on request). In order to make sure that the copies you make are good, you should print out the contents of the last file on the destination disk. If the output is OK, then the rest of the disk should also be OK. Use the CP/PRTEXT75/PRINTEXT programs if possible, since this prevents the "Memory Lost" associated with copying bad files to RAM. FORMATTING YOUR CONTRIBUTIONS: The easy way to prepare documentation for swapdisks is to use a fancy word processor on a desktop machine. This documentation can be downloaded to series 70 machines via RS-232 or HPILLINK. Those of us who do not have access to such facilities must make do with text editing capabilities built into our machines. HP-41 : HP-41 owners should use the ED function built into CX machines / Extended Functions modules if available. If not, write a program consisting of only text lines. In either case, it is very difficult to produce a well formatted output. We need a program that will help us do the job. Until someone does the job, this is the best that can be done. Hopefully, someone with an HP-71 & text formatter will reformat the file before it is stored on a swapdisk. (I believe we should be able to do the job easily enough with the DEVIL module IO buffer. I'll have to try one of these days. HINT: a simple loop would copy data from the ALPHA registers to the buffer, until PT? returns a value larger than 80. Then, do a search to find the last space prior, transfer junk back to ALPHA, then to a text file... Easy concept, but complex in implementation! A file re-formatter would probably be better, as it could do the work while you do something else. HP-75 : HP-75 machines have a wonderful text editor. If you have an I/O ROM, you can avoid making lines longer than 80 characters with the MARGIN option. See also the one-line editor "TE" by ????????, on the CHHU01 swap disk. Finally, if you have a video monitor, you have available an excellent full-screen editor. See files VE, VEMAN and VELEX on swapdisk CHHU04, by Stefano Piccardi (I think). HP-71 : The HP71 text handling capability is not built-in. The FORTH/ASSEMBLER, Text Editor or WorkBook ROMs (any will do) provide this capability. If none of these are available, you can manage quite well without by editing BASIC files that consist of comments (!) lines. Better yet -- put all of the documentation for a given BASIC file right into the file, as additional comments lines. Once again, a MARGIN keyword is available to help prevent line length overflow. See swapdisk CHHU05. HP's Text Formatter ROM, used in conjunction with the EDRDPRAM program (see swapdisk CHHU03), allows us to produce a formatted file in RAM. This is convenient, since it allows you to edit the file freely, make changes to your heart's content, and still end-up with a nicely formatted RAM file. This capability is also provided with additional features by Tapani Tarvainen's XEDFORM(P) programs, which are available on the CHHU04 and CHHU06 disks. Also, the FINPUT keyword in JPCLEX is opening many interesting possibilities. Finally, HP-71 full screen editors similar to VE (HP-75) exist, see FSEDIT on CHHU06, which came from Australia, and VE71 by Stefano Piccardi and Stefano Tendon in Italy. VE71 was originaly writen for the CHHU ROM project. VE71 has not yet been released as the authors are considering alternatives such as offering it to the Paris ROM project or, possibly, marketing through Educalc. (Excellent screen editor, surpassed only by that of my desktop machines.) Incidentally -- in order to test the above suggestions, I created the file you are now reading on my HP-71, using the FORTH / ASSEMBLER editor, with the help of the Margin keyword. This was much slower than typing on a portable, but the result seems to be of reasonable quality. Still, I expect that writing improved text editors / formatters will be a challange that will keep many of us busy for a long time to come. In particular, we need a good HP-41 formatter. The goal should be minimizing memory requirements without sacrificing execution speed. DUPLICATING SWAPDISKS / TAPES: MCOPY functions for duplicating mass storage media are provided for both the HP-41 and the HP-75, as follows: HP-41 : I/O ROM. Limited to copying media whose capacity is equal to that of the Cassette Drive (130K). Also available on the Auto Start / Duplication ROM. HP-75 : MCOPY is included in both the I/O ROM, and in the MCOPY (User Library) LEX file. Unfortunatelly, HP writen MCOPY keywords have built-in safeguards that, among other things, are intended to prevent unauthorized duplication of private files. These features occasionally cause problems when you attempt to MCOPY disks or tapes with, for example, "unknown" file types such as HP-71 DATA. Also, these functions are slow, which causes unneccessary waste of limited battery capacity. In order to overcome these difficulties, MCOPY routines have been writen that implement a direct device to device transfer. These programs, and the associated documentation are available on swapdisks CHHU03 and CHHU04. See files MCOPY71A, MCOPY71B, MCOPY71C, MCOPY71T, MCPY41, MCOPY75, MCOPY75A, MCOPY71C, MCOPY1D, MCPY41 (improved version, CHHU04), MCOPY71S and MCOPYD2. See also DISKCOPY and DISCOPY on CHHU06. Most of these routines assume that the first drive on the HP-IL loop contains the master disk. BE SURE TO WRITE-PROTECT YOUR MASTER! Some of these routines perform a fair amount of automatic testing that free the user from insuring a correct set-up. Try them, and let me know what still needs to be improved. Note: MCPY41 is a two drive program. It needs to be modified to permit multiple copies. I'll do it whenever I find the time. The HP-75 MCOPY programs are prototypes I wrote one day for a friend who wanted to duplicate MCOPY71 on the HP-75. Therefore, the user should first test these routines on disks you can afford to lose. Testing, if any, was minimal. The MCPY41 routines were writen by Mitch Hoselton. Documentation was to be published in the CHHU Cronicle. Copies are available from me or from Mitch Hoselton, P.O. Box 36047, Dallas, Texas 75235 (USA). The above utilities are all intended to make EXACT duplicates of the "Master" medium, using two or more mass storage units and media of equal capacity. If you have only one mass storage device, you can still duplicate media by using RAM for temporary storage. This is a slow, painstaking process that has been automated by Albert Shan. See swapdisk CHHU03, files SCOPYCD71 and COPYCD. While these programs were intended primarily for cassette drives, they can be used with any mass storage medium. See also CASCOPY on CHHU04, which takes advantage of the memory expansion capabilities of the HP-71. COPYING DISKS ONTO CASSETTES AND VICE VERSA : or how to deal efficiently with media of dissimilar capacity. Albert Shan's COPYCD71 was one of the first routines developed to copy cassettes onto disks, where directory sizes could be different. See CHHU03. Shortly thereafter, I wrote my own version, see BCOPYDOC and BCOPYTXT on the CHHU04 swapdisk. The BCOPYTXT file is hereby incorporated by reference, since it documents several other similar utilities that were also stored on CHHU04. See also DSK2CAS and SWEEPV3 on CHHU06. SWEEPV3 is particularily interesting because it implements very flexible disk managment / selective copy options. Selective copy routines will play increasingly important parts in the future. We need software that could allow copying, for example, only HP-41 files AND the associated documentation. Ideally, this would provide the same flexibility that is available to DOS machines, such as COPY D:BROW*.* E: (copy all the files that have names starting with "BROW") A number of new keywords, most notably MASSCOPY by Nigel Davies (see SYDMELEX on SWAP07) are offering many opportunities to improve additive / selective copy utilities. The next generation of utilities for the HP-71 should be designed to work with the multi-loop environment. MAKING SURE YOUR CONTRIBUTION IS USEFULL: A - Documentation Any software contributed should be sufficiently documented to allow the average user to get useful output with a minimum of effort. To the extent possible, programs should be menu driven, with help screens available to help first-time users answer prompts correctly. Comments line should be incorporated so that the program could be useable even if separated from associated documentation files. B - Making sure your contribution is complete: Once in a while, you will forget that some program uses some strange subroutine or keyword you always keep in your machine, but that is not commonly available. It can be very embarrasing -- I know, this is perhaps the one mistake I repeat regularly... perhaps because my HP-71 routinely carries two 64K EPROMs loaded with stuff. Anyways, the only way I know to prevent such errors is to make one final test before putting something on a swap disk: a) Remove ALL ROMs from your machine, except perhaps the HP-IL module. b) Master Clear the machine, trashing everything, to include IRAM if applicable c) Load the program, and ONLY such lex files as may be mentioned in the program header. d) Try to use it... After you have proven that you have identified ALL the files you really need, contribute all of them. C - Tell people what you are contributing. Here, all you have to do is create a small Text file that contains one or two paragraphs of information. For example, consider file INDDSCUT : the first three characters, IND, would let everybody know that the file is an INDex file the next several characters may be any convenient identifier. Here, we should seriously consider starting the names of all files contributed as part of this contribution with this identifier. So, what should the file contain? Example: DSCUTI - Disk drive utilities for the HP-41, by Mike Markov Program files : NEWMED, WRTP, SRCHX, GDIRX, DIRLX, WA & WA2 Required : HP-41 I/O ROM Documentation files : DSCUTIL1, DSCUTIL2, DSCUTIL3, DATAFLOW, LIFDATA Description: These files allow the HP-41 to a) access the full capacity of disk drives, b) Access mass storage files rapidly in spite of long directories, and c) save the entire contents of your HP41, Extended Memory included, by running WA or WA2. Help : Mike Markov, P.O. Box 17, Lockwood, N.Y. 14859 USA Tel. (Optional)= 607-598-2547 after 7PM. Restrictions : None -- this material is hereby placed in the public domain. (Here, you could also say something like: Restriction: Commercial users please send $..... per copy to above address) D - Consider the use of ARChived files HP-71 users can now combine several files into a single ARChive file. See the ARCER program on SWAP07. If I understand correctly, this program modifies the file pointers of the first file in a chain, which then allows you to copy the combined files in a single operation... and, of course, you can UNARChive the file as well. This would be a convenient method for linking all the files needed to run a given program. I have not tried this particular program myself, but similar DOS utilities have proved very reliable, and the best of them also implement data packing algorithms that can reduce filesize down to 60% of the original file size... This program should probably be in assembler, in order to remove or add ARChived LEX files to the LEX configuration buffer, as may be applicable, and to perform all the required housekeeping tasks more rapidly. Keep in mind that TEXT / IND / documentation files should NOT be archived, to allow people without the archiving capability to access / view / print these files. SWAPRULES -- or how this game is played: Guidelines for the SWAP program were worked out over time, and represent a concensus of the opinions of the contributors. These guidelines were presented informally at various conferences, and a summary was put on swapdiscs CHHU03 & CHHU04. To recap briefly: -- Swapdisks may not be sold. Copies are to be made for users free of charge. -- Users are expected to cover any expenses, such as the cost of disks and postages, if applicable. StAmped, Self-addressed Envelopes (SASE) prefered. -- There is no warranty as to performance for swap software. You, the user, assume all risks. -- The copyright of all swap program material remains with the author(s). -- Swap material is "Not for commercial use". Authors reserve all commercial rights unless otherwise specified. This means you can use this software for personal enjoyment / benefit anyway you like. If, however, you want to use the stuff in the "commercial" environment, ie., at work for profit, you are on your honor to contact the author(s) and make suitable arrangment to compensate them for their work. (Question -- how do you all feel about occasional use of software at work, when it is NOT part of company standard routine? I would think this is legitimate personal use, but how do you distinguish between organized exploitation and personal use?) SUMMARY : The above document is intended to acquaint swadisk users with both the philosophy and technology (software) that has been developed to make swapping disks fun and useful. The software currently in use is adequate, although improvements will always be welcome. However, we are still lacking a "structured" approach that will make swapdisks useful. The proposed solution is simple in concept : a) provide a documentation TEXT file that is already formatted, for easy printing, b) tell people what you have contributed (in a file named IND????, for INDex) c) Make sure your contribution is complete. Most of all, if you know of a better way to do the job, please let us know!