@DATABASE "$VER: ZShell.doc 2.2 (02.01.95)" @NODE MAIN "ZShell-Documentation 2.2 (02.01.95)" #============================================# # ZSHELL V1.30 (C) 1990,91 PAUL HAYTER # # updated to V2.2 (C) 1993,94 MARTIN GIERICH # #============================================# If you have used another version of ZShell, please read @{" Changes " Link Changes}. @{" Introduction " Link Introduction} @{" Features " Link Features} @{" For those who never read the whole Documentation" Link For_those} @{" Distribution " Link Distribution} @{" General Usage " Link General_Usage} @{" Builtin Commands for Disk Management " Link BUILTIN1} @{" Builtin Commands for Scripts and Controlling " Link BUILTIN2} @{" Builtin Commands for Advanced Users " Link BUILTIN3} @{" Past, Present and Future " Link Past} @{" Copyright " Link Copyright} @{" Credits " Link Credits} @{" Authors " Link Authors} @ENDNODE @NODE Introduction "Introduction" ZShell is a small, fast and powerful SHELL replacement. Have a look at @{" Features " Link Features} to see the advantages. ZShell is tested with Kickstart 1.3 , 2.04 and 3.0 and should run also with other Kickstarts. There are no special requirements. I tried to made usage similar to AmigaDOS. If you did not understand something, have a look at your AmigaDOS usermanual. @ENDNODE @NODE Features "Features" * @{" Freeware " Link Copyright}, no payment required. * Usage is similar (or better) to the standard AmigaDOS shell. * About 26K small (pure assembler code, source included). * Supports the standard housekeeping commands which are builtin, so no disk access is necessary. eg. list, dir, cd, rename, makedir, delete, copy, path, info, type * A total of 64 builtin commands. * @{" Starting " Link Starting} from Workbench or CLI/Shell. * @{" Filenamecompletion " Link Filenamecompletion} by simply pressing TAB. * @{" Review-buffer " Link Review} to see what scrolled out of the window. * @{" Command line editing " Link history} better than KS2.0 . * @{" Command line history " Link history} with searching. * Command and Function key @{" aliasing " Link alias}. * @{" Online Help " Link Help} function and AmigaGuide-Documentation with examples. * Colorful output (or fast scrolling with OS3.0+, see @{" CTRL -R " Link CTRL 37}) * @{" Wild Card " Link Wild_Card} file descriptions (*,?,~,[],|). * @{" DIR " Link DIR} and @{" LIST " Link LIST} both sort (by default) and show filesize. * Simple @{" MORE " Link MORE} type text viewer. * Has a kind of @{" Memory-Clock " Link MemClk} with alarm. * Makes itself @{" resident " Link resident} for quicker @{" starting " Link starting} and memory saving. * @{" Script file " Link Execute} execution and special script commands (like IF, ASK). * Some @{" commands " Link BUILTIN3} and features for debugging system/programs. @ENDNODE @NODE For_those "For those who never read the whole Documentation" @{" Start "link Starting} the file called ZShell from Workbench or CLI (SHELL), or even better: Put the file ZShell in the C: directory and start the file ZSH. Now press the HELP key. Among lots of other information you see "TYPE HELP ? ...". Make sure that ZShell.doc is in the @{" current directory " link CD} or in S: and try that. You will see how to use the @{" ONLINE HELP " Link HELP}. Try to type "HELP HISTORY" to see how @{" command line editing " link History} works. @{" Execute " link Execute} the example startup file "ZStart" or @{" put " link Copy} it into the S: drawer and @{" have a look " link More} at it. Please send @{" me " Link Authors 9} your comment; @{" my " Link Authors 9} Internet-Adress is: uj3w@ibm3090.rz.uni-karlsruhe.de (Martin Gierich). Things somewhere hidden in the documentation: * To avoid using an internal command or an alias, you can put a point before it, eg. ".assign libs: df0:libs add". * To complete a filename, type in a bit then press TAB. * If you use "ctrl -c *.info", DIR and Filenamecompletion ignores Icons. * To start buffering output, use "review 20000". Press Shift+TAB to see it. * If you have OS3.0+, try "ctrl -r 01111111". * If you start ZShell from the Workbench-Menu "Execute Command", you can close the window after ending ZShell with CTRL-\ . * You get a standard prompt with: prompt "%n.%p> " * Try to execute "ZShell ?". * See @{" Tips and Hints " link Tips} for more. @ENDNODE @NODE Distribution "Distribution" Following files belong to this document: 1) ZShell The main executable 2) ZSH The small starter 3) ZShell.doc The documentation (and online help manual) 4) ZShell.guide The AmigaGuide documentation 5) ReadMe Short description 6) ZStart An example startup script (can be put in S: ) 7) ZShell.s Source code of the main executable 8) ZSH.s Source code of the small starter and some icons. @ENDNODE @NODE General_Usage "General Usage" @{" Starting ZShell " Link Starting} @{" History and Command Line Editing " Link History} @{" Executing Commands " Link Executing} @{" Wild Cards " Link Wild_Card} @{" Filenamecompletion " Link Filenamecompletion} @{" Options " Link Option} @{" Redirect Input/Output " Link Redirect} @{" Special Characters " Link Special_Characters} @ENDNODE @NODE Starting "Starting ZShell" * There are three ways of starting ZShell: 1. The easiest way: Start the file called "ZShell" from Workbench or CLI/Shell. 2. Put the file called "ZShell" in the C: directory and start the file called "ZSH" from Workbench or CLI/Shell. 3. A bit complicated and only for starting from Workbench: Make a startup script (see below) or an empty file with a PROJECT icon. Change the default tool to "ZSH" or "ZShell" (better ZSH, but put ZShell in C: ) with the right path. Doubleclicking on this project icon will start ZShell and execute its script. You can also shift-doubleclick a startup script with ZSH/ZShell. (You can rename "ZSH" as what you like, but do not rename "ZShell"). The first way is recommended for having a quick glance at ZShell, but if you use ZShell sometimes, the second way is better. Why ? Because "ZSH" is about 800 Bytes long and starts the ZShell- resident if possible. So loading "ZShell" is only necessary the first time you use ZShell after booting up. * If starting from CLI/Shell you can specify the name of a script file (see @{" EXECUTE " Link EXECUTE}) as an argument which will be executed after starting. Precede the name with "-s". If there is no name given, ZShell will try to execute S:ZStart . After "-w" you can specify a window-description. See @{" NEWCLI " link NewCLI} for more details, it is exactly the same. eg. ZSH -sram:hello {will try to execute ram:hello} ZShell {will try to execute S:ZStart} ZSH -sram:hello "-wCON:10/10/90/90/Hi there" {opens this window} * If starting from Workbench you can specify the window-description and the startup script (default S:ZStart , see above) with ToolTypes: eg. WINDOW=con:20/50/400/100/Moin SCRIPT=ram:hello WINDOW= {this would not open a window} Make sure that WINDOW and SCRIPT are in capital letters. (You can edit the ToolTypes by selecting an icon and then choosing "Information" from the Workbench-Menu.) * NOTE1: If you start ZShell from the Workbench-Menu "Execute Command", you can close the window after ending ZShell with CTRL-\ . * NOTE2: ZShell and ZSH are PURE (see @{" RESIDENT " Link RESIDENT},@{" PROTECT " Link PROTECT}). @ENDNODE @NODE History "History and Command Line Editing" ZShell has a 1024 byte circular history buffer. It works similar to most other shells, the NEWCON: handler in Workbench V1.3 and the standard console handler in Kickstart 2.0+. You can change the edit keys with @{" CTRL " Link CTRL}. These are the default keys: UP ARROW - go back one line in the history buffer DOWN ARROW - go forward one line in the history buffer SHIFT UP ARROW - go to the 1st line in the history buffer if nothing was typed. Otherwise the string left of the cursor will be searched in history buffer (like KS2.0+) SHIFT DOWN ARROW- go to the last line in the history buffer, which should be blank LEFT ARROW - move cursor left RIGHT ARROW - move cursor right SHIFT LEFT ARROW- move cursor to left end SHIFT RIGHT ARROW move cursor to right end CTRL S - move cursor to start of line CTRL E - move cursor to end of line CTRL R - move cursor to start of previous word CTRL T - move cursor to start of next word CTRL W - delete one word right of cursor CTRL Q - delete one word left of cursor CTRL X - delete whole line CTRL L - clear the ZShell window RETURN - put commandline in history-buffer and execute it SHIFT RETURN - put commandline in history-buffer without executing TAB - see @{" FILENAMECOMPLETION " Link FILENAMECOMPLETION} (that is great !) SHIFT TAB - read @{" review-buffer " Link review} with @{" MORE " Link MORE} CTRL V - read history-buffer with @{" MORE " Link MORE} ESC (Escape) - quit ZShell like @{" ENDCLI " Link ENDCLI} (I like this very much !) Words are delimited by space, point, slash and colon ( ./:). Again, command line editing is similar to most shells. Backspace, delete and return do what they are supposed to do. @ENDNODE @NODE Executing "Executing Commands" Most commands can be aborted by depressing Control-C. Nearly everything is case independent. To use a disk command simply type its name after the prompt, the same way as you would do in other shells. The first part of the input up to the first space is interpreted as commandname. It is searched for (in this order) : 1. in the @{" alias " Link alias} list 2. in the internal (builtin) command list (see BUILTIN COMMANDS) 3. in the @{" resident " Link resident} command list 4. in the current directory (see @{" CD " Link CD}) 5. in the command search @{" path " Link path} and, if it is found, it is executed. The part after the first space is taken as arguments, also called parameters. The arguments are separated by spaces. ZShell will allow up to 25 arguments. If the commandname is a directory, the current directory will be changed (see @{" CD " Link CD}). eg. addbuffers df0: 15 "addbuffers" is the command, that will be found as a internal command. "df0:" is the first argument. "15" is the second argument. The third argument does not exist. You can avoid using an @{" alias " Link alias} or an internal (builtin) command or changing the current directory by typing a point before the commandname (this is called "force disk"). To abbreviate internal or @{" resident " Link resident} commands put a point behind it. If you use just a point, the current directory will be set to the last current directory ("dir back"). eg. .addbuffers df0: 20 {This uses the disk command or if available the resident addbuffers} ad. df0: 20 {uses the internal addbuffers command} .ad. df0: 20 {if available this uses the resident addbuffers} . {go back to old current dir} BEWARE of other matching commands! The first matching will be taken! res. can mean reset or resident, but reset will be taken ! There is no abbreviation for disk commands, take @{" FileNameCompletion " Link FileNameCompletion} ( TAB-Key ) instead. A textual error message will be displayed if an AmigaDOS error occurs. @ENDNODE @NODE Wild_Card "Wild Cards" ZShell supports wild card file descriptions on some commands (@{" DIR " Link DIR},@{" LIST " Link LIST},@{" DELETE " Link DELETE},@{" COPY " Link COPY},@{" RECOPY " Link RECOPY},@{" CTRL " Link CTRL}). Wild cards are like those supported on MS-DOS (tm) or UNIX (tm) systems, and not the same as the ones on AmigaDOS. So use * instead of #? . NOTE: You can only effectively put one * character in a wild card. Character Meaning * Match zero or more characters. ? Match one character. ~ Negates the following wildcard. [ ] Specifies a class of characters to match. (One of the characters in the brackets must match) | Separate multiple filenames (can be wildcards) (One of the file descriptions separated by | must match) To get that just try the examples following and try it out with @{" DIR " Link DIR}. eg. list *.info {lists all files ending in .info} dir z*.s {lists all files starting z, ending in .s} delete df0:*.info {deletes all .info files from df0:} copy *.s ram: {copies all .s files to ram:} copy 1? df0: {copies all two char files beginning with 1} dir ~*.s {lists all files NOT ending in .s} list ~*.info {lists all files except for .info files} dir *.[co] {lists files ending in .c or .o} list [abcd]* {lists files beginning with a,b,c or d} list c:mount|version {lists the files Mount and Version} list ram:env/a*|*b {lists all files starting with a or ending with b from RAM:env (environment)} copy ~*.info|*.bak {copies all files NOT ending in .info and NOT ending in .bak} @ENDNODE @NODE Filenamecompletion "Filenamecompletion" Filenamecompletion makes typing long filenames and directorynames easier. It does not matter if you want to type it as command or as argument. Just type some beginning characters of the desired name and then press TAB . If there is more than one possibility that match, it will only be completed as far as all possibilities match. In this case type the next character then again press TAB . If a filename was fully matched, a space after it will be inserted. If a directoryname was fully matched, a slash (/) will be inserted after. If no partial match is found, the screen blinks (display beep). Maybe you do not want *.info files to be completed. This will avoid some trouble. Use "ctrl -c *.info" for that or see @{" CTRL " Link CTRL}. For example a directory contains: MegaEditExample MegaEditExample.info MegaViewer MoreMegaFiles {directory} If you want to change the current directory to MoreMegaFiles you type: mo then press the TAB key. You will see the full name with a slash at the end. Just press RETURN and you changed it. To delete MegaViewer you type: delete me and press TAB . You will see "Mega". Now type the V key and press TAB again. You see "delete MegaViewer ". Press RETURN and it will be gone. You want to start MegaEditExample. Type: me and press TAB. Then type E and press TAB. There is no space after the name. This is because MegaEditExample.info also matches. Start it by pressing RETURN. @ENDNODE @NODE Option "Options" The internal commands support only three options, because this is easier to remember. These options start with a dash (-) . 1. -C or -CLEAR , used by @{" AVAIL " Link AVAIL},@{" ENDCLI " Link ENDCLI},@{" LOCATE " Link LOCATE},@{" PATH " Link PATH}, @{" RESIDENT " Link RESIDENT},@{" RUN " Link RUN},@{" CTRL " Link CTRL} 2. -R or -RECURSIVE , used by @{" COPY " Link COPY},@{" DELETE " Link DELETE},@{" DIR " Link DIR},@{" LIST " Link LIST},@{" RECOPY " Link RECOPY} 3. -Q or -QUICK , used by @{" DIR " Link DIR},@{" LIST " Link LIST} So instead of typing "dir -q" you can also type "dir -quick". As nearly everything, options are also case independent. @ENDNODE @NODE Redirect "Redirect Input/Output" The standard redirection operators are supported for all internal commands, as well as disk based programs. (Redirection only affects those programs which use the dos.library's Input() and Output() functions.) > redirect std output. < redirect std input. >> append redirect output. (tacks output onto the end of file) <> redirect input and output (not yet implemented). eg. dir >ram:directory df0:c type zshell.doc raw:0/0/640/100/output sortfile things >>df0:things.log @ENDNODE @NODE Special_Characters "Special Characters" The following characters have special meanings to ZShell. " " Double quotes. Used to enclose strings with spaces. eg "hello world". ^n Hat character. Prefixes a control character letter (n). Used in @{" ASK " Link ASK},@{" ECHO " Link ECHO}&@{" ALIAS " Link ALIAS} commands. eg ^L <-clear screen %n Percent prefixes a number (0-7) to specify an optional parameter for command aliases. Used in @{" ALIAS " Link ALIAS} command. Can also be used to specify prompt arguments. See @{" PROMPT " Link PROMPT}. $n Dollar prefixes a number (0-7) and corresponds to an optional parameter specified with %n (above). *?~[]| @{" Wild card " Link Wild_card} characters. * matches 0 to n characters. ? matches one character, ~ negates the following wild card, and [ ] surround a class of characters to match. \n Backslash prefixes a special character, whose meaning you want ignored. eg. echo "hello \"fred\"" (hello "fred") ; Semi-colon seperates multiple commands on one line. eg. cd df1:;dir > @{" redirect " Link redirect} output. < @{" redirect " Link redirect} input. >> @{" redirect " Link redirect} append output. @ENDNODE @NODE BUILTIN1 "Builtin Commands for Disk Management" Following there are descriptions of the standard DOS commands which are builtin in ZShell (and therefore need not be loaded from disk). Square brackets [] mean that the argument enclosed in is optional. A vertical bar | separates multiple possibilities, choose only one. @{" AddBuffers " Link AddBuffers} drive number_of_buffers @{" Assign " Link Assign} [logical name:] [directory] @{" Cd " Link Cd} [destination] @{" Copy " Link Copy} [-R] sourcefile1 [sourcefile2] ... destination @{" Delete " Link Delete} [-R] source1 [source2] [source3] [source4] ... @{" Dir " Link Dir} [-Q] [source] @{" FileNote " Link FileNote} file|directory comment @{" HType " Link HType} source @{" Info " Link Info} @{" Join " Link Join} [sourcefile1] [sourcefile2] ... destfile @{" List " Link List} [-R] [-Q] [source] @{" Lock " Link Lock} device ON|OFF @{" MakeDir " Link MakeDir} [directory1] [directory2] ... @{" More " Link More} source [line count] @{" Protect " Link Protect} [filename] [h|s|p|a|r|w|e|d] @{" Relabel " Link Relabel} drive newname @{" Rename " Link Rename} source destination @{" Resident " Link Resident} [command1] [command2] ... @{" Search " Link Search} file search_string @{" SetDate " Link SetDate} file|directory [date/time] @{" Type " Link Type} source @ENDNODE @NODE AddBuffers "AddBuffers" ADDBUFFERS drive number_of_buffers * ADDBUFFERS increases disk access speed on the specified drive by adding a number of sector cache buffers. Each additional buffer reduces memory by about 560 bytes. Generally, 25-30 buffers per floppy drive is optimal. eg. addbuffers df0: 25 addbuffers df1: 30 @ENDNODE @NODE Assign "Assign" ASSIGN [logical name:] [directory] * ASSIGN will assign a logical device name (must end in a colon (:) ) to a disk directory. eg. assign z: df1:zshell_source Now if you do a DIR Z: you will get a directory of df1:zshell_source. Similarly, the default device names can be reassigned. eg. assign libs: df1:libs * Typing ASSIGN with no parameters, will list the current device assignments. eg. assign ASSIGN is compatible with the AmigaDOS Assign command. @ENDNODE @NODE Cd "Cd" CD [destination] * Changes the current directory to "destination". If no parameter is given, the current directory's name is shown. It is easier to change the directory by simply typing its name (without CD). eg. cd ram: ram:t {same as "cd ram:t"} @ENDNODE @NODE Copy "Copy" COPY [-R] sourcefile1 [sourcefile2] ... destination * There are 6 derivatives of the copy command : 1. copy file to file. eg. COPY C:LIST RAM:LS 2. copy file to a directory. eg. COPY C:MOUNT DF1:C 3. copy multiple files to a directory. eg. COPY L:PORT-HANDLER L:DISK-VALIDATOR DF1:L 4. copy files in a directory to another directory. eg. COPY C: DF2:C 5. copy multiple directories to a single directory. eg. COPY L: DEVS: C: RAM: 6. Recursively copy all files and subdirectories within the source directory to the destination directory. eg. COPY -R DF0: DF1: Other examples: copy fred wilma copy c:dir df1:c copy dir list type cd df1:c copy -r df0:devs df1:devs copy -r source:*.s ram: copy df0: df1: {only copy the files in df0: to df1:} @ENDNODE @NODE Delete "Delete" DELETE [-R] source1 [source2] [source3] [source4] ... * Deletes one or more files or directorys ("source1","source2",...). * If you specify the -r @{" option " Link option} when deleting a directory, then all subdirectories are recursively deleted also. Otherwise (if the -r option is not given) only the files in the specified directory are deleted. WARNING: You can hardly get back what you have deleted ! So be careful, especially when using the -r option ! (Try DISKSALV for getting lost files back, DO NOT USE DISCDOCTOR!) eg. delete fred wilma barney betty dino delete df0:devs df1:c df1:data ram: delete menu delete -r devs: delete -r df1: {better use "format drive df1: name x quick"} @ENDNODE @NODE Dir "Dir" DIR [-Q] [-R] [source] * Lists the directory of the "source" to the screen. Hitting space will pause the listing and backspace will continue it. Files are shown with their size in bytes. DIR lists the current directory if no parameter is given. If "source" is a filename, then only that file is listed. If the @{" option " Link option} "-q" is not given, the filenames will be sorted alphabetically. With the @{" option " Link option} "-R" given it will @{" list " Link List} recursive. * All files/dirs with the H-bit (see @{" PROTECT " Link PROTECT}) set, will not be shown. All files that are ignored by @{" FILENAMECOMPLETION " Link FILENAMECOMPLETION} are also hidden. eg. dir df0: dir -q devs:printers/hp* @ENDNODE @NODE FileNote "FileNote" FILENOTE file|directory comment * FILENOTE creates or changes a comment of the file or directory. This comment can be up to 116 characters long and can be displayed using the @{" LIST " Link LIST} command. It is useful if the filename does not say what for this file is. Add a comment to this file and you will forever know what this file does. eg. filenote devs:mountlist "This is used by the mount command" @ENDNODE @NODE HType "HType" HTYPE source * HTYPE outputs a hex listing of the file specified. Output is the same as the M command. SPACE pauses the listing, BACKSPACE gets it going again, and CTRL-C will abort the listing. eg. htype c:list @ENDNODE @NODE Info "Info" * Lists lots of information about all available volumes (like disks). These columns mean: NAME: Name of the device containing the volume UNIT: Unitnumber, not very interesting SYS: Filesystem, can be one of: OFS : Oldfilesystem (old fashioned and slow) FFS : Fastfilesystem (needs at least Kick 2.0) INO/INF : International OFS/FFS DCO/DCF : Directory Cache OFS/FFS (needs Kick 3.0) MSD : CrossDOS Filesystem (MessyDOS) ??? : Unknown SIZE: Maximum useable size of the Volume in KBytes (1024 Bytes) FREE: Free/useable size in KBytes FULL: Ratio between used size and maximum size BLOCK: Size of a single block in Bytes STATUS: Says if it is possible to write to that volume ERR: Number of soft errors, I only saw 0 yet VOLUME: Name of the volume (name of the disk). * Note: It would not make sense to show the free size in Bytes, because space can only be allocated in whole blocks and one block is at least 488 Bytes large. eg. info @ENDNODE @NODE Join "Join" JOIN [sourcefile1] [sourcefile2] ... destfile * JOIN concatenates one or more files to form a new file (destfile). eg. join fred.doc roy.doc dog.doc mydocs.doc @ENDNODE @NODE List "List" LIST [-R] [-Q] [source] * Lists the directory of the "source" to the screen. Hitting space will pause the listing and backspace will continue it. * LIST acts similar to @{" DIR " Link DIR}, but outputs more information: - Hidden files will be shown - Shows the date and time of the last change (date-of-last-change) - Shows the protection-bits (see @{" PROTECT " Link PROTECT}) - If available, the comment will be shown (see @{" FILENOTE " Link FILENOTE}) * LIST supports recursive listing. That means the contents of all subdirectories are shown. To use it, specify the -r @{" option " Link option}. eg. list list sys:system list -q df0: list -r -q *.info {show all INFO-files in the current and in the sub-directories} list -r ram:~*.info {show all except *.info files in RAM:} @ENDNODE @NODE Lock "Lock" LOCK device ON|OFF * "LOCK device ON" locks the write-access to a device eg. lock df0: on will make it impossible to write to or change something on the disk inserted in DF0: * "LOCK device OFF" makes write-access to a device possible again. eg. lock dh0: on lock dh0: off @ENDNODE @NODE MakeDir "MakeDir" MAKEDIR [directory1] [directory2] ... * Creates one or more directories of the names specified. eg. makedir temp makedir c l s libs devs fonts makedir devs/printers ram:c @ENDNODE @NODE More "More" MORE source [line count] * MORE acts as a simple (ANSI) text file viewer. By default, it will show 19 lines of a text file, then wait for some user input. To move around in the text, you can use the CURSOR-KEYS: UP : Go one line up DOWN : Go one line down LEFT : Go one page (default 19 lines) up RIGHT : Go one page down SHIFT-UP : Go to the top of the text SHIFT-DOWN: Go to the bottom of the text The key "P" creates a printout of the text (sends the text to PRT:) The key "S" will prompt you what to search for. If you just press RETURN, then the last item will be searched for. Searching begins at the second top line shown. If the item is found, the line, it is in, is displayed as the first line. Typing any other key will abort you back to the shell. eg. more readme * Specifying the optional line count will allow you to show more or less than the default 19 lines. {Very useful for large borderless PAL screens or small windows} eg. more contents 12 more super.doc 25 @ENDNODE @NODE Protect "Protect" PROTECT [filename] [h|s|p|a|r|w|e|d] * Allows you to alter/see the protection bits associated with a file or a directory (default: current directory). * PROTECT filename Shows the protection bits for the file specified. eg. protect editor * PROTECT filename [h|s|p|a|r|w|e|d] Toggles the specified protection bits on the file. eg. protect editor pd If "editor" was already pure, then the pure bit would be reset. If "editor" was not pure, then the pure bit would be set. If "editor" was deletable, then the delete bit would be reset. If "editor" was not deletable, then the delete bit would be set. eg. protect game hprwd eg. protect monitor hsparwed Bits: "h" hidden V1.3 "s" script V1.3 "p" pure V1.3 "a" archive V1.3 "r" readable "w" writable "e" executable "d" deletable <- V1.2 only understands this bit @ENDNODE @NODE Relabel "Relabel" RELABEL drive newname * RELABEL renames the disk specified with the newname given. eg. relabel Empty: MY_DISK relabel df0: FISHMONGER @ENDNODE @NODE Rename "Rename" RENAME source destination * Renames the file or directory of name "source" to that of "destination". You can use this to move files on a disk. eg. rename df0:c/list df0:ls {moves and renames} rename ed Editor {just renames} @ENDNODE @NODE Resident "Resident" RESIDENT [command1] [command2] ... * RESIDENT allows you load commands into memory, such that they will execute immediately, rather than be loaded from disk all the time. The benefit of RESIDENT over saving commands on the RAM: disk is that only one copy of the command is in memory all the time. RAM: based commands will use up twice as much memory when the command is being executed. * The limitation of RESIDENT is that only certain commands will work. Generally, all commands which have their PURE bit (see @{" PROTECT " Link PROTECT}) set can be made RESIDENTABLE. However, RESIDENT does not check whether the PURE bit is set before loading, and hence you can try out commands to see if they work. They'll always work the first time. Its only when executing the 2nd time that the Amiga will likely crash. Note: Crunched programs will most likely not work. * Typing RESIDENT with no parameters will show the current list of resident commands: ADRESS is useful for programmers USECOUNT says how many times it is used right now ROM internal residents have negative values NAME means the name (hard to guess :) * Typing one or more command names after RESIDENT will make those commands resident. ZShell will search the command search @{" path " Link path} to try and find them. eg. resident c/list c/cd c/date c/avail resident ed RESIDENT is compatible with the AmigaDOS Resident command. @ENDNODE @NODE Search "Search" SEARCH file search_string * SEARCH searches for the search_string in the file. The file can be a binary (eg. executable) or a text. Each occurance will be printed on the window with highlighted search_string. If the file is a text, the whole line will be printed. If it is a binary file, it will be printed from the occurance to the next NULL or LF. * Searching is case independent (of course!). * To search for a string at the beginning of a line (textfile only) put a point (.) before the search_string. eg. search zshell.doc "binary (eg." search s:startup-sequence .assign {show all assigns, but not "resident assign"} search c:mount $ver: {show version number and date, should work with all newer executables} @ENDNODE @NODE SetDate "SetDate" SETDATE file|directory [date/time] * SETDATE changes the date-of-last-change (DOLC) of a file or directory. The DOLC can be shown by simply listing this file with @{" LIST " Link LIST}. * SETDATE with no date/time given sets the DOLC to the systemtime (see @{" DATE " Link DATE},@{" SETCLOCK " Link SETCLOCK}). * If you want to set the DOLC to a special date you have to specify the date or time or both in a format described at @{" DATE " Link DATE}. eg. setdate ram:newthings setdate devs:mountlist 21.8.71 {very old} setdate murks 18:24:12 12-24-96 {future} @ENDNODE @NODE Type "Type" TYPE source * Prints to the screen the ASCII/ANSI text file specified as "source". Hitting any key will pause the listing. Backspace will restart it. CTRL-C will abort the listing. * Use @{" MORE " Link MORE} instead of TYPE, if possible. eg. type readme @ENDNODE @NODE BUILTIN2 "Builtin Commands for Scripts and Controlling" Following there are descriptions of the other commands which are builtin in ZShell (and therefore need not be loaded from disk). Square brackets [] mean that the argument enclosed in is optional. A vertical bar | separates multiple possibilities, choose only one. @{" Alias " Link Alias} [variable] [definition] @{" Ask " Link Ask} [question] @{" Avail " Link Avail} [-C] @{" Border " Link Border} ON|OFF [number] @{" Cls " Link Cls} @{" Date " Link Date} [hh:mm:ss|dd.mm.yy|mm-dd-yy] @{" Echo " Link Echo} [string] @{" Else " Link Else} @{" EndCLI " Link EndCLI} [-C] @{" EndIf " Link EndIf} @{" Eval " Link Eval} expression @{" Execute " Link Execute} source @{" FailAt " Link FailAt} [failat_level] @{" Fault " Link Fault} [error_number] @{" Help " Link Help} [topic] @{" If " Link If} [NOT][WARN][ERROR][FAIL][EXISTS file] @{" Lab " Link Lab} label @{" MemClk " Link MemClk} ON|OFF|ALARM @{" NewCLI " Link NewCLI} [-Wnew_window] [-Sstart_script] [-Ccommand] @{" Path " Link Path} [-C] [path1] [path2] [path3] [path4] ... @{" Prompt " Link Prompt} [string] @{" Quit " Link Quit} [error_code] @{" Review " Link Review} [bytesize] @{" Run " Link Run} [-C] commandline @{" SetClock " Link SetClock} LOAD|SAVE @{" Skip " Link Skip} label @{" Stack " Link Stack} [size] @{" UnAlias " Link UnAlias} [alias1] [alias2] [alias3] [alias4] ... @{" Wait " Link Wait} timeout @{" Comments " Link Comments} @ENDNODE @NODE Alias "Alias" ALIAS [variable] [definition] * ALIAS assigns a variable name to a definition. The variable name can be up to 15 characters long, and the definition can be up to about 360 (250) characters long. * Function Keys eg. alias f1 "ed df0:s/startup-sequence^M" This example assigns the unshifted F1 key to the text enclosed in quotes. Note that the ^M characters puts an auto carriage return in the definition. eg. alias F10 "cd df0:^M" This sets shifted F10 to "cd df0:". Other egs. alias f2 "cd df1:^M" alias f4 "genim2 " alias F9 "scribble df0:text/" alias f1 "a68k z.a;blink z.o to z^M" * The secondary use of ALIAS is to assign command aliases. eg. alias mv rename This allows an alternate name for rename. i.e. mv. So you could type mv oldname newname {to rename oldname to newname} eg. alias as a68k alias pp powerpacker alias go "a68k zsh.s;blink zsh.o to zsh" alias cped "copy df0:c/ed" You would use this last alias, if you need to copy a particular file a lot. So, to copy c/ed to ram: use:- cped ram: * You can also pass external parameters to an alias. eg. alias al "%1 a68k $1.s;blink $1.o to $1" Typing al test will assemble test.s using a68k, then blink test.o to become test. You can specify upto eight parameters to pass to a command alias. At the start of the alias definition, specify the parameters to pass with the variables %0 thru %7. These need not be in sequence. The first %n will be assigned to the first parameter, the 2nd %n to the 2nd parameter etc. Insert the corresponding variables $0 thru $7 at the points in the alias definition where that parameter is to appear. eg. alias disp "%1 %2 %3 echo \"$3 $2 $1\"" alias cram "%0 %1 %2 %3 copy $0 $1 $2 $3 ram:" alias go "%5 %1 %6 %2 echo \"1st-$5 2nd-$1 3rd-$6 4th-$2\"" * Command aliases can be nested to 1 level. eg. alias clear "echo ^L";alias cdir "%1 clear;cd $1;dir" * An important point about aliases, is that you can redefine the existing internal command names. eg. alias help "type help_screen" This would make it so that pressing HELP or typing H E L P would not generate the standard help command list, but would type the file called help_screen to the screen. Similarly eg. alias copy c:copy {replace copy by disk-based copy} alias info c:dfree alias assign .assign {replace assign by disk-based assign} * Typing ALIAS with no parameters at all, will generate a list of all current alias definitions. eg. alias * See UNALIAS for how to remove alias definitions. @ENDNODE @NODE Ask "Ask" ASK [question] * ASK prompts the user with a question requiring a Yes or No answer. If the first letter of the users response is "Y", ASK returns code WARN. Responding "E" returns ERROR, "F" returns FAIL. Any other letter will result in return code OK. The question can include ASCII characters as well as control codes as per the @{" ECHO " Link ECHO} command. eg. ask "Do you want commands copied to ram? " if warn copy c: ram: endif Note: You can @{" redirect " Link redirect} the ANSWER to a file by redirecting the OUTPUT. eg. ask >ENV:CallIt {The answer is written to CallIt} @ENDNODE @NODE Avail "Avail" AVAIL [-C] * AVAIL shows the available memory as: 1.Total chip memory free, 2.Total fast memory free, 3.Total memory free. * With @{" option " Link option} "-c" given, it tries to free unused memory (remove unused libraries, devices and the help manual) eg. avail avail -c @ENDNODE @NODE Border "Border" BORDER ON|OFF [number] * Switches the border of the window on or off. If the border is off there will fit some more characters in a line; this can be useful when viewing texts with @{" MORE " Link MORE}. * If you run Kickstart 1.3, you should do a @{" CLS " Link CLS} or "echo ^L" after using BORDER OFF. * If you specify a number after ON or OFF, the window is resized as large as possible. The number means the wanted distance of the window top to the screen top in pixels. By specifying a negative value the window will just not hide the screens menu bar. eg. border off border on 0 {fills full screen} border off -1 {does not hide the menu bar} border on 10;cls {with KS 1.3} @ENDNODE @NODE Cls "Cls" * CLS clears the window. It also resets the consolehandler, so if you see lots of funny characters on the window, try CLS. * You can do the same by using "echo ^[c". * CTRL L only clears the window (same as "echo ^L"). eg. cls @ENDNODE @NODE Date "Date" DATE [hh:mm:ss|dd.mm.yy|mm-dd-yy] * DATE without arguments shows the actual date and time (systemtime). * You can specify one or two arguments to set date or time or both. The time format must be in HOUR:MINUTE:SECOND . Do not forget the colon (:) between. Give only one or two digit numbers. There exists two formats for setting the date. First is DAY.MONTH.YEAR . Second is MONTH-DAY-YEAR . Use only one or two digit numbers. eg. date date 14:15:00 {quarter past two PM} date 12.5.94 {12th of May in 1994} date 3-30-88 8:12:45 {30th of March in 1988 in the morning} @ENDNODE @NODE Echo "Echo" ECHO [string] * Prints the "string" to the screen. If you want spaces in the string, make sure the whole string is enclosed in quotes. If you want to print special control characters (eg. ctrl-L clear screen) then prefix the control letter with a ^ character. If you want to print double quotes, then use the \ character before the qoutes. If you want to print some special characters like the CSI ($9B), you can put a (hexa-)decimal number after the ^ character; you can separate it from the next character by a point (.) . Do not forget the ^J at the end of a line. eg. echo hello^J echo "Hello world !" echo Hello world ! echo "^Lthe screen was just cleared^J" echo "^Lline 1^Jline 2^Jline 3^J" echo "these are double quotes ->\"^J" echo ^$9b.33mColor^$9b.32mful^J echo ^$9b.4mUnderlined^$9b.0mNormal^J * Some common control codes are: ^7 ^G bell (makes a DisplayBeep) ^10 ^J linefeed. ^12 ^L clear screen. ^13 ^M carriage return. ^24 ^X clear line. ^27 ^[ escape. ^$9b CSI (command sequence introducer). @ENDNODE @NODE Else "Else" * ELSE marks the middle of an @{" IF " Link IF} statement. All statements following it, and before the @{" ENDIF " Link ENDIF} statement will be executed only if the IF condition is FALSE. See @{" IF " Link IF} for usage. @ENDNODE @NODE EndCLI "EndCLI" ENDCLI [-C] * Exits you from ZShell back to the AmigaDOS CLI prompt or Workbench. * If the @{" option " Link option} "-c" was specified, it will clear ZShell as a @{" resident " Link resident}: only in low memory situations needed. * Instead of using ENDCLI you can simply press the ESC key or click on the close gadget, if available. eg. endcli endcli -c @ENDNODE @NODE EndIf "EndIf" ENDIF * ENDIF marks the end of an IF statement. See @{" IF " Link IF} for usage. @ENDNODE @NODE Eval "Eval" EVAL expression * EVAL evaluates the "expression" as a reverse polish expression, and displays the answer in decimal and hex notation. Reverse Polish Notation (RPN) is used in Forth and in Hewlett Packard calculators (the best calculators in the world). It is based on how arithmetic is actually done at the lowest possible level. RPN allows calculating complex expressions without using brackets. eg. eval 4 5 + This gives the answer 9. When a number is found, it is "pushed" onto the arithmetic stack. The + always adds the last two numbers on the stack. eg. eval 7 2 3 + - This gives the answer 2. It is the same as (7 - (2 + 3)). See, 7 is first pushed onto the stack, followed by 2, then 3. The + adds together the 2 and 3 and leaves the result 5 on the stack. Which means that the number 7 followed by 5 are left on the stack. The - subtracts the last entry (5) on the stack from the one before it (7), leaving the result 2. eg. 12 * (3 + 9) > eval 12 3 9 + * (15 - 4) * (6 + 18) > eval 15 4 - 6 18 + * (6 * ((87 + 13) / (2 * 25))) > eval 6 87 13 + 2 25 * / * * EVAL only performs 32 bit integer arithmetic. Negative numbers are prefixed with - .(hexadecimal they are shown as a 31 bit integer with bit 32 set, as usual) Prefixing positive numbers with + is optional. eg. eval +5 -3 + {results in 2 hex:$00000002} eval -5 3 + {results in -2 hex:$fffffffe} * EVAL supports decimal, hexadecimal and binary numbers. If you prefix the number with $, the number is hex If you prefix the number with %, it is binary. Programmers: For BPTR-APTR conversion you can use & to specify a hexadecimal APTR when asked for a BPTR and vice versa with eg. eval $c00000 $a0 16 * + * EVAL can also be used to perform base conversions (to dec or hex) eg. eval $ca eval %10110001 eval 45 eval &5a8 * The operators + - * / & | @ ! are supported. The & allows logical AND'ing. And | allows logical OR'ing. The @ is similar to PEEK in BASIC. Conversely, ! is similar to POKE in BASIC eg. eval $80 $21 $08 | | $aa & eval $67 %11001011 & eval $c00000 @ This prints out the long word in memory locations $c00000 - $c00003. eval $aa55aa55aa $40000 ! This pokes the long word $aa55aa55aa into locations $40000 thru $40003. * For environment handling you can specify the value of an environment variable with | followed by the name. To store the result in a variable, @{" redirect " Link redirect} the output. eg. eval >ENV:aa |ENV:bb 1 + This adds 1 to the value in ENV:bb and stores the result in ENV:aa * If the result was 0 an error (fail-level 10) will be returned. If it was negative, a warn (5) returns. (Not when redirecting output) @ENDNODE @NODE Execute "Execute" EXECUTE source * Executes the ZShell script file of name "source". All ZShell commands, as well as commands from disk are valid within a script file. * If the S-protection-bit (see @{" PROTECT " Link PROTECT}) of "source" is set, you do not need to type EXECUTE, just use "source" like a command. * You can break scripts by pressing CTRL-D. eg. execute install_hard_disk @ENDNODE @NODE FailAt "FailAt" FAILAT [failat_level] * FAILAT sets the error code level at which scripts (and multiple commands on one line) will be aborted. The default level is 10. Most commands return 10 as an error, (20 for serious errors) while compilers returning Warning type errors will return 5. Hence, the default of 10 will allow Warnings to occur without the script (or line) being aborted. If a command returned an error code higher than the failat level, it will be printed out on the window. eg. failat 20 {sets failat level to 20} * If you do not specify a failat level, the current setting is shown. eg. failat @ENDNODE @NODE Fault "Fault" FAULT [error_number] * FAULT displays a textual error message of the given DOS-error-number eg. fault 103 {says something like "no free store", go and buy some extra memory :-) @ENDNODE @NODE Help "Help" HELP [topic] * HELP shows the lines of this manual corresponding to the topic. To see all topics available, type "HELP CONTENTS" . Make sure that the manual "ZShell.doc" is in your command search @{" path " Link path}! For some help about a command you can also type "commandname ?" . Type only "?" to read the manual with @{" MORE " Link MORE}. Note: Instead of typing the topic you can only type some starting characters. Note: The manual is only loaded once and will stay in memory till you use @{" AVAIL -C " Link Avail} or @{" ENDCLI -C " Link EndCLI} eg. help contents {"help cont" will do the same} help copy makedir ? ? * HELP without a topic lists the names of all available ZShell commands to the screen. This does not need the manual. HELP can also be invoked by hitting the HELP key. eg. help @ENDNODE @NODE If "If" IF [NOT][WARN][ERROR][FAIL][EXISTS file] * The IF command allows conditional execution of statements following it. * If the condition specified is true, then execution continues after the IF statement until either an @{" ENDIF " Link ENDIF} or @{" ELSE " Link ELSE} statement is encountered. If it is an ELSE statement, then all statements between the ELSE and the closing ENDIF are skipped. * If the condition is false, then all statements after the IF and before either an @{" ENDIF " Link ENDIF} or @{" ELSE " Link ELSE} statement are skipped. If an ELSE is encountered, then execution continues for all statements after the ELSE and before the closing ENDIF. * IF can examine the state of the return code from the last command execute with WARN, ERROR, and FAIL tests. You can test for the non existence of such a state by including the optional NOT parameter. eg. IF WARN echo "last command returned warnings" ELSE echo "last command did not return warnings" ENDIF IF NOT FAIL echo "last command did not fail" ENDIF * IF can also test for the existence of a file or directory. eg. IF EXISTS :system/format echo "this disk has a format command" echo "you can look yourself. I'm not joking" ENDIF IF NOT EXISTS ram:ed copy c:ed ram: ENDIF @ENDNODE @NODE Lab "Lab" LAB label * LAB specifies a destination (label) for the @{" SKIP " Link SKIP} command. @ENDNODE @NODE MemClk "MemClk" MEMCLK ON|OFF|ALARM * MEMCLK is for using a clock shown in the border of the actual window. The current total free and chip free memory are also shown. It can do a DisplayBeep (short flash on all screens) at a specified time. The DisplayBeep can be converted into a sound by using a PD-utility for that or using Workbench 2.1+ . * Programmers: There will be only one "MemClock"-Task, even if you run MEMCLK on many windows -> memory and CPU saving. * MEMCLK ON switches the clock on or does nothing if it already exist. * MEMCLK OFF switches the clock off or does nothing if it does not exist. * MEMCLK ALARM shows the alarm time. If you type a time (see @{" DATE " Link DATE}) after ALARM, you set the alarm time. (You cannot set an alarm date or multiple times.) ( MEMCLK A is the same as MEMCLK ALARM ) eg. memclk on memclk off memclk alarm memclk a 21:34:07 * The clock can also be used on non-ZShell windows, but MAKE SURE that the clock is switched OFF BEFORE the window is CLOSED, otherwise you will see THE GURU (or an ALERT with KS2.0+) For example, to get a clock on the Workbench, type in ZShell wait 5;memclk on and press RETURN. Now you have 5 seconds to click on the Workbench screen. For removing use "wait 5;memclk off" . @ENDNODE @NODE NewCLI "NewCLI" NEWCLI [-Wnew_window] [-Sstart_script] [-Ccommand] * NEWCLI without arguments starts a new ZShell process. Things like paths, aliases and history buffer (!) will be copied to the new ZShell. The input/output window is created with the default specification. The startup script will be S:ZStart. * "NEWCLI -Wnew_window" is used for opening a window with different specifications than the default. If you specify just "-W", there will be no window and output will be send to NIL: ; if there is input necessary, the ZShell process will just end (for example at a end of a script). * "NEWCLI -Sstart_script" is used if the name of the startup script should be different from S:ZStart. If you specify just "-S", no script will executed. * "NEWCLI -Ccommand" @{" executes " Link Executing} the command when starting. No script will be executed. eg. newcli newcli -wcon:30/30/400/50/Shell newcli -wcon:50/20/500/100/Hello -ss:shell-startup newcli -sram:doassigns -w newcli "-wcon:30/30/400/50/Great Shell" "-cecho Welcome !" @ENDNODE @NODE Path "Path" PATH [-C] [path1] [path2] [path3] [path4] ... * PATH defines the command search path used by ZShell when searching for disk based commands (see @{" EXECUTING " Link EXECUTING} COMMANDS) . If you give the "-c" @{" option " Link option}, the old search path will be cleared and the new search path consist only of the given paths. eg. path -c c: ram:c df0: df1: This example will make it so that if you type a command which is not internal in ZShell, the @{" resident " Link resident} list will be searched for it, then the current directory, then the c: directory, then the ram:c directory, then df0:, and finally df1: * By omitting the -c @{" option " Link option}, you can add a number of paths onto the existing command search path. eg. path df2:c Adds the directory df2:c onto the existing command search path. eg. path df1:bin df1:myprogs Adds the two directories df1:bin and df1:myprogs onto the existing command search path. * If, however, you type path with no parameters, the current search path will be displayed. PATH is not yet compatible to the AmigaDOS Path command. Sorry. @ENDNODE @NODE Prompt "Prompt" PROMPT [string] * If no parameter is typed, the current prompt setting will be shown. eg. prompt * If a prompt string is specified, the current prompt setting will be changed to that string. The character "%" specifies a special prompt option: %p Insert whole path of current directory. %s Insert last part of the path of current directory. %n Insert CLI number %l Insert current input line number (for fun!) %c Insert last command (for even more fun ! :-) eg. prompt "%s> " {default prompt. Show current directory + ">"} prompt "%n.%p> " {show CLI number, then current dir, then ">"} prompt "Hello ." {shows "Hello ." at the start of every line} @ENDNODE @NODE Quit "Quit" QUIT [error_code] * QUIT forces a script file to end, and return to the shell. An optional error code can be passed back (ie. 5=WARN 10=ERROR 15=BAD 20=FAIL etc). eg. quit 5 quit @ENDNODE @NODE Review "Review" REVIEW [bytesize] With the reviewbuffer you can see that again what scrolled out of the window or was @{" redirected " Link redirect}. In the reviewbuffer are all outputs stored. To see what is in the reviewbuffer just press SHIFT TAB. This activates the @{" MORE " Link MORE} text reader. * "REVIEW bytesize" (re)creates a reviewbuffer with the given size. Can also be used to clear the buffer. * "REVIEW 0" removes the reviewbuffer. * "REVIEW" without arguments shows the adress and size of the current reviewbuffer. * "REVIEW S filename" saves the reviewbuffer to that file. eg. review 10000 {starts normal reviewbuffer} review 50000 {starts big reviewbuffer} review 0 {deletes reviewbuffer} NOTE 1: Because it uses a circular buffer with fixed size, this is much faster than having a fixed number of lines. The decrease in scrolling speed is neglible. NOTE 2: The Write function of the dos.library will be patched, so there might be problems with other programms that patch this too. @ENDNODE @NODE Run "Run" RUN [-C] commandline * RUN @{" executes " Link Executing} a commandline in a separate process. If you want to execute several commands, you can separate them with \; . * If you do not need a window, you can specify the "-C" @{" option " Link option}. eg. run dir ram: run -c assign libs: df0:libs @ENDNODE @NODE SetClock "SetClock" SETCLOCK LOAD|SAVE * SETCLOCK only works if you have a battery backed up clock (BBUC). It accesses the adresses $DC0000 and I do not know if it works with very old or very new (A1200) clocks. * SETCLOCK LOAD sets the systemtime (you can see the systemtime with @{" DATE " Link DATE} or @{" MEMCLK " Link MEMCLK}) to the time in the BBUC (hopefully this is the right time). * SETCLOCK SAVE first resets the BBUC, then stores the systemtime to the BBUC. To set the BBUC to the right time, use @{" DATE " Link DATE} to set the correct date and time, then use SETCLOCK SAVE. eg. setclock load setclock save @ENDNODE @NODE Skip "Skip" SKIP label * SKIP searches for the label within the current script file. If it finds it, execution continues from that point onwards. Labels are specified using the @{" LAB " Link LAB} command. eg. lab myloop dir ram: ask "list ram again? " if warn skip myloop endif @ENDNODE @NODE Stack "Stack" STACK [size] * Allows you to view or alter the current stack size. eg. stack {shows the current stack size} stack 30000 {sets current stack = 30000 bytes} @ENDNODE @NODE UnAlias "UnAlias" UNALIAS [alias1] [alias2] [alias3] [alias4] ... * UNALIAS removes one or more @{" alias " Link alias} definitions from the alias list. eg. alias f1 "cd df0:;dir^M" alias f2 "cd df1:;dir^M" ... alias f10 "ed df1:s/startup-sequence^M" unalias f1 f2 f3 f4 f5 f6 f7 f8 f9 ... unalias f10 @ENDNODE @NODE Wait "Wait" WAIT timeout * WAIT halts processing for the time given. Timeout is in seconds. You can abort this with CTRL-C. eg. echo "I'll wait a minute" wait 60 @ENDNODE @NODE Comments "Comments" ; blah blah blah blah * etc etc etc # hello ma * Placing a semi-colon, an asterisk or a hash character as the 1st character in the line of a script file allows you to place comments in it. eg. ; This is a comment line * If you want to place a comment at the end of a line, you have to put ;# before it. eg. info;#to see something interesting @ENDNODE @NODE BUILTIN3 "Builtin Commands for Advanced Users" These commands are thought for users with a deeper knowledge of the system. Maybe they are also useful for those not knowing of the system internals (like beginners). Just try the examples to find that out. @{" Break " Link Break} task_description [signalmask|C|D|E|F] @{" Check " Link Check} ON|OFF @{" Ctrl " Link Ctrl} [max_16_chars | -C [ignore_name] | -R 8_colour_digits] @{" DiskChange " Link DiskChange} device @{" Die " Link Die} device @{" GetMsg " Link GetMsg} [portname] @{" Locate " Link Locate} [-C] lock|filename @{" M " Link M} [start_address] [end_address] @{" PutMsg " Link PutMsg} port_description [number1|string1] [number2|string2] ... @{" Recopy " Link Recopy} [-R] [directory|file_description] @{" Reset " Link Reset} @{" Show " Link Show} D|I|L|M|P|R|S|T @{" Strings " Link Strings} sourcefile [count] @{" TaskPri " Link TaskPri} priority [task_description] @{" Vec " Link Vec} @ENDNODE @NODE Break "Break" BREAK task_description [signalmask|C|D|E|F] * BREAK sets some signals at a given task * task_description can be one of: - task/process name (case dependent !) - task/process adress - CLI-process number (one from 1 to 20) - zero (0) for this task It will be checked if the node-type field contains TASK or PROCESS * signalmask is a longword; all bits, which should be signalled, must be 1 . Alternatively you can specify c,d,e or f to set the according signal to CTRL-C,-D,-E or -F. (CTRL-C is bit 12) * BREAK without signalmask (and c,d,e,f) given sets all signals the task is waiting for. eg. break RexxMaster {and it will be gone...} break Exchange c {Exchange will get itself off too} eg. If 2 ZShells are running. The one with the CLI-number 1 (get that out with prompt %n) lists a very large directory. You can break that by using the other ZShell typing: break 1 c Thats the same like you pressed CTRL-C on the ZShell number 1. @ENDNODE @NODE Check "Check" CHECK ON|OFF * Activates or deactivates the programmers status line. eg. check on {activates status line} check off {deactivates status line} The status line (if activated) will only appear once a disk based or resident program has been executed. The line appears as follows: Result2: 0 time = 00:00:23.66 changes-> chip: 0 fast: 0 total: 0 Result2 shows the error code that can be asked for with IoErr. Time shows how long the program took to execute in hours, minutes, seconds, hundredths (This time does NOT include the time it takes to load the program from disk). Changes show if the program has left any memory still allocated. i.e. if 200 bytes of chip memory were left allocated by the program, then you see "chip: -200". The Return code (the program returns in D0) is shown as Fail-Level. @ENDNODE @NODE Ctrl "Ctrl" CTRL [max_16_chars | -C [ignore_name] | -R 8_colour_digits] This command is for changing the default settings. * CTRL is for command-line-editing-keys-definitions (great word :). In other words: You can change the meaning of keys pressed with CTRL (Control) and some other keys (TAB ^I, Backspace ^H, Return ^M, Shift-Return ^J, ESC ^[). * "CTRL" without arguments shows the current definitions. eg. ctrl * "CTRL WQSEIX[RYHJMLAVn" (case dependent) sets the default settings. To change something, just change the character corresponding to the key pressed with CTRL. See some lines above for some CTRL- equivalents ( eg. TAB is same as CTRL-I ). You may get confused if you define one key twice. eg. ctrl QWKU {half line deleting like KS2.0 shell} ctrl QWSEAXTIYMJH {...and you will have lots of fun} * There is a special meaning with the 16th character. This is by default the point (.), which is displayed as a "n" (don't get confused). The point has a special meaning in some commands (@{" ECHO " Link ECHO},@{" SEARCH " Link SEARCH},@{" PUTMSG " Link PUTMSG}, dir back, force disk, abbreviation) and can be redefined using "CTRL WQSEIX[RYHJMLAVn", but replace the point by the character desired. The ASCII code must be between 32 and 64. eg. ctrl WQSEIX[RYHJMLAV# {# is now a special character} * "CTRL -C" shows the ignored filenames for @{" filenamecompletion " Link filenamecompletion}. By default this is unset. (-C means here -Complete) * "CTRL -C filedescription" defines which names are not completed. "filedescription" contains @{" wild card " Link wild_card}(s) in most cases. eg. ctrl -c {display ignore_name} ctrl -c *.info {ignore *.info-files} ctrl -c *.info|*.bak {ignore files ending in .info and .bak} ctrl -c ~*.tex|*.dvi {complete only *.tex and *.dvi-files} ctrl -c "" {unset ignore_name} * "CTRL -R colours" defines the use of colours. "colours" has to be a 8 digit number. The digit at position x defines to what colour number the default colour x is mapped to. Everything clear ? (I think no!) eg. ctrl -r 01234567 {sets the default colours} ctrl -r 01111111 {switches to one colour mode, very useful with OS3.0+ to speed up scrolling} ctrl -r 01233321 {if you want to use only 4 colours} @ENDNODE @NODE DiskChange "DiskChange" DISKCHANGE device * Needed for devices which do not detect a diskchange. eg. mount rad:;diskchange rad: Makes your rad:-disk appear on the Workbench. diskchange ram: If the ram-disk does not exist yet, the handler will be started (and the ram-disk can appear on Workbench when done before LOADWB) @ENDNODE @NODE Die "Die" DIE device * DIE lets the handler of a device end itself. It seems not to work with most handlers. @ENDNODE @NODE GetMsg "GetMsg" GETMSG [portname] * GETMSG waits for a message arriving at the process-internal messageport (pr_MsgPort). The message will be shown, strings will be tried to detected (this could cause lots of enforcer hits). Then you will be asked if to reply the message. "y" replies it and should be used normally. "e" replies and gets back to waiting mode again. Abort waiting is possible with CTRL-C. * "GETMSG portname" gives the process-internal port the given name. Then it behaves as described above. * See @{" PUTMSG " Link PUTMSG} for examples. @ENDNODE @NODE Locate "Locate" LOCATE [-C] lock|filename * "LOCATE lockadress" (lockadress is a BPTR) shows information about that lock structure. fl_Access must be -1 (write) or -2 (read). * "LOCATE filename_or_dirname" gets an ACCESS_READ lock structure on that file/dir. (If you type -1 after the filename you should get an ACCESS_WRITE lock, but there seems to be an error in DOS !) * "LOCATE -C lockadress" unlocks (removes) the lock structure. eg. locate &21f45c {shows lock on adress $21f45c} locate $9f5b7 {shows lock with BPTR $9f5b7} locate -c $9f5b7 {removes this lock} locate ram:rdit {tries to read-lock ram:rdit} locate ram:rdit -2 {same as above} locate c:mount -1 {got a write-lock on c:mount ?} @ENDNODE @NODE M "M" M [start_address] [end_address] * M is a memory contents dumping command. * Typing M with a start and end address will display the hex and ASCII contents of those bytes in the memory locations specified. * Typing M with only a start address will display 160 bytes starting at the location specified. * Typing M with no parameters will display 160 bytes starting from the current memory location. * The current memory location is always one location higher than the last location shown by a prior M command. eg. m $70000 $77fff m $fc0000 m @ENDNODE @NODE PutMsg "PutMsg" PUTMSG port_description [number1|string1] [number2|string2] ... * PUTMSG is useful for testing programms which wait for a message, or to reactivate a task that waits for a message which will never arrive. PUTMSG sends a message to the given messageport. * port_description can be given in 5 (!) ways: - Name of the messageport - Adress of the messageport - 3 ways of a task_description, see @{" BREAK " Link BREAK}. This MUST be a Process because the process-internal messageport will be used. * number|string is a longword number or a string. If it is a number, it will just be added to the message. If it is a string, a adress pointing to this string will be added to the message. If number1|string1 was a point (.), the message will be initialized as an DOS-Packet. * After sending the message PUTMSG will wait for the reply and show that reply like @{" GETMSG " Link GETMSG}. Abort waiting with CTRL-C. WARNING: Your machine might CRASH if you send a message to a (Process-internal) port that is not waiting for this message. NOTE: PUTMSG without arguments makes a DisplayBeep (even without a window) and outputs the internal register value of A5. eg. putmsg testtask $21fd68 12 putmsg testport "Hello World!" If you have 2 ZShells, execute in the one with CLI-number 1 "getmsg". Activate the other shell and type putmsg 1 "like some chatting ?" The ZShell no. 1 should display that and prompt "reply ?". Answer "y" and the message goes back again. Now try "getmsg wurgutz" at one ZShell and "putmsg wurgutz $abcd" on the other. Do not forget to reply. * You can use PUTMSG to use the AREXX interface of a programm. This works with some programms even with Kick 1.3 and no AREXX-Package. eg. putmsg showdvi 0 0 0 0 0 "tofront" {gets ShowDVI to front} Instead of the first 0 you sometimes must write the adress of this task. If available replace the second 0 with a pointer to the rexxsyslib.library. The third 0 is called rm_Action. I do not know what it is for. The fourth and fifth are results, only interesting in the reply. eg. putmsg showdvi 0 0 0 0 0 "loadnew tex.dvi" * Specify a point as first number if you want to send a DOS-Packet. eg. putmsg DF0 . 0 1023 0 0 -1 {same as LOCK DF0: ON} If you get $FFFFFFFF as 4th longword, it was successful. (with Kick 1.3 you need to use FileSystem instead of DF0) @ENDNODE @NODE Recopy "Recopy" RECOPY [-R] [directory|file_description] * RECOPY copies a file to the same directory with a slight different name (new file), then deletes the old file and renames the new file like the old file was called. After that the new file is the same as the old file was (date and comment are copied too). You might say: What is the use of that ? - Answer: You can process lots of files with a LoadSeg patch or a patch at the device. Depending on the patch it sometimes would be a good idea to run a diskoptimizer after RECOPYing. * In other words: Put some powerpacked textfiles in RAM: then run the PowerPackerPatcher (from Nico Francois), then do "RECOPY RAM:". After that these textfiles should be unpacked. Similarly you can crunch whole disks (in DF0:) running a stacker- like programm on DF0: then doing "RECOPY -R DF0:". This is tested with EPU and might also work with XFH (from the XPK-Package). * The @{" option " Link option} -R (recursive) does the same as in @{" LIST " Link LIST}. * If no directory is specified, the current directory is taken. * If you want to give a file_description make sure that it contains at least one @{" wild card " Link wild_card}. For specifying a single file put a "|" (vertical line) behind it. eg. recopy -r recopy ram:~*.info {do not RECOPY .info-files} recopy ram:bigdoc| {RECOPY only the file bigdoc} @ENDNODE @NODE Reset "Reset" RESET * Performs a COLD reset of your Amiga. i.e. RAD will go, and you will get back fast memory that may have been disabled. And viruses should disappear. You will be asked before resetting. eg. reset @ENDNODE @NODE Show "Show" SHOW D|I|L|M|P|R|S|T * Shows some information about important exec-lists: - Devices - Interrupts - Libraries - Memory - Ports (MessagePorts) - Resources - Semaphores - Tasks (and Processes) Use the first character of one of them as argument. * The output means: - Adress: hexadecimal start adress of the structure - Pri : Priority, often unused - Ver : Number of version (only with D,L,R) - Rev : Number of revision (only with D,L,R) - Name : Name - State : Task state (only with T) - SignWait : Signals, a waiting task waits for (only with T) - PT : Pr means Process, Ta means Task, Tm means Task with Messageport like Process (only with T) * If displaying the tasklist, the CLI-number (-> CLI ?:) and the loaded command will be shown at processes with cli-structure. eg. show d {have a look at the device-list} show Devices {same as above} show t {This is REAL MULTITASKING ! :) } @ENDNODE @NODE Strings "Strings" STRINGS sourcefile [count] * STRINGS displays all valid ASCII strings in a file which have a length greater than or equal to the count. If no count is given, a default of 10 characters is used. * This command is very useful for finding out which libraries a program uses. eg. strings c:zshell 20 strings c:mount @ENDNODE @NODE TaskPri "TaskPri" TASKPRI priority [task_description] * TASKPRI sets the priority of a task, it can be displayed using "SHOW T". The priority must be between -127 and 128 and should be within -50 and 20 to avoid system-hangups. Standard is 0 . * task_description is same as described at @{" BREAK " Link BREAK}. * With one argument TASKPRI sets the priority of this task. * If task_description is given, TASKPRI sets the priority of the given task. NOTE: I did not like to call this command CHANGETASKPRI, because this name is really too long. eg. taskpri 2 {This task will be preferred} taskpri -1 3 {affects CLI no. 3} taskpri 4 Workbench @ENDNODE @NODE Vec "Vec" * Displays some important execbase pointers, which give a good indication of whether a virus is present in your system. WarmCapture, CoolCapture, ColdCapture, KickTagPtr, KickMemPtr, and KickCheckSum are displayed. If any of these are are NOT zero, then either a virus, RAD, or virus protector or some other program that takes control of your machine when you reset, is present. If you suspect a virus, you may want to eject the disk from DF0: and type the @{" RESET " Link RESET} command, which should clear the virus. Now you should boot up on a clean disk. eg. vec @ENDNODE @NODE Past "Past, Present and Future" @{" Changes " Link Changes} ->Past @{" Tips and Hints " Link Tips} ->Present @{" Possibilities for Future Improvements " Link Future} ->Future @ENDNODE @NODE Changes "Changes" UP TO V1.3:See the source code of the ZShell V1.3 release (for example on FISH disk 537). @{" Author: Paul Hayter " Link Authors} Source: 103 KByte, Executable: 13 KByte, Doc 32 KByte. V2.0:There were so many changes, I think there is no sense in listing them all here, because it may be longer than this document. So just read this document or the source code. All changes since V1.3 made by @{" Martin Gierich " Link Authors 9}. Released 14.10.94. Source: 180 KByte, Executable: 25 KByte, Doc 72 KByte. V2.1:* IMPORTANT FOR THOSE WHO USED ZSHELL V2.0: Do not start ZShell V2.1 * * if ZShell V2.0 is resident. This will crash your machine ! * * Do not use ZSH V2.0 with ZShell V2.1 and vice versa. * - Added a @{" review " Link review} buffer to see that again what scrolled out of the window. A scrollbar will probably added in future. - Added possibility to specify window when @{" starting " Link starting} from CLI. - Changed default @{" CTRL " Link CTRL}-keys; added 2 new CTRL-keys (see @{" HISTORY " Link HISTORY}). - Changed usage of @{" MORE " Link MORE} (you can still use the cursor keys). - @{" DIR " Link DIR} now hides all these files that @{" Filenamecompletion " Link Filenamecompletion} ignores. - Some bugs found with mungwall and scratch are fixed. All changes since V1.3 made by @{" Martin Gierich " Link Authors 9}. Released 11.12.94. V2.2: I did some bugfixes and minor improvements (I have no time for more). - Fixed a REALLY NASTY BUG that trashed taskswitching when closing ZShell. - @{" AmigaGuide-Documentation " Link Distribution} added - @{" MORE " Link More} is now "more fast". 8-) - @{" Filenamecompletion " Link Filenamecompletion} (display-)beeps if no match - @{" CTRL-J = Shift-RETURN " Link History} puts the command line in History buffer without executing. - @{" PROMPT " Link Prompt} now knows the args %s and %c :-) . Default Prompt changed to "%s> ". - Better building of the CLI-Interface when @{" starting " Link Starting} from WB. - Now the @{" Assign " link Assign} PROGDIR: is provided (KS2.0+ only). - @{" LIST -Q -R " Link List} also works; @{" DIR " Link Dir} can also list recursive. - @{" ECHO Hi There ! " Link Echo} will now do the same as ECHO "Hi There !" . - @{" NEWCLI " link NewCLI} has a new argument template. - @{" RUN-Command " link Run} added. - Improved options when @{" starting " link Starting} from CLI. - Tooltype for @{" starting " link Starting} from WB without window: WINDOW= - Probably added some brand new nasty bugs and left some ugly old bugs ;-) - And what is best: The versionnumber is changed ! @{" ;-) " Close} All changes since V1.3 made by @{" Martin Gierich " Link Authors 9}. Released 3.1.95. @ENDNODE @NODE Tips "Tips and Hints" * Use @{" MORE " Link MORE} instead of @{" TYPE " Link TYPE}. * Useful @{" aliases " Link alias}: alias arexx "%1 %2 putmsg $1 0 0 0 0 0 \"$2\"" So 'arexx showdvi "tofront"' is the same as the example in @{" PUTMSG " Link PUTMSG}. If you want some shortcuts like MessyDOS: alias md makedir alias ren rename alias del delete alias dc diskchange These are only needed for Kickstart 1.3: alias setenv "%1 %2 echo >ENV:$1 $2" alias getenv "%1 type ENV:$1" alias unsetenv "%1 delete ENV:$1" * A script counting down from 10 to 0 (a bit complicated and slow) : failat 11 ; setenv helpenv 11 lab backtohere copy >NIL: ENV:helpenv ENV:counter eval >ENV:helpenv |ENV:counter 1 - echo "Current number: " ; eval |ENV:helpenv if not error skip backtohere endif * From Workbench assigns are most likely done by clicking an icon: For example if you have the assigns below in the script failat 10 assign TEX: dh0:text/pastex assign MF: dh0:text/pastex/metafont putmsg you need to get a PROJECT ICON for that. Now define the default tool as ZSH (or ZShell) and a tooltype containing WINDOW= (case sensitive). That's all. Failat 10 breaks the script if an error occurs. Putmsg flashes the screen to indicate that everything was successful. No window will be opened. @ENDNODE @NODE Future "Possibilities for Future Improvements" * Make the PATH command AmigaDOS compatible (near future !). * Make a special Version for OS 2.0 and up which would be even smaller. * Scrollbar for review-buffer * Improve script file execution, like passing arguments, allow subroutine scripts and commands like FOR. * More flexible environment variable handling. * Include MOUNT/MOVE/INSTALL command. * Rewrite COPY/DELETE. * Faster scrolling (jump scroll/1 bitplane scroll) * Filenamecompletion shows all files that match. * Support more than one "*" in wildcards. * Mini-Editor ? * Requester to choose file/dirname. * MORE adapts itself to the size of the window. If you want to see these or other improvements made, please write to @{" me " Link Authors 9}. @ENDNODE @NODE Copyright "Copyright" COPYRIGHT FOR THE V1.3 PART ZSHELL IS FREELY DISTRIBUTABLE. YOU CAN DISTRIBUTE THIS AS LONG AS THIS DOC FILE REMAINS WITH THE EXECUTABLE, AND THAT NO CHARGE IS MADE FOR THEM (APART FROM A NOMINAL COPYING CHARGE). IF YOU FEEL LIKE SENDING ME SOMETHING FOR THIS PROGRAM, SEND ME A POSTCARD!, A P.D. DISK, A PROGRAM YOU'VE BEEN WORKING ON ,BUT DON'T SEND ME ANY MONEY (WELL, IF YOU REALLY, REALLY WANT TO, I GUESS I COULD PUT UP WITH IT). COPYRIGHT FOR THE V2.x PART This may be confusing, that there are two copyrights, but I (Martin) did not like to change the original copyright notice. The parts belonging to V2.x are marked in the source code with 'V2.x'. ZSHELL IS FREELY DISTRIBUTABLE. YOU CAN DISTRIBUTE THIS AS LONG AS THE TWO EXECUTABLES REMAIN WITH THIS DOCUMENTATION TOGETHER (AND PLEASE DISTRIBUTE THE SOURCE FILES WITH THEM TOO), AND THAT NO CHARGE IS MADE FOR THEM (APART FROM A NOMINAL COPYING CHARGE). IT IS NOT ALLOWED TO USE ZSHELL COMMERCIALLY ! @{" I " Link Authors 9} would like to get your comment on ZShell to see if anybody is using it and what can be improved. Amiga, AmigaDOS, Workbench and Kickstart are registered trademarks of Commodore-Amiga Inc. DISCLAIMER USE THE FILES OF THIS PACKAGE ON YOUR OWN RISK ! The authors are in no way responsible for what you are doing with it or what it does to you or your soft- and hardware. @ENDNODE @NODE Credits "Credits" CREDITS FROM PAUL Many thanks to Wayne for his invaluable help in doing the history and command line editing parts of ZShell. Also, thanks to Tim Strachan who asked for the history stuff. ZShell was entirely written using Wayned by Wayne Hayter (various versions). And was assembled with A68K V2.61 by Charlie Gibbs. And linked with Blink V6.7 by the Software Distillery. CREDITS FROM MARTIN Many thanks to the six people who wrote me: Laura, Igor, Willem, Nico, Max and Alexandros; especially to Laura for lots of mail :). Thanks to Frank for using ZShell. I hope that in future some more people write to @{" me " Link Authors 9}. @ENDNODE @NODE Authors "Authors" * Please send any correspondence and/or bug reports referring V1.3 to me at the address below:- Paul Hayter PO Box 331 Ballina 2478 AUSTRALIA * Please send correspondence, bug reports, comments, suggestions for future improvements etc. referring V2.x to this adress: Martin Gierich Narzissenweg 7 76297 Stutensee GERMANY If you have EMAIL access, please send me one at this adress: uj3w@ibm3090.rz.uni-karlsruhe.de (Internet) or to uj3w@rz.uni-karlsruhe.de (but better to the above one) or to UJ3W@DKAUNI2 (Bitnet) I will try to reply EVERY EMail I get ! @ENDNODE