Readme from the 1.27 version of Davex, the last release before this reengineered one, 11 years ago:
==============================================
Davex v1.27 ProDOS command shell
25-Mar-90 Copyright (c) 1990 David A. Lyons
==============================================
[See the last page of this document for trademarks and other notices.]
INTRODUCTION
Davex is a command shell for ProDOS. ProDOS has no way to accept commands from you directly, so some sort of command interpreter is required. Davex includes a large number of "housekeeping" commands for managing your disks, directories, and files.
Davex is also a starting place for using other ProDOS programs. When you run another program from Davex (just by typing its name), you will normally be returned automatically to Davex when you Quit the other program.
Note: This document is not a ProDOS tutorial. Please refer to reference manuals or other introductory ProDOS texts for explanations of ProDOS basics like volume, file, pathname, directory, prefix, and filetype.
HARDWARE REQUIREMENTS
Any Apple II or compatible system that can run ProDOS and display lower case can run Davex. Davex will be much more convenient for you if you have at least one of the following: a hard drive, a large RAM drive, two 5.25 inch drives, or at least one 3.5 inch drive.
Davex has been tested extensively on a variety of hardware. If you find that your hardware is not supported, contact me to see what can be done, or whether an updated version is already available to support your hardware.
OPTIONAL HARDWARE
Davex supports the Echo II and SlotBuster II speech synthesizers, using the TEXTALKER or SCAT software that you should already have if you own one of these boards. To use TEXTALKER, just put a copy of PT.OBJ in the same directory as Davex. PT.OBJ is part of the Textalker software which has been licensed from Street Electronics Corporation, the designers of the Echo, for distribution with Davex.
For the SlotBuster, ProSCAT must already be installed in memory; Davex will recognize it but will not install it. (Note to SlotBuster users: Use ProSCAT 1.3 or higher. Reviewing the screen will not work in 80 columns with ProSCAT versions less than 1.3.)
FILES NEEDED FOR DAVEX
When you install Davex on a hard disk or RAM disk, you should create a subdirectory for Davex. The name of the subdirectory doesn't matter, but "DAVEX" is the obvious choice. From within Davex, this directory's name can always be abbreviated as "%".
Davex itself is a SYS file in the % directory and is usually called DAVEX, although the name does not matter to Davex. %CONFIG is a BIN file; it stores configuration options like printer slot, your scan list, and a file type table. %HELP is a directory containing help files for individual commands. If you are short on disk space, you may want to leave %HELP off of your work disk. If you do, the "help" command will report "directory not found" when you ask for help on a specific command. (You can also put the help directory on another disk; use the 'config' command to tell Davex the pathname of your help directory.)
No other files are required in the % directory. Typically there will be external commands (BIN files or $2E files) and other programs (SYS files) there. If you are using any aliases, there will be a TXT file called "aliases" in your % directory (see "help alias"). If you are using the Echo speech synthesizer, there should also be a copy of PT.OBJ in the % directory.
RECOMMENDED HARD DRIVE SETUP
Copy the entire "%" directory onto your hard drive. Then, if you want your system to boot up directly into Davex, use the "sysalias" command (try "help sysalias") to create a one-block SYS program, with a name ending in ".SYSTEM", in your top-level directory.
For example:
copy % /hard1/davex
sysalias /hard1/davex/davex /hard1/davex.system
(If there are other ".SYSTEM" files earlier in the directory than davex.system, copy the first one to another disk, delete it, create davex.system using the 'sysalias' command, and finally copy the ".SYSTEM" file back onto the disk. This way, davex.system will be the first program ProDOS sees when it looks for a program to run.)
Once you have Davex installed, you will probably want to use the "scan" command to tell Davex what directories to search when looking for programs to run. You may also want to (1) edit the %aliases file and (2) use the config command to set miscellaneous options.
RAM DISKS
If your RAM disk is backed up by a battery, the instructions for hard disks apply to you. Just install it once, and you're all set.
To set up a disk that will copy Davex to the RAM disk and execute it there, first you need to understand the "copy" and "exec" commands. If there is a %autoexec file, it will be executed automatically when you boot Davex. A typical %autoexec file contains something like this:
copy %=:sys /ram/davex
copy %=:bin /ram/davex
copy %aliases /ram/davex
copy %help /ram/davex/help
/ram/davex/davex
The first line copies all SYS files from the % directory to the RAM disk, and the second line copies BIN files. The third line copies the help directory (if you have a small RAM disk, you may not want to copy the help). The last line simply runs the copy of Davex from the RAM disk.
(Note that it would be simpler to just "copy % /ram/davex". But this is a problem because the %autoexec file will be in use, causing the copy to fail.)
Once you are running the copy of Davex from the RAM disk, your "%" directory is "/ram/davex".
A different approach to moving Davex to a RAMdisk would use the "vrestore" command to copy an complete image of your RAMdisk from a file. See "help vrestore" for more information.
APPLE IIGS USERS
See your dealer for the most recent version of the System Software. The most recent version (as of February, 1990) is 5.0.2. Davex will work with older versions, but keeping up to date is always a good idea for maximum compatibility with new software. The most recent version of ProDOS 8 is 1.8.
If you have an Apple IIgs and wish to have your system boot into Davex through GS/OS (so you can run S16 and EXE programs without rebooting), the above instructions still apply to you.
You will also need to delete or rename the START file in your SYSTEM directory. This forces the ProDOS loader to scan your root directory for a startup application instead of running START. You may want to rename START to FINDER and type
scan -a /your.boot.disk/system
so that you can run FINDER (in the SYSTEM directory) just by typing its name.
USING DAVEX
When you enter Davex, you see (in 80 columns if your system supports it):
Davex vX.XX
Type ? for help, $ for Freeware notice.
current_date_and_time
prefix:
Your current ProDOS prefix (the directory you're "in"), followed by a colon (:), is your prompt. Davex expects you to type a command and press RETURN. (If you press RETURN without typing anything, you just get the current date and time and another prompt.) [You can use the 'date' or 'setdate' command to set the date and time if your machine doesn't have a clock.]
Some commands can be executed just by typing their names. For example:
help
online
quit
Other commands require additional information (called "parameters") after the command name. You must type at least one blank space between a command name and the parameters that follow it. Examples:
delete that.file
lock /disk3/standard.ltr
For some commands, parameters are optional.
help
help copy
info
info /my.disk/my.file
You may put more than one command on a line if you separate the commands with semicolons (;). If an error occurs during one command, the remaining commands are ignored.
WHAT IS A COMMAND?
There are three kinds of commands:
1. built-in commands
Built-in commands are part of Davex and are always available. When you type a command, Davex always checks first to see if it's an internal command. (The '?' or 'help' command displays a list of all internal commands.)
If the command you typed is not internal, it looks on your disks, trying to find a file with the same name. You can tell Davex what directories to look in by using the 'scan' command. (See "help scan".)
2. external commands
If the non-internal command is found to be a BIN file or a $2E file, Davex attempts to execute the file's contents as an external command. These files are usually found in the same directory as Davex, although they can be in any directory on your scan list.
Davex features such as wildcards and shorthand pathnames are available with external commands.
A number external commands are supplied with Davex, and an appendix describes how assembly language programmers can write additional external commands.
3. SYS, S16, and EXE programs
If a non-internal command is found to be a SYS or S16 program, Davex runs the program. When you quit the other program, you are automatically returned to Davex.
[You need the file BRIDGE.S16 in the same directory as Davex to run S16 and EXE programs directly from Davex. These work only on the Apple IIgs, and you need to boot through ProDOS 16 or GS/OS to run them.]
SHORTHAND FOR PATHNAMES
'%' is shorthand for the name of the directory Davex is in. A '/' after the '%' is optional. Examples:
cat %
cat %help
cat %/help
info %davex
You can specify a volume by slot and drive number like this:
info .61/prodos <==> info /xxx/prodos, where /xxx is the name of the ProDOS volume in slot 6, drive 1
prefix .32 <==> prefix /xxx, where /xxx is the name of the ProDOS volume in slot 3, drive 2 (usually /RAM)
Finally, '.' is shorthand for the name of the current directory, and '..' is shorthand for the name of the directory above the current directory. Slashes after '.' and '..' are optional, as with '%'.
cat .. display catalog of directory above
./help run program called 'help'
WILDCARDS
It is often convenient to execute one command (for example, delete, lock, or copy) on a group of files all at once, rather than on one file at a time. Davex provides wildcards as a convenient way to work with groups of files.
'=' and '?' are wildcard characters; they "match" any number of characters in a file's name. You can use wildcards in the last segment of pathnames for many commands. Only one wildcard per pathname is permitted.
Examples:
lock = Locks all files in the current directory
delete =.old Deletes all files ending in ".old" from the current directory
'?' is like '=', but Davex asks you whether or not to operate on each matching file. Examples:
lock ? For each file in the current directory, asks you "lock xxxxx? (Y/N)". Type Y to lock the file, or N to skip to the next one.
delete ?.old For each file in the current directory whose name ends in ".old", asks whether or not to delete it.
You can restrict a wildcard to match files only if they are of a particular type. Examples:
pg part?:txt For each "txt" file in the current directory beginning with "part", ask whether or not to "pg" the file ("pg" displays a file one screenful at a time)
ALIASES (ABBREVIATIONS)
Before Davex tries to find your commands (in the built-in list or on disk), it first checks your aliases. If there is an alias for a command word you typed, Davex replaces the word with what it stands for; then it continues processing the command line.
Type "alias" to see what aliases are defined; see "help alias" to learn how to create, remove, and save aliases.
Alias expansion can happen up to ten times in a row--the expansion can start with a word that is itself an alias for something.
A "~" as the first character of a command halts alias expansion right away--this is useful both from the keyboard and inside alias definitions. For example, "~cat" executes the 'cat' command even if there is an alias expanding "cat" into something else. Also, an alias expanding "ls" into "~cat" means that "ls" always executes the 'cat' command, even if there is an alias expanding "cat".
The aliases are stored in the TXT file %aliases. See Appendix C for an explanation of the aliases that come on the disk as shipped from DAL Systems. (Of course, you can change the supplied aliases and add your own--see "help alias".)
Note: If you use wildcards with an alias, you may be surprised to see Davex refer to the command by its real name. For example, if you have an alias expanding "kill" into "delete":
/my.disk: kill a?
delete /my.disk/apple? (y/n)
delete /my.disk/apricot? (y/n)
PAUSING AND ABORTING
If you press SPACE while the screen is scrolling, it will freeze. Each SPACE press will generally advance the display by one line. Press RETURN to continue scrolling.
Ctrl-C or Apple-period will print "*** aborted" and will always return you to the command line prompt.
ESC aborts the current operation, but does not necessarily return you to command level. For example, if you are executing "pg =", ESC will abort paging the current file, but pg will begin executing on the next file matching the wildcard.
CONTROL CHARACTERS AVAILABLE WHILE TYPING A COMMAND LINE
(from "help cmdline")
Ctrl-B = move to beginning of line
Ctrl-D = delete character at cursor
Ctrl-E/Ctrl-N = move to end of line
Ctrl-F = find forward; press ESC to exit
Ctrl-H (left arrow) = move left
Ctrl-I = insert (cancelled by arrows or Ctrl-D)
Ctrl-J (down arrow) = move down on the list of previous commands
Ctrl-K (up arrow) = move up on the list of previous commands
Ctrl-L = toggle Caps-lock on/off for Apple II+
Ctrl-M = return (accept whole line, even the part after the cursor)
Ctrl-O = if the following character is a control character, inserts it (control characters can't normally be entered). If the following character is "K" to "O" or "k" to "o", a special character is inserted (useful only on the II+ keyboard):
K L M N O k l m n o
[ \ ] ^ _ { | } ~ DEL
Ctrl-Q = accept portion of line before cursor
Ctrl-R = re-edit previous input
Ctrl-U (right arrow) = move cursor right
Ctrl-X = cancel input
Ctrl-Y = erase from cursor to end of line
DELETE = erase character to left of cursor
Apple-Y = same as Ctrl-Y
Apple-< = move to beginning of command line
Apple-> = move to end of command line
Apple-E = switch between insert and overstrike ("exchange")
Apple-H = Hardcopy of screen (set printer slot with config)
(beeps twice if printer is busy)
Apple-Space = advance printer one line
Apple-Return = advance printer to next page
MUCH MORE INFORMATION ONLINE
This document is intentionally short. Information on each command and on other topics can be found using the 'help' command. Type 'help help' (or '??') to get started.
The first line of each help file shows alternative names for the command, if there are any. Then the command's syntax is given, using square brackets around the parts you can leave out.
DON'T IGNORE THE ONLINE HELP! Even if a command's purpose and use seem obvious, take a quick look at the help. Lots of commands have handy options that you won't know about if you skip the help.
"DASH" PARAMETERS
Many commands take optional parameters following a "-". A letter identifying the parameter follows the "-". In some cases, a value (a number, or string, for example) is expected after the letter, and in other cases nothing more is required.
Starting with Davex 1.25, it doesn't matter whether you put the "-" parameters before or after the other parameters. (Older versions required the "-" parameters to come last.)
Examples
cat -t /xyz The "-t" stands for "tree"; when a DIR appears in the listing, "-t" tells the catalog command to indent two spaces and list the contents of the directory. No value is expected after the "-t".
cat /x -fsys The "-f" stands for "filetype"; a filetype must be specified after the "f". (In this example, files not of type SYS will not appear in the listing.)
INTERNAL COMMANDS
This is just a list of commands. It tells you what commands are built into Davex, but it does not explain them. Consult the online help to find out how to use a specific command. (Start with "help help" or "help topics".)
help | ? display command information
cat display directory
prefix change prefix
top set prefix to parent volume
up change prefix to parent directory
over move to another directory
online print names of online volumes
copy copy files or trees of files
update replace outdated files
pg display files a screenful at a time
type display files
rename change name
delete destroy files
create create a directory or other file
filetype change file's type (and auxiliary type)
config show or set various Davex options
ftype display or update filetype table
dev list, add, or remove ProDOS devices
scan examine or change the scan list
exec get keyboard input from a TXT file
como redirect command output to file or printer
size show size of file or directory
info print info on file
lock make a file read-only
unlock allow read, write, rename, delete
prot protect file
spool spool files for later printing
eject eject a volume or all volumes from SmartPort
touch touch a file, updating its modification date/time
(or set/clear backup bit)
bye quit Davex
cls clear screen (or send Ctrl-L to file/printer)
rep repeat: execute a command several times
err print ProDOS error message from code
num convert numbers between decimal and hex
dt print date and time
boot boot the system
mon enter the Monitor
echo echo string
= print pathnames
wait wait for spooled files to finish printing
EXTERNAL COMMANDS
These commands are supplied with Davex. Other external commands can be written in 6502 assembly language (see Appendix).
alias show or change aliases (abbreviations)
blist list a BAS file in ASCII
brun run a BIN file ['brun' is actually a small SYS file, not an external command]
combine join several files into one
conp set IIgs control panel options
date set the ProDOS date and time (if you have no clock)
deschw describe system hardware
doscat catalog a DOS 3.3 disk in a 5.25" drive
du summarize disk usage
expand expand tabs into spaces
ffind search directories or volumes for files (find by name, type, auxiliary type, need-backup)
find search files for lines containing a given string
gsbuff set Apple IIgs printer/modem buffer sizes
hdr show lines from the beginning of a file
iw2 set up print options for ImageWriter II
modchk compare modification dates on pairs of files
mx80 set up print options for Epson MX80
pset set up print options for NEC8023 / ProWriter / ImageWriter
ptype display a Pascal Text file (type $03)
ram3 disconnect or reconnect slot 3 RAMdisk
setdate sets date and time (only if no clock available)
setstart examine or set the startup path of a SYS application
split split a file into two pieces
strings display legible strings in any file
sysalias create an alias for a SYS or S16 file
tail show lines from the end of a file
tr translate strings in file into other strings
viewdhr view a double high resolution graphics file
viewhr view a high resolution graphics file
wc count the lines, words, and characters in a file
what determine what a file is (this can be really handy!)
SHORTCUTS
If Davex is looking on disk for a command and finds a directory by that name, Davex simply sets your prefix to that directory. This is similar to using the 'prefix' command, except that the scan list is used.
Typing a full pathname (beginning with a slash) always sets your prefix. Pathname shorthand works, too--pathnames beginning with a period (.) or percent sign (%) are expanded into full pathnames internally (try "= %", "= .61", etc).
After an optional parameter that accepts no parameter value, additional parameters can follow without another "-". For example,
copy this that -fb
is the same as
copy this that -f -b
and
cat -ta .61
is the same as
cat -t -a .61
HOWEVER,
cat .61 -at
is NOT the same as
cat .61 -a -t
because the "-a" parameter takes a string value (in "cat .61 -ta" the string value following "-a" consists of 0 characters).
Note that in
cat -a .61
the ".61" string belongs to the "-a" option, and there is no pathname provided. You can get the desired effect by instead using
cat -a"" .61
or
cat -an .61
Some SYS files can take a pathname parameter; BASIC.SYSTEM, for example, will run whatever BAS file you specify as its parameter (actually it does a '-' command, so you can also BRUN a BIN file, EXEC a TXT file, or launch a SYS file). If BASIC.SYSTEM is available in one of your scan directories, you can type
BASIC.SYSTEM MYPROGRAM
to run MYPROGRAM under BASIC.SYSTEM. To Davex, the parameter following the name of a SYS file is a STRING, not a pathname. This means you can't use the "%" or ".xx" shorthand notations in the parameter.
(Note that BASIC.SYSTEM does not always preserve your prefix. If your prefix refers to a subdirectory, BASIC.SYSTEM will preserve it; otherwise it sets the prefix to be EMPTY and behaves like DOS 3.3--it goes by slot and drive numbers and defaults to the slot/drive that BASIC.SYSTEM was loaded from.)
The 'what' command tells you whether a particular SYS file has a startup buffer.
Appendix A: Hardware Compatibility
Davex has been tested with the following Apple IIs and compatibles: Apple II+ (SmarTerm 80-column, shift-key mod), Apple //e (original and enhanced), Apple //c (original and UniDisk 3.5 ROM), Apple IIgs, and Laser 128.
IIgs Support
Davex is compatible with the IIgs but does not behave much differently than on an earlier Apple. Since Davex does not disable interrupts, you can use Classic Desk Accessories (including the Control Panel) with no problem. If you launch Davex from a GS/OS program like Finder, APW, or ECP16 you will return to it automatically when you quit Davex. You can launch a GS/OS application (a file with type S16) by typing its name (assuming the directory it's in is in your scan list), and you still automatically return to Davex when you quit. (The file %BRIDGE.S16 is a tiny GS/OS application that makes this possible.)
Appendix B: AppleWorks Classic Compatibility
The pg and type commands recognize AWP files but have not been revised especially for AppleWorks 3.0. In future Davex versions, 'spool' and 'exec' may recognize AWP files.
The 'cat' command displays AWP, ADB, and ASP filenames using the capitalization you used when naming the files in AppleWorks. (This information is stored in the files' auxiliary type fields.)
Appendix C: Standard Aliases
This appendix lists and explains the aliases provided in the "%aliases" file. You can use the 'alias' command or a text editor to remove or change these aliases, and you can add your own. The maximum size of the %aliases file is currently 768 bytes; if your %aliases file is longer than that, Davex simply ignores the excess.
q bye
quit q
Explanation: "q" and "quit" stand for "bye" (leave Davex).
> como
< exec
Explanation: ">" stands for "como" (send output to a file or slot) and "<" stands for "exec" (get command input from a file)
cd prefix
pfx cd
down cd
Explanation: "cd" (change directory), "pfx", and "down" all stand for "prefix". "down" is appropriate because the 'prefix' command takes you down to a subdirectory if you use a partial pathname (example: "down mydir" or "down firstdir/xyz/abc").
\ up
Explanation: "\" stands for "up", which takes you to the directory above.
over up;prefix
Explanation: "over" stands for "up" followed by the directory name you type. Example: If your prefix is "/mydisk/dir1" and you type "over dir2", your prefix will then be "/mydisk/dir2". Wildcards are allowed, because they are not expanded until the "prefix" command is executed.
or %;top
origin or
Explanation: "origin" or "or" takes you to the top level directory of the disk Davex is running from. "%" takes you to the Davex directory, and then "top" takes you to the top level directory.
o online
Explanation: "o" stands for "online", which shows a list of all disks in your drives.
home cls
Explanation: "home" stands for "cls", which clears the screen (or starts a new page on the printer).
more pg
Explanation: "more" stands for "pg", which displays the contents of a file one screenful at a time.
mv rename
Explanation: "mv" (move) and "cname" (change name) stand for "rename", which changes the name of a file, directory, or volume.
mkdir create
md create
Explanation: "mkdir" and "md" (make directory) stand for "create", which can be used to create subdirectories (as well as other files).
rm delete
del rm
Explanation: "rm" and "del" stand for "delete", which erases files and directories.
catalog cat
dir cat
ld cat
ls cat
Explanation: "catalog", "dir" (directory), "ld" (list directory), and "ls" (list) all stand for "cat", which displays catalog listings.
tree cat -t
Explanation: "tree" stands for "cat -t", which displays a catalog listing including the contents of subdirectories.
mod cat -am
Explanation: "mod" stands for "cat -am", which displays a catalog listing sorted by last-modification date (most recently modified files appear first).
cp copy
Explanation: "cp" stands for "copy", which copies files and directories.
e echo
Explanation: "e" stands for "echo", which prints the strings you feed it (useful from "exec" files).
ej eject
Explanation: "ej" stands for "eject", which ejects 3.5" disks from their drives.
print > &;
Explanation: "print" stands for redirecting output to the printer, and the semicolon between commands is included in the alias, so you don't need to type one when you use it. Example: "print help rename", or "print cat -t", but NOT "print filename".
page > &;cls
Explanation: "page" does a clear-screen after sending output to the printer. Result: the printer advances to the top of the page.
The Conspicuous Last Page
WARRANTY AND LIMITATION OF LIABILITY. DAL Systems warrants that Davex can be a useful tool for some people in some situations, but not necessarily for you. The author uses Davex all the time and is reasonably sure it won't do anything destructive to your data. But he DOES keep BACKUP COPIES of all important data, and so should you. DAL SYSTEMS AND DAVID A. LYONS SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO THE PURCHASER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY DAVEX. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.
The following are registered trademarks of Apple Computer, Inc.: Apple, AppleTalk, AppleWorks, Disk II, ImageWriter, LaserWriter, ProDOS.
The following are Apple trademarks pending registration: ProFile, UniDisk, Apple IIgs.
APPLE COMPUTER, INC., MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.
----------
Mike Lutz suggested the name "Davex." If you don't like it, blame him.
Download Latest Version
Davex_1.30p.zip (232.2 kB)
