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


