PDA Software Library

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

/ PDA Software Library / pdasoftwarelib.iso / PSION / UTILS / SHELL3A / README.TXT < prev next >

Wrap

Text File | 1996-09-01 | 13.8 KB | 336 lines

Shell3a V1.70 ============= Copyright (c) Nick Murray 1996 Introduction ------------ Shell3a is a command line shell for the Psion Series 3a which allows basic file operations such as copy, delete, rename, etc, as well as more sophisticated operations. Highlights: <NEW> A 'pipe' like feature allowing the output of one command to form the input of another <NEW> Input redirection <NEW> Multiple commands per line, separation by ';' Command history accessed with the cursor keys Support for external, user written, commands Access to ROM (rom::) and remote (rem::) filesystems Relative pathnames (. ..) Wildcards on filenames (e.g. cp *.bat a:\bat) Command aliasing Output redirection to a file (e.g. ls > ls.out) Shell variables, allowing extensive configuration Support for batch files including parameter passing and the additional commands IF, GOTO and SHIFT Extensive help Ability to run .OPA and .APP files (inc. parameters) [experimental] Pop-up error log window Inline arithmetic evaluation, e.g. echo 1+1 is ${1+1} Sophisticated 'path' mechanism Commands: alias, at, banner, bg, cat, cd, chmod, cls, cp, date, df, (Builtin) echo, edit, exit, goto, hash, history, if, ls, man, mem mkdir, more, mv, od, pause, pwd, rename, rescan, rm, rmdir, set, shift, unalias, unset, ver, which Supplied as external modules: battery, du, kill, play, ps, setpr (inc. source and help file) view, wc More detailed information is contained within the program's help system. The help system is based on Tom Dolbilin's OPL Help System, so if you've already installed this you won't need sys$help.opo. Installation ------------ 1) Copy SHELL_3A.OPA to \APP on A: B: or the internal disk. 2) Copy AUTOEXEC.BAT to \APP\SHELL3A on the same drive as above, or to the root directory, \, on any disk. 3) Install SHELL_3A.OPA onto the desktop using PSION-I. [the rest of the installation can be performed using the shell and is only necessary to use the help and supplied external commands] 4) Create a directory (eg. \BIN) and copy the .OPO files into it. 5) Create a directory (eg. \HLP) and copy the .HLP files into it. 6) Set the 'path' and 'helppath' variables respectively in the AUTOEXEC.BAT files to reflect the directories chosen in (4) & (5) [ Changing the autoexec.bat file can best be done via the shell 'edit' command. ] HINT: If you want to keep all the Shell3a files together, use a single directory (eg. M:\APP\SHELL3A) for both the .OPO and .HLP files. Customisations (usually set in AUTOEXEC.BAT) -------------- (1) path - This is the list of directories in which the shell will look for .BAT, .OPO, .OPA and .APP files. Each time the path is searched and a command found, the location is recorded (HASHED). This hash table is cleared when the path is changed and can be directly manipulated via the 'hash' command. In order for the help system to work, SYS$HELP.OPO must be in one of the directories of the path. eg. set path="loc::m:/opo,loc::m:/bin,loc::m:/app/shell3a" (2) helppath - The directories in which the help files are stored. If help is invoked for a command, eg. mycom, that isn't built into the shell, a help file 'MYCOM.HLP' is searched for in these directories. This allows help to be provided for user written commands. eg. set helppath="loc::m:/hlp,loc::a:/hlp" (3) Setting path and helppath should allow you to view the online help. See the *(v) sections at the end of the online help for the remaining shell settings. Files included: \APP\SHELL_3A.OPA - the main application \APP\SHELL3A\AUTOEXEC.BAT - a sample start up file \APP\SHELL3A\SHELL3A.HLP - the help file \APP\SHELL3A\DOS.BAT - Aliases more familiar to MS-DOS users. \APP\SHELL3A\BATTERY.OPO - command to display battery status \APP\SHELL3A\DU.OPO - show disk usage by directory \APP\SHELL3A\KILL.OPO - terminate a process \APP\SHELL3A\PLAY.OPO - play a .WVE sound file \APP\SHELL3A\PS.OPO - display the running processes \APP\SHELL3A\SETPR.OPO - change the priority of a process \APP\SHELL3A\VIEW.OPO - show .PIC files \APP\SHELL3A\WC.OPO - count the lines, words and chars. in a file \APP\SHELL3A\BATTERY.HLP - help for the above commands \APP\SHELL3A\DU.HLP \APP\SHELL3A\KILL.HLP \APP\SHELL3A\PLAY.HLP \APP\SHELL3A\PS.HLP \APP\SHELL3A\SETPR.HLP \APP\SHELL3A\VIEW.HLP \APP\SHELL3A\WC.HLP \APP\SHELL3A\HCP.OPO - Tom Dolbilin's OPL Help System \APP\SHELL3A\SYS$HELP.OPO - " " " " " README.TXT - this file PROGRAM.TXT - a description of how to write external commands SRC.ZIP - ZIP file containing the source for the 8 external commands New features in this version ---------------------------- 1) Redirection of input into commands Input can be redirected into a command either by using the notation '< file', e.g. more < file.txt or by PIPING the output of another command using the '|' notation, e.g. ls | more Notes: In the example above 'file.txt' should be a text file as it is opened in text, rather than binary mode which restricts input lines to less than 255 characters. Batch files cannot be subject to input/output redirection See notes on pipes below 2) Multiple commands on an input line Multiple commands can occur on a single command line. The separator between commands is ';', e.g date ; pwd Notes: ';' is close to the standard for separation of multiple commands within a single command line. As ';' was already used to separate pathname components, I have had to change the pathname separator to ','. If an error occurs in one of the commands the subsequent commands are still executed, unless it was an error caught in the initial parse of a command (e.g. bad wildcards). 3) Implementation of 'pipes' This allows the output of one command to form the input of another command, e.g. ls | more Commands must be specially coded for this to work. On the output side, if the shell flags to the command that the output is redirected, the command should write output to the handle SHout% using the IOWRITE command. This is automatically handled if fprint is used to produce the output. On the input side, if the shell flags the input is redirected, the command should read input from the handle SHin% using the IOREAD command. The shell builtins more, od and cat have been modified to accept redirected input. They were the only commands that already took input from a file. Notes: The pipe character |, char 179 can be produced within the shell by pressing <PSION> +. Otherwise use <CONTROL>179. Pipes are implemented by using intermediate files to which output is written and read. These files are LOC::M:\|.1 and LOC::M:\|.2. Data between processes should be text as the intermediate files are opened in text not binary mode (to make reading them easier!). Batch files cannot appear in pipes. If a command doesn't accept redirected input the input is ignored. If a command doesn't produce redirected output the input to the next command will be empty, but it will still execute. If an error occurs in the pipe, the subsequent commands are still executed, albeit with empty input (except when it' an error with redirection or wildcards). If an alias is used in a pipe, multiple command or input/ output redirection there MUST be a space between the alias and the '|', '>','<' or ';' symbol. e.g. alias h history Work Fail h | more h| more h |more h|more This isn't a new bug, it exists due to the way aliases are detected. Within batch files, GOTO commands and labels may behave stangely if they are part of multiple command line. 4) A new command to count the number of lines, words and characters in a file - wc. This is really just an example of code that can use input redirection. Changes between V1.70 and V1.60 ------------------------------- - change of separator from ';' to ',' in PATHs - enhanced the 'man' command to include searching for topics and command-line access to any topic - ability to have AUTOEXEC.BAT file in \APP\SHELL3A directory - bug fixes for ls (corrupt output on remote drives) and play (could crash the machine under certain circumstances) New features in V1.60 --------------------- - Log window. This displays error and information messages that previously were displayed on the text screen. Currently these are the messages from "rescan" and bad path/helppath component warnings. This window is shown during initialization and then hidden. The key toggles the window. - ${expression}. This allows the evaluation (using the OPL EVAL construct) of arithmetic expressions. This allows the numeric manipulation of shell variables. eg. set i=${$i-1}. This removes the need for a separate "EVAL" command. - The path searching has been reworked. In previous versions the list of commands found in the directories of the path were stored when the path was set and never changed. Although this was fast, it meant relative paths couldn't be used (eg. '.') and new files weren't automatically found (hence the rehash command). The new algorithm searches the path when an unknown command is encountered and stores the path if it is found. The "hash" command is used to manipulate the hash table. - External command execution. In previous versions, a separate command "exec" was needed to run .OPA and non-shell .OPO files. This has been reworked and any .BAT, .OPO, .OPA or .APP files can be run by typing it's full pathname or just the name if it is in a directory in the path. The extension is optional now, and if one isn't supplied the search order is BAT, OPO, OPA then APP. If "." isn't in your path programs in the current directory can be accessed as "./program". A single parameter can be supplied to an OPA or APP. Some applications EXPECT an argument and will fail without one. Others ignore the argument, or perform unusually if one is given! A word of warning - some APPs don't like being executed like this. For example running ROM::RUNOPL.APP or ROM::RUNIMG.APP causes a soft reset! - I've never found out exactly why. Changes between V1.60 and V1.40 ------------------------------- - Back to 1 executable - Variables are prepended either by $ or % depending on "unixvar" - Loss of eval, exec and rehash commands; their functionality has been moved elsewhere (see new features above). - Extra commands: mem, banner, battery, view, setpr, du - Use of the OPL cache New features in V1.40 --------------------- - The number of commands stored in the history can be set via the 'set' command - There is no longer any limit on the number or size of aliases. - batch files can now take variables which are are accessed using %0 .. %9 - Shell variables have been introduced. These are specified as %string - Settings such as path, helppath, etc are implemented as shell variables - new IF command (DOS syntax) - SHIFT, GOTO and labels in batch files. Changes between V1.40 and V1.23 ------------------------------- - The program now consists of 2 parts, shell3a.opa and commands.opo which contains all the user commands. - As shell variables use the '%' DOS convention, prompt 'variables' are now referred as $H and $p rather than %H and %p. New features in V1.23 --------------------- - Items in the command history are accessed using the up/down cursor keys - The <Help> key brings up the main help menu. - Support for external modules and hence user-expansion of the capabilities of the shell. Changes between V1.23 and V1.02 ------------------------------- - The comment string in .BAT files is now '#' - The Mac 3-link can now be used. Pathnames and device names with spaces have to be quoted, eg. cd "rem::Hard Disk:". - The path is no longer searched each time a command that doesn't match a built-in is found. Instead a list of .OPO of .BAT files found in the path is stored and searched. This means external .OPO modules are executed with little noticable delay. Members of the list are accessed WITHOUT the suffix .BAT or .OPO. - Separate current directory for each device. Because of this all possible devices are scanned when the program starts. If devices are added the command 'rescan' must be used to recognize the new device. Note the rescan command has the side-effect of resetting the current working directory. - 'df' without arguments show a summary of all devices Acknowledgements ---------------- Psionics files by Clive Feather Tom Dolbilin for his excellent help system Suggestions: Chris Dadd mike@btwelve.demon.co.uk External Commands ----------------- If you write any useful external commands that you'd like to make available to other users, either send me the source or drop me a note of where it's available, and I'll include this information in the next release. Bugs, suggestions, etc. ----------------------- I can be reached via email at nmurray@csd.abdn.ac.uk Disclaimer ---------- The author of this software is not responsible for any damage due to use of this program. This software is provided without warranty of any kind. Copyright --------- Last and by no means least, this program is NOT public domain and I retain the copyright. However provided you don't make money from it this program is freely distributable.