D33Shell.txt Manx Aztec C SHELL for Apple II DOS 3.3 Version 2.4 from Manx Software Systems, 1983 Introduction This document is excerpted from AztecC_minimanual.txt (AKA C65DOS33manual.txt) which was produced by Rubywand (Jeff Hurlbert). It is intended to describe the Aztec C SHELL program for Apple DOS 3.3 and is focused primarily on the features of the SHELL rather than Aztec C's other features. AztecC_minimanual.txt can be referenced for details about the compiler and libraries and the other Aztec C utilities. It also contains information about configuring the SHELL for use and a rather in-depth tutorial about using the Aztec C DOS 3.3 Native Mode compiler in the SHELL environment. The Aztec C SHELL is relatively Unix-like in nature and those familiar with Unix commands will find it straight-forward to use. Bill Buckels August 2008 Corrections by Michael J. Mahon November 2009 2. THE SHELL 2.5 General Use The simplest form of a SHELL command is the name of a function followed by a carriage return. A SHELL command may either be one of the built-in utilities or the name of a binary or text file which resides on disk. The following is a list of the built-in functions available with the SHELL. If a file has the same name as one of these functions, the SHELL will not execute that file, but will execute the built-in function instead. boot cp mv bye load rm call lock run cat ls save cd/ce max files unlock These commands are all specified using lower case. A complete description of each command can be found in the Commands section. Binary programs which are normally run using the DOS 'BRUN' command can be loaded and executed by simply typing the name of the file followed by a carriage return. The first two words of binary files which contain executable programs contain the load address and length in bytes of the memory image. These are used to load the program into memory. The SHELL 'load' command can be used to load the image into a different section of memory much the same as the DOS 'BLOAD' command. Text files containing a series of SHELL command lines can be executed by simply typing the name of the text file followed by a carriage return. All SHELL input is then taken from that file until the end is reached For more information see the Batch Facilities section. Some built-in SHELL utilities as well as binary programs produced using the Aztec C compiler system require or allow arguments to be specified when the command is executed These arguments are placed on the same line as the command name separated by spaces. An example of this is the SHELL 'lock' command Under Apple DOS, if it is desired to lock several files, the DOS 'LOCK' command must be given once for each file. To lock several files using the SHELL, the user would type something like: lock test1 test2 test3,d2 to lock files "test1" and "test2" on the current drive and "test3" on drive two. Because arguments are separated by spaces, file names containing spaces must be enclosed in double quotes to enable the SHELL to distinguish the single name from two names. For example, to unlock a file called "test prog", the user would type: unlock "test prog" Double quotes should also be used around file names used as commands if the name contains any blanks. The final feature of the SHELL which will be discussed is the ability to redirect the standard input and/or output of a program to a file or a device. Normally the standard input and output of a program are connected to the keyboard and screen respectively. The user may redirect either or both of these connections to a file or a device such as a printer. This is accomplished by using the special character '<' for input and '>' for output. As an example, to place the output of the NM command, which produces a symbol table from an object file, into a file for later perusal, type: nm objfile > listing The namelist will not be printed to the screen, but to the file 'listing' instead The SHELL also pre-opens a second channel to the screen called the standard error output. This channel cannot be redirected. 2.6 Built-in Commands This section describes the commands which are built into the SHELL program itself. Each SHELL command will be listed along with a description of its use and its function. All commands are specified as being lower case. File names may be typed with either upper or lower case letters, however they will all be mapped to upper case for compatibility with Apple DOS. File names may contain blanks, but to distinguish arguments from the parts of the file name, the entire name must be enclosed within double quotes. In the following discussions, the concept of current data drive and current execution drive are used Under DOS, the last drive accessed is considered the current drive. Under the SHELL, the current data slot. drive and volume must be explicitly changed by the user using the "cd" command At any point where an optional slot. drive or volume parameter may be given, if any are not specified, they will default to the current data value respectively. The examples given for specific commands should clarify this point. In general, all arguments to SHELL commands and to utility programs are separated by blanks. Arguments in square brackets are optional and most commands allow more than one file name per command line. In the following descriptions, any reference to a file name is assumed to include the optional slot, drive and volume parameters. 2.6.1 boot boot n Does a jump to address $Cn00. (Usually to reboot.) Example: boot 6 Causes the floppy disk to reboot 2.6.2 bye bye Does a jump to the Apple machine language monitor at location $FF65. Reentry to the SHELL is through $3D0 or by hitting RESET on systems with the autostart ROM. 2.6.3 call call addr Performs a "jsr" to the address given. If addr is preceded by a '$', it is interpreted as hex, otherwise as decimal. Examples: call $800 call -151 The first example does a "jsr" to hex 800, while the second calls the monitor. 2.6.4 cat cat [file1] [file2] ... Concatenates the named files to the standard output if no files are specified. input is taken from the standard input This is the quickest and easiest way of looking at a text file. Examples: cat test1 test2,d1 cat test1 test2,d1 > test3 cat > pr: cat kb: > pr: The first example displays "test1" from the current data drive on the screen immediately followed by the file "test2" located on drive one. The second example creates a new file called "test3" containing the two files "test1" and "test2". The third example reads a character from the standard input and writes it to the device "pr:" which is the printer. The fourth example is equivalent to the third. 2.6.5 at cd sn,dn,vn Change the current data slot. drive and/or volume. Any or all of the three parameters may be changed Those not specified will remain the same. If a volume number is specified. it will be checked whenever a file is opened A volume number of zero, however, will match any disk. Examples: cd s6,d1,v0 cd d2 The first example changes the current data disk to be slot six, drive one, and any volume. The second example changes from whatever the current drive was to drive two. The slot and volume remain the same. 2.6.6 ce ce sn,dn,vn Change the current execution slot, drive and/or volume. Execution parameters are used when loading and running a particular binary program or SHELL file. If the name includes a specific reference to a slot, drive or volume, that parameter is used If there is no reference as to which device holds the file, the current data disk is searched and if the file is not found there, then the current execution disk is checked This allows all utility programs to reside on a different disk than the one being actively used. ce s6,d2,v0 ce d1 The first example changes the current execution disk to be slot six, drive two, and any volume. The second example changes from whatever the current drive was to drive one. The slot and volume remain the same. 2.6.7 cp cp file1 file2 Copies files from the specified device to file2. Note that file2 will be overwritten if it already exists. Examples: cp test oldtest cp test,d1 test The first example makes a copy of "test" on the same disk called "oldtest". The second example assumes that drive one is not the current data drive and copies the file "test" from drive one to the current drive. 2.6.8 load load file [aN] [lN] Loads a binary file into memory. If the starting address and/or length are not specified, they are taken from the first two words of the file. After loading, the start address and length are displayed on the screen. These values are remembered for use in the save and run commands. If N begins with a '$', the value is interpreted as a hex value otherwise as decimal. Examples: load tabset A=0800 L=12F2 load tabset a$2000 A=2000 L=12F2 The first example loads the tabset program into memory. The shell displays the load address and length. The second example loads the tabset program into memory at address hex 2000. 2.6.9 lock lock file 1 [file2] ... Lock the file on the specified slot, drive and volume. If any of slot, drive or volume are not given, they default to the current data values. Examples: lock test1 lock tcst1 test2 test3,d2 The first example locks file test1 on the current data disk. Example two locks files test1 and test2 on the current data disk and locks file test3 on drive two of the current data slot and volume. 2.6.10 ls ls [sn,dn,vn] ... Perform the catalog function on the specified slot, drive and volume. This command defaults to the current data slot, drive and volume. If more than one is specified, they will be cataloged in order. The SHELL will wait for a key to be pressed between different catalogs. Unfortunately, the output of ls cannot be redirected. Examples: ls ls d1 d2 The first example does a catalog of the current data slot. drive and volume. The second example catalogs drive one and then drive two of the current data slot and volume. 2.6.11 maxfiles maxfiles n Allocates n buffers for open files. This command is similar to the DOS 'MAXFILES' command. It specifies the maximum number of disk files which may be open at anyone time. When the SHELL is initialized, the value is defaulted to 3. Example: maxfiles 4 For an application which will have four disk files open, maxfiles is set to four. 2.6.12 mv mv [-f] file1 file2 Moves file1 to file2. If the slot, drive, and volume of file1 are the same as that of file2, file1 is simply renamed as file2. If they are different, file1 is copied to file2 on the specified device and file1 is deleted. If file2 exists, an error message will be printed. If the '-f' option is given, no error message will be given and file2 will be removed first. Examples: mv test foo mv -f test foo mv test test,d2 The first example simply renames the file "test" as "foo". The second example deletes the file "foo" and then renames "test". The last example copies the file "test" from the current data drive to drive two and then deletes "test" from the current drive. 2.6.13 rm rm file1 [file2] ... Delete the specified file or files. If a file is locked, a message is displayed giving the name of the file which is locked. Examples: rm file1 file2 rm foo,s5 The first example deletes files "file1" and "file2" from the current data drive. The second example deletes the file "foo" from the disk in slot five. The drive number will be the same as the current data drive number. 2.6.14 run run [argl] [arg2] ... Does a jsr to the starting address of the last file loaded after pushing a pointer to the argument vector and the number of arguments on the stack. Argv[0] will be the "run" string. Example: load tabset A=0800 L=12F0 run 8 This example loads the program "tabset" into memory. The SHELL displays the load address and length. The "run" command then calls hex 800 ($800) with the argument "8". The three lines are equivalent to typing: tabset 8 all by itself. 2.6.15 save save file [aN] [lN] Saves a part of memory to a file on the specified device. If the starting address and length are not specified, the starting address and length of the last file "load"ed will be used if N is begun with a '$', the value is interpreted as a hex value otherwise as decimal. Examples: save foo save foo a$800 l1000 The first example will save in a file called "foo", whatever the last program loaded or run. The second example will save a thousand bytes of memory starting at hex 800 in a file called "foo". 2.6.16 unlock unlock file1 [file2] ... Unlock the file on the specified Slot, drive and volume. If any of Slot, drive or volume are not given, they default to the current data values. Examples: unlock test1 unlock test1 test2 test3,d2 The first example unlocks file test1 on the current data disk. Example two unlocks files test1 and test2 on the current data disk and unlocks file test3 on drive two of the current data slot and volume. 2.7 Batch Facilities Text files containing a series of SHELL command lines can be executed by simply typing the name of the text file followed by a carriage return. Note that the type of the file must be 'T'. All SHELL input is then taken from that file until the end is reached SHELL command files may not be nested, but they may be chained If a SHELL command line executes a second SHELL command file, the first command file is closed and forgotten. Lines beginning with the '#' character are ignored by the shell and can be used as comments. When the SHELL is booted for the first time, the disk that the SHELL was booted from is searched for a file called ".PROFILE". If this file is found and is a text file, it will be executed immediately. This allow any special startup procedures to be automatically initiated SHELL command files may also be given up to 9 arguments. These arguments are referenced by the character '$' followed by the number of the argument to be used. Argument 0 is the name of the SHELL command file itself. For example, to link together several files, the following one line SHELL command file might be created: ln -o In.out $1 $2 $3 $4 $5 $6 $7 $8 $9 sh65.lib If the file was called "linkit", it could be used by typing: linkit f1.rel f2.rel f3.rel If an argument does not exist, it is ignored. There are two special "built-in" commands that the SHELL will only recognize when read from a SHELL command file. These commands are used for additional control over the processing of the commands in a SHELL command file. 2.7.1 loop loop This command is used to start and end a loop in a SHELL command file. The command lines between the two loop statements will be executed once for each argument given to the SHELL command file. During the loop, two special arguments are available for use. '$#' is replaced by the number of the current argument being processed. The two-character sequence '$%' will be replaced by the current argument itself. The following is an example of a SHELL command file which will compile and assemble from one to nine files, one at a time. set -x -a loop # This is argument number $#, $% c65 -a -o $%.asm $%.c as65 -o $%.rel $%.asm loop If the preceding lines were placed in a file called "compile", then the statement: compile test junk foo would compile and assemble the three files "test.c", "junk.c", and "foo.c" into the corresponding ".rel" files and produce: loop This is argument 1, test c65 -a -o test.asm test.c as65 -o test.rel test.asm loop This is argument 2, junk c65 -a -o junk.asm junk.c as65 -o junk.rel junk.asm loop This is argument 3, foo c65 -a -o foo.asm foo.c as65 -o foo.rel foo.asm loop 2.7.2 set set [+-x] [+-a] [+-n] Sets or clears one of three internal flags in the SHELL. Using '+' will clear the flag while '-' will set it. The flags are defined as follows: x Echo command lines to the screen. Defaults to off. a Abort the SHELL command file if a command or program exits with a non-zero value. Defaults to no abort. n Parse the command lines, but do not execute them. Defaults to off. Thus, to see each line being executed, the first line of a SHELL command file should be: set -x To have a SHELL command file exit if an error occurs, include the line: set -a The "set" command may only be executed within a SHELL command file. 2.8 Configuration The basic Apple II is limited in it's ability to deal with upper and lower case and has a limited screen size. The SHELL contains device drivers which allow it to overcome these limitations to some degree. However, these same routines have been set up to take advantage of optional peripherals which greatly enhance the Apple's operation. There are two approaches to dealing with peripheral devices, writing custom routines to deal with one particular device or to write a general routine to handle a number of similar devices. The original versions of the SHELL device drivers were examples of writing custom routines. The current version contains general purpose routines for dealing with three devices, the keyboard, screen and printer. The device routines make use of a table at a fixed location in the driver to handle the functional differences between different hardware configurations. This table can be modified by using the CONFIG program provided on the STARTUP diskette. A separate set of options is available for each device and are detailed in the following. 2.8.1 Keyboard The first device is the keyboard There are four variations of keyboard available. First, is a full upper and lower case keyboard as is available with the //e or a keyboard enhancer. If this option is selected, no mapping is done at all. Second, is an Apple keyboard with the single wire shift key mod installed, while the third is an Apple keyboard without the SWSKM. Both of these options map characters from the keyboard to get the full range of ASCII characters. Finally, it is possible to specify that the keyboard is a remote terminal In this case, the driver will use the Pascal 1.0 entry point to the card that is assumed to be in slot 3. It will not do any mapping on the data received from the card Also, since there is no status entry point, the AS and AC output control characters are not available. The AC abort is still enabled during input. 2.8.2 Screen The second device is the screen. There are three types of screen. First, the basic Apple screen with 40 columns and upper case only. Second, 40 columns with upper and lower case capability. Examples of this are the //e and a II with a lower case adapter. Finally, there are the 80-column screens. All 80-column screens, remote and otherwise, are assumed to reside in slot 3 and are accessed by using the Pascal 1.0 output hook. Not all 80-column screens are identical, and do not necessarily use the same control sequences to perform such functions as clearing the screen, moving the cursor and others. To minimize this problem, a table of control codes has been built into the SHELL device driver. This table is used by the ioctl() routine when performing the appropriate functions. The values in this table are already known for several devices by the CONFIG program. The devices whose values are known are the //e, the Videx Videoterm, and the Smarterm. If a device is used which is not compatible with any of the above three cards, then the entries to the table must be provided by the user. The only programs which currently make use of the ioctl() screen calls are the screen editor VED, and the CONFIG program. For VED, the only required functions are cursor positioning, clear to end of line, and clear screen. CONFIG only uses the clear screen. 2.8.3 Printer The last device is the printer. The printer is assumed to be driven by a peripheral card in slot 1 with firmware which supports the PR# basic protocol. The printer is initialized by placing the address of the card in the CSW vector in low memory and then calling the card Normally the card then replaces the address in the CSW vector with the normal character output routine. The printer driver then sends a string of characters to initialize the firmware on the card The default sequence is: ^I^Y^Y255N which tells the card that the width is 255 and not to echo the characters to the Apple screen. It is not really necessary to change the control character to be something other than a ^I since tabs are expanded to spaces by the print driver. After the driver sends the initialization string, it saves the address in CSW for use when sending characters to the printer. When sending characters, the address is placed back in CSW and control passed to the firmware by jumping indirectly through CSW. The printer has three other control modes. First, some printer card firmware requires that the high bit be on for characters sent to it. If so, the driver has a flag which will cause it to "or" in a hex 80 with each character before transmitting it to the firmware. Also, the print driver automatically converts newlines (LF) to carriage returns before transmitting to the firmware on the card. If the appropriate flag is set, the print driver will automatically send a line feed after each carriage return. Finally, when the printer is closed it is possible to have the print driver automatically send a form feed ($0C) character to the device. All these flags are set by answering the appropriate questions in the CONFIG program. 3. PROGRAMS 3.7 VED Screen Editor ved [-tn] [file] VED is a screen oriented text editor written in C for use with the Aztec C65 system. The source to VED is included in the archive "VEDSRC.ARC". VED is not a particularly fast or smart editor, but it does get the job done. If VED is invoked with a file name, that file will be loaded into the memory buffer, otherwise it will be empty. VED does all its editing in memory and is thus limited in the size of files that it will edit. In VED, the memory buffer is never completely empty. There will always be at least one newline in the buffer. The "-t" option specifies that a different tab size should be used. Normally VED will use the current system value, but this may be overridden with this option, as in: ved -t8 file.a65 which is useful since C programs work well with a tab size of four, but assembly language works better with a tab size of eight. VED has a 1000 character limit on the size of a line. If a line is longer than the width of the screen, it will wrap to the next line. If a line starts at the bottom of the screen, and is too wide to fit, the line will not be displayed Instead, the '@' character will be displayed. Likewise, at the end of the file, all lines beyond the end will consist only of a single '-' on each line. A number of commands take a numeric prefix. This prefix is echoed on the status line as it is typed. The normal mode of VED is command mode. During command mode, there are a number of ways to move the cursor around the screen and around the whole file. newline move to the beginning of the next line. - move to the start of the previous line. space move to the next character of the line. backspace move to the previous character. 0 move to the first character of this line. $ move to the last character of this line. h move to the top line of the screen. I move to the bottom line of the screen. b move to the first line of the file. g move to the n'th line of the file. /string move to the next occurrence of 'string'. When the cursor is in the appropriate spot, there are two commands used to delete existing text. x delete the n character under the cursor up to but not including the newline. dd delete n lines starting with the current line. Note that deleting the last character on the line (newline character) causes the following line to be appended to the current line. To add new text, hitting the 'i' key will cause the top line of the screen to indicate that you are now in mode. To exit insert mode, type ESCAPE (unless the CAPS LOCK mode is enabled, in which case type control-Q). To insert a control character which means something special to VED into a text file, first type control-V followed by the control character itself. Control characters are displayed as '^X', where X is the appropriate character. Typing 'o' will cause a new line to be created below the current line, and the cursor will be placed on that line and the editor placed into mode. There are three commands used for moving text around. These commands make use of a 1000 character yank buffer. The contents of this buffer is retained across files. yy yank n lines starting with the current line into the yank buffer. yd yank n lines starting with the current line and then delete them. p "put" the lines in the yank buffer after the current line. The yank buffer is not modified. The 'z' command redraws the screen with the current line in the center of the screen. The 'r' command replaces the character under the cursor with the next character typed. When in command mode, if the ':' key is hit, a ':' will be displayed on the status line. At this point, a number of special file-related commands may be given. :f displays info about the current file. :w file writes the buffer to the specified file name. :w writes the buffer to the last specified file. :e file clears the buffer and reads the named file. :e! file clears the buffer and reads the named file even if the file was modified :r file reads the named file into the buffer. :q exits the editor. :q! exits editor even if the file was modified As can be seen VED protects from accidentally destroying the work being edited by preventing exiting or editing another file if the current file has been modified. If the file has been written using the ":w" command, the modified flag will be cleared. VED will only edit Apple text files. Binary files will not be edited. 3.12 TABSET tabset [newsize] This program displays the current setting of the tab width parameter of the SHELL. If the argument is specified, the tab width parameter is set to that value. In that case, both the old and the new value are displayed. The parameter is stored in location $D088 of bank 1 of the RAM card. 3.13 CONFIG config This program takes no parameters as it is completely interrogative. CONFIG is used to alter the SHELL's device driver tables and thus make use of any non-standard peripherals. More information on the use of the CONFIG program can be found in the SHELL section of this manual. 3.14 LDEV ldev file This program replaces a former "built-in" SHELL command. LDEV loads the named file into bank 1 of the RAM card and is used when loading a new or custom set of device drivers. The format of the device driver module is the same as that previously used. However, to take advantage of new features such as the settable tab width parameter, custom drivers will need to be incorporated into the new SHELL drivers. More information is available in the SHELL section and in the Technical Information section of this manual.