
While using CHAMELEON to transfer BDS "C" to Apple II CP/M disks, I discovered
that the file "DEFF2.CRL" was being copied but that the directory of the output
disk was not being updated.  In an attempt to figure out why this was happening
I reverse-engineered the executable and created a source file that, when
assembled, matched the executable.  I then modified "Apple2000", an Apple II+
emulator for the Amiga, to allow it to be used as a debugger.  The bug was
located and the source corrected.  At the same time, some routines were altered
to create more efficient code.

I was able to reach Ewen Wannop by e-mail and so I explained to him what I had
done.  He agreed that CHAMELEON should become freeware.

The original documentation follows except that all the lines about CHAMELEON
being shareware were deleted.

Willi Kusche
March 30, 2004
willi@wilserv.com

Copyright notice updated to reflect freeware status.

Bill Buckels
December 27,2008
bbuckels@mts.net


                         CHAMELEON DOCUMENTATION

The Apple II is one of the few computers that allows you the freedom to run
under more than one operating system. It is just as happy to think of itself as
a Pascal machine, a CPM machine or to be run under its normal disc operating
system. Each of these systems constructs the data on their discs in a
different way, thus making it impossible to read the discs of one system from
another. To complicate the issue still further, we have two native operating
systems, and there are even SOS discs from the Apple /// to contend with as
well. It is not normally possible to move files easily from one type of system
disc to another. To add to all this confusion, you may find yourself with a
file that has originated in one system, only to find that it will not read
correctly when transferred by normal transfer utilities, in another.

There are some file transfer programs available that will allow file conversion
between systems. Indeed the //c utility disc allows transfer from DOS to ProDOS
to PASCAL. However none have the power to convert from all five types of system
discs with the flexibility, power, speed and friendliness of the CHAMELEON.
In fact you may find that you are unable to transfer some types of file with
your existing transfer program in any meaningful form. CHAMELEON can cope
with all of these types of file.

The CHAMELEON is intended primarily to transfer text files around the various
operating systems, and it optimises for this when you use it normally. It will
however transfer binary or data files as well. But it can only of course
transfer data, it will NOT convert a 6502 machine code program into a Z80 CPM
program or Pascal P-Code file, or an Applesoft program into Z80 Microsoft
Basic. It does however attempt to treat the source and destination discs in
a suitable and correct manner. Appleworks Text files for instance, will be
correctly converted to normal text files as will CPM text files. To fully use
the power of the program however, you must have some knowledge of file
structure and the importance of the hi-bit in the data byte of Text files in
the Apple system.

You will find the program very easy to use, and except where you wish to alter
a file name, you will normally only need to use a few keys. Often all you will
need are the number keys for menu selection, the space bar to toggle options
and the return key to select. The escape key will always return to menus and
the 'Y', 'N' or 'C' keys may be needed when faced with choices.




SYSTEM REQUIREMENTS:

The CHAMELEON will run on any 64K Apple II, Apple //e, //c or IIGS.

One disc drive will only allow transferring of files to the same disc.

Two disc drives allow transferring between different disc types.

You may use as many disc drives or devices that ProDOS will recognise.

You may use ProDOS /RAM drives. (See RAMDRIVES)



QUICK START:

Boot the CHAMELEON disc.

To reach the Main menu, press a key when you see the title page.

Press '3' for 'New Discs', and CHAMELEON will determine the contents of all
drives attached to the system.

Press '2' for 'Set Source and Destination' and using the space bar move the
highlight to the source disc. Press return to accept, and then do the same for
the destination disc. You will then see the source disc displayed with an
inverse 'S' and the destination disc as an inverse 'D'.

Now press '1' and shortly you will see a Catalog of the source disc. Using the
space bar once more, highlight the file you wish to transfer. You may back up
the display with the left or up arrow key. Accept with the return key.

