T H E P R O T O N C O M M A N D S H E L L R E F E R E N C E M A N U A L Manual Written by Brian Campbell Proton Command Shell Reference Manual For Apple II Computer systems Apple II+, IIe, IIc, IIc+, IIgs Programming by Brian Campbell Copyright 1992 Brian D. Campbell. All rights reserved. Apple, Apple IIGS, and ProDOS are registered trademarks of Apple Computer, Inc. The software described in this manual is provided under a license agreement and may be used or copied only according to the terms of the agreement. No part of this manual may be reproduced, transmitted, or stored in a data retrieval system in any form or by any means, electronic, mechanical, or otherwise, including photocopying or recording without the written permission of Brian D. Campbell. Printed in the United States of America. Page - 2 Proton Command Shell Reference Manual TABLE OF CONTENTS Chapter 1: Proton Command Shell OverView Installation Entering Commands Leaving the Proton Command Shell Customizing Your Environment Summary of Commands Chapter 2: Description of Proton Commands Command Parameters Command Reference Chapter 3: Supplemental Information DOS Error Codes ProDOS File Types Operation of the Editor Operation of the Assembler More on Scripts Page - 3 Proton Command Shell Reference Manual Chapter 1: PROTON COMMAND SHELL OVERVIEW The Proton Command Shell (PCS) is a command line environment. You can enter commands provided with PCS, or you can develop your own programs and enter them as commands. The PCS operates under ProDOS 8. Release 1.0 provides the following features: - Various ProDOS file and directory utilities. - A 6502 Assembler to create machine language programs or subroutines. - A compiler for programs written in the Proton programming language. Proton is an integer based language. It provides many predefined functions and subroutines available for your use, particularly for file or other system level applications. - Demo programs written in the Proton programming language. A few of the demos take advantage of the IIgs tool box and capabilities. Program source is provided for several of the utilities and demo programs written in the Proton programming language. Feel free to study the program source provided, and use any of it as a starting point in any Proton programs that you may wish to write. INSTALLATION The PCS requires an Apple II+, //e, //c, //c+ or IIgs and at least one disk drive. At least 64K of memory is required, but at least 128K is recommended. The PCS runs best with a Hard Disk drive, or with a RAM drive such as the /RAM disk (Slot 3, Drive 2) that is automatically set up by ProDOS in the alternate 64K memory bank of a 128K machine. Floppy Disk Users: First, with an ProDOS file utility, make a working copy of the disk, and place the original in a safe place. If you want the working copy to be bootable, first format the disk copy, and then copy the ProDOS System file (the SYS file called PRODOS) from your Apple system disk (With a IIgs system disk: copy the file named P8, which may be in the SYSTEM directory, and rename it to PRODOS). Then copy all of the directories and files from your original Proton Utility disk. Page - 4 Proton Command Shell Reference Manual To start the PCS, insert your working copy into a disk drive. If your copy is bootable, simply reboot the machine. That is, turn on the machine, or press Open Apple-Control- Reset. If your working copy is not bootable, simply switch to the disk prefix and execute the PROTON.SYSTEM file on the disk. For example, if the working copy disk is located in slot 6, drive 1, then from the BASIC prompt "]", type: PREFIX,S6,D1 -PROTON.SYSTEM In a few seconds, you should see an introductory message and the PCS prompt "%". At this prompt, type: CMDPATH /PROTON/CMDS Now you are ready to run any of the commands described in the next chapter. With the above CMDPATH command, you must keep your working copy of the PCS disk in the disk drive. If you want the option of removing the disk, you can copy the CMDS directory to the /RAM disk; see the Customization section. Hard Disk Users: First, with an Apple file utility, create a directory on the hard disk and copy all of the files from the PCS disk to the directory. You can start the PCS from a BASIC prompt, from the ProDOS selector, from the IIgs Finder, or from another selector program. Change the prefix to the directory with the PCS files, and run the SYS file PROTON.SYSTEM. To do this from the BASIC prompt "]" enter the following. The example assumes that the hard disk volume name is /HD and that the directory name is PROTON. PREFIX /HD/PROTON -PROTON.SYSTEM In a few seconds, you should see the PCS prompt "%". At this prompt, type: CMDPATH /HD/PROTON/CMDS This tells the PCS system to run utilities located in the CMDS directory located in your PROTON directory. If you reboot ProDOS, you will need to perform this step again. After a second, you should see another prompt "%". Now you are ready to run any of the utilities described in the next chapter. ENTERING COMMANDS When you type in a command name after the prompt "%", simply type the name and any arguments that it might require. Do Page - 5 Proton Command Shell Reference Manual not precede the name with the word RUN or "-" as you might when running a program in BASIC. Normally arguments are separated by blanks. A command can be entered by typing its fully qualified path name, that is, a file name prefixed by its volume name and its subdirectories, if any. If you do not enter the name fully qualified, PCS first searches to see if the command's object file is in the directory you specified on the CMDPATH command. If it is not there, then it searches the directory as defined by the current path prefix. For example, if the CMDPATH parameter was /PROTON/CMDS, and the current ProDOS prefix is set to /PROTON, you can type any of the following to run the CATALOG command: /PROTON/CMDS/CATALOG CATALOG CMDS/CATALOG A command is valid if it has an associated object file. A Proton Object file is type OBP and its contents must conform to the Proton Object Format. You can create your own object files with the Proton Language Compiler. When you enter a command, the Proton command processor searches a directory according to the above rules. If it finds it, it loads the command's object file into memory and runs it. When the command is finished running, another "%" prompt is displayed. If you want to abort a command while it is running, hold down the CONTROL key and press the RESET key. You can create your on OBP command files by writing programs in the Proton Programming language and convert them (i.e. compile) to OBP with the COMP command. Three other types of files may be run as a command, simply by typing its file name as described above: Files of type BIN. Be sure that the BIN file has executable binary program, or you may "crash" your computer. If the binary program quits with an RTS opcode, then upon completion you will be returned to the PCS prompt "%". If you know how to write assembly code, you can create your own BIN programs with the PCS assembler (the ASSEM command). Files of type SYS. Depending upon its programming, a SYS file may leave the PCS environment; to return to it, you will have restart PROTON.SYSTEM and enter the CMDPATH command as described in the previous section. If you know assembly code, you can create your own SYS files. You can assemble your programs at address $2000 with ASSEM and change them to SYS files with the CHANGE command. Files of type SCR with an auxilary type of 8. The file must contain a text script of one or more PCS commands, just as you would type them at the "%" prompt. The command files Page - 6 Proton Command Shell Reference Manual can be any of the previously mentioned file types: OBP, BIN, or SYS. Unless any of these commands terminate the PCS environment, the prompt is redisplayed after all of the commands are executed. You can used the PCS editor (the EDIT command) to create PCS script files. The editor will create a file of type TXT, but you can convert it to a script file with the CHANGE command. For example, to convert a TXT file called MY.SCRIPT, enter the command: CHANGE MY.SCRIPT "" SCR 8 LEAVING THE PROTON COMMAND SHELL One way to leave the PCS environment is to run a SYS file designed to operate as an independent environment, such as Apple's FILER, or BASIC.SYSTEM. Another way is to execute the PCS command QUIT. It will return you to the ProDOS selector (via the ProDOS "Quit Code") if you are operating exclusively under ProDOS 8. If you started the PCS environment with the IIGS finder, you will be returned to the finder. CUSTOMIZING YOUR ENVIRONMENT If you have a 128K (or more) Apple, and you want speed up the loading of commands, you may prefer to run them from your RAM disk. This also allows you to remove your working copy of the PCS disk and insert other disks. Upon entering the PCS environment, enter these commands instead: CPDIR CMDS /RAM/CMDS CMDPATH /RAM/CMDS The first command creates the directory CMDS in your /RAM disk, and copies all of the command files located in the CMDS directory on your PCS disk to the CMDS directory on your /RAM disk. The second command causes the PCS to search the /RAM directory for PCS commands. If you reboot ProDOS, the /RAM disk is destroyed, and you will need to perform these commands again. If you perform the above procedure, and find the CPDIR command taking too long, you can delete command files that you find that you do not need. (Don't delete anything on your original PCS disk). Or just create the /RAM/CMDS directory and copy just the files you need. For example: CREATE /RAM/CMDS COPY CMDS/EDIT /RAM/CMDS/EDIT COPY CMDS/CATALOG /RAM/CMDS/CATALOG COPY CMDS/PREFIX /RAM/CMDS/PREFIX You may find it convenient to put these commands in a PCS script file. Then you all you have to do is enter the name of the script file at the PCS prompt. In fact, if the name of the file is STARTUP and it's in the same directory as the Page - 7 Proton Command Shell Reference Manual PROTON.SYSTEM file, it will be executed automatically when you enter the PCS environment. Each PCS command is stored in a separate file with the file type OBP. The command name you type at the prompt "%" is based entirely on the name of the file. Thus, you can change the name of a command simply by changing its file name. For example, you could change the PREFIX command to CD (as an abbreviation for Change Directory, for example) simply by renaming the file PREFIX to CD in the CMDS directory on your working PCS disk or directory. (Note to RAM disk users: to make the change immediate, also rename the file in /RAM/CMDS too). Feel free to change the names of any of the utilities to names that you prefer. However, this manual refers to the utility names as they originally appear on your PCS disk. SUMMARY OF PROTON COMMANDS Parameters are shown for commands that support them. Brackets [] are used to denote optional parameters. Uppercase denotes commands and options you type exactly as is. Lower case letters denote file names or other options that you need to substitute. ASSEM Assemble a 6502 source program and create a binary program ASSEM assembly.source bin.file [listing.file] CATALOG List files in a ProDOS directory CATALOG [-L] [directory [listing.file]] CHANGE Change attributes of a file CHANGE file [access.parms [file.type [aux.type]]] CLOSE Close all open files CLOSE CMDPATH Define a ProDOS directory that has PCS commands CMDPATH directory COMPILE Compile a Proton source program to an OBP program COMP proton.source object.file [listing.file] COMPARE Compare two files and show differences COMPARE [-M] file.1 file.2 [listing.file] Page - 8 Proton Command Shell Reference Manual COPY Copy one or more files to a new file COPY file.1 [file.2 ... file.n] new.file COPYDIR Copy a directory and its files to a new directory COPYDIR directory new.directory CREATE Create an empty file or directory CREATE file [file.type [aux.type]] DECODE Decode a file in the UU encoded format DECODE uu.file bin.file DELETE Delete a file or directory DELETE file.1 [file.2 ... file.n] EDIT Edit a text file and backup the original text EDIT text.file [backup.file] ENCODE Encode a binary data file into the UU encoded format ENCODE bin.file uu.file FIND Find text in a file and display all occurrances of it FIND text [+n] text.file [listing.file] LOADBIN Load a portion of a binary file at a specific memory address BLOAD file [address [byte.offset [byte.length]]] MON Enter the ROM Monitor MON ONLINE Display all online block devices ONLINE PASSWORD Lock up the screen and request a password to resume PASSWORD [password] PREFIX Change the ProDOS directory prefix PREFIX [directory] QUIT Quit and exit the PCS Environment QUIT RECEIVE Copy data from an input device to a file RECEIVE file [slot] RENAME Rename a file RENAME file new.name Page - 9 Proton Command Shell Reference Manual SEND Copy data from a file to an output device SEND file [slot] SPLIT Split a text file into smaller pieces SPLIT num.lines text.file first.file SORT Sort data in file and copy results to a new file SORT column length text.file [sorted.file] TIME Display the current date and time TIME TYPE Display text data in a file using ASCII characters TYPE text.file TYPEHEX Display the data in a file using HEX characters TYPEHEX file [listing.file] Page - 10 Proton Command Shell Reference Manual Chapter 2: DESCRIPTION OF PROTON COMMANDS COMMAND PARAMETERS Unless otherwise stated, all output files (that is, files that have data written to them by the command), must not exist prior to executing any of the commands listed below. The command will create the file and then write data to it. All input files must already exist and contain data as required by the command. Unless otherwise stated, PCS commands will not alter input files. All files and directories are specified using standard ProDOS path names. That is, files are specified using the full directory path starting with the disk volume. Or, if the first portion of the path name matches the current prefix (set by the PREFIX command), that portion may be omitted. For PCS commands that have numerical parameters, decimal numbers must be in the range -32768 to 32767 to avoid a syntax error. If the command supports the parameter in hexadecimal form, it must entered with a $ prefix, and must be in the range $0 to $FFFF. Some commands may have additional restrictions. In the syntax shown for each command, the brackets [] are used to show optional parameters. The symbol ... is used to show a repeating parameter. Do not type these symbols. Substitute your own file and directory names for the lower case files and directories in the syntax line. Commands and options shown in upper case are to be typed in as is, letter by letter, but can be typed in lower case, if desired. That is CATALOG -L and catalog -l do the same thing. Optionally, any parameter may be quoted with quote (") characters. For example, MY.DATA and "MY.DATA" are equivalent. Quotes are required when you need to imbed a blank as part of a single parameter. Some commands allow parameters to be null, and thus are entered as a null string (""). If an error is produced while accessing a file or directory, the command will display a DOS error code. A list of the DOS error codes and their meaning is described in the next chapter. Page - 11 Proton Command Shell Reference Manual COMMAND REFERENCE ASSEM - Assemble a 6502 source program and create a binary program Syntax: ASSEM assembly.source bin.file [listing.file] Assembly.file is an input text file containing a 6502 assembly program. The remaining two files are output files. Bin.file receives the executable code that can be loaded into memory with the BLOAD command or the PROTON language READ statement. Once loaded it can be executed from the ROM monitor, or from a CALL statement or the BINSUBR DATA section in the PROTON language. Listing.file is a listing that contains a copy of the source with the memory address and assembled values of each 6502 instruction. It also has information about assembly errors if any are found. If listing.file is omitted, the listing is displayed on the screen. For more information about the format of the assembly source and listing, refer to the next chapter. CATALOG - List files in a ProDOS directory Syntax: CATALOG [-L] [directory [listing.file]] CATALOG lists all of the files and their types in the specified directory. If -L (or -l) is specified, a "long" listing is given which shows more information about each file. If the directory name is omitted, the current directory (as defined with PREFIX) is used. The files are listed in similar fashion as in that in BASIC, where the following information is displayed for each file: the file type and auxilary type, the file size in bytes and blocks, the date and time of creation and last modification. The file type is listed as a three letter mnemonic. These mnemonics listed in Chapter 3. The auxilary type, if shown, is listed as a decimal number for TXT file types and is listed as a hexadecimal number for other file types. With -L, CATALOG displays a unique column labeled ACC (for Access Parameters). This column has up to five characters - - if these characters are present it means: D - the file can be deleted N - the file can be renamed B - the file has not been backed up with a backup utility W - the file can be written R - the file can be read Page - 12 Proton Command Shell Reference Manual If any of these characters are absent, then a dash (-) is displayed and the opposite meaning is in effect. For example, if you don't see a D, then the file can not be deleted. If the listing.file parameter is an output file name, and if specified, the listing is written to the file. If it is omitted, the listing is displayed at the screen. To write the current directory to the listing file, use a null string for the directory name, e.g. "". CHANGE - Change attributes of a file Syntax: CHANGE file [access.parms [file.type [aux.type]]] CHANGE allows you to change three different attributes of a file: the access parameters, the file type, and the auxiliary file type. The access parameters are described with the CATALOG command. You can enter the parameter as it would appear on the CATALOG commmand, or you can leave out the dashes (-) if you prefer. For example, to unlock a file, enter DN-WR or DNWR for the access.parms parameter (or DNBWR to maintain the backup attribute). To lock a file enter ----R or R (or BR to include backup). To prevent any access to the file and remove the backup attribute, enter one or more dashes (e.g. - or -----). The letters can be enter in upper case or lower case. The file.type is entered as a three letter mnemonic as displayed by the CATALOG command. These mnemonics are listed in the Chapter 3. The aux.type parameter is entered as a decimal or hexadecimal number. It represents the file's auxiliary file type and is a number whose meaning depends on the file type. It's displayed with the file type in a CATALOG display (that is, if it is not zero). For example, a non-zero value for a TXT file is often interpreted to mean that the file is a random access file and the value is the length of its fixed sized records. For BIN files, the value is typically used as the memory address in which to load the binary data. For other file types, it has other meanings, or perhaps the value may be ignored. If any of these parameters are omitted or entered as a null string, they are ignored, that is, the parameter's attribute is not changed. Caveat: Simply changing the type of file does not mean the file will work properly with its new identity. Depending on Page - 13 Proton Command Shell Reference Manual what type you changed it from and changed it to, the internal format of the data may need to change too. This command does not modify the internal format. For example, changing the type of TXT file to BAS does not mean the file will run as a BASIC program. CLOSE - Close all open files Syntax: CLOSE CLOSE simply closes all open files, if there are any open. If there are none, this command does nothing. This command is usually not needed unless you happen to write and run your own programs and you find that your program forgot to close a file. Pressing control-RESET also closes all open files. CMDPATH - Define a ProDOS directory that has PCS commands Syntax: CMDPATH dir CMDPATH specifies a directory prefix that defines where OBP, SCR, BIN, or SYS files can be executed simply by typing the file's name. For example, if you type CMDPATH /MY.DISK/CMDS, then you can execute an OBP program in that directory, say MY.PROG, simply by typing MY.PROG as a command, rather than typing /MY.DISK/CMDS/MY.PROG. This is true regardless is the current directory prefix set by the PREFIX command. When you start up the PCS environment, the default CMDPATH directory is CMDS (without a specific volume name). If you switch to a different directory, chances are it won't have its own CMDS subdirectory, and then you lose the ability to type short simple command names (instead you have to add the volume name and CMD directory name in front of them. Therefore, if you plan to use the PREFIX command to switch to other directories, you first need to execute the CMDPATH command with the CMDS directory name fully qualified (that is it includes the volume name). COMPILE - Compile a Proton source program to an OBP object program Syntax: COMP proton.source object.file [listing.file] Proton.source is the name of an input file with a program written in the Proton programming language. However, the PCS can not run the program text directly. It must be compiled into object form. The remaining two files are output files. Object.file receives the object code and is Page - 14 Proton Command Shell Reference Manual created as an OBP file that you can later type as a command at the command prompt. Listing.file receives the listing that contains a copy of the source plus any error messages, that is, if COMP finds errors during the compilation. If listing.file is omitted, it is displayed on the screen. The listing file also displays an offset value with each line. If the PCS detects a run time error while running the OBP program, it displays an offset value that can be matched to a line in the listing that has the nearest offset that is less than or equal to it. That line corresponds to the proton statement where the run time error occurred. Refer to the Proton Language Reference Manual for information on how to write a Proton Program. COMPARE - Compare two files and show differences Syntax: COMPARE [-M] file.1 file.2 [listing.file] File.1 and file.2 are input files. COMPARE compares the lines of data in both files. Differences are written to the file specified as the listing.file parameter. If listing.file is omitted, the differences are displayed on the screen. If the -M (or -m) parameter is specified, listing.file receives one copy of the data that is common to both file.1 and file.2. Data that is unique to file.1 is highlighted in a box and is labeled as OLD. Data that is unique to file.2 is similarly highlighted and is labeled as NEW. In other words, both matching lines and differences are displayed. If -M is omitted, only differences are displayed. New lines are preceded with a + symbol, and old lines are preceded with a - symbol. If the differences between file.1 and file.2 represent small insertions or deletions of lines, the results will generally be satisfactory. More complex differences, such as movement of text from one place to another, may confuse COMPARE, resulting in more lines marked as different than there may actually be. However, COMPARE will never miss a difference. COPY - Copy one or more files to a new file Syntax: COPY file.1 [file.2 ... file.n] new.file In its simplest form, file.2 through file.n may be omitted. In this case, COPY creates new.file, and copies the data from file.1 into new.file. One or more additional files may Page - 15 Proton Command Shell Reference Manual be specified. The data from all files up to file.n are concatenated together and copied into new.file. COPYDIR - Copy a directory and its files to a new directory Syntax: COPYDIR directory new.directory The directory parameter is a directory that already exists with files in it. COPYDIR creates a new directory with the name specified on the new.directory parameter, and then copies all of the files from "directory" into "new.directory". COPYDIR will produce an error message if the new directory already exists. Currently, COPYDIR only copies files in the directory, and ignores any subdirectories in the directory. CREATE - Create an empty file or directory Syntax: CREATE file [file.type] CREATE allows you create a empty file or directory. File.type is a three letter mnemonic that tells PCS what type of file to create. To create a directory use a file.type of DIR, or omit the file.type parameter. For an empty file use one of the file type mnemonics listed in Chapter 3. TXT and BIN are common file types. DECODE - Decode a file that is in the UU encoded format. Syntax: DECODE uu.file bin.file DECODE allows you convert a file that contains UU encoded data. This encoding format is commonly used on systems running the Unix operating system to transfer binary data across computers. If you receive such a file, you can decode the data back to its original form. The uu.file is a file containing the encoded data, and the bin.file is the output file that recieves the decoded binary data. The uu.file ordinarily includes the original file name and file attributes, but these are ignored by this DECODE command. See also the ENCODE command. DELETE - Delete files or directories Syntax: DELETE file.1 [file.2 ... file.n] DELETE deletes file.1 from the disk. Any number of additional files may be entered on the command. Whatever Page - 16 Proton Command Shell Reference Manual files can be deleted, will be deleted. Error messages will be produced for files that can't be deleted. A directory can be specified in place of a file. However, for a directory to be deleted successfully, it must be empty, i.e., it must contain no files or other directories. If it has any, you'll need to delete those first. EDIT - Edit a text file and backup the original text Syntax: EDIT text.file [backup.file] EDIT is a full screen editor. It copies the data from the text.file into an "edit buffer" in the computer's memory. The edit buffer is displayed on the screen where the user can edit the data. When the user quits the editor, the edit "buffer" will be saved back into the text file. A back up copy of the original file is maintained in the file specified with the backup.file parameter. If no editing changes are made to the edit buffer, then the back up file will be a copy of original text file. If the back up file does not already exist, it will be created. If the back up file already exists, it will be over written. If backup.file parameter is omitted, then EDIT will default the backup file name to the text file name followed by a ".". In this case, the text file name must be less than 15 characters long. For example, if you type the command "EDIT MY.DATA", then the back up file will be named "MY.DATA.". If the text file does not exist, then EDIT will create the file and allows you to enter data starting with an empty edit buffer. In this case, no backup file is created, and if the backup.file parameter is specified, it is ignored. For information regarding the operation of the editor, refer to the Chapter 3. ENCODE - Encode a binary file into the UU encoding format. Syntax: ENCODE bin.file uu.file ENCODE allows you convert a binary file to one that contains UU encoded data. This encoding format is commonly used on systems running the Unix operating system to transfer binary data across computers. The format consists only of printable ASCII characters and newlines so that transfers may occur across varied systems without loss of data. If you have need of this feature, you can encode binary, transfer it, and then have it decoded on another computer Page - 17 Proton Command Shell Reference Manual system. The bin.file is a file containing the original data, and the uu.file is the output file that recieves the encoded binary data. ENCODE stores the original bin.file name and the unix file permissions 755 in the uu.file. See also the DECODE command. FIND - Find text in a file and display all occurrances of it Syntax: FIND string [+n] text.file [listing.file] The string parameter is simply a string of characters that you want to find in the file specified by the text.file parameter. If the string contains blanks, then you will need to quote it with double quote characters. FIND will look at each line in the text file, and display all lines that contain the character string. The +n parameter is the "+" symbol followed by a number. If specified, FIND will also display the next "n" lines that occur after the each line that contains the string. If the listing.file parameter is specifed, the matching lines are written to the file. If it is omitted, then the lines are displayed on the screen. For example, if the file PROTON.LISTING contains a Proton language compilation listing (produced by the COMP command), then to display all error messages and the line on which each error occurs, use the command: FIND "] Error" +1 PROTON.LISTING FREESHR - Free the Super High Res screen from the IIGS Finder Syntax: FREESHR Use this command only if you call the PCS (i.e. select the PROTON.SYSTEM file) from the IIGS Finder and you want to run a Proton program that is designed to use the SHR (Super High Res Screen). The Finder keeps the screen "locked up" until you use this command. If you use FREESHR, don't forget to run the RETSHR command before you return to the Finder. Otherwise, you may crash the Finder when you go back to it. Page - 18 Proton Command Shell Reference Manual LOADBIN - Load a portion of a binary file at a specific memory address Syntax: LOADBIN file [address [byte.offset [byte.length]]] BLOAD loads the file at a specified memory address in the computer memory. BLOAD loads the number of bytes specified by the byte.length parameter, starting at a byte offset in the file specified by the byte.offset parameter. The address, byte.offset and byte.length parameters are all numbers and can be entered in decimal or hexadeximal form. If you omit the address or specify it as a null string, the address will default to that stored in the file's auxiliary type. If you omit the byte.offset parameter or specify it as null, it defaults to 0 (the beginning of the file). If you omit the the byte.length or specify it as null, it will default to the full length of the file. This command is intended to load files with a type of BIN, but BLOAD loads a file of any type. MON - Enter the ROM Monitor Syntax: MON MON enters the Machine Language Monitor built into the ROM of all Apple IIs. This is equivalent to typing CALL -151 in BASIC. To escape the monitor, and get back to the PCS prompt, press Control Y (unless you override the function of Control Y while in the monitor). Another way to escape is to enter the monitor command 3D0G (that's a zero in there, not an O, folks). If that fails, try A014G. While in the monitor, all memory is free (available for your use) in most of page 3 (starting at $300), and all memory between $800 and $9FFF, inclusive. ONLINE - Display all online block devices Syntax: ONLINE A block device is any device that stores data in block format, such as a floppy disk drive, a hard disk drive, and a RAM disk. This command displays all block devices currently active (online) on your computer system. It displays the Slot number, drive number, and volume name of the device. If the volume name can not be retrieved, then a DOS error number is displayed in its place. Page - 19 Proton Command Shell Reference Manual PASSWORD - Lock up the screen and request a password to resume Syntax: PASSWORD [password] The password parameter is an arbitrary string of characters. If you omit the parameter, then the command will prompt you for it. PASSWORD will clear the screen and prompt you to re-enter the password. If you don't get it right it will keep prompting you for it. This keeps unauthorized people (both little and big) from disturbing your PCS session. PASSWORD can easily be thwarted by pressing Control-Reset. PATCH - Make changes to a non text file Syntax: PATCH file PREFIX - Change the ProDOS directory prefix Syntax: PREFIX [directory] PREFIX makes it easier to specify files and directories. What ever you enter on the PREFIX command you don't have to specify on the file path names on subsequent commands. For example, instead of typing: COPY /MY.DISK/MY.DIR/MY.FILE /MY.DISK/MY.DIR/FILE.O.MINE You can type: PREFIX /MY.DISK COPY MY.DIR/MY.FILE MY.DIR/FILE.O.MINE Or even better yet: PREFIX /MY.DISK/MY.DIR COPY MY.FILE FILE.O.MINE The specified directory remains the current prefix for all subsequent commands until another PREFIX command is entered to change it. If you use .. for the directory parameter, PREFIX changes the prefix to the next higher level directory. For example, if the current prefix is: /MY.DISK/MY.DIR Entering the command PREFIX .. changes it to: /MY.DISK Entering PREFIX with no directory parameter displays the current directory prefix, and makes no changes to the prefix. Page - 20 Proton Command Shell Reference Manual QUIT - Quit and exit the PCS Environment Syntax: QUIT When you are ready to quit a PCS session enter the QUIT command. You should always do this before turning off the computer to guarentee that all data written to files actually makes it to the physical disk drive(s). This command will return you to the ProDOS selector, or possibly another selector program that you may customarily use. For example, if you started PCS from the IIGS Finder (by selecting PROTON.SYSTEM), then you will be return to the finder. By the way, if you did use the finder, and if you used the FREESHR command, be sure you enter the RETSHR command before the QUIT command. RECEIVE - Copy data from an input device to a file Syntax: RECEIVE file [slot] RECEIVE allows you to specify the slot number of an input device (such as a modem connected to your serial port). For example, to read data in from a serial port in slot 2, and put the data into a file called MY.DATA, then enter the command "SEND MY.DATA 2". RECEIVE creates the file and all data collected from the slot is written to the file. To stop the RECEIVE command from collecting data, press the Open-Apple key. If the slot number is omitted, it defaults to 1. RENAME - Rename a file Syntax: RENAME file new.name The first parameter is the name of a file or as it exists prior to the rename. The second parameter is the file's new name. RENAME will also rename a directory. RETSHR - Return the Super High Res screen to the IIGS finder Syntax: RETSHR Use RETSHR returns the SHR (Super High Res) screen back to the IIGS Finder. Use this command only if you have used the FREESHR command, and are ready to return back to the Finder with the QUIT command. Page - 21 Proton Command Shell Reference Manual SEND - Copy data from a file to an output device Syntax: SEND file [slot] SEND allows you to specify the slot number of a character stream output device, such as a serial port or parallel card. For example, to write data that exists the the file MY.DATA out to a serial port in slot 2, enter the command "SEND MY.DATA 2". SEND reads all data in the file and writes it out to the slot device. For example, SEND could be used to print a text file, by specifying the slot number of the printer. SORT - Sort data in file and copy results to a new file Syntax: SORT column length text.file [sorted.file] The text.file parameter is the name of an input file with data that needs to be sorted. SORT sorts the lines of data in the file, and writes the results to the file named by sorted.file. The column and length parameters defines a field in text.file that will be the basis of the sorting. The column parameter is the column number where the field begins. The length parameter defines the length of the field (i.e. how many columns are to be used). The sorting is done against the field in ascending order based on the ASCII collating sequence. All columns are copied to the file named by sorted.file, regardless of what columns are used to define the sorting order. If the column parameter is a null string, it defaults to 1. If the length parameter is a null string, it defaults to the whatever the length is to the end of each line. Suppose you have a file called CUSTOMERS that has a list of names and the last name always begins in column 11 and can go to column 25 (i.e. the last name field is 15 characters long). Then to sort the lines in the file in alphabetical order by last name then use the command: SORT 11 15 CUSTOMERS CUSTOMERS.SORT SORT will create the file CUSTOMERS.SORT and put the sorted lines in it. The original file CUSTOMERS will remain unaffected. If you have matching last names, then those lines will be sorted next to each other, but their respective order will be the same as in the original file. You can use this fact to sort multiple fields using multiples passes with SORT. For example, to sort the first names, when you have matching last names, sort the first names firsts. Let's assume the first names are in columns 1 through 10. We'll use an intermediate file called TEMP. The commands you use are: SORT 1 10 CUSTOMERS TEMP Page - 22 Proton Command Shell Reference Manual SORT 11 15 TEMP CUSTOMERS.SORT SPLIT - Split a text file into smaller pieces Syntax: SPLIT num.lines text.file first.file SPLIT breaks up a large file into smaller files that has "num.lines" number of lines each. The last file can contain less than "num.lines" lines. The first file is given by the third paramater, and receives the first piece of the file. The remaining pieces go into files whose names are derived from the first file: the last letter or number is incremented. For example, if the text file MY.TEXT contains 2300 lines of text, the following command SPLIT 1000 MY.TEXT X.A creates three files called x.a, x.b, x.c and they will contain 1000, 1000, and 300 lines of text respectively: By the way, you could reassemble these pieces back into one new text file called MY.NEW.TEXT with the following command: COPY X.A X.B X.C MY.NEW.TEXT TIME - Display the current date and time Syntax: TIME TIME simply displays the current date and time in the format: MM/DD/YY HH:MM:SS That is, it displays them in the order: month, day, year, hours, minutes, seconds. TYPE - Display text data in a file using ASCII characters Syntax: TYPE text.file TYPE displays the data contents of the file named by the text.file parameter to the screen. To avoid screen display problems, only use TYPE for files that have ordinary text. TYPEHEX - Display the data in a file using HEX characters Syntax: TYPEHEX file [listing.file] TYPEHEX displays the data contents of the file named by file parameter. However, each byte is displayed as a hexadecimal number. TYPEHEX is useful for files that have binary data that can not be displayed as ordinary text. TYPEHEX displays data in a format that is similar to the memory display in the ROM monitor. Each line of displayed output Page - 23 Proton Command Shell Reference Manual shows an address relative to the start of the file, 16 bytes of data represented by hexadecimal, followed by an attempt to display the sixteen 16 bytes as ASCII characters. A period "." is used to represent nondisplayable characters. Page - 24 Proton Command Shell Reference Manual Chapter 3: SUPPLEMENTAL INFORMATION DOS ERROR CODES If an error is produced while accessing a file or directory, a PCS command will display a DOS error number. The meaning of each number is described in the following table: 39 - I/O Error: a disk is not in a drive, or the disk is not properly formatted with ProDOS, or the disk is damaged. 43 - Write Protected: a write protect tab or switch is enabled on the disk. 46 - Volume switched: a disk was removed and replaced while accessing a file on the disk. 64 - Invalid syntax for file or directory name: the given file name does not begin with a letter, or has invalid characters in its name (valid characters are letters, numbers, and periods), or is more than 15 characters long, or is prefixed with an invalid directory prefix (a valid prefix has one or more directory names, each separated by a slash (/). 66 - Too many open files: No more than eight files may be open at the same time. 68 - Path does not exist: file name is prefixed with a directory prefix that has a directory which does not exist. 69 - Volume not mounted: The specified volume in the file path is not in any disk drive. 70 - File does not exist: the file could not be found in the file path directory. 71 - Duplicate file name: an attempt was made to create or rename a file that already exists. 72 - Disk full: no more room exists on the disk volume to finish writing the file. 73 - Volume directory full: an attempt was made to create a file in the volume directory but no more are allowed. 78 - Access Error: an attempt was made to read, write, delete, or rename a file that is locked for that operation; the access parameters must be changed first. 80 - File open already: a file was not closed properly in a previous command; press control-reset to close all open files. 81 - Bad file count in directory: ProDOS internal file count data in one of the directories in the file path was found to be inconsistent. 82 - Not a ProDOS disk: The specified volume is not a ProDOS disk. 86 - Bad buffer address: an attempt was made to set aside memory for buffering file data, but no memory is available. 87 - Duplicate volume: a volume with the same name was found in more than one disk drive. Page - 25 Proton Command Shell Reference Manual 88 - Bad volume bit map: ProDOS internal data used to indicate used and free disk space on a disk volume was found to be inconsistent. PRODOS FILE TYPES Below are a list of all ProDOS file types that have mnemonics supported by PCS. Each file type has an associated number that can often be used instead of the mnemonic. The first and second columns list the number in decimal form and hexadecimal form, respectively. The third column lists the file type mnenomic that is displayed by or entered on PCS commands. The last column is a description of what the file type means or what the file should contain. 0 $00 NOT No Type 1 $01 BAD Bad Blocks (for reserving bad areas of disk from use) 2 $02 PCD SOS Pascal Code 3 $03 PTX SOS Pascal Text 4 $04 TXT ASCII text 5 $05 PDA SOS Pascal Data File 6 $06 BIN Binary Data 7 $07 CHR SOS Character Font 8 $08 PIC Picture Graphics 9 $09 BA3 SOS Business BASIC Program 10 $0A DA3 SOS Business BASIC Data 11 $0B WPD SOS Word Processor Document 12 $0C SOS SOS System Data 15 $0F DIR Subdirectory 16 $10 RPD SOS RPS Data 17 $11 RPI SOS RPS Index 18 $12 AFD SOS AppleFile Discard 19 $13 AFM SOS AppleFile Model 20 $14 AFR SOS AppleFile Report Format 21 $15 SCL SOS Screen Library 22 $16 PFS SOS PFS Document 25 $19 ADB AppleWorks Database 26 $1A AWP AppleWorks Word Processing 27 $1B ASP AppleWorks Spreadsheet 32 $20 DTM Desktop Manager Document 33 $21 IPS Instant Pascal Source 34 $22 UPV UCSD Pascal Volume 41 $29 DIC SOS Dictionary 42 $2A SR2 Apple II Source Code 43 $2B OB2 Apple II Object Code 44 $2C IN2 Apple II Interpreted Code 45 $2D LA2 Apple II Language Data 46 $2E PCM ProDOS Code Module 47 $2F OBP Proton Formatted Object 66 $42 FTN File Type Names 80 $50 GWP GS Word Processor 81 $51 GSP GS Spreadsheet 82 $52 GDB GS Data Base Page - 26 Proton Command Shell Reference Manual 83 $53 DRW Drawing 84 $54 DTP Desktop Publishing 85 $55 HYP Hypermedia 86 $56 EDU Educational 87 $57 STA Stationary 88 $58 HLP Help 89 $59 COM Communications 90 $5A CFG Configuration 91 $5B ANM Animation 92 $5C MUL Multimedia Document 93 $5D GAM Game and Entertainment Document 94 $5E DEV Development Utility Document 107 $6B BIO PC Transporter BIOS 109 $6D DDT PC Transporter device drivers 110 $6E PRE PC Transporter Pre-boot 111 $6F HDV PC Transporter MSDOS Hard Disk Volume 160 $A0 WPF WordPerfect Document 171 $AB BAG GS BASIC Program 172 $AC TDG GS BASIC TDF 173 $AD DAG GS BASIC Data 176 $B0 SRC GS Source Program 177 $B1 OBJ GS Object Code 178 $B2 LIB GS Library 179 $B3 S16 GS 16-bit System Application 180 $B4 RTL GS Runtime Library 181 $B5 EXE GS Executable Shell Application 182 $B6 PIF GS Permanent Initialization File 183 $B7 TIF GS Temporary Initialization File 184 $B8 NDA GS New Desk Accessory 185 $B9 CDA GS Classic Desk Accessory 186 $BA TOL GS Tool Set 187 $BB DVR GS Device Driver 188 $BC LDF GS Generic Load File 190 $BD FST GS File System Translator 191 $BF DOC GS Document 192 $C0 PNT GS Paint Document 193 $C1 SHR GS Super High Resolution Screen Image 194 $C2 PAN GS Paint Animation 195 $C3 PAL GS Paint Palette 197 $C5 OOG Object Oriented Graphics 198 $C6 SCR Script 199 $C7 CDV Control Panel Device 200 $C8 FNT Character Font 201 $C9 FND Finder Data 202 $CA ICN Finder Icons 213 $D5 MCS Music Construction Song 214 $D6 MCI Music Construction Instrument 215 $D7 MID MIDI Standard Data 216 $D8 IFF Audio IFF Document 219 $DB DBM DB Master Document 224 $E0 ALU ALU Library 226 $E2 ATI Appletalk Initialization 238 $EE R16 EDASM 816 Relocatable Code 239 $EF PAS ProDOS Pascal Program Page - 27 Proton Command Shell Reference Manual 240 $F0 CMD BASIC Command Addition 241 $F1 US1 User 1 Data 242 $F2 US2 User 2 Data 243 $F3 US3 User 3 Data 244 $F4 US4 User 4 Data 245 $F5 US5 User 5 Data 246 $F6 US6 User 6 Data 247 $F7 US7 User 7 Data 248 $F8 US8 User 8 Data 249 $F9 SYG GS System Data 250 $FA INT Integer BASIC Program 251 $FB IVR Integer BASIC Variables 252 $FC BAS AppleSoft BASIC Program 253 $FD VAR AppleSoft BASIC Variables 254 $FE REL ProDOS EDASM Relocatable Code 255 $FF SYS ProDOS System Application OPERATION OF THE EDITOR Editing functions are entered as control keys. For example to quit the editor, press Control Q. Pressing a key without holding the control key will simply insert a character at the cursor. Or the user can enter the "escape" mode, where the editing functions are available without pressing the Control key. However, text cannot be inserted while in the "escape" mode. Use the "Escape" key to toggle between the two modes. The bottom line of the screen has the word "Esc" if the "escape" mode is active. Below is a summary of the editing functions and the key you press to get the functions (the control key must be pressed too, when not in the "escape" mode). A - Find text Again using the same text entered with the F command. B - go to the Bottom of the file. C - Copy text from the origin (marked with the O command) to the cursor and put the copy in the paste buffer. D - Delete text from the origin (marked with the O command) to the cursor and put it in the paste buffer. E - Enter text from the paste buffer at the cursor; after the text is entered, the paste buffer still has a copy of the text. F - Find the next occurrence of some text in the edit buffer; you will be prompted for it at the top of the screen. G - Go to a line given by a line number; you will be prompted for the line line number at the top of the screen. H - "Hike" (move) the cursor one character to the left (same as left arrow key). Page - 28 Proton Command Shell Reference Manual I - Insert one or more blanks at the cursor; the number of blanks is defined by the W function (the I command is same as the TAB key). J - Make the cursor "Jump" down one line (same as the down arrow key). K - "Kick" the cursor up one line (same as the up arrow key). L - Move the cursor to the Left side of the line (to the beginning of the line). M - Make (insert) a carriage return at the cursor (same as the RETURN key). N - Scroll down to the Next screen. O - At the cursor, mark an Origin (the beginning of a range of text) for the C and D commands. P - Scroll up to the Previous Screen. Q - Quit the editor and save changes to the file. R - Move the cursor to the Right side of the line (to the end of the line) T - Go to the Top of the file. U - "Urge" (move) the cursor one character to the right (same as the right arrow key). W - Prompt for the Width (number of characters) used by the I (TAB) and X commands. X - X-out (delete) one or more characters at the cursor; the number of characters is defined by the W function (the X command is the same as the CLEAR key on the IIgs). The editor supports a paste buffer. The C and D commands move selected data from the edit buffer into the paste buffer (replacing data already there), and E copies the paste buffer back into the edit buffer. For example, to move text from one portion of your file (that is, the edit buffer) to another location: press Control O on the first character of your text to move, press Control D right after the last character to delete it, move the cursor to the data's new location, and press Control E to enter it in the new location. Copying text from one place to another (without affecting the original text) is accomplished the same way, except use control C instead of control D. If you want additional copies of the same data in your file, just move the cursor where ever you want a copy and press control E. Often, a useful thing to do in an editor is to do a repetitive search and replace. For example, you might want to change all occurrences of Bill to William. To do this in the PCS editor, first, type in the replacement string (e.g. William) anywhere in the edit buffer and delete it with the O and D commands. This puts the replace string in the paste buffer. Then set the Width parameter to the number of characters in the search string with the W command (for example, enter 4 for Bill). Then find the search string with the F command; it will prompt you for the search string Page - 29 Proton Command Shell Reference Manual (where you can type Bill, for example). If you want to replace the found string, use the X command to delete it and the E command to insert the new text. Repeat this process by finding subsequent occurrences of the search string with the A command and replacing each occurrence (when desired) with the X and E commands. Ironically, this sequence can be remembered by the appropriate mnemonic AXE. OPERATION OF THE ASSEMBLER The assembly program for the PCS assembler must use the standard Apple mnemonics for 6502 opcodes. Each instruction has the format: label opcode argument ; comment The "label" and "; comment" portions are optional. One or more blanks must separate the label and opcode, and the opcode and argument. The label, if included, must begin in column 1. A label can be up to 8 characters long. It must start with an alphabetic character can be followed by alphabetic, numeric, or "." characters. If the label is omitted, at least one blank must precede the opcode. Hint: In the PCS editor you may find it convenient to set the TAB width to a number such as 9, and use the TAB key for indenting lines without labels. The argument, depending on the opcode, can be one of the following: #num addr (addr),Y (addr),X (addr,X) (addr) Addr or num must be a one byte value, a two byte value, or either depending on the opcode. If the opcode supports either, and the value fits in one byte, normally it will be assembled as a byte. However, if the addr is or contains a label that is defined later in the source program, it will be assembled as two bytes. Addr or num may be a number or an expression. A number is one of the following: decimal number (e.g. 235) a hex number (e.g. $C000) a label. An expression is a number that optionally can be preceded by a the function < or >, optionally followed by a + or -, another optional function and a number. < takes the high byte of a number and > takes the low byte of a number. For example, <$C050 results in $C0 (192) and >$C050 results in $50 (80). The + or - adds or subtracts the two numbers. The following Pseudo opcodes are supported: ORG addr ; define address where code is assembled Page - 30 Proton Command Shell Reference Manual label EQU num ; make label equal to num (can be an addr) label BYT num ; assemble num in one memory byte label WRD num ; assemble num in one memory word (2 bytes) Comments can be placed on an entire line by putting a * in column one. Example source for file.1: KEY EQU $C000 ;Define Key to be equal to be a hex number LOOP LDA #