CHAMELEON DOCUMENTATION CHAMELEON - Request For Payment PLEASE COPY CHAMELEON AND GIVE IT TO EVERYONE YOU KNOW !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! THIS IS SHAREWARE. Shareware is software that YOU distribute. Feel free to copy and distribute Chameleon as much as you like, subject to certain restrictions (see "Legal Stuff", below). You may also run the program ONCE in order to try it out. However, to legally run the Chameleon program more than once, please send $25 directly to: Dark Star Systems Suite 123 351 Pleasant Street Northampton, MA 01060 You will receive copies of all the shareware you haven't seen yet, and a catalog of other innovative Dark Star software. Your honesty will allow us to distribute future programs this same, low-cost way. We are a tiny company, and we depend on your integrity to help us recoup the cost of developing this shareware. This method of distribution offers tremendous advantages. The cost of Chameleon is less than 1/2 of what it would be if distributed conventionally. With most software, the advertising costs and dealers' and distributors' markups make up 50% to 75% of the price. This comes out of your pocket. With shareware, you save that money, and what you pay goes to the hard-working programmers (us) who wrote it. Also, you can test the program before you buy it. We accept checks, Visa, Access, and American Express cards. If you send us your credit card details, please include the expiration date and the address to which the credit card company sends your bills. ************************************************************ *********** LEGAL STUFF - TERMS OF SALE Although Chameleon is copyrighted, Dark Star Systems allows copying and distribution of the program subject to the following restrictions: 1. Anyone receiving and using a copy of Chameleon must send a license fee of $25 directly to Dark Star Systems within 1 week. 2. Dark Star Systems will do its best to help licensees with any problems they may have using Chameleon. 3. Any disk containing Chameleon which is distributed to others must display the message explaining how to send the Chameleon license fee directly to Dark Star. 4. No company except Dark Star Systems is allowed to charge a fee for copies of Chameleon, except for the cost of the disk itself. TELL YOUR FRIENDS ABOUT THIS! Look, this isn't supposed to be a big secret. In fact, if this 'shareware' stuff is going to work, we've got to let as many people know as possible... any way possible. Tell everyone you know about this: that it's good software at a very reasonable price! If you use any computer bulletin board services, spread the word there. If you belong to a user's group, tell them about it and put the disk in their library. If your user group has a newsletter, write a letter offering the shareware to whoever wants it. We need all the help we can get to make this work. Make sure your local computer stores know, and convince them to keep the software in stock. Consumers CAN make a big difference in the marketplace! Really! And here again is our address. Write and tell us that you like our software! Tell us what new shareware you'd like us to write! And send your $25 license fee. We'll send you our catalog, and any other shareware you haven't seen yet. Remember, we depend on YOUR ENCOURAGEMENT to keep us writing shareware for you. Dark Star Systems Suite 123 351 Pleasant St. Northampton, MA 01060 Electronic mail: Compuserve mailbox 73317,3015 *** THE CHAMELEON *** Apple II File Transfer Utility (C) Ewen Wannop 1986 Distributed by Dark Star Systems Ltd. Greenford Middlesex UB6 7QW 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 sold on an 'as is' basis, and no warranty is given or implied as to its fitness or suitability for any particular purpose. COPYRIGHT NOTICE: This manual is copyrighted. All rights are reserved. This document may not be copied, photocopied, reproduced or translated to any other medium, other than for the making of a single printed copy for the sole use of the owner, without written permission from the author. The CHAMELEON system disc is copyrighted. All rights are reserved. The disc may not be copied in any form, other than for the production of a single copy for use as a backup or working copy for the sole use of the owner of the original disc. ProDOS (c) Apple, 1983 CHAMELEON (c) Ewen Wannop, 1986