Extended Command Processor 8 User Guide Version 5 19 Janurary 1989 By Donald R. Elton Carolina System Software [0.10] Table of Contents: Topic: Section: Table of contents.................................. 0.10 Program bugs....................................... 0.20 Notices............................................ 0.30 ECP8 Extensions.................................... 0.40 Introduction....................................... 1.00 Functional diagram................................. 1.10 ProDOS file types used with ECP8................... 1.20 Other ProDOS file types............................ 1.30 Definitions........................................ 1.40 Installation instructions.......................... 1.50 ECP8 commands...................................... 2.00 ECP8 command types................................. 2.10 Line editing....................................... 2.20 ECP8 Batch programs................................. 3.00 Positional parameters with ECP8 Batch programs...... 3.10 Conditional execution with ECP8 Batch programs...... 3.20 Special ECP8 Batch programs......................... 3.30 Using ECP8 with other programs..................... 4.00 ECP8 command descriptions (alphabetical)........... 5.00 (c) 1989 -1- Carolina System Software Extended Command Processor 8 [0.20] Program Bugs: This program is a complex system that is constantly undergoing changes to improve performance and add features. If, during your use of this program, you note any discrepancy between the actual program action and this documentation or if you have suggestions for new features or improvement of old features then we would greatly appreciate your sending us a note describing you suggestions/findings. You may write to the author at the following address: Donald R. Elton 3207 Berkeley Forest Drive Columbia, SC 29209 ProLine [Pro-Carolina] 1-803-776-3936 (300/1200/2400 baud) [0.30] Notices: APPLE COMPUTER, INC. AND THE AUTHOR MAKE NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE. ProDOS 8, FILER, CONVERT, and BASIC.SYSTEM are copyrighted programs of Apple Computer, Inc. licensed to Carolina System Software to distribute for use only in combination with the Extended Command Processor. Apple Software shall not be copied onto another diskette (except for archive purposes) or into memory unless as part of the execution of the Extended Command Processor. When the Extended Command Processor has completed execution Apple Software shall not be used by any other program. The External commands GREP, SIZEOF, WHERES, SORTDIR, and COPYDIR were written by Brian Fox, an early ECP customer and user. He's donated these commands to the ECP package. Brian has also written a full Apple ProDOS implementation of the popular editor EMACS. His package is called AMACS and is available from him for $75 at this printing. You can contact Brian at: Brian Fox Creative Thinking, Included. 21 Commonwealth Terrace Brookline, MA 02146 (c) 1989 -2- Carolina System Software Extended Command Processor 8 [1.00] Introduction: The Extended Command Processor 8 (ECP8) is an operating system shell and program selector for use with Apple Computer Inc's ProDOS (tm) Professional Disk Operating System. This program is compatible with the Apple IIgs, Apple //e, Enhanced Apple //e, Apple //c, Apple ][+, and other computers capable of running ProDOS 8. This documentation assumes that you have some familiarity with ProDOS such as might be obtained by reading the User's guide for ProDOS. Several more advanced features of ECP8 designed for assembly language programmers may require that you have access to the ProDOS technical manuals. The documentation for ECP8 is divided into three parts. Part I is the User Guide which is an explanation of how to use ECP8 as it is shipped from the publisher. This guide requires no programming experience and many users will find it the only manual they need to read. Part II is the disk based HELP facility. This is a quick reference of ECP8 command syntax and usage rules that is always available when in the ECP8.SYSTEM program by entering "HELP" or "?" at the ":" prompt. Much of the information contained in the User's Guide is available in abbreviated form on the ECP8 system disk. Part III of the ECP8 documentation is the Technical Reference Guide. This explains in detail the inner workings of ECP8.SYSTEM and gives assembly language programmers the information they will need to write their own custom commands and other features to augment the ECP8 system. This guide also includes documentation for all of the machine language subroutines, entry points, and global variables that an assembly language programmer can use to write powerful routines designed to run within the ECP8 environment. ECP8 is both an operating system shell and a program selector. You may think of ECP8 as a bridge between you the user, and the ProDOS operating system. ECP8 also acts as a means of switching between application programs that run under ProDOS. The following diagram shows the place of ECP8 in relation to other ProDOS elements: (c) 1989 -3- Carolina System Software Extended Command Processor 8 [1.10] Functional Diagram: Hardware | Device Drivers | ProDOS <---> S16 Programs | SYS Programs <---> ECP8 <---> BIN Programs /\ / \ / \ / \ BAT Programs CMD Programs Note that Basic programs are really run by BASIC.SYSTEM, (renamed to BASIC), a SYS program. ECP8 can make BASIC.SYSTEM start a particular Basic program, however, simulating ECP8 actually running the basic program directly. (c) 1989 -5- Carolina System Software Extended Command Processor 8 [1.20] ProDOS File types used with ECP8: When you CATalog a ProDOS volume, each file is displayed along with a 3 letter ProDOS file type. A file type gives a hint as to what kind of information the file holds. The following file types are commonly seen on ProDOS volumes: BIN - This is the type given to BINary files. A BINary file is one that contains 8 bit data or machine language programs. Unfortunately, there is no easy way to tell what is actually contained in a BIN file from the type alone so other means such as examining the file name must be used to determine their contents. The AUX type field of a BIN file typically contains the load address of the file in memory. When you start a BIN program from ECP8, ECP8 looks at this AUX type field to determine where the file should be loaded prior to execution. CMD - This is the type given to files that are transient command programs for ECP8. They are binary in nature (contain machine language programs). BIN files may also contain ECP8 transient commands but it is assumed that BIN programs are NOT dependent upon the internals of ECP8 while CMD programs are. LBR - This is the type given to library files. A library file is a file that contains several other related files that have been grouped together using ECP8's LU (Library Utility) command [available in the ECP8 file utility extension package]. A typical use for these files would be to group several related files to facilitate transmission together via modem or for archiving. TXT - This is the type given to files of ASCII (readable) text. Text files are used to hold books, program data, letters, or reports. You can easily display a TXT file to the screen with the ECP8 TYPE command to help determine their contents. BAT - This is a special file type that designates a special TXT file that contains commands for ECP8, also known as an ECP8 Batch program. SYS - This is the type given to files that contain special machine language programs such as ECP8 that are called SYSTEM programs by the ProDOS technical reference manual. They have the ability to be the first program run after ProDOS itself is loaded. All SYS programs load at address $2000. (c) 1989 -5- Carolina System Software Extended Command Processor 8 S16 - This is the file type for ProDOS 16 System programs. ECP8 can launch S16 programs provided that you set up a ProDOS 16 system disk described elsewhere. DIR - This is the type given to directory files. You may create or delete empty directory files but only ProDOS itself can modify them. A directory file holds information about the location and type of files in a ProDOS subdirectory. BAS - This is a type given to special binary files that contain BASIC programs. They are loaded and executed by BASIC.SYSTEM, (renamed as BASIC) either directly or from ECP8. [1.30] Other ProDOS/SOS file types: BAD - Used to cover up a defective part of the disk media. PCD - Pascal code file. PTX - Pascal text file. PDA - Pascal data file, also used by Quark's Catalyst. FNT - Font file. FOT - Foto file (screen image). BA3 - Apple /// Basic file. DA3 - Apple /// Basic data file. WPF - Word processor file. SOS - Apple /// SOS file. RPD, RPI - Apple /// application specific files. AWP, ASP, ADB - AppleWorks files. PAS - ProDOS Pascal file. IVR - Integer Basic variables file. VAR - ProDOS Applesoft basic variables file. REL - EDASM RELocatable binary file. OBJ - ORCA/M relocatable OBJect module. INT - Integer BASIC program file. SRC - ORCA/M source file. LNK - ProDOS EDASM Linker files. MAC - Ascii Express or WordPerfect macro files HLP - WordPerfect Help files DAT - WordPerfect data files LEX - WordPerfect dictionary files EXE - ProDOS 16 shell program CDA - Classic Desk Accessory NDA - New Desk Accessory TOL - Tool file STR - Startup file (c) 1989 -6- Carolina System Software Extended Command Processor 8 [1.40] Definitions: ARGUMENTS - ECP8 is a command-oriented product. This means that you communicate with ECP8 by typing commands at the keyboard. Most commands have arguments or qualifiers that direct the command-handlers in software where they are to do their work. For example, the CAT command has an optional argument that allows you to specify what directory is to be listed. If the argument is not given, then the prefix directory is listed. When you enter a command at the keyboard you must separate the command name from the first argument (if any) with a space character. Subsequent arguments for the same command may be separated by either a space character or a comma. If the argument to be passed to the command-handler must include characters that could be interpreted as argument separators then you must enclose the argument in quotes. All of the following are equivalent commands for ECP8: CAT /a /b [list directory for volumes "/A" and "/B"] CAT /a,/b [arguments separated by comma] CAT "/a" "/b" [enclosed by quotes, separated by space] CAT '/a' '/b' [enclosed by half-quotes] Note that you may use either double or half-quotes to enclose arguments. This means that you can include one type of quote character inside the text of the argument itself by using the other type of quote character as the delimeter. This is important when you are using a command with a free-text type of argument such as the FKEY, SAY, XMIT, and MON commands. BASIC - This is the Apple-supplied BASIC.SYSTEM program that allows you to run BASIC programs under ProDOS. If this is the first SYS file whose name ends with ".SYSTEM" in your disk directory then it will be run automatically by ProDOS when you BOOT (startup) your disk. It has been renamed from "BASIC.SYSTEM" to simply "BASIC" so you can start ProDOS Basic programs by specifying "BASIC " from the ECP8 command prompt. (c) 1989 -7- Carolina System Software Extended Command Processor 8 Boot - This is the process of starting up a disk device. From basic you can initiate this process by entering the command PR # where is the number of the slot that contains the disk controller card of the device you wish to start up. On the Apple this will usually be slot 6. If you wish to startup a hard disk then consult the documentation for your particular hard disk for directions on how to startup from that drive. Some hard disk drives cannot be automatically started up. On the Apple //e and //c you can cause a disk to be booted (started up) by holding down the CONTROL, OPEN APPLE, and RESET keys simultaneously. Built-in Commands - Built-in commands are commands that are contained within ECP8.SYSTEM and are thus always available as long as ECP8.SYSTEM is in memory. See Transient Commands, ECP8 Commands. ECP8.SYSTEM - This is the main program of the Extended Command Processor. It is a standard ProDOS system program or interpreter. If it is the first file of type SYS whose name ends with ".SYSTEM" in your disk directory then it will be run automatically by PRODOS when you startup (boot) your disk. Operating System Shell - An operating system shell program is a computer program that acts as an intermediary between the user and the regular operating system of the computer. ECP8 is a shell that takes commands from you the user and passes them to ProDOS. A shell frequently adds functions not previously available directly from the operating system and makes it easier for the user to access operating system features that were not previously readily available. Pathname - A pathname is a path of directories required to access a specific file on a disk device. To reference a file named "MYDATA" on volume "/MY.DISK" you would use a "path" to the file: "/MY.DISK/MYDATA". Some files may be additional directories and those directories may contain references to more files or more directories. Directories other than the main volume directory are called subdirectories. If you want to refer to a file contained in a subdirectory then you must include those intermediate subdirectory names in your full pathname. Say you have a volume called "/GAMES" and have a subdirectory called "ADVENTURE" and have a file called "WAR" the complete pathname to access the file "WAR" would be: "/GAMES/ADVENTURE/WAR". See PREFIX and VOLUME. (c) 1989 -8- Carolina System Software Extended Command Processor 8 Prefix - The ProDOS prefix is a standard default partial pathname that is added to any file name you specify if your pathname is not fully qualified. A fully qualified pathname is one that starts with the volume name followed by any subdirectories that must be accessed to find the file in question. A prefix is used to shorten the amount of typing you must do to specify a pathname to a file. As an example. Suppose you have a volume called "/MY.DISK" and that volume has a subdirectory called "GAMES" and you have a program file called "WAR" that is in the "GAMES" subdirectory. Without a prefix, you would have to use "/MY.DISK/GAMES/WAR" as the pathname to your file. You could, however, set the prefix to "/MY.DISK/GAMES" and then you would only have to specify "WAR" as your pathname as "/MY.DISK/GAMES" would be automatically attached to the pathname you specified. Prefix directory - The PREFIX DIRECTORY is the directory specified by the current ProDOS prefix. i.e. if the prefix is set as "/MY.DISK/GAMES" then the PREFIX DIRECTORY would be the subdirectory called "GAMES" found in the "/MY.DISK" volume directory. ProDOS 8 - Apple's Professional Disk Operating System. This is the software contained in the file PRODOS that handles all low level access to devices such as disk drives that are connected to your computer. Note that ProDOS 8 is a replacement and update to ProDOS 1.1.1 previously shipped with ECP. Program Selector - A ProDOS program selector is a program that is used to switch from one ProDOS 8 system program to another. When you leave a ProDOS 8 system program via the QUIT or BYE option, a selector program, if available, is automatically loaded into memory. (c) 1989 -9- Carolina System Software Extended Command Processor 8 RESET - If you get yourself into a part of the program and can't leave, then as a last resort you can usually use a CONTROL-RESET command. You execute this feature by holding down the CONTROL and RESET keys simultaneously, followed by releasing the RESET key. Note that if you use this option while ECP8 is trying to write to disk that you may damage the data on your disk. A common reason you might have to use this option would be routine output to a printer that does not exists. ECP8 will wait for the printer to become ready and it never will, thus using CONTROL-RESET is the only way out of the situation short of buying a printer or turning off your computer. In the event of a serious software failure, a FATAL ERROR message will be displayed. You should record any screen message and if the reason for the error is not apparent contact the program author. Pressing CONTROL-RESET will reset most fatal errors. Root Directory - The ROOT DIRECTORY is the directory that ECP8.SYSTEM will search to find the HELP and CMDS subdirectories and the CP.KEYS Batch program. This is normally the directory that the ECP8.SYSTEM program is stored in at startup time. You can change the ROOT DIRECTORY to the PREFIX DIRECTORY by pressing CONTROL and C simultaneously or by entering the CTRLC command at the keyboard or from a Batch program. Transient Commands - These are commands that are stored on disk rather than in memory. Normally these are only kept in memory while they are being executed. Transient commands can be written in such a way as to reserve memory to perform such functions as communicating with outside devices or other tasks. Transient commands that are stored in the CMDS subdirectory of the ROOT DIRECTORY are always available by simply typing their name along with any arguments that might be required by the given command. The PATH command can be used to change the default CMDS directory if desired. These files should always have the file type CMD so ECP8.SYSTEM will know that these are files that may depend on internal subroutines contained within the ECP8.SYSTEM program. These Transient Commands may use memory anywhere from $6000 to $BEFF. See Built-in Commands, ECP8 Commands. Volume - Refers to a logical disk storage unit. Usually a volume will be the same as a floppy disk. i.e. you may place any of several ProDOS volumes into a disk drive. Some disk devices such as hard disks may contain more than one volume online at any given time. Under ProDOS, volumes are referred to by name rather than physical location. Volume names may be up to 15 letters, numbers or periods long and must begin with a letter. Volume names are always preceded by a slash "/". An example volume name might be "/MY.DISK". (c) 1989 -10- Carolina System Software Extended Command Processor 8 [1.50] Installation instructions (ProDOS 8): The ECP8 system expects to have it's own directory or subdirectory to be designated as the root directory. Installation of the system is flexible in that you may forgo creating a CMDS or a HELP subdirectory if your needs require it. A full installation of ECP8 would involve creating a new subdirectory or setting the prefix to an existing subdirectory that you will use as your root directory. Most users find it most convenient to use the main directory of the boot volume as the root directory. This would be the disk in slot 7 drive 1 (or slot 6 drive 1 if you don't have a disk drive in slot 7). The next step is to copy ECP8.SYSTEM into place in the root directory along with the file PRODOS if it does not already exist there. If you will use ECP8 to start ProDOS BASIC programs then you must also create a CMDS subdirectory in the same directory with ECP8.SYSTEM and copy BASIC.SYSTEM into that CMDS subdirectory. It is recommended that you rename "BASIC.SYSTEM" to "BASIC" after copying it into the CMDS subdirectory. This will simplify the syntax for running Basic programs. (Note that the PATH command can be used to direct ECP8 to look to a directory other than CMDS for its external commands). Next you just copy any help files you need into a HELP subdirectory (if you want to have help available) and copy any ECP8 external commands, utilities, or other programs you may want to have in the CMDS subdirectory into the CMDS subdirectory. After creating a CP.KEYS and/or CP.STARTUP file into the root directory you can then execute the ECP8.SYSTEM file. Note that if you want ECP8.SYSTEM to be the boot-up interpreter (as most users will) then it must be the first file in the directory that ends with ".SYSTEM". There is an ECP8 Batch program called INSTALL on the ECP8 distribution disk that will automate the process of installing the ECP8 system into a directory. Just enter the command "INSTALL " where is the name of the desired root directory and INSTALL will do the installation for you. You may of course look at and change the INSTALL Batch program at will for special purposes. It is a nice example of the power of ECP8 Batch programs. The prefix should be set to the directory containing the INSTALL Batch program prior to executing the INSTALL Batch program. After installation, you should check the root directory to assure that the file "ECP8.SYSTEM" is the first ".SYSTEM" file in the catalog. This will allow ECP to take control of your system when you initially start up with ProDOS. After you have ECP installed on your boot disk you will want to use a text editor to create a CP.KEYS file. This is a special Batch file (described later) that can contain any ECP comamnd that you want executed every time you startup with ECP. This file would typically contain any special printer initialization your printer may need (See PINIT command) and function key definitions (See FKEY). You may also want to change the default path to the directory that will be your (c) 1989 -11- Carolina System Software Extended Command Processor 8 CMDS subdirectory (See PATH command). Some users use the CP.KEYS file to copy their ECP files onto a Ram disk or to install or run any special drivers they will need to support special devices such as ram disks or hard disks. The possibilities are endless so take your time and use your imagination. A file named CP.GAG is a Batch file that illustrates some of the flexibility of ECP Batch files. You should examine this Batch file and every other type BAT file in your ECP CMDS subdirectory for ideas on ways you can use Batch files to make your life easier. [1.55] Installation instructions (ProDOS 16 system disk): ECP8 versions 4.03 and above can now be used to launch ProDOS 16 applications in the same fasion that ProDOS 8 applications are launched. ProDOS 16 applications have the file type S16 for 16 bit system programs. In order for ECP8 to launch these programs, you will need to change the arrangement of files on the ECP8 disk to create a ProDOS 16 system disk. You will need a copy of the Apple IIgs system disk (which is included with the Apple IIgs) as well as a copy of ECP8 to create the ECP8 system disk. Below is the directory structure that must exist along with a description of the files involved. /ECP8 Volume name PRODOS The ProDOS 16 launcher program (required) ECP8.SYSTEM The ECP8 system program (required) CP.KEYS The ECP8 FKEY startup program (optional) CP.STARTUP The ECP8 startup program (optional) SYSTEM/ The SYSTEM subdirectory (required) P8 ProDOS 8 (required) P16 ProDOS 16 (required) SYSTEM.SETUP/ (required subdirectory) TOOLS.SETUP (required tool patch file) DESK.ACCS/ (optional subdirectory) TOOLS/ (required subdirectory) DRIVERS/ (optional subdirectory) FONTS/ (optional subdirectory) Note that there should be no file named "START" in the "SYSTEM" subdirectory and there should be no "xxxx.SYS16" files in the volume directory in order that ECP8 will be the startup program. If volume "/ECP8" should be offline when you attempt to start an S16 ProDOS 16 system program, ProDOS will ask for the ECP8 system disk back so it can pass control to ProDOS 16 and then to the program you have selected. (c) 1989 -12- Carolina System Software Extended Command Processor 8 [2.00] ECP8 Commands: ECP8 is a command based program. This means that in general, to get ECP8 to do something, you must type in a command at the keyboard that ECP8 recognizes. The section of this manual entitles ECP8 Command Documentation describes the specific usage of all of the currently supplied ECP8 commands. What follows is a general description of how ECP8 processes commands. When you are at the ":" prompt you may type in commands and press the RETURN key to have them executed. Commands may be entered in upper or lower or mixed case. You may enter more than one command on the same line as long as you separate each command with a ";". Some commands have arguments or additional information that must be entered after the command name. There must always be at least one space (blank) between the command name and the first argument and subsequent arguments must be separated by either a space or a comma ",". Any SYS, BIN, or Batch program command must also be the last command on a line as they overwrite ECP8.SYSTEM itself or the command line in memory making it impossible to continue with other commands on the same line. See section [1.40] for a description of ECP8 argument processing. [2.10] ECP8 Command types: The following are the currently defined command types you may enter from the keyboard, a function key (FKEY), or an Batch program : :COMMAND - built-in command name + arguments :COMMAND - transient command name + arguments :COMMAND - ProDOS SYSTEM program :COMMAND - ProDOS BINary program :COMMAND - CP Batch program :DIRNAME - sets prefix to DIRNAME :* - sets prefix to ROOT DIRECTORY :\ or :< - backs up the prefix one directory Note that in some cases and/or are optional. [2.20] Line Editing: You may use the DELETE or left arrow key as a destructive backspace. Pressing CONTROL-X cancels the current entry. If you type too many characters, additional keypresses will cause a buzz to be issued. You may at this point press RETURN to accept current input, use CONTROL-X to cancel the input line, or use DELETE or left arrow to erase some of your input. (c) 1989 -13- Carolina System Software Extended Command Processor 8 [3.00] ECP8 Batch programs: An ECP8 Batch program is a special text file given the BAT file type by the ECP8 CHTYPE command containing ECP8 commands that you might have typed in at the keyboard but want to be executed under file control rather than keyboard control. This feature is useful if you have frequently used or complex tasks that can be automated. You may also use ECP8 Batch programs to enhance or augment the built-in commands already provided with ECP8. You may execute a text file that contains valid ECP8 commands by simply typing the name of the text file at the ":" prompt. The maximum allowable line length is 127 characters. Note that Batch programs should be saved as BAT ($F5) files [Note that versions of ECP8 prior to 2.74 used $F8 or $B8 for BAT files. If you have $F8 or $B8 Batch programs, you will need to use the CHTYPE command to set the file type to BAT again]. If your editor will not edit BAT files, you should change the file type to TXT with CHTYPE, edit the file, and change the file type back to BAT with CHTYPE. This prevents ECP8 from accidentally trying to execute commands from a TXT that may not contain valid ECP8 commands. You may save Batch programs in the CMDS subdirectory of the ROOT DIRECTORY to make them available regardless of the current prefix. Your Batch program call must be the last statement on a given command line since the Batch program itself will overwrite the command line with command lines from the Batch program. [3.10] Positional Parameters with ECP8 Batch programs: Your executive commands may contain positional parameters that are passed from the command line much the same as arguments may be passed to built-in or transient commands. To do this you can include up to 3 special positional parameter variables (&1, &2, and &3) in the text of your Batch program. When the file is executed, the first argument from the keyboard will be substituted everywhere the &1 variable name is found; the second argument from the keyboard is substituted everywhere the &2 variable name is found and so on. An example executive command is included on the distribution disk and is named MOVE. The text of the MOVE command is as follows: :COPY &1 &2 :DELETE &1 When you enter ":MOVE FILE1 FILE2" at the keyboard, the following statements are executed: :COPY FILE1 FILE2 :DELETE FILE1 This is a very powerful feature that greatly extends the utility and flexibility of Batch programs. Note that ordinarily, commands inside an exec file are not displayed to the screen. (c) 1989 -14- Carolina System Software Extended Command Processor 8 [3.20] Conditional Execution within Batch programs: The IF, IFNOT, IFEQ, IFBYTE, and IFYES commands can be used to control the execution of ECP8 Batch programs. IF and IFNOT allow for conditional execution of ECP8 statements determined by the existence of a specified pathname on disk. IFEQ allows you to test a user supplied command line argument for equality with a string in your Batch program. IFYES allows you to write interactive Batch programs that branch based upon a user's answering a yes or no question that you display on the screen with the SAY command. These commands, IF, IFNOT, IFEQ, IFYES, IFBYTE, and SAY, are described in detail in the ECP8 Commands Documentation section of this document. [3.30] Special ECP8 Batch programs: (STARTUP files) When the system is started up, the ROOT DIRECTORY is searched for an executable file called CP.KEYS. This file is ordinarily a Batch program that contains FKEY definitions but may also include other ECP8 keyboard commands that you want executed every time ECP8 is started such as serial port definitions (via the MON command) or printer setup information (PINIT command). Note that the CP.KEYS file is optional. Next, the PREFIX DIRECTORY is searched for a file named CP.STARTUP. If it is found and the file has a valid executable file then the file are executed automatically. You may have more than one CP.STARTUP file on your disk (in different directories) so you can set prefixes, display files, or run various commands or programs automatically when you leave another ProDOS system program (and are automatically restarting ECP8 from that directory). [3.35] Special ECP8 Batch programs: (Function key files) Function key definition Batch programs are supported by ECP8. These are special Batch programs that are automatically executed when you press either the open or solid apple keys (to the left and right of the space bar on the Apple //e or //c) together with a letter key. For example, if you press "open apple - A" in command mode, then the Batch program named FKEY.A will be started. There are 26 of these files available for your use. This gives you up to 26 automatically executing Batch programs available at a simple keystroke. You can use the FKEY files to perform tasks that are too complicated to be handled by simple memory based FKEY's. (see FKEY in the command documentation section). (c) 1989 -15- Carolina System Software Extended Command Processor 8 [4.00] Using other programs with ECP8: Any ProDOS 8 SYSTEM program such as Ascii Express (tm), AppleWorks (tm), Access // (tm), or FILER (tm) can be started from ECP8.SYSTEM by simply entering the pathname for that program. Using the quit option from any ProDOS SYSTEM program will cause ECP8 to be automatically reloaded and executed. Note that the NEWQUIT command, described in the ECP8 Commands Documentation section of this document, can be used to change the name of the program that gets run by the ProDOS QUIT command. If you are using ECP8 as your ProDOS 16 system disk (see Installation instructions for ProDOS 16 section 1.55) then you can also start ProDOS 16 System programs (type S16) in the same fasion as ProDOS 8 System programs (type SYS). You can also run BINary programs by entering their pathnames. BIN programs should have their starting address stored in the aux type field of their directory entry. BIN programs should exit with either a ProDOS quit call or an RTS instruction for best results. Note that BIN programs that load below $6000 will be started by ECP8 via BASIC.SYSTEM (renamed as BASIC in the CMDS subdirectory). If the BIN program ends with an RTS (machine language RETURN statement) then control will pass to BASIC or ECP8 if it is still in memory. If it ends with a ProDOS QUIT call then control will go back to ECP8. Running a BIN program from an ECP8 Batch program will result in the Batch program being terminated. ProDOS BASIC programs can be started by entering the pathname of the program you want to run. ECP8 will automatically load BASIC and direct it to run the BASIC program whose name you entered. ProDOS BASIC EXEC programs can be started by entering BASIC which will load BASIC and direct it to execute the ProDOS BASIC EXEC program (which is not the same as an ECP8 Batch program. (c) 1989 -16- Carolina System Software Extended Command Processor 8 [5.00] ECP8 Command Descriptions: [5.01] ! BUILT-IN This is a command that tells CP.SYSTEM to ignore the remainder of a line of input. It is used primarily to allow you to add comments to Batch programs that can explain what various statements are for etc. Note that a space must immediately follow the "!". Example: :! Copy the file :copy file1 file2 [5.02] APPEND BUILT-IN This command will append the contents of to the end of . is unchanged. This command should ordinarily be used for TXT files but can be used with any type of file. [5.025] ASK BUILT-IN This command will display the specified, if any, to the current output device and wait for a keypress. The key entered will then have its ascii value stored (MSB on) at address $2063 where it can be tested with the IFBYTE command. This command is intended to be used within an ECP Batch program to allow a user to select from a list of options via a single keypress. i.e. ASK "Choose the number of your choice: " ifbyte $2063 $b1;say "You pressed '1'^M" ifbyte $2063 $b2;say "You pressed '2'^M" If the user presses the "1" key then the message is displayed confirming this fact. Note that $B1 is the ascii code for the numeral "1" with MSB on. [5.03] BASIC EXTERNAL The BASIC command will load the BASIC.SYSTEM (named BASIC in the CMDS subdirectory) program from the CMDS subdirectory and will direct BASIC.SYSTEM to run the program indicated by . If the file is of type BAS, it can be run automatically by simply typing its at the ":" prompt. The "BASIC " syntax is used primarily to make BASIC start a BIN, SYS, or TXT program but can be used to start a BAS program. Because of peculiarities in ProDOS BASIC, you cannot always depend on the PREFIX retaining its original value when your basic program starts. For best results, your ProDOS BASIC program should set the prefix as desired prior to executing filing statements. (c) 1989 -17- Carolina System Software Extended Command Processor 8 [5.04] BOOT BUILT-IN Starts up the disk in . Valid entries for are 5, 6, or 7. [5.05] CALL BUILT-IN This statement transfers control to the start of the Batch program whose pathname is specified as the argument. A RETURN statement in the CALLed Batch program will transfer control back to the line following the CALL statement in the CALLing Batch program. i.e. this is a subroutine call. Note that you cannot nest these calls.. only one "return address" is remembered. See the RETURN statement. [5.06] CAT BUILT-IN Display a list of files from the indicated directory to the current output device. If the pathname is not provided then a list of files in the current Prefix directory is displayed. Multiple pathnames are allowed [5.07] CHTYPE |<$xx> EXTERNAL Changes the type of to . is a valid ProDOS pathname and is either the 3 letter type identifier or a single byte hexadecimal type. For example, to change the BINary file STUFF to a TXT file you could use either of the following commands: :CHTYPE stuff txt :CHTYPE stuff $04 Note that CHTYPE can also be used the change the file type attribute of DIR files. This can be dangerous but has some interesting implications. Use with care (on a backup first!). [5.08] CMDNAMES EXTERNAL This is a utility program that can be used to rename any or all built-in commands in CP.SYSTEM. The program will display each command and prompt for a replacement command. If you want to accept the current command then just press RETURN. Note that the number of characters left over are displayed prior to each prompt. If at the end of your editing, the number of characters remaining is less than zero, the changes will not be processed and you will have to start over. As this command permanently alters a copy of CP.SYSTEM, you should only use this utility on a backup copy for safety. The PREFIX must be set to the directory where CP.SYSTEM sits prior to running this utility. NOTE: This command is a basic program stored on side 2 of the distribution disk. (c) 1989 -18- Carolina System Software Extended Command Processor 8 [5.09] COL40 BUILT-IN Changes the display mode to 40 columns and disables the 80 column firmware (if any). Note that certain commands will behave differently when 40 column mode is in effect so their displays will fit the 40 column screen. These are the ONLINE, DUMP, and CATALOG commands. If you are using a non-standard 80 column card that is not turned off by this command then use the COL40 command followed by pressing CONTROL-RESET. Make sure that you are not in the process of writing to disk (such as during output redirection) when you press CONTROL-RESET as you may damage your disk. This command cannot be used during output redirection. [5.10] COL80 BUILT-IN Turns on the 80 column display firmware in slot 3 if an 80 column card is present in that slot. If an 80 column card is identified at boot time or after the CONTROL-C (soft boot) command is issued the display mode will default to 80 column mode. This command cannot be used during output redirection. [5.11] COPY , BUILT-IN COPY Copies the file indicated by to the file indicated by . If already exists then you will be asked to confirm that you want to overwrite . Note that both files specified by and must be online at the time you use the COPY command. i.e. this command cannot be used to copy a file from one volume to one drive system unless you first copy the file to /RAM and then swap disks and copy the file from /RAM to your second volume. Other file copying should be done using FILER or the DCOPY command.. Note that if exists, it must be unlocked prior to using this command. If only is specified and it refers to a file in a directory other than the PREFIX directory, then the indicated file is copied from the indicated directory to the PREFIX directory. Note that the COPY command will NOT correctly copy a sparse (random access) text file. Use FILER to copy sparse files. (c) 1989 -19- Carolina System Software Extended Command Processor 8 [5.115] COPYDIR [-nocpr] Copies the files from into . Both directories must exist. The following flags may be used: -o: overwrite existing files without prompting. Default: off -c: prompt before copying files. Default: on -p: print filenames as they are copied. Default: off -r: recurse into subdirectories as well. Default: on -n: negate any flag (i.e. -nr means non-recursive copy.) At the Copy File prompt, you may supply the following responses: Y: yes, copy this file. N: no, don't copy this file. !: copy this file, and turn off prompting for all subsequent files. L: copy this file, and turn off prompting for the remainder of this directory. S: do not copy this file, and skip the remainder of the files in this directory. If prompting has been turned off, printing of the filenames will commence, and prompting may be re-enabled at any point by typing control-P. The Overwrite File prompt has similar resopnses: Y: yes, overwrite this file. N: no, don't overwrite this file. !: yes, overwrite this file, and all other subsequent files where overwriting is necessary. L: yes, overwrite this file, and all other subsequent files where overwriting is necessary on this directory only. S: no, don't overwrite this file, and skip copying any file which would replace an existing file for the remainder of this directory. A control-O will re-initiate overwrite prompting if it has been turned off, as control-P above. [5.12] CREATE BUILT-IN Creates a subdirectory file as directed by . If begins with a "/" then the pathname is considered to be fully qualified. Otherwise, the current prefix will be appended to the front of prior to creating the file. Example: To create a subdirectory ARCADE on volume GAMES you would use the following command: CREATE /GAMES/ARCADE (c) 1989 -20- Carolina System Software Extended Command Processor 8 [5.13] CONTROL - C BUILT-IN CTRLC When the CP.SYSTEM program is started, it sets the ProDOS prefix to the ROOT DIRECTORY and then searches to see if there is a CMDS and or a HELP subdirectory available. For the rest of the session, if a command is typed at the ":" prompt, it is first looked for in the built-in command table in memory. If it is not found there it is looked for in the prefix directory. If it is still not found then the ROOT DIRECTORY CMDS subdirectory is searched. If the command is found it is loaded and executed. Pressing the CONTROL and C keys together or entering the CTRLC command restarts this initialization process making the current PREFIX DIRECTORY the new ROOT DIRECTORY. You can use this command to log to another volume as the "Root volume", i.e. the one that is searched when looking for Commands or Help files. [5.14] CONTROL - P BUILT-IN CTRLP If you press the CONTROL and P keys simultaneously or enter the CTRLP command all future output will be directed both to the screen and to the device connected to slot 1 (usually the printer). This condition will continue until you press CONTROL-P again (or enter CTRLP) or until you press CONTROL-C to reinitialize the system. To list the ASCII contents of a file to the printer you should type the following: ^P (control-P to start printing) :TYPE ^P (control-P to stop printing) Note that while output redirection is in effect, lower case characters sent to the output hooks will NOT be translated to upper case regardless of the setting of the LCON/LCOFF flag. [5.16] DELETE BUILT-IN Deletes the file indicated by . A locked file or a non-empty subdirectory cannot be deleted with DELETE. To delete a locked file you must first UNLOCK the file. To delete a subdirectory file you must first DELETE all files defined within that subdirectory. Multiple pathnames are allowed. (c) 1989 -21- Carolina System Software Extended Command Processor 8 [5.17] DUMP BUILT-IN Outputs a hexadecimal listing of the indicated file to the current output device. The relative byte position within the file is listed in hexadecimal at the left margin separated from data by a ":". Example: :DUMP /VOL/FILE 00000:AA AA BB 00 34 55 23 0D 00008:FF EE 00 This command also works with directory and subdirectory files. Multiple pathnames are allowed. [5.19] ECHO BUILT-IN This command enables CRT display of ECP8 commands. When a Batch program is running, the echo status defaults of off. i.e., commands are not displayed as they are executed or scanned during a GOTO command. See also NOECHO. [5.20] FILER EXTERNAL (system) Runs the Apple (tm) FILER program. Use this program for formatting new volumes, copying volumes, copying sparse files, and doing wild-card copies/deletes. Further documentation is available within this program. [5.21] FKEY <#> BUILT-IN FKEY <#> FKEY The FKEY command is used to create, cancel, or display function key definitions. <#> can be any number from 0 to 9 and represents the key that when pressed simultaneously with either the open apple or closed apple keys will cause to be entered instantly at the command level. If you are not using an Apple //e or //c then you must press the ESC key followed by a number key from 0 to 9. This allows you to create single key substitutions for keyboard commands. Note that may consist of one or more CP commands separated by ";". If your contains any blanks or commas, you must enclose the in quotes. If is omitted, then the definition for the indicated key is deleted. You may redefine any function key by using another FKEY command. (c) 1989 -22- Carolina System Software Extended Command Processor 8 FKEY - continued: If FKEY is entered without a key number or then a list of all of the current FKEY definitions will be displayed to the current output device. When the CP system is started up or Control-C is pressed, the ROOT DIRECTORY is searched for a special Batch program named CP.KEYS. The CP.KEYS file may contain FKEY statements or other statements that will automatically define any or all function keys at the time of startup. The CP.KEYS executive is run before any CP.STARTUP file that may be found in the PREFIX directory. Example CP.KEYS file: :FKEY 1 cat catalog disk :FKEY 2 "/hard1/aepro;ae.system" set prefix and run aepro :FKEY 3 "/hard1/appleworks;aw.system" :FKEY 4 "/hard1/basic;basic edit.pro" set prefix, start edit.pro Another way to define function keys involves the use of special fkey files. These files should be named "FKEY.A", "FKEY.B", "FKEY.C", etc and are executed whenever open apple A, B, or C are pressed respectively. The FKEY files can be any executable files which presently include BAT, BIN, BAS, SYS, and CMD files. These FKEY files would ordinarily be kept in the CMDS subdirectory for global availability. Note that the disk based FKEYs are not displayed by the FKEY command. With FKEY's 1-0 and A-Z (file based) there are a total of 36 user-defined function keys available under ECP8. [5.22] GOTO