ReadMe for appletools.zip Introduction This zip file contains a modest number of 16 bit MS-DOS utilities that I used back in the early 1990's to help me in the programming of Apple II PRODOS graphics-based educational programs written in Aztec C. They are intended to be used in conjunction with the AppleX Aztec C Apple II PRODOS cross-development environment for Windows XP that is available from my website at www.clipshop.ca/Aztec They were never finished to any great brilliance but proved useful to me in my conversion of IBM CGA Graphics to Apple II HIRES Graphics etc. and they are essentially programmer's tools and are pretty primitive as such, and intended to be used from the command line or to be called from batch files. The comments in the source code are not all that great if they exist at all which is arguably quite a disadvantage to an inexperienced programmer or even to a careless programmer. No MAKEFILE for these programs was ever produced because I wrote these on the fly and wasn't into MAKEFILEs in those days, and further I used whatever compiler I was into at the time and I flip-flopped between Mix Power C, MicroSoft C, and even Aztec C86 16 bit MS-DOS compilers in those years... So if you want to recompile these, or re-use the source code in your own programs you are likely to need to fix-up something or other. Regardless, all utilites in this zip are (C) Copyright Bill Buckels 2007 All Rights Reserved. Unless otherwise noted. They are provided as-is without any guarantee or warranty of any kind. In any case, I am not liable in any way whatsoever for their use. If you do not agree don't use them. Otherwise you have a royalty free right to use these in any way you find useful and I hope they prove useful in some way. Some of their functionality has been incorporated into my Windows XP ClipShop program available at www.clipshop.ca which may suit your purposes better, especially if you prefer a higher-level interface and you only want to do conversion to Apple II full screen HIRES images. OTOH, since ClipShop supports Windows ClipBoard pastes and a variety of other options and graphics formats, and you can use Windows Paint to create your Apple II Graphics before saving to Apple II format or IBM CGA BSaved Format in ClipShop, a copy of ClipShop may prove useful in augmenting the use of some of the utilities in this zip file. I should also note that the IBM Graphics that are used by these utilities are really old formats... IBM CGA BSaved Format and IBM CGA PCX Format. Despite that ClipShop can produce these from other formats, or ClipBoard Pastes from Windows Paint. Just keep in mind that the Apple II screen resolution is 280 x 192 and ClipShop only gives you 2 additional colors besides Black and White to create IBM CGA or Apple HIRES Screens, so keep your graphics simple. Read ClipShop's online documentation for more info. If I ever release a new version of ClipShop, I may expand Apple II graphics conversion functionality to include almost everything that the utilities in this zip file do and more. In the meantime... Graphics File Formats - .TOP, .BOT, and .RAG These formats were developed by me (Bill Buckels) in conjunction with the development of the "Little Running Steps" Collection which is a collection of Apple II PRODOS graphics-based educational programs written in Aztec C. All of these are the same file format. The file extensions are descriptive naming variations. These are uncompressed graphics files in scanline orientation and are aligned on 2-byte (14 pixel) boundaries. They have a 2 byte header, with the first byte being the width of the image in bytes (7 pixels per byte) and the second byte being the height of the image. The header is followed by raw scanline oriented data to be displayed directly on the Apple II screen in HIRES graphics mode. Unlike the Apple II BSaved HIRES Image format which is not raster aligned these files are not padded and store visible graphics data only which results in a slightly smaller file size over a screen saved in the BSaved format. The .TOP file format is intended for use in Apple II mixed text and graphics screen mode and is 280 x 160 in size which is the same size as the graphics area in this screen mode. The .BOT file format is intended for use in Apple II full graphics screen mode and is 280 x 192 in size which is the same size as the graphics area in this screen mode. The .RAG file format is a variable size image fragment with a mazimum size of 280 x 192 which is the maximum size of Apple II HIRES graphics screen mode. Programs and Their Use Note: I wrote these for a long time ago, and I took lots of shortcuts to get the job done. I didn't check for null pointers much, and I didn't check for input file formats much, and if you don't like it, then don't use these programs or fix them before you use them. Consider yourself warned. They worked for me and if you are careful they will work for you. Regardless, they are provided as-is with no guarantee especially of being bulletproof and remember that the naming convention for files at the time they were written is MS-DOS 8.3 so do yourself a favor and stick with the DOS naming convention. I didn't check for name buffer overflow in these either. Just pretend you are programming in MS-DOS back in the '80's and you will probably be fine. Regardless I am not liable in any way shape or form, so use at your own risk. I haven't worried much about this. I have used them in Windows XP without problem with the same degree of success that I used them in MS-DOS when I wrote them, and I probably would have told you to be careful back then, the same as I am doing now. ABINLOAD.EXE ABINLOAD(C) CopyLeft Bill Buckels 1991-2006 All Rights Reversed. Apple II 8K BSaved Picture Loader for the IBM-PC Usage is : ABINLOAD [MyPicture] converts from prodos's BIN format to IBM BASIC's BSAVED format and does other funky things. Outputs a Basic BSAVED Image when no options are specified Options : ABINLOAD [MyPicture] COLOR TOP & BOT : ABINLOAD [MyPicture] TOP TOP & BOT (save): ABINLOAD [MyPicture] TOP BIN Saves TOP or BOT Image to PRODOS BSaved format when BIN option is specified HIRES (default) : ABINLOAD [MyPicture] HIRES APPIBTXT.EXE Converts apple to IBM text files or vice versa. It is important to remember when creating text files on the IBM and using them on the Apple II that the IBM-PC stores its text with a cr-lf (ascii 13,10) between lines and the Apple II uses only a cr. (ascii 13) so text files need to be converted. This utility converts back and forth between them. Usage is: APPIBTEXT [infile] [outfile] [FORMAT-optional] OUTPUT FORMAT = "A" for APPLE or "I" for IBM Default is "I" APPLETOP.EXE Converts from a 320 x 200 IBM 4 color CGA graphics image to an apple format picture either in the BOT or TOP format. 1 arg is full screen 2 args are 160 lines Usage is: APPLETOP MY.PCX or APPLETOP MY.BAS Output is MY.BOT Alternate Usage is: APPLETOP MY.PCX TOP or APPLETOP MY.BAS TOP Output is: MY.TOP BOT2BSV.EXE Converts from an apple BOT or TOP format screen image to an apple HIRES full screen image. Usage is: BOT2BSV MY.BOT or BOT2BSV MY.TOP Output is: MY.BIN FRAGRAG.EXE This utility converts from the IBM CGA BSaved Image Fragment used in GWBASIC programs of the day to an apple image fragment. My ClipShop program still creates these (using the .PUT extension) and you can read all about them in my Wikipedia article at http://en.wikipedia.org/wiki/BSAVE_(graphics_image_format) Unless you have some of these IBM CGA image fragments, this won't be of much use. Usage is: FRAGRAG MY.PUT Output is: MY.RAG PIXSYS.EXE Extracts an embedded image from a prodos sys program with an embedded graphic. This needs a little explanation. I embed my title screens into my PRODOS SYS programs using a utility that I wrote called MAKEPRO2.EXE. This utility also trims the 4 byte header that the aztec c cross-compiler always places on an executable program whether the target is DOS33 or PRODOS. Anyway, when the SYS PROGRAM loads and switches to graphics mode, the picture that was embedded in the SYS program is immediately displayed. This was if not a common practice, a standard practice back-in-the-day. These ProDOS programs could be called any old thing. I preferred to use the .SYSTEM extension so PRODOS would automatically run my program on boot-up. Usage is: PIXSYS MY.SYSTEM Output is: MY.BIN Possible uses for this utility are to steal someone else's title screen from their program (perish the thought) or to extract your own if you lost your orginal graphic. Other than that, not much use for this one. RIBCOOK.EXE This utility creates binary libraries that can be loaded into the apple IIe's auxilliary memory which is supported in my G2.LIB in AppleX. It is a programmer's tool and not good for much else. This is pretty advanced, but a tremendous time saver at runtime since all your graphics and other stuff can be pre-loaded from disk into auxilliary memory in the form of one of these libraries and then accessed from auxilliary memory in the upper ram of the IIe thereby avoiding further (slow) disk IO. RIBCOOK is incremental and libraries can be appended to. I am not going into great detail about all this. The G2 library source is there for anyone who wants to take this further, and image loaders etc. are supported from auxilliary memory in G2.LIB so you can do animation with library images etc. When I have more time I will probably create a simple example program to show how all this is done. For Image Data: Usage is: RIBCOOK MYLIBRARY.RIB MY.RAG Output is: MYLIBRARY.RIB and MYLIBRARY.RAP For Binary Data: Alternate Usage: RIBCOOK MYLIBRARY.RIB MY.BIN BIN Output is: MYLIBRARY.RIB and MYLIBRARY.RAP You can use the BIN option as noted to put anything you wish into this library. The output files should be kept paired because you need the info in the RAP file to include in your program. In simple terms: RAP - Map file to include in your Aztec C ProDOS program RIB - Binary Data File (AKA Library File) to distribute with your program. ROTATO.EXE This utility should have been called "fliphorizontal" since it creates a "left-hand" copy of an IBM CGA Basic Bsaved Image from a "right-hand" original in IBM CGA Bsaved or PCX format. This is called a "mirror image" in real life but in paint programs Image->Flip->Horizontal seems to be the standard to differentiate from rotate. I don't care at this point... but "ROTATO" implies that the image would end-up upside down, which is not the case and I probably chose the name because it reminded me of POTATO and TOMATO and just to tell-it apart from my other programs when I was suffering from lack of sleep due to excessive programming so I thought Id best not mislead you a decade or so later... Usage is: ROTATO MY.BAS OUTPUT.BAS or ROTATO MY.PCX OUTPUT.BAS Output is: OUTPUT.BAS I used this to create left-hand cursors or left-hand graphics when it would enhance my interface somewhat, prior to cutting these graphics into image fragments for use in my PRODOS programs. Other than that, if you need a mirror image these days, Windows Paint and other paint programs will be happy to accomodate you. I used to just write these types of things as needed. SND2APP.EXE This utility is meant to be used with a binary sound file that I used back-in-the-day when we used-to play music through the IBM speaker using frequency,duration pairs. In GWBASIC this was accomplished through the SOUND statement and some C compilers provided an equivalent, and if they didn't it was easy enough to write one. Anyway, I had accumulated lots of sound files and used this utility to convert them to a format that I could use in my apple programs. You can reviewe the source code for my G2 library in AppleX for more info. Usage is: SND2APP MY.SND Output is: MY.TXT and MY.BIN The sound that these produced on the apple was reasonable and certainly recognizable compared to no sound at all. For the time it wasn't so bad. TOPCOOK.EXE This utility is a programmer's tool and not good for much else. It takes an apple image fragment in the the .RAG format as created by TOPRAG.EXE (see below), FRAGRAG.EXE (see above) or in the .BOT or .TOP formats as described above, and creates a C language character array of the image suitable for embedding in an apple prodos program. Really, you should use this only for small images because you haven't much memory on the apple and no point in using it-up with character arrays in main memory. Usage is: TOPCOOK MY.RAG Output is: MY.NAP TOPRAG.EXE This utility creates apple image fragments from IBM CGA images in PCX or BAS formats. The top left is used as 0,0 base and the arrow keys can be used optionally to expand the image up to 280 x 192 before saving. The initial values are in pixels and provide a seed value so you don't need much time to move the arrows around. If you press escape, the process is abandoned. Otherwise an apple image fragment is saved from the top left to the cursor extents. Run the program and read the source code for more info. Usage is: TOPRAG MY.PCX or TOPRAG MY.BAS Output is: MY.RAG All that I really have to add to this: When you run 16 bit programs in Windows XP from a cmd windows and you are also running Windows Explorer, you may not be able to delete files afterwards. You will get the message that the file is being used by another process when this occurs. Without getting into the reason why Windows does this, to delete the file, open a cmd window if you don't already have one open. Then close down all your explorer windows if they aren't already closed. You should now be able to delete the file from the commandline. This isn't a bug in Windows XP; this is the way interop works between the desktop and the cmd window, and what I have just passed-on applies to moving and renaming of files as well. If you leave a file locked in this manner and ignore this problem if it occurs you won't be able to delete, rename, or move the parent folders until you fix the problem using the steps I have outlined above. You need to be aware of this if you are mucking-about with these 16 bit utilities of mine to avoid driving yourself crazy trying to figure-out what has happened if and when you encounter this problem. Welcome to the Wonderfully Ancient World of MS-DOS! Bill Buckels 2007 Addendum: March 2008 I have added a utility called Fraggle to this zip file. This utility will cut IBM-PC BSaved Image fragments from IBM-PC BSaved Images. It offers more options than TOPRAG and you might like it better. However, TOPRAG saves directly to Apple II format and FRAGRAG will be required to convert image fragments from FRAGGLE. FRAGGLE is also menu driven which for some jobs is preferable. This utility is zipped into its own zip file called fraggle.zip and contains sample screen layouts and a memory chart. Bill Buckels 2008 Addendum 2009 I have added a number of other utilities to this zip file. Since it seems that this has no end, and since the source code is provided which you can read for more information I have not listed these further. Please read the source code for more info. Bill Buckels January 2009