GEMini Atari

home *** CD-ROM | disk | FTP | other *** search

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / zip / cli / tsh911g.lzh / TSH_REF.DOC < prev

Wrap

Text File | 1992-09-02 | 28KB | 737 lines

TomShell Reference Manual October 4, 1990 last revised September 2, 1992 Tom Clegg Table of Contents ----------------- 0. 0.911g new features 1. TomShell Commands alias dir ls system author echo mkdir unalias cat exit mv unset cd help ren verbatim cls history rm word condense input rmdir cp interact set 2. Batch file only commands gosub resume goto return if :label ifv 3. Special variables 0..99 dcdwatch keystat quick anygem f margin resolution cwd f1..f20 mem status date font nolabel time disk force owrite verbosity dcd key PATH volume ********** NEW: pause, prompt, shortdir, width *********** 4. Special characters > >> < $ \ # ; ! " 5. Explanations .1 Batch files .2 Errorlevels .3 Filename completion .4 Modes of Operation .5 Output devices .6 Running Programs .7 Variables ======================================================================= 0. 0.911g New features (in the order in which they were added) ---------------------- .1 Your command history buffer (last 20 commands) is saved when you "exit" TomShell, and reloaded the next time you run it. .2 A 'set font' command now has no effect in resolutions other than ST high; this rather than crashing or generally confusing the operating system. .3 '>' and '<' characters preceding filenames are ignored when TomShell is attempting filename completion. .4 System and user variables are expanded with the filename-complete (tab) key. For example, typing "$PATH" and a <tab> will show you the contents of your PATH variable. .5 The "path" variable is case-insensitive. This is mainly because while TomShell likes lower-case variable names, the standard name for the PATH variable is upper-case. So, both work. :-) .6 The 'mv' (move) command will try renaming files before copying/ deleting them. Since GEMDOS allows files to be 'renamed' into other places on the same drive, this greatly speeds up commands like "mv c:\fu\*.* c:\fu\bar\". .7 'cp' and 'mv' now work on batches of over 128 files. They already did, way back before cp/mv sorted their source files, but I had a momentary logic drop, and buggered it all up. :-) .8 A new system variable, 'flash', changes or disables cursor flashing. .9 Some internal cleanup was done, much of it in the external program execution section. 0.200! New features ------------------- .1 Finally, "ls" does good columns! The list goes down the first (left) column, down the second column, down the third column, and so on. This is much better for actually trying to find files. Maybe eventually this will be used in the "help" command as well. :-) .2 Two new variables have been implemented: pause and prompt. Check out the appropriate sections in the manual (search for "(NEW)"). I'm especially proud of "prompt". :-) Why are there so many happy faces here? :-) .3 Two more variables have been implemented: shortdir and width. Again, check for function later on. .4 With all these new variables, the "set" output got far too long to be useful (on a 25-line screen, all user variables were scrolled off the top by the system variables), so the system variables are hidden unless a "set s" command is given. Much nicer looking. .5 Small and probably unnoticed feature removed: "alias f" would do the "set f" output but preceded by "f= ". Rather insignificant, but worth fixing anyway. :-) 1. TomShell Commands -------------------- alias author cat cd cls condense cp dir echo exit help history input interact ls mkdir mv ren rm rmdir set system unalias unset verbatim word alias assign a complex meaning to a simple word. alias jim cat d:\stadel\money # `jim' now means `cat d:\...' alias jim # what is "jim" aliased as? alias # list all aliased words author display initial message about me and my address. author cat display a [text] file to the current output device. Can be redirected via >whatever cat file1 cat file1 file2 cd change current default (working) directory. Equivalent to "set cwd ..." cd e:\stadel\ cd \files\texts cd d:\ cls clear the screen using the VT52 "esc E" command. Can be redirected via >whatever cls condense take the spaces out of a variable's value. condense blah # blah="foo bar" => blah="foobar" cp copy files. If there is more than one argument, the last one is considered to be the destination directory or file. cp jimbob.doc joebob.asc # copy jimbob to joebob cp fubar.txt \texts\ # copy fubar.txt to \texts\ cp fubar1.txt fubar2.txt \texts\ cp fu*.doc \texts\ cp fu*.doc # copy to current dir. cp fubar.txt # copy to current dir. dir list files in current or given directory. A search mask or path may be given. Each file is displayed on a separate line, with its size, date, time, and status bits displayed in neat columns along with it. Subdirectories are denoted by a trailing "\". dir # list all files in cwd dir \texts\ # list all files in \texts\ dir \texts\*.doc dir *.txt *.doc g:\*.c echo display the arguments to the current output device. echo blah # output: blah<cr/lf> echo # output: <cr/lf> echo -n blah # output: blah echo this is a test echo -n this is a test echo -n $disk;echo k # output: (eg) 763k exit exit the current batch file or interactive session. exit exit 44 # sets $status to 44 and, if exiting TomShell completely, returns 44 to the calling program. (see also "system") help display a list of available commands and reserved variables. help history display the last twenty commands entered, with line numbers. These entries can be accessed with !# or !string (!# refers to the line with the given number attached to it, !string to the most recent command starting with "string"). history input take one line of text input from the current input device and place the received text in the given variable. input name input name <aux: >aux: interact enter interactive mode until the command "exit" is issued. See "Modes of Operation" below for more details. ls display a short listing of files. Sytax is the same as "dir", but the files are listed in columns of filenames rather than with the size, date, time, etc. mkdir create a directory (folder) with the given name. mkdir tree mkdir c:\blah mkdir \test\phroo # note: \test will not be created # if it doesn't already exist mv identical to "cp" but, if a file is successfully copied, the original file will be deleted. [Starting in 0.911,] a "rename" will be attempted on each file first, in case GEMDOS allows it. This speeds up same-disk file moves. ren rename a file ren fubar.doc foobar.doc ren jimbob \texts\ # jimbob -> \texts\jimbob * Note: files can be renamed to anywhere on a logical drive without being copied or moved (renaming is faster), but not between drives. * Note: under TOS 1.4 or greater, folders can also be renamed. rm delete the specified file or files. rm fubar.txt rm *.* rm *.txt rmdir delete the specified directory (folder) rmdir test rmdir c:\temp * Note: trying to delete a non-empty directory will result in an error message. set change the value of a user or system variable, or, if the variable specified does not exist, create a new variable with the given information. set name Tom set verbosity 2 set name # display the contents of $name set # list all defined variables and # their contents system exit all levels of TomShell and return to the calling program. Differs from "exit" in that if it is called from a nested batch file or an "interact" system, the system will exit completely rather than going back one level. system unalias remove an alias entry from the list unalias v unset remove a variable entry from the list unset name verbatim display a file to the console. NOTE: This will ONLY output to the console and cannot be redirected. It provides the advantage of being able to view a file containing non-ASCII characters properly. Any character except for <cr> and <lf> will be output as some form of character. Great for looking at binary files (why?) verbatim tomshell.ttp word truncate the given variable to only one word (everything before the first space) word name # "Tom Clegg" -> "Tom" 2. Batch files only ------------------- gosub goto if ifv resume return :label gosub branch to a given label until a "return" statement is encountered, whereupon execution will continue from this point gosub test.label goto branch to a given label goto test.label.2 * Note: gosub, goto, and return work just like in BASIC. if conditional statement, can use "and"/"or". Just like BASIC, but the [in]equality operators are like C (==, !=, <, >, <=, >=) if <exp> and <exp> or <exp> then <cmd> if $status >= 0 and $key == off then phroo.bat if $status <0 or $key == on then fubar if $status != 3 then gosub test.label.3 ifv simplified form of "if". ifv status 0 goto foo [equivalent to:] if $status == 0 then goto foo resume reset the "stopped" flag. The "s" key sets the flag, and "resume" or the command prompt display resets it. If it is set, no text is displayed unless "force" == "on" (see "force") cat 1stfile resume # in case 1stfile was aborted cat 2ndfile # this one's important! return return from a subroutine. An error results if there is no "address" on the stack to return to (we aren't in a subroutine). return :label define a label that can be jumped (goto label) or branched (gosub label) to. :test.label :test.label.2 Special variables ----------------- 0..99 ^ anygem cwd date ^ disk ^ dcd ^ dcdwatch f f1..f20 font force key ^ keystat ^ margin mem ^ nolabel owrite PATH quick resolution ^ status time ^ verbosity volume ********** NEW: flash, pause, prompt, shortdir, width *********** ^ == read only 0..99 the arguments passed to the current batch file, or the last one executed. $0 is the name of the batch file, $1 is the first argument, $2 the second, and so on anygem if tomshell is run from the \auto\ folder or as a .TOS program, set this variable to "off" before running any programs within Tomshell. This disables the mouse on/off routines and automatic GEM program recognition (.prg/.app). cwd current working directory. "set cwd gleep" is equivalent to "cd gleep". Good for putting in the prompt string. date the current date: Mmm dd, yyyy disk free space on the current drive, in kilobytes. dcd DCD pin on serial port (carrier detect). dcdwatch if this is set to "on", TomShell will exit to its calling program as soon as it detects loss of carrier. Default is off. f list of all the function key settings f1..f20 individual function key macro settings. f11..f20 mean shift+f1 to shift+f10. Always use "definition" when setting these (always use quotes). To include a <return>, use "\r". Similarly: \b backspace \t tab \e escape \r return \< left arrow \> right arrow \[ shift-left arrow \] shift-right arrow \^ up arrow \v down arrow flash (NEW) the cursor flash rate (0 for a steady cursor). If you're like me and don't like flashing cursors, stick a "set flash 0" in your tomshell.bat file. If you are trying to avoid Line-A calls (advisable on TOS 2 and up), don't *read* this variable. Setting it is okay, but reading it does line-A stuff to figure out if the cursor is actually flashing or not. There must be a better way... :-) font big/small (monochrome only). Refers to the system font size, small == 8x8, big == 8x16. The 8x8 (small) font gives you 50 lines per screen, the 8x16 (big) font gives you 25. Default is big. force if this is set to "on", the [P] and [S] keys are disabled (display is uninterruptable). Default is off. key "on" if there is a key waiting in the key input buffer keystat bit mapped number, each bit represents a different status key: bit value meaning 0 1 right shift 1 2 left shift 2 4 control 3 8 alternate 4 16 caps lock on 5 32 right mouse button 6 64 left mouse button margin the number of spaces output before each line displayed (after each <cr><lf>). Usually only good for printing. Default is 0. mem the size of the largest block of free memory, in kilobytes. nolabel "exit" or "cont". Controls behaviour of tomshell when a label is not found (goto/gosub). "exit" will force a "system" command when a variable is not found, and when $nolabel == "cont", tomshell will continue as if the gosub or goto command had not been made. Default is exit. owrite controls behaviour when the destination file for a cp or mv operation already exists. "off", "on", and "ask". Should be obvious. PATH list of folders, separated by commas, where tomshell will search for programs and batch files that are called but not found in the current directory. "." does not need to been included. pause (NEW) set to any value under 32767 to pause after the given number of lines have been displayed (since the last keypress). The "More..." prompt will be shown, and you can type: S stop output: like normal [s] C continuous: don't do any more pausing Note that the C option is temporary; it will stay in effect until you press a key. This includes pressing a key during the listing of (for instance) the file being displayed, which is a bit silly but sometimes useful. To turn this feature off permanently, set pause to 0. The default for this variable is 0 (no pause). prompt (NEW) like many shells' prompt string, but slightly more powerful and interesting. Not only can you display whatever you want in place of the standard "1 c:\tomshell > " prompt, you can run programs and execute other commands when the prompt is displayed. Please note that this is a bad place to put an "interact" command. Probably the worst place. Don't. :) A trailing space character is always output after this command is executed, since it's very difficult to coerce tomshell into outputting a space character on its own. The default setting is "echo -n $ncmd $cwd >", which outputs the index of the current command (useful for !13 etc) and the current directory. You could run batch files and neat stuff like that from here, but it's good to keep the execution time of this command down, since it's done a lot. Usually you'll just use the "echo" command. When setting this, put the command you want to be in the prompt string in quotation marks. Otherwise, $variables are likely to be evaluated at the time of the "set prompt" command rather than during execution of the prompt string. set prompt "goo;echo -n $ncmd FOOBAR $cwd SILLY >" quick "on" or "off". Makes output to the screen quicker, but must be turned off for remote use. Default is off. resolution the current resolution of the ST's screen. High, medium, or low. shortdir if on, the time and date are left off the "dir" listing. Good for getting two columns on an 80-column screen and still seeing the file sizes and attributes. Default is off. status the exit code returned by the last command or program executed. Most tomshell commands leave $status intact. time the current time. hh:mm:ss in 24-hour format. verbosity 0, 1, and 2 supported now. Controls amount of information displayed by tomshell. Currently only restricts "cmd exit code #" (displayed only when $verbosity >= 1) and "File not found" (GEMDOS verbal error messages) (displayed only when $verbosity >= 2). Default is 2. volume if set to "on", the volume name and serial number of the disk in question will be displayed on the first line of a "dir" output. Default is off. width screen width. Used for figuring out how many columns to use in "ls" and "dir". ------------------ Special characters ------------------ > >> < $ \ # ; ! " > | >> | redirection < | $ precedes variable names (echo $name) \ separates directory names from each other and from filenames # (.tom files) from here to end of line is a comment ; separates two or more commands (echo $name;cat phroo;exit) ! used to access command history entries (see "history") " text enclosed in "quotes" will not be inspected for > < >> $ -n etc. Use if you want to print "test test" (>1 space between words) or "$56.45" or "shmoo -n pak" or something like that. ======================================================================= 5. Explanations =============== .1 Batch files -------------- To create a batch file, use any editor or word processor that can save a file "as ASCII", that is, with no special format or styling commands. An editor such as STeno or MicroEmacs will do fine. Each line of a batch file is processed separately, just as if it were entered on the keyboard in interactive mode. There are a few important differences, however. The first is that there are some commands available only in batch files. See "Batch files only" above for a list of these commands. Comments can also be imbedded in batch files. To include a comment in a batch file, use a # character. When Tomshell sees a # it will disregard everything until it gets to the next line of the file. Batch files' filenames should end with .bat, .tom, or .btp (for NeoDesk users). To execute a batch file, simply type its name. You don't need to type the .bat (or whatever) at the end of it, but it won't do any harm. When Tomshell is looking for programs matching a certain name (such as when you type "phroo"), priority will be given to batch files over program files (.prg, .tos, .ttp, .app). This means that if you tell Tomshell to run "foo", and there is a "foo.bat" and a "foo.tos" in the current directory, Tomshell will run "foo.bat". When it is first run, Tomshell will look for a batch file called "tomshell.tom" or "tomshell.bat" and automatically execute it before entering interactive mode. This is a good place to put some commonly used aliases and variable assignments, and possibly turn off the keyclick or something like that. It's just like autoexec.bat in the Messydos world. .2 Errorlevels -------------- An errorlevel (also called return code or status) is a number that has some particular meaning, specific to the program or batch file that returns it. The negative errorlevels are usually reserved for errors relating to the operating system, such as -33, which means "file not found" and is well known to anyone using a command line interpreter for more than about five seconds. Tomshell will look for negative errorlevels and output an appropriate message, if it has one. Whether or not Tomshell finds a verbal message, it will output a "cmd exit code #" if the status after the last command is not zero. Zero is returned when nothing of note has happened and everything is fine and dandy, so there is no need for any "warning" to this effect. Aside from the reserved gemdos/bios/xbios errorlevels, a number returned by a program can mean just about anything. Some programs even return weird numbers like 2851, for no apparent reason. Usually, however, programs will return a 0, unless an error occurs. You can set up batch files and programs that return meaningful error codes not necessarily relating to errors. For example, a BBS program may exit and return 8, which means that it's midnight and the "today's callers" file should be deleted, and maybe some other stuff. The errorlevel returned by the last command is kept in the status variable ($status). If you don't want the verbal messages ("File not found"), set $verbosity to 1. If you don't want the verbal messages _or_ the numeric messages, set $verbosity to 0. The default for $verbosity is 2 (show both lines). .3 Filename completion ---------------------- A very useful feature of TomShell, and one for which I got the inspiration and keys and so on from Gulam, is filename completion. With this nifty doo-dad, you can get a list of all the files that start with what you've just typed. This only works if the cursor is in the last position of the entered command line (at the very end). If the command line looks like this: d:\devpac > cp c:\bin\foobar\jam The cursor must be here ^ for filename completion to do anything. If you press Tab, Insert, or ^I (ASCII tab), TomShell will attempt to expand the partial filename you have typed as much as it can, which is until either there is more than one match or the complete filename has been completed. For example, if you have the following files in the current directory: foobar fubar fooobar tomfile Pressing any of the abovementioned keys will accomplish the following: You type... TomShell turns into... f f fu fubar fo foo foo foo fooo fooobar foob foobar t tomfile If tomshell manages to fill in the complete filename, it will also add a space after it, which not only lets you know that the filename is complete, but readies the command line for another, separate, argument. If you use the Home key (or ^O), TomShell will first do everything mentioned above, but if it can't fill in the whole filename it will give you a list (in "ls" format) of all files that match the most specific pattern that it can derive. The command line will then reappear with the text you entered before the ^O still intact. Try it, it's neat. It's particularly handy for accessing files such as temporary files created by Arc: "a6238124.tmp" can be entered, in most cases, by typing "a6<tab>", which is considerably faster than typing in the whole filename yourself. *** Starting with 0.911, filename completion can also be applied to variables, in order to check their contents. For example, to add to your PATH variable, type "set PATH $PATH" <tab> ",c:\bar,f:\sneh". .4 Modes of Operation --------------------- Tomshell has two modes of operation. At any given time, it is either processing commands from a batch file or waiting for you to type commands directly into the shell and processing them as they are entered. The second ("interactive") mode can be entered from the first ("batch") mode with the "interact" function. To return to batch mode from interactive mode, give the "exit" command. If you are in the "top" level (not within a batch file or interact command, which incidentally can also be used from the command line) and you issue the "exit" command, Tomshell will terminate and you will be returned to the desktop, or whatever you ran tomshell from. Batch files can be started up from within other batch files with no problem. Actually, there is a limit to how "deep" this can go, but it shouldn't get in your way. .5 Output devices ----------------- There are a few special output devices that can be used with the redirection operators (> >> <) for various purposes. The devices supported by Tomshell are: con: the console (screen) prn: the parallel port (printer) aux: the serial port (modem) Use these devices in place of filenames and output from commands (and properly written programs) will be output to them rather than the current output/input device (usually con:). .6 Running Programs ------------------- If you type only the main filename of the program you want to run, the rest will be added automatically if a matching file is found. If more than one executable (.bat, .btp, .tom, .prg, .tos, .ttp, .app) matches the given filename, priority is given to the first batch file in the directory listing as it is on the disk. This is not always the first one displayed in a "dir" listing, but usually this shouldn't be a consideration. If the extension of the file is not given, and there is no executable match found in the current directory, the directories listed in the "PATH" variable (separated by commas) are searched in the order in which they appear in the list. If the extension of the file _is_ given, and the file is not found in the current directory, the PATH directories will not be searched. .7 Variables ------------ These are very important things for everything but the most basic of applications. They are exactly what they sound like. You can keep anything you want in a variable: numbers, text, symbols, whatever. If you want to include reserved characters (such as > or ;) that would otherwise mess up Tomshell's operation, simply include them in "quotation marks". At the moment, Tomshell has no math operators (even + and -) so you can't do much in the way of counting or things like that. You can compare variables, input them from the user, display them, and so on. The most notable variables are the reserved variables used by various parts of Tomshell (see _Special_variables_). To change the value of a variable, use the "set" command. For example, set foo bar will create the variable "foo" (or change it if it already exists) and set its value to "bar". The reserved variables work the same way: set verbosity 1 Some reserved variables are read-only (for obvious reasons), such as $disk (free space on the current drive) and $mem (largest block of free memory). You've probably noticed the $ in front of the variable names by now, and may not know why it's there. All it does is tell Tomshell that the word immediately following it is the name of a variable and should be replaced with the value of that variable. For example, to echo (show) the free space on the current drive, type echo $disk This tells Tomshell to look for a variable called "disk" and echo that rather than the word "disk". The $ is not required for the "set" command. In fact, you can become quite confused if you start typing something like set $verbosity 2 This might, for example, create a variable called "1" and set its value to "2". This presumably isn't what you want. If you want to copy the contents of variable a to variable b, type set b $a Note that the $ is used for the "a" variable. This is because we want to set the variable "b" to _the_contents_of_ $a. Typing the $a tells Tomshell to use the contents of the "a" variable. Enjoy. Tom Clegg Contact me by mail at 276 Main Street, Ottawa K1S 1C9, or on NCAUG BBS at 613-231-3633 and -3636.