When the Transfer display is shown, press 'Y' at the prompt, and the transfer
process will be started. After completion, you will be shown the source Catalog
once more. If you are finished, simply press Escape to return to the main menu.

You may exit to the ProDOS operating system by entering a valid system file
pathname or pressing Reset to boot a disc.

That is all there is to it. You have successfully converted a file from one
disc system to another.

To really get the best out of CHAMELEON, please read through the rest of these
instructions.



THE KEYBOARD:

In general you will not need to use many keys.

The Escape key will always return you to the previous menu level, and abort the
current function.

Menu selection uses the number keys.

The space bar and the arrow keys are used to cycle through any options.

The return key is used to accept choices.

The 'Y', 'N' and 'C' keys are used to make the final choice before transfer.

Finally, the alpha keys are used if you wish to change the suggested name of a
file.



THE MAIN MENU:

1) Transfer Files

   This starts the file transfer process. You must first tell CHAMELEON the
   program discs you have online with option '3', and you must also have
   selected the source and destination disc with option '2'.

   You will be given a Catalog of the source disc. Cycle through the entries,
   using the spacebar or the arrow keys. Accept an entry with the return key.
   If you wish to abort transfer, press the escape key.

   You will find that if you select the disc pathname on a ProDOS or Pascal
   disc, that this too will abort the Transfer command.

   A status display is given next, and you will see the type of file that was
   found and various parameters connected with it. If you have selected any
   special options, you will see an inverse message, 'Options Set'.

   The program attempts to parse the original filename into a suitable name
   for the destination disc type. If this name is unsuitable, simply say 'N'
   and enter a new one. If your destination is a Pascal disc, and the source
   was a Text file, a '.Text' suffix will always be added. If the destination
   is a CPM disc the suffix will be made from the second word of any filename,
   or any part following a stop delimiter. If there is no second part to the
   name given, a suitable suffix will be appended.

   If the filename selected already exists, when you try to transfer, you will
   receive an error message. To continue you must enter a different filename.

   If there is not enough room on the destination disc the transfer will not
   proceed. Be WARNED, although the program may think that there seems to be
   sufficient room, the file conversion process in some cases may increase
   the file length on the destination disc. This may lead to the point where
   the destination disc reports a DISC FULL error.

   You have the option to Catalog the destination disc at this point. If you
   are not sure what filename to use you may find this useful.

   On completion of the transfer, you will see once again a Catalog of the
   source disc. This gives you the chance to easily transfer more files.

   To return to the Main Menu, simply press Escape when you see the catalog.


2) Set Source and Destination

   In order to carry out a file transfer, you must first select the source
   and destination disc.

   Use the space bar and return keys. First select the source disc, and then
   the destination disc.

   The source disc is displayed by an inverse 'S' and the destination by an
   inverse 'D'.

   If you have used any of the facilities on the utility menu, you will have
   to re-select the source and destination disc to continue with a transfer.


3) New Discs

   You must do this before you do anything else. In fact CHAMELEON will let,
   you do very little till you have done this.

   Place your discs in the drives, making sure you have sufficient space on any
   destination discs. You must initialise any discs you require beforehand. No
   initialising program is provided within CHAMELEON.

   The program will search through all the active devices and display their
   contents. The following are the disc types that you may see displayed:

   'DOS'  a Dos 3.3 disc
   'PRO'  a ProDOS or SOS disc
   'PAS'  a Pascal disc
   'CPM'  a CPM disc
   'UNK'  a disc was found but is of unknown type
   '---'  no 'disc' was found in the device

   Slot 3 Drive 2 on an extended //e or a //c is available as a ProDOS /RAM
   drive. See also RAMDRIVES.


4) Utility Menu

   This takes you to a second Menu of utilities.


