Extended Command Processor 8 Technical Reference Manual Version 5 19 Janurary 1989 By Donald R. Elton Carolina System Software [0.10] Table of Contents: Topic: Section: Table of contents.................................. 0.10 Introduction....................................... 1.00 Source code examples disk.......................... 1.10 ECP8 Global page................................... 1.20 Parsing scheme..................................... 2.00 ECP8 Machine Language Interface.................... 3.00 IO calls summary................................... 3.10 Filing calls summary............................... 3.20 Batch program calls summary........................ 3.40 Miscellaneous calls summary........................ 3.50 ECP8 MLI specific documentation.................... 4.00 IO calls group..................................... 4.00 Filing calls group................................. 4.10 Batch program calls group.......................... 4.30 Miscellaneous calls group.......................... 4.40 ECP8 memory usage.................................. 5.00 ProDOS 8 global page bitmap........................ 5.10 External GETCMD protocol description............... 7.00 (c) 1989 -1- Carolina System Software Extended Command Processor 8 [1.00] Introduction: This is the Technical Reference Guide for the Extended Command Processor 8. This manual contains the information needed by assembly language or c programmers that would like to add transient commands or applications to the ECP8 environment. Like ProDOS 8 and BASIC.SYSTEM, all communication between a user's program and ECP8 is done through a ECP8 GLOBAL Page. Every time ECP8 is reassembled, all internal entry points will change. The only way to assure that your program will stay compatible with future releases of ECP8 is to handle all communication with ECP8 through the pointers contained in the ECP8 GLOBAL Page. There are three approved entry points into CP.SYSTEM. They are as follows: JMP $2008 CP machine language interface entry (CPMLI) JMP ($200C) Calls the character input routine JMP ($200F) Calls the character output routine The above addresses will not change in future ECP8 releases. The first part of this manual will document the ECP8 GLOBAL Page, the second part will document the CPMLI, while the last part will document the memory use of the ECP8 system. NOTE: An Equates file of system globals is included on the distribution disk as Globals.Src. (c) 1989 -2- Carolina System Software Extended Command Processor 8 [1.20] ECP8 Global Page: The data stored in the global page can be modified (where appropriate) by using an external transient command or by using the MON command. The ECP8 GLOBAL Page starts at address $2000 (8192 decimal), the assembler listing follows: ORCA/M ASM6502 4.1 10 Jan 89 03:40 0000 ********* 0000 * 0000 * GLOBAL PAGE, ECP8 V 5 0000 * 0000 ********* 0000 * 0000 MAIN START 0000 REG1 GEQU $68 ;ZP VARIABLES REG2 GEQU $6A REG3 GEQU $6C REG4 GEQU $6E 2000 4C0080 JMP COLD 2003 0000 DC A'$0414' ;VERSION 2005 2005 000000 DC H'00' ;RESERVED 2006 0000 DC H'00 00' ;RESERVED 2008 2008 EXTERNAL ENTRY 2008 4C5900 JMP EXTCONT ;CPMLI entry 200B 200B 00 DS 1 200C 0080 DC A'GETKEY' ;PTR TO INPUT External programs, coresident with ECP8 should use an indirect jump to this address to wait for a keypress from the user. The Control-C, Control-P, and Control-S functions, the type-ahead buffer, remote mode, and other features are only supported when this entry point is used. 200E 00 DS 1 200F 0080 DC A'COUT' ;PTR TO OUTPUT External programs, coresident with ECP8 should use an indirect jump to this address ($200F) to output a character to the current output device. Output redirection and remote mode are only supported when this entry point is used. (c) 1989 -3- Carolina System Software Extended Command Processor 8 2011 FF DC H'FF' ;STARTUP STATUS This address is used internally by ECP8 to determine whether a full cold start is finished or in progress or needs to be done. At startup, the value should be $FF. At different stages in the startup process, this byte is incremented. User programs should not modify this byte as its operation may change in future releases. If you need to cold start the system from a user program then use the COLDSU call in the CPMLI as it will always work. 2012 0080 DC A'CMDTABLE' This is a pointer to the start of the command table. The command table is a serial list of command names following length bytes. The end of the table is marked by $FF $FF bytes. The maximum length of this table is not fixed and can only be determined by looking for the $FF $FF bytes. Note that some commands (such as "?" and "HELP" call the same routine) but there must be a table entry for each command name defined in the table currently. This pointer is included for those who wish to write a program to rename commands to emulate other operating systems. See also the PROMPT byte (address $203A). 2014 0080 DC A'TYPES' This is a pointer to the start of the ProDOS file type table. The current table has the following format: TYPES DC H'FF',C'SYS',H'01',C'BAD',H'02',C'PCD',H'03',C'PTX' DC H'04',C'TXT',H'05',C'PDA',H'06',C'BIN',H'07',C'FNT' DC H'08',C'FOT',H'09',C'BA3',H'0A',C'DA3',H'0B',C'WPF' DC H'0C',C'SOS',H'0F',C'DIR',H'10',C'RPD',H'11',C'RPI' DC H'1A',C'AWP',H'1B',C'ASP',H'EF',C'PAS',H'F0',C'CMD' DC H'FB',C'IVR',H'FC',C'BAS',H'FD',C'VAR',H'FE',C'REL' DC H'A1',C'MAC',H'B1',C'OBJ',H'19',C'ADB',H'FA',C'INT' DC H'B0',C'SRC',H'F5',C'BAT',H'B1',C'ORC',H'E0',C'LBR' DC H'F8',C'PRM',H'A2',C'HLP',H'A3',C'DAT',H'A5',C'LEX' DC H'B4',C'RTL',H'B5',C'EXE',H'B6',C'STR',H'B3',C'S16' DC h'B9',C'CDA',H'FF',C'SYS',H'FF',C'SYS',H'FF',C'SYS' (c) 1989 -4- Carolina System Software Extended Command Processor 8 2016 0080 DC A'PDPREFIX' This is a pointer to the current ProDOS prefix stored in standard ProDOS fashion. 2018 00 DC H'00' ;Batch ACTIVE? This is a boolean variable. Zero means that no ECP8 Batch program is active while non-zero means that an ECP8 Batch program is active. You should not directly modify this byte. If you wish to stop an ECP8 Batch program then use the STOPEXEC CPMLI call. 2019 00 DC H'00' ;NOCTRLC 201A 00 DC H'00' ;LCFLAG NOCTRLC is a boolean variable. When set to a non-zero value, a Control-C typed at the keyboard will have no effect. LCFLAG is a boolean variable. Zero means that lower case restrict mode is off, non-zero means that all lower case output is translated to upper case. The LCON and LCOFF commands modify this byte. At startup, if ECP8 determines that it is running on an Apple IIgs, ///, //e, or //c this byte is set to zero. 201B 00 DC H'00' ;SKM PRESENT? This is a boolean variable. Zero means that the shift key hardware modification is either not present or is to be ignored. 201C 0080 DC A'INITSTR' ;PINIT PTR This is a pointer to the printer initialization string. It is modified by the PINIT command. The string is in normal ProDOS form, followed by a length byte. The maximum length of the init string is 16 bytes. 201E 00 DC H'FF' ;ECHO RESTRICT? This is a boolean variable. A non-zero value will turn off the display of Batch program commands. This byte is controlled by the ECHO and NOECHO commands. 201F 01 DC H'01' ;PRINTER SLOT This byte holds the current printer slot. A value of 8 signifies that the default printer location is a file whose pathname is stored at the location pointed to by CPATH ($2053). This byte is modified by the OUTPUT command. (c) 1989 -5- Carolina System Software Extended Command Processor 8 2020 00 DC H'00' ;CTRL AVAILABLE? 2021 00 DC H'00' ;LAST CTRL CHAR These bytes are used by GETKEY to keep up with special control keys such as CONTROL-S, CONTROL-C, CONTROL-P, and ESC. These keys are not transferred into the type-ahead buffer. If a control key is available to be read, it is stored at address $2021 and address $2020 is set to a non-zero value. See GETCTRL ECP8MLI call. 2022 00 DC H'00' ;CLICK DURATION This byte holds a count byte that determines the sound of the keyboard click feature. If set to zero, the keyboard click feature is disabled. This byte should be set to an even number. 2023 0000 DS 23 203A BA DC C':' ;PROMPT This is the default keyboard input prompt. 203B 0080 DC A'INLINE' ;INPUT BUFFER 203D 0080 DC A'ARGS' ;ARGUMENT BUFFER 203F 0080 DC A'PATH1' ;1ST PATHNAME 2041 0080 DC A'PATH2' ;2ND PATHNAME The above are pointers to various buffers used by ECP8. They are referred to in the CPMLI documentation. 2043 0080 DC A'SCRSIZE' This is a pointer to the byte that holds the current screen width. (40 or 80 columns). (c) 1989 -6- Carolina System Software Extended Command Processor 8 2045 0080 DC A'ROOTPFX' 2047 0080 DC A'CMDPATH' 2049 0080 DC A'HELPPATH' The ROOTPFX is a pointer to the prefix where ECP8 looks to find the CMDS and HELP subdirectories. The CMDPATH and HELPPATH are pointers to the pathnames of the CMDS and HELP subdirectories. 204B 0080 DC A'ARG1' 204D 0080 DC A'ARG2' 204F 0080 DC A'ARG3' The above are pointers to the buffers that hold positional arguments for ECP8 Batch programs. 2051 0080 DC A'EPATH' 2053 0080 DC A'CPATH' 2055 0080 DC A'CREF' 2057 0080 DC A'EREF' 2059 0080 DC A'KBUFFER' 205B DE DC H'5E' ;CTOKEN '^' 205C 00 DC A'00' ;Value word for HEXBIN call 205E 00 DC H'00' ;IORESULT The above are pointers to the active Batch file pathname (EPATH), the output redirection file pathname (CPATH), the file reference numbers associated with the above (EREF and CREF) as well as the type-ahead and modem input buffers (KBUFFER). CTOKEN is the byte used to designate control characters for the SAY and PINIT commands. The Value word is used by the HEXBIN ECP8MLI call to store a result. See HEXBIN below. The IORESULT byte is set to the most recent ProDOS MLI error code by the PDERR routine. Note that there is no prior initialization of this value by ECP8. If you want to use this byte to determine the identity of the last ProDOS error code passed to PDERR then you need to set the byte to zero prior to any call to PDERR. 205F 0000 DC A'0000' ;FAKE IRQ VECTOR If non-zero, the above address is called frequently by ECP8 to simulate an interrupt driven process. Specifically, the routine will be called after every keyboard scan. Keyboard scans take place during each call to CHKKEY which is after almost every ProDOS MLI call in ECP8 and during every character output or character input operation. (c) 1989 -7- Carolina System Software Extended Command Processor 8 2061 FA DS 2 2063 00 DC H'00' ;ASKBYTE 2064 FF 5E DC A'$5EFF' ;MEMORY SIZE 2066 00 DC H'00' ;DEBUG FLAG ASKBYTE is the byte where the key pressed in response to the ASK command is stored with MSB set to 1. The memory size word is used to tell ECP8 commands how much memory above $6000 is available for their use as general purpose memory. The default is for all of the memory from $6000 to $BEFF to be available. If you should need memory for a custom driver or FAKEIRQ vector handler then you should decrease the value of the MEMORY SIZE word and place your routine in the highest part of memory. ECP8 will not overwrite this memory except when exiting to an alien BIN program, SYS or BAS program. The DEBUG FLAG, if set to a non-zero value, will cause an ECP8 Fatal error (BRK instruction) to branch into the Apple system monitor. 2067 60 DC H'60' ;EXTGETCMD vector (RTS) 2068 00 00 DC A'0000' ;EXTGETCMD address 206A 00 DC H'00' ;MAXLEN for GETCMD 206B 00 DC H'00' ;INPMODE for GETCMD 206C 00 00 DC A'0000' ;INPBUFFER pointer These bytes are used to allow a programmer to install an alternate user-supplied keyboard input and editing routine. Details of how this protocol is designed are included near the end of this document. (c) 1989 -8- Carolina System Software Extended Command Processor 8 [2.00] Parsing Scheme: The following is the way ECP8 processes commands: GETCMD Get line of input from user and store at INLINE, with MSB ON, followed by a carriage return ($8D). | PARSE Find command number from table and remove command from INLINE. | DOCMD Given command number, call a command handler. After command handler returns, wipe any remaining unprocessed arguments from INLINE using ZAPLIN. | COMMAND HANDLER Get arguments if needed and process function. Call GETARGS until ARGS = 0 (no more args). | GETARGS Move first argument from INLINE and store at ARGS with preceding count byte, MSB OFF. If there are no more arguments then ARGS set to zero. Argument removed from INLINE buffer after each call. [3.00] ECP8 Machine Language interface (ECP8MLI) The CPMLI provides a method of calling almost all of the internal subroutines contained within CP.SYSTEM. Every time CP.SYSTEM is reassembled, all internal entry points change. The CPMLI calls will NOT change and are the only approved mechanism for calling internal ECP8 subroutines. The CPMLI entry point is $2008. You select a call number by loading the X register via LDX with the call number of the desired subroutine. Other parameters that may be needed are documented in the section describing each call. Not all of the externally available subroutines will be useful but some are essential to writing transient commands that will interface with ECP8. You should refer to the documentation of the ECP8 GLOBAL Page as well because some calls depend on your setting up parameters pointed to by GLOBAL Page pointers and the 4 zero page registers. (c) 1989 -9- Carolina System Software Extended Command Processor 8 [3.10] I/O Calls summary: BUZZ 2 COUT 8 COUT1 9 DSPCURS 12 DSPTIME 13 GETCMD 17 GETKEY 18 HOME 20 INPUT 27 ASK 28 PUTPATH 29 SHOWTYP 31 TITLE 33 READLN 38 FKEY 44 COL40 45 COL80 46 PRTTOG 53 HOME2 57 PINIT 58 WRITEFL 60 PRINTON 61 FILEON 62 UPCASE 63 CHKKEY 67 CHKBUF 68 GETCTRL 69 EIGHTOFF 82 [3.20] Filing Calls summary: CALLTIME 3 CATALOG 4 CLOSE 5 FINDPFX 15 EXTCOPY 21 ONLINE 23 EXTAPPEND 25 PREFIX 26 TIME 32 DELETE 35 RENAME 36 COPY 37 LOCK 39 UNLOCK 40 TYPE 41 DUMP 42 PDERR 43 BACKPFX 49 PREFIX2 50 INITPARM 80 XDUMP 86 PATH 87 [3.40] Batch program Calls summary: STORE 47 EXECFL 51 EXECLN 52 STOPEXEC 55 IF 83 IFNOT 84 IFYES 85 GOTO 89 CALL 90 RETURN 91 IFEQ 92 DOLINES 95 IFBYTE 102 [3.50] Misc. Calls summary: BOOT 1 FAKEIRQ 6 COPYPATH 7 DEBLANK 11 EXIT 14 GETARGS 16 GOMON 19 MOVELN 22 PARSE 24 DOQUIT 30 GETARGS1 34 DOCMD 54 COLD 56 ZAPLIN 59 NOARGS 64 MONCMD 66 COLDSU 79 EXIT2 88 ARGINTERP 98 ROOTARG 99 ARGPATH1 100 ARGPATH2 101 HEXBIN 103 EXISTS 104 (c) 1989 -10- Carolina System Software Extended Command Processor 8 [4.00] Specific CP MLI Calls: I/O group BUZZ 2 Issues the ProDOS BUZZ. COUT 8 Call character output routine. Redundant call, use the indirect address in the global page. COUT1 9 Call character output routine. Redundant call, use the indirect address in the global page. DSPCURS 12 Call output routine but display cursor to CRT. (Note that cursor doesn't go to alternate devices but the character in the accumulator does). DSPTIME 13 Display the ProDOS format time and date. TIME should be stored in REG1, DATE should be stored in REG2 prior to calling this routine. GETCMD 17 Gets a line of input from the user and stores it at INLINE, MSB ON, followed by a carriage return. Transient commands should avoid using this call and should get their arguments from the command line using GETARGS. See also INPUT ECPMLI call. GETKEY 18 Waits for a keypress and returns it in the accumulator. This is a redundant call, use the indirect address in the Global Page. HOME 20 Clear the screen. (c) 1989 -11- Carolina System Software Extended Command Processor 8 INPUT 27 Reads a line of input from the keyboard into the buffer pointed to by REG5 with a maximum length as specified by the accumulator. ASK 28 Displays the contents of the buffer ARGS to the current output device and then reads a single key from the keyboard storing its ascii value to $2063 with MSB set. PUTPATH 29 Prints the ProDOS format string pointed to by REG4 to the current output device. SHOWTYP 31 Displays the 3 letter file type identifier for the file type code stored in the accumulator to the current output device. This command uses the TYPES table pointed to by the ECP8 Global Page. TITLE 33 Clears the screen and displays the title page for ECP8. READLN 38 Reads a line of input from the keyboard into the Batch program variable specified by the string at ARGS (Contains "1", "2", or "3". The string is stored to ARG1, ARG2, or ARG3 respectively. The maximum length of the string stored is $3F plus a count byte. FKEY 44 Processes the FKEY command. The argument for the command should be stored at INLINE. Note that FKEY does not call GETARGS to get its arguments. If you want FKEY processed with no arguments then you must store an $8D at INLINE. COL40 45 Places ECP8 in 40 column mode and calls TITLE. (c) 1989 -12- Carolina System Software Extended Command Processor 8 COL80 46 Places ECP8 in 80 column mode (if there is an 80 column card in slot 3) and calls TITLE. PRTTOG 53 Processes the CONTROL-P command and toggles the default output between the CRT and the default specified by the OUTPUT command (either a slot or a file). HOME2 57 Calls HOME and writes a CONTROL-L to the current output device. PINIT 58 Processes the PINIT command. The argument should be stored at INLINE followed by a carriage return. WRITEFL 60 Sends the character in the accumulator to the current output redirection file provided that the file has been defined by OUTPUT and opened with FILEON. This command should not ordinarily be used by external programs. PRINTON 61 Activates output to a slot, usually to the printer. FILEON 62 Opens the output redirection file defined by OUTPUT and sets the output hooks to point to WRITEFL. UPCASE 63 Translates the lower case character in the accumulator to upper case. (c) 1989 -13- Carolina System Software Extended Command Processor 8 CHKKEY 67 This is a pseudo interrupt routine used to scan the keyboard and fill the type-ahead buffer. It should be called frequently in any transient command program that wants to support type-ahead. It is automatically called after every character output call. CHKBUF 68 This checks to see if there is any data in the type-ahead buffer. BEQ to a no character routine or BNE to a character present routine. GETCTRL 69 This call returns the last pressed control character in the accumulator or zero if there is no control character pending. Note that there is only a one character control-character buffer and that a call to getctrl will remove the character from the buffer such that subsequent calls will return zero unless another control character is pressed. Currently, the only control characters supported by this call are ESC, CTRL-C, CTRL-S, and CTRL-P. Note that CTRL-C and CTRL-P are acted on immediately and can not normally be read by this call. You may also manipulate the $2020 and $2021 addresses (see global area description) directly rather than using this call if desired. EIGHTOFF 82 This call turns off the 80 column display device and sets the screen width to 40. [4.10] Specific CPMLI calls: Filing group CALLTIME 3 ProDOS updates the ProDOS system time and date. CATALOG 4 The CAT command is processed. The argument(s) should be placed in INLINE followed by a carriage return. (c) 1989 -14- Carolina System Software Extended Command Processor 8 CLOSE 5 All files at or above the current file LEVEL (see ProDOS Tech manual) are closed. FINDPFX 15 PDPREFIX is set to the current ProDOS prefix. If no prefix has been set then the last device accessed is looked at and the prefix is set to the volume name. EXTCOPY 21 The file whose pathname is stored at PATH1 is copied to the file designated by PATH2. ONLINE 23 The ONLINE command is executed. No arguments. EXTAPPEND 25 The file whose pathname is stored at PATH1 is appended to the file designated by PATH2. TIME 32 The TIME command is executed. No arguments. DELETE 35 The DELETE command is executed. Argument(s) are stored at INLINE followed by a carriage return. RENAME 36 The RENAME command is executed. The arguments are stored at INLINE followed by a carriage return. COPY 37 The COPY command is executed. The arguments are stored at INLINE followed by a carriage return. (c) 1989 -15- Carolina System Software Extended Command Processor 8 LOCK 39 The LOCK command is executed. The argument(s) are stored at INLINE followed by a carriage return. UNLOCK 40 The UNLOCK command is executed. The argument(s) are stored at INLINE followed by a carriage return. TYPE 41 The TYPE command is executed. The argument(s) are stored at INLINE followed by a carriage return. DUMP 42 The DUMP command is executed. The argument(s) are stored at INLINE followed by a carriage return. PDERR 43 The error message associated with the ProDOS error code in the accumulator is displayed. Any active Batch Program is terminated before displaying the message. BACKPFX 49 The current ProDOS prefix is backed up one directory level from the current prefix. Same effect as "\" command. PREFIX2 50 The prefix is set to the directory stored at ARGS following a count byte. (c) 1989 -16- Carolina System Software Extended Command Processor 8 INITPARM 80 The ProDOS MLI parameter tables are initialized. The following table lists the addresses of the parameter tables: PDQUIT EQU $1D11 PDRDBLK EQU $1D18 PDPREFIX EQU $1D20 PDWRBLK EQU $1D61 PDCREAT EQU $1D67 PDDSTRY EQU $1D73 PDRENM EQU $1D76 PDSETINF EQU $1D7B PDGETINF EQU $1D89 PDONLINE EQU $1D9B PDGETPFX EQU $1D9F PDSETPFX EQU $1DA2 PDOPEN EQU $1DA5 PDNEWLN EQU $1DAB PDREAD EQU $1DAF PDWRITE EQU $1DB7 PDCLOSE EQU $1DBF PDSETMRK EQU $1DC1 PDGETMRK EQU $1DC6 PDSETEOF EQU $1DCB PDGETEOF EQU $1DD0 PDSETBUF EQU $1DD5 PDGETBUF EQU $1DD9 IRQON EQU $1DDD IRQOFF EQU $1DE1 XDUMP 86 Similar to DUMP except this command displays the ascii and hexadecimal contents of a file together on the current output device. PATH 87 Sets the default path for external commands. The argument should be saved at ARGS. [4.30] Specific CPMLI Calls: Batch program group STORE 47 Stores the string stored at ARGS into the Batch variable specified by the next argument. (Either ARG1, ARG2, or ARG3). EXECFL 51 Starts the Batch program whose pathname is stored at ARGS after a count byte. (c) 1989 -17- Carolina System Software Extended Command Processor 8 EXECLN 52 Called by GETCMD when a Batch is active, to read in a line of input and expand any positional parameters for the Batch. User programs should not use this call. STOPEXEC 55 Stops any Batch program in progress. IF 83 Processes the IF command. IFNOT 84 Processes the IFNOT command. IFYES 85 Processes the IFYES command. GOTO 89 Transfers control to the Batch file line following the label stored at ARGS. CALL 90 Calls the Batch program whose pathname is stored at ARGS as a subroutine. RETURN 91 Returns to the Batch program that CALLed the current Batch program. No arguments. IFEQ 92 Tests the argument at ARGS for equality with the next argument stored at INLINE and continues execution with the statements at INLINE if the two arguments are equal. (Difficult to use as an ECP8 MLI call) - designed for use within a Batch program. (c) 1989 -18- Carolina System Software Extended Command Processor 8 DOLINES 93 Processes lines of input. To start and run a Batch program from an external program, you should call EXECFL followed by a call to DOLINES. DOLINES will return once the Batch program terminates. Note that this routine was not designed for external user use. Use it at your own risk. IFBYTE 102 Processes the IFBYTE command. [4.40] Specific CPMLI Calls: Misc group BOOT 1 Processes the BOOT command. Argument(s) stored in INLINE followed by a carriage return. FAKEIRQ 6 Calls the FAKEIRQ address routine referred to in the ECP8 Global area. COPYPATH 7 Copies the ProDOS format string pointed to by REG1 to the location pointed to by REG2 DEBLANK 11 Removes leading blanks from buffer pointed to by REG5. EXIT 14 Processes any command at INLINE that is not a built-in command. (c) 1989 -19- Carolina System Software Extended Command Processor 8 GETARGS 16 This call moves the first argument from INLINE to ARGS after a length byte. It then copies the remaining line from INLINE down such that the next argument starts at INLINE (with no preceding spaces). Note that the contents of INLINE are usually stored MSB on while the contents of ARGS are always stored MSB OFF. This way, you can use the contents of ARGS as a valid ProDOS pathname. Examples: Before GETARGS call: INLINE = COPY FILE1 FILE2 ARGS = <$0> After the first call to GETARGS: INLINE = FILE1 FILE2 ARGS = COPY After the second call to GETARGS: INLINE = FILE2 ARGS = FILE1 After the third call to GETARGS: INLINE = ARGS = FILE2 After the fourth call to GETARGS: INLINE = ARGS = <$0> Internal and external routines can thus recall the contents of the input buffer, one argument at a time. GETARGS is called once by the ECP8 system prior to jumping to the command handler thus at entry, the command handler can check the length byte at ARGS to determine if any arguments were entered. Note that arguments can be separated by spaces or commas. Note that starting with CP.SYSTEM version 2.71, the accumulator contains the same value found at ARGS and can be tested immediately after the JSR GETARGS call to see if any argument was found. External programs that rely on this fact should check the version of ECP8 being run (see ECP8 Global page for version number) to assure that this information is available. The data in the accumulator is undefined in versions before 2.71. See also GETARGS1. GOMON 19 Processes the MON command. Arguments stored at INLINE. (c) 1989 -20- Carolina System Software Extended Command Processor 8 MOVELN 22 Removes the number of leading characters from the buffer pointed to by REG5 specified by the accumulator. PARSE 24 Determine the command number of the first command stored at INLINE and removes the command if found. The command number is returned in the accumulator. Currently defined command numbers can be found by examining the source code. DOQUIT 30 Executes the QUIT command. No arguments. GETARGS1 34 Works just like GETARGS except the argument is taken from the buffer pointed to by REG5 instead of being taken from INLINE. DOCMD 54 Calls the command handler specified by the command number in the accumulator. See PARSE for command numbers. COLD 56 Calls the initialization routine for ECP8. User programs should use COLDSU instead of this call. (c) 1989 -21- Carolina System Software Extended Command Processor 8 ZAPLIN 59 This call cancels the remainder of any input line (yet to be processed) such that execution continues with the next input line. NOARGS 64 Buzzes the speaker and displays the "Bad argument" error message. MONCMD 66 Processes the Apple ROM monitor command found at INLINE. COLDSU 79 Cold starts the system. EXIT2 88 Transfers control the the executable file whose pathname is stored at ARGS. See EXIT. ARGINTERP 98 Copies the ProDOS string at ARGS ($300) to INTERPSU ($280). ROOTARG 99 Copies the ProDOS string at ROOTPATH to ARGS. ARGPATH1 100 Copies the ProDOS string at ARGS to PATH1. ARGPATH2 101 Copies the ProDOS string at ARGS to PATH2. (c) 1989 -22- Carolina System Software Extended Command Processor 8 HEXBIN 103 Converts the argument at ARGS from ascii hexadecimal into binary at location VALUE ($205C). An error is displayed for invalid data. The carry flag is cleared for a successful conversion. EXISTS 104 Prompts the user that a file exists and asks if he wants to proceed. If the user answers "N" then the accumulator returns as zero. The accumulator returns non-zero if the user answers "Y". [5.00] ECP8 Memory Usage: The following is the memory usage scheme for ECP8: $0000 - $00FF Zero page $0100 - $01FF Hardware stack $0200 - $03FF Reserved for ECP8 (data areas) $0400 - $07FF Screen memory $0800 - $1FFF ECP8 file buffers and data storage $2000 - $5FFF CP.SYSTEM program code $6000 - $BEFF Free memory area for transient commands and user programs. You may restrict the size of this area from the top down by altering the MEMORY SIZE word in the ECP8 global page area. $BF00 - $FFFF ProDOS [5.10] ProDOS Global Page Bitmap: ECP8 reserves memory in the ProDOS Bitmap from $2000 to $5FFF. It releases all memory from $800 to $1FFF and from $6000 to $BEFF at startup and after return from any transient command. This way, you can use transient command programs from ECP8 that reserve their own memory while in RAM without getting errors in case those commands don't release their own memory. This feature makes it possible to use programs created with the ByteWorks (tm) ORCA/M Small C compiler as transient commands so long as they ORG at $6000 or above. ECP8 can load CMD programs to any address from $6000 to $BEFF, SYS programs load to $2000, BIN programs can load from $2000 to $BEFF. (c) 1989 -23- Carolina System Software Extended Command Processor 8 [7.00] External GETCMD routine support protocol The GETCMD subroutine in ECP is used to read input from the keyboard or from an active Batch file. Keyboard input is stored, carriage return terminated, MSB on, at the buffer address pointed to by the pointer INPBUFFER ($206C). Batch file input is normally read in at $300. Batch file parameter variables are expanded into the input line as it is copied, MSB on, to the normal INLINE ($1F00) buffer. Up to MAXLEN ($206A) characters are read except when in Batch file mode when $80 bytes are read. When Batch mode is in effect as indicated by the Batch mode flag, GETLN passes control to the EXECLN routine (ECPMLI call #51). EXECLN reads in the file and expands Batch parameter variables. There are currently two modes of input supported specified by INPMODE ($206B). If INPMODE = $0 then regular command mode is in effect. The default prompt is displayed prior to calling the GETCMD routine. If INPMODE = $FF then external input mode is in effect. This mode is used by ECP's internal READLN command and may be called by external routines via the INPUT ECPMLI call. Calls to the INPUT routine (INPMODE = $FF) will result in a "?" being displayed to the screen prior to the GETCMD call so the user will know that he is responding to a general input request rather than a request for a command. Before installing your handler you should check the version of ECP in use. It is stored as packed hex at $2003. You will want to make sure the version is at least 3.54. This is stored as $2003 = $54, $2004 = $03. To install your external handler, you should store a jump (JMP) to your code along with the address of your code at $2067. At boot-time, $2067 holds $60 for RTS. The GETCMD routine, once it determines that input is needed from the keyboard, will call $2067 via a JSR. Your routine should check INPMODE ($206B) and determine if your routine knows how to handle the mode stored there. If it does not it may allow ECP to handle that mode by simply returning with RTS. If your routine will handle this input request, it should pull two bytes off of the stack such that an RTS in your code will return to the routine that originally called GETCMD. If your routine will not manipulate Batch mode commands you may return to the caller based upon the status of the Batch mode flag in the ECP global area ($2018). If your routine will handle Batch mode input it should test the status of the Batch mode flag ($2018) and if it is non-zero should call the ECPMLI routine EXECLN (Call #51). Upon return from EXECLN the input line will be stored at INLINE ($1F00) where the user routine can do any further expansion or manipulation as desired before returning to the routine that called GETCMD. To remove your external handler, simply store a $60 at $2067. Calls to ECP's GETCMD ECPMLI routine will set MAXLEN to $FE and INPMODE to $00 with INPBUFFER set to INLINE ($1F00). Calls to ECP's INPUT ECPMLI routine will set MAXLEN to the value in the accumulator and will set INPMODE to $FF. The caller must have already set INPBUFFER prior to the call. (c) 1989 -24- Carolina System Software Extended Command Processor 8 Note that INPUT is really a second entry into GETCMD that sets INPMODE to $FF while entries to GETCMD set INPMODE to $00 automatically. In either case, control will eventually be passed to EXTGETCMD ($2067) where your code can intercept control with the modes already set. Important addresses for External GETCMD protocol: ------------------------------------------------- VERSION $2003 INPMODE $206B MAXLEN $206A INPBUFFER $206C EXTGETCMD $2067 BATCHMODE $2018 INLINE $1F00 ARGS $ 300 (c) 1989 -25- Carolina System Software