8L xC)pJJJJ IH(ȱH:=IH[H`@H^H 2 9 @   I/H`JLNGȄBȄF aK ' faaFF  RJm# KKJ qJ )J ۈJJm  JFȱJGJKaȄM ' 5aaNNJFLGJ Extended Command Processor 8 User Guide Version 5 19 Janurary 1989 By Donald R. Elton CarolinECP8DOCS' )ECP8.DOCS+33)ECP8.TECHO›3.3/PAGE2N*`Q& PRINTb `aa8aa XL LG &PRODOS`DaElH$?EGvѶK+`L XX LU ŠϠĠӥS)*+,+`F)) (*=GJFjJJA QE'+ '== `@ STSP8QSS8 m P o R(8Ra System Software [0.10] Table of Contents: Topic: Section: Table of contents.................................. 0.10 Program bugs....................................... 0.20 Notices..........  !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 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 F, 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 AMACSt 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, SIZEO 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 (excepCLUSION 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,-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 EX 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-803ergoing 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....... 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 undprograms...... 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)........................ 2.00 ECP8 command types................................. 2.10 Line editing....................................... 2.20 ECP8 Batch programs................................. 3.00 Positional parameters with ECP8 Batch ith ECP8................... 1.20 Other ProDOS file types............................ 1.30 Definitions........................................ 1.40 Installation instructions.......................... 1.50 ECP8 commands.................................................... 0.30 ECP8 Extensions.................................... 0.40 Introduction....................................... 1.00 Functional diagram................................. 1.10 ProDOS file types used w 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 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 tiven 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 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 gning the basic program directly. (c) 1989 -5- Carolina System Software Extended Command Processor 8 [1.20] ProDOS File types used with ECP8: When you \ 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 runPrograms | SYS Programs <---> ECP8 <---> BIN Programs /\ / \ / \ /essor 8 [1.10] Functional Diagram: Hardware | Device Drivers | ProDOS <---> S16 ograms 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 Procto 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 prommands 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 n 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 cThis 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 ois 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. 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 his 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 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 ew Desk Accessory TOL - Tool file STR - Startup file (c) 1989 -6- Carolina System Software Extended Command Processor 8 [1.40] Definitions: ARGUMENTS - ECP8 is 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 - Nger 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 - 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 - Intetypes: 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 ectory. 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 - 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 subdir 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 ical 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 Softwarethat 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 technoks, 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 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 bo 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 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 separatbetween 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 previousyour 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 ands. 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 eys 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 Commthat 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 kthe 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 f 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 ng "BASIC " from the ECP8 command prompt. (c) 1989 -7- Carolina System Software Extended Command Processor 8 Boot - This is the process o 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 specifyiEY, 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 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 FKtes, 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 rgument 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 quoed 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 aly 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 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 yo 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 DOS 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 acement 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 Proating 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 replrefix. 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 Operve 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 p "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 ha 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 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 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 e 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 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 fil 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 ur 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 EM 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.SYSTt 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.SYSTsystem 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 rootem 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 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 Sys 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 t-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. SomeTEM 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 Buil 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.SYS 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 e 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 suchange 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 arP8.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 ch 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 ECEM 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 SYSTEM/ The SYSTEM subdirectory (required) P8 ProDOS 8 (required) P16 ProDOS 16 (required) SYSTEM.SETUP/ (required subdirectory) TOOLS.SETUP (required tool patch file) 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) 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 nameched. 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 ays 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 launess 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 w 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 endlfunction 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 e. 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 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 fil 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.nd "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 examplethen 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 comma 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) 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 systle 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 wi 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 fixt 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 oreft 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 tee. 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 lts 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 backspac:COMMAND - ProDOS SYSTEM program :COMMAND - ProDOS BINary program :COMMAND - CP Batch program :DIRNAME - sets prefix to DIRNAME :* - se 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 verwrite 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 themust 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 ontered 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 ic 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 eCommands: 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 specifem 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 ll 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 t 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 exes: (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 thedifferent 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 programKEYS 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 rogram 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.e 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 pIFYES 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 thBatch 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. 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 1 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- 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 FILE. 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 ional 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 programhe 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 positcuting 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 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 automatic^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 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'] 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 2 [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.025ainder 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 fileolina 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 remd. 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- Car 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 enterery). 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 Batchfield 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 subdirecto 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 mmands 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(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 Coally 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 So 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 Co 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 identifiedlumn 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 damagethe 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 con 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 ters 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 distributio 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 al 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 thatCHTYPE 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 path> 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 :he 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 . BUILT-IN Display a list of files from the indicated directory to ts 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. ftware 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 Thipies 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 usinogether 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 Cable 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 tarted, 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 tES/ARCADE (c) 1989 -20- Carolina System Software Extended Command Processor 8 [5.13] CONTROL - C BUILT-IN CTRLC When the CP.SYSTEM program is stathname 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 /GAMdirectory. 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 pry. 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 -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 necessale, 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 reny 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 fiting 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 aftware 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 existhe 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 Sog 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 ommands 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: ARTUP 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.systeIRECTORY 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.STsor 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 Dted, 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 Process 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 omitmultaneously 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 allow[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 si 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. 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 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 mmand 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 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 Coting 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. ^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 setm" :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 dirog2 :if /ram/prog2;say "Program 2 is now on /RAM^M" (c) 1989 -24- Carolina System Software Extended Command Processor 8 [5.245] IFBYTE ; BUILT-IN to write Batch programs that can have logical branches to other Batch programs. Note that if multiple pathnames are entered, the IF test will fail unless ALL pathnames exist. Example: (Batch program) :if /RAM;copy prog1 /ram/prog1;copy prog2 /ram/pe, execution will continue with the next statement. Note that this command is intended primarily to allow you to write Batch programs that can verify the existence of certain files before causing an error in future statements. This also makes it possible d is a conditional execution statement similar to the IF...THEN construct in many computer languages. If the pathnames that immediately follow the IF token exist then the statements that follow the IF statement on the same line will be executed. Otherwisd normally contain a list of available help files) from the HELP subdirectory. If no HELP subdirectory is found when the system is initialized then the HELP command will have no effect. [5.24] IF ; BUILT-IN This comman BUILT-IN ? HELP ? Lists instructions for use of the CP.SYSTEM program for the indicated command. HELP HELP will list this file. HELP with no arguments will display a file called CMDLIST (which shoul the names of the files containing pattern. -n Precede each printed line with its line number. -h Suppress display of filename headers. -y Ignore alphabetic case when matching. [5.23] HELP -r Recursive subdirectory search. -a Search ALL lines, not just until match found. -v Display all lines NOT containing pattern. -c Print only total number of matching lines. -l Display onlysearched. If no filename argument is given, the current prefix directory is assumed. Grep normally only prints the first occurence of the string if it is found, the -a argument allows you to continue the search throughout the entire file. The flags are: each TXT or BAT file in the specified directory for an occurence of string. If -r is used, subdirectories will also be searched; you can scan every TXT type file on the entire device if you wish! If a simple filename is specifed, then only that file is of the Batch program to find a label match. (c) 1989 -23- Carolina System Software Extended Command Processor 8 [5.225] GREP [-ravclnh] string [directory | file] Grep searchesorld ^M" :goto start would result in an endless loop displaying "Hello World" continuously until the user presses the ESCape key to terminate the Batch program. Note that branches may be forward or backward and that lines are searched from the startch program to cause an unconditional transfer of control to the statement following the