5) Exit to the System

   The CHAMELEON conforms to normal ProDOS format, and so to exit the program
   without re-booting, you must specify the pathname of a valid System file.
   On the CHAMELEON system disc, you will find copies of BASIC.SYSTEM and
   FILER, you may run either of these programs by entering their names at the
   prompt. Follow the prompts to exit this way.
   The default pathname is /CHAMELEON.

   However, you may also exit by pressing Reset to give a cold boot, or by
   entering a carriage return, you may use the space bar to select with the
   highlight a slot to boot from. This must be a valid slot with a suitable
   device present. Accept your choice with a Return.

   You will be returned to the Main Menu if you do not enter any valid
   pathnames or entries, or if you press Escape.



UTILITY MENU:


1) Date Entry

   If you have a clock card that is recognised by ProDOS, you need not enter
   the Date and Time. The files will be correctly marked.

   You may if you wish enter a date and time for datestamping files on ProDOS
   or Pascal volumes. Enter a valid date in the format DAY/MONTH/YEAR. The date
   should be entered in this format: i.e. 23,JUN,86 for the 23rd of June 1986.
   You may use most punctuation as a delimiter between the entries. On entering
   a valid date or pressing return, you will see the date displayed and will
   then be asked for the time. Enter in the same way with the format
   HOURS/MINUTES. The time is entered in 24 hour format. If you have entered
   incorrectly you will be prompted once more. After a valid entry or a
   carriage return you will be returned to the menu. The Date and Time are only
   displayed while changing them, but they will be correctly entered in the
   directory entry for any files you may subsequently write in ProDOS or
   Pascal.


2) Force a disc type

   If CHAMELEON finds a disc in a drive, but is unable to determine what
   type it is, it will give the 'UNK' label.

   If you receive the 'UNK' label for a disc, you may force the program
   into thinking it is a particular type of disc. You could of course
   also force the program into thinking any disc was of a different type.

   Be WARNED, you may destroy a disc by writing an incorrect type of file
   to it. Use a backup in case you are in doubt.


3) Catalog a Disc

   This allows you to catalog any of the different kinds of disc. This in
   conjunction with 'New Discs' is an easy way of identifying the type and
   contents of unknown discs.

   You may cycle through the catalog using the spacebar or arrow
   keys. To exit from the catalog, press the Return or the Escape key.

   The display will vary slightly between disc types. The lefthand column
   displays the type of file that the system found, either BAS, BIN or TXT.
   This is the type that CHAMELEON will use unless instructed otherwise.

4) Special Options

   This takes you to a third Menu of special options.



SPECIAL OPTIONS:

Be WARNED, some of these options may cause unpredictable results on the
subsequent files. To use the full power of this menu you should have some
knowledge of the file structure in the different systems.

Please refer to the individual system notes if you are in doubt.


S) Special Options

   When you first enter this menu, you will only see this first option. With
   special options OFF, no further processing will be done to the files
   over and above the normal handling to be expected with the appropriate
   systems involved.

   Pressing 'S' will switch the special options ON, and the full menu will
   be displayed. Pressing 'S' once more will switch OFF the options once
   again.


1) Force Sourcefile

   The sourcefile will normally be treated as the type found on the disc, and
   in fact will be read as such. However you may force the program to handle
   the data as a different file type with this command. This is useful in the
   case of a CPM disc, where the filename may not indicate the actual filetype.

   To transfer a Random Access text file successfully, you will need to force
   the source file to be seen as Binary, do not force the destination file
   type.

2) Destination File

   This works in tandem with the previous command, and allows you to force
   the destination type. This might be used to create a Binary file from a
   Text file. Sometimes a file that has been downloaded from another computer
   using Xmodem protocols, will actually contain Binary code, though it
   appears on disc as a Text file.

   Be WARNED, with both these commands, you may create an unusable disc file.


3) Force:   AWP ==> TXT

   Normally when you transfer an Appleworks text file it will be correctly
   translated to a Text file. However if the destination disc is also a
   ProDOS disc, it will be left intact.

   To force a Text file to be created while transferring to and from a ProDOS
   disc, use key '3' to set the direction to AWP ==> TXT.

   If you wish to create an Appleworks text file on a ProDOS disc from a text
   file, use key '3' to set the direction to AWP <== TXT.


4) Enable option (3)

   Enables whichever setting of the AWP ==> TXT command you may have chosen.


5) Format:  CPM ==> TXT

   Toggle the direction of this command with key '5'. This will allow you
   to force the conversion of a CPM type file to a normal text file and
   vice versa.

   Normally a CPM file will have no hi-bit set, and it will have linefeeds
   after every carriage return. It may also have embedded control characters
   and have some hi-bits set on such as 'soft' returns. These will be handled
   by setting the hi-bit, stripping linefeeds and removing control characters
   respectively.

   To convert from TXT to CPM, the high bit will be stripped, and linefeeds
   inserted. Where a single return is encountered it will be written as a
   'soft' return suitable for programs such as Wordstar. Where two or more
   returns are found, the second and following returns will be written as
   'hard' returns.

   Use the CPM to TXT option to normalise files downloaded from public data
   systems such as the SOURCE, COMPUSERVE or bulletin boards. This is
   especially suitable for programs that must be 'EXECed' into Basic.


6) Enable Option (5)

   Enables whichever setting of the CPM ==> TXT command you may have chosen.


7) Force Hi-Bit:

   The Apple internally uses ASCII data with the seventh or hi-bit set.
   However except on DOS 3.3 files, it stores Text files with the hi-bit
   stripped or cleared.

   To force the hi-bit on for DOS files, select 'ON'. To force the hi-bit off
   for other files select 'OFF'.


8) Enable Option (7)

   Selects whichever hi-bit option may have been set in option '7'.


9) Utility Menu

   Returns you to the Utility Menu.




GENERAL NOTES:


RAMDRIVES

CHAMELEON runs under the ProDOS operating system. It will therefore handle any
device that ProDOS recognises, such as RAMWORKS, the FLIPPER and 3.5 inch
Unidisks. The ProDOS present on the disc is a standard version of ProDOS
and may not directly recognise your particular device. This will be especially
true of some of the /RAM drives such as conventional Ramcards running as Pseudo
discs. CHAMELEON resides on the system disc as a single file called
'CHAM.SYSTEM'. You may therefore copy a custom ProDOS driver to the system disc
in place of the normal PRODOS file. This will allow the use of these custom
/RAM devices.

Only ProDOS devices may be used in this way. You may find that you can also
access Pascal Ramcards as well, their block format is arranged in a similiar
way to ProDOS devices. Because of the special disc handling required in
CHAMELEON, DOS 3.3 and CPM discs can only be read and written to from 5.25 inch
drives.


DOS 3.3

There are basically three filetypes available under DOS 3.3. Text files, Basic
language files and Binary data or code files. Other types do occasionally
occur, CHAMELEON treats these as Text files unless told otherwise.

Text files are stored with the Hi-Bit set.

Basic files are stored in a tokenised form. DOS basic files may be transferred
to and from, and run on, ProDOS discs only. Integer files will not run under
ProDOS.

Binary files may be either program or code files, or data files. Program files
may be transferred to, and run only on ProDOS discs. Data files may be
transferred to any system. Binary files are usually stored in eight-bit form,
so you should not normally force the hi-bit ON or OFF on these files.

Filenames may be up to 30 characters long and may contain all but lower case
characters and commas. They must start with an alpha character.


PRODOS

There are many types of files possible under ProDOS. Where possible CHAMELEON
recognises the filetype and uses them in the transfer process. Certain
filetypes will only be preserved on transfer to and from ProDOS discs.

Recognised types include Text files, Basic files, Binary or code files and
Appleworks Text files.

Text files do not have their hi-bits set and may be transferred to any system.
Basic files and code files may only be transferred and used with DOS 3.3 discs.
Data files may be transferred to any system.

Appleworks text files are constructed in a particular way and can only be
transferred to Text files by CHAMELEON. It is not possible in the transfer
process to create these types of files.

Filenames may be up to 15 characters long, and must not contain any spaces or
characters other than normal alphanumeric. Spaces are normally converted to
stops.

As the program is running under ProDOS, you must not enter any invalid
pathnames as part of a file name. You will receive an error message if this
occurs. Unpredictable results may occur if you enter the pathname of another
disc than the one selected. You may however enter the pathname of a
sub-directory as part of a full pathname, this will place the file in that
sub-directory.

If you have entered the current date, or you have a clock card that is
recognised by ProDOS, the files will be correctly datestamped.


PASCAL

Pascal has three or four main file types. Normally you will only be handling
data or text files. Binary files will be written out as codefiles. Remember
they will not run under Pascal unless they contain P-Code data.

Pascal textfiles are constructed in 1 K blocks. CHAMELEON will correctly
read these files, and will also correctly construct them as well. However, it
is possible that if extreme paragraph or word lengths are encountered, that
extra carriage returns will be inserted in the finished file to correctly
terminate each block. Also you may find that the linelengths are excessive
when you enter the editor, and it may be necessary to truncate them on screen.

Filenames may be up to 16 characters long, and as a rule Text files should end
with the .TEXT suffix. CHAMELEON will add this to the filename of any text file
being written.

If you have entered the current date, or you have a clock card that is
recognised by ProDOS, the files will be correctly datestamped.



CPM

There are no generic filetypes under CPM, as there are with the other systems.
All files are stored in the same way. When files are loaded run or used, it is
up to the user to make sure that the filename suffix is correct, as this is the
only distinction that can normally be made. CHAMELEON will attempt to add a
suitable suffix when the filename is parsed. However it will assume that a
space or stop in the filename is a delimiter, and so it may be necessary to
amend the filename to a sutiable one when prompted.

Text files under CPM contain a carriage return/linefeed pair instead of the
usual carriage return. This is altered automatically when transferring a file
with one of the usual TXT suffixes. It may be forced by either forcing the
source file as a text file, or forcing CPM ==> TXT option. When writing to CPM
text files, the first occurence of a carriage return is written as a 'soft'
return suitable for Wordstar files. Two or more successive returns are written
with the first return 'soft' and the second 'hard'. This should be transparent
to any other program using text files, and will enable the integrity of a
paragraph to be maintained while working with Wordstar.

Filenames may be up to eight characters with a three character suffix.




ERROR MESSAGES:


Errors are reported as they occur, and will result in the aborting of the
current action. If an unusual error is encountered, the ProDOS error code only
will be reported. Normally you will be given a descriptive message. Take
appropriate action to avoid the error happening again. You will be returned to
the Main menu after pressing a key.

Remember that although CHAMELEON may think sufficient disc space is present,
file expansion due to the different ways of storing text files, may cause a
DISC FULL error to occur. Under CPM it is possible to fill the directory,
though there may still be space on the disc, if very long files are
encountered. CPM uses multiple directory entries rather than multiple track
sector lists or volume directories to store long files.

Make sure that destination discs are not write protected or an I/O error will
be reported.



DISCLAIMER OF WARRANTY:

APPLE COMPUTER (UK) LTD MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED,
REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS
FITNESS FOR ANY PARTICULAR PURPOSE.

CHAMELEON is provided on an 'as is' basis, and no warranty is given or implied 
as to its fitness or suitability for any particular purpose.


COPYRIGHT NOTICE:

The Chameleon System and this manual are (C) Copyright Ewen Wannop 1986. All 
rights reserved.

Use and distribute freely provided you agree that Ewan Wannop and/or Willie 
Kusche are not liable in any way whatsoever from its distribution or use.


ProDOS (c) Apple, 1983

CHAMELEON (c) Ewen Wannop, 1986
