GEMini Atari

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

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / utility / system2 / system2.doc < prev next >

Wrap

Text File | 1989-04-19 | 75.2 KB | 2,118 lines

******* ******** *** *** *** *** *** *** *** *** *** *** *** ****** ******** ****** ********** *** **** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ******** *** *** *** *** *** *** *** **** *** *** *** *** *** *** *** *** ***** *** *** *** *** *** *** *** *** *** *** ****** *** ****** ****** ****** *** *** *** *** *** *** *** ----------****-----Operating Environment for the Atari ST-----*************-- (C) Copyright 1989 DW Software. Written by David Wild. U S E R ' S M A N U A L System 2 operating environment User's Guide index page 1 --------------------------------------------------------------------------- INDEX ----- DETAILS REFERENCED UNDER Introduction and details intro About the author author A note on the syntax used in this manual syntax Starting System2 starting General usage of System2 general Special characters special Device names devices Redirection & piping redirection Macros macros Variables variables System Variables system XSL programs xsl-programs The little things in life oddments Writing programs to run under System2 technical Internal Commands baud baud cat cat cd cd chmod chmod clear clear contains contains cp cp date date decr decr del del dir dir diskfree diskfree drive drive echo echo else else endif endif equal equal exists exists exit exit false false getc getc goto goto if if incr incr input input istrue istrue locate locate ls ls mcat mcat mkdir mkdir mkill mkill mv mv notequal notequal path path pr pr putc putc System 2 operating environment User's Guide index page 2 --------------------------------------------------------------------------- INDEX ----- DETAILS REFERENCED UNDER pwd pwd quit quit ren ren result result rm rm rmdir rmdir set set time time true true type type unset unset xsl xsl . . $ $ * * External commands help help bombs bombs tl50 tl50 tl25 tl25 Glossary glossary System 2 operating environment User's Guide Introduction --------------------------------------------------------------------------- INTRODUCTION AND DETAILS ------------------------ System 2 is an operating system shell for the Atari ST computer. It should work without problem on all versions of the computer and TOS. What is an operating system shell (a.k.a Command Line Interpreter)? An OS shell, like System2, provides a different method of giving commands to the computer. The usual way of controlling things on the ST is via the GEM desktop, where you drag files around, etc. with the mouse. This is all good stuff, but there are many instances when it can be restrictive, such as in copying & deleting files, formatting text, running TOS programs, etc. This is where System2 comes into it's own. It allows commands to be typed in, instead of using a graphical front end, and is in many ways similar to Unix*. Here are some of it's features: o Unix Style command entry o Full input/output redirection & piping o Around 50 built-in commands o Ability to quickly recall the last 10 commands typed o Only takes up around 45K of memory o Aliasing and variables o Mini programming language with IFs and GOTOs o Built in expression evaluator System2 is Copyright (C) 1989 by DW Software, and was written using Mark Williams C and assembler by: David Wild 62 Lascelles Avenue Withernsea North Humberside HU19 2EB England JANET EMAIL : WILDDJ@UK.AC.ASTON.VAXB ---------------------------------------------------------------------------- * UNIX is a registered trademark of AT&T Bell Laboratories System 2 operating environment User's Guide About the author --------------------------------------------------------------------------- About the author ================ Hello! I'm David Wild, the author of System2, and I just thought I'd say a bit about myself. I'm 19, and am currently doing a computer science degree at Aston University in Birmingham. The idea for writing System2 came from an interest in Unix, so many of the commands have a similar "Look and feel" to them (Oh dear, I shouldn't have said that. What's betting I have 100 lawsuits from AT&T through the door in a few weeks time!!). System2 isn't anywhere near as powerful as Unix (TM (R) (C) etc..) but it is hopefully a useful program. If you have any suggestions, queries, complaints, etc., please write to me at: 62 Lascelles Avenue Withernsea North Humberside HU19 2EB Or send JANET EMail to WILDDJ@UK.AC.ASTON.VAXB System 2 operating environment User's Guide syntax --------------------------------------------------------------------------- SYNTAX USED IN THE MANUAL ------------------------- The following syntax conventions are used in this manual when describing commands: o Items of text written directly should be typed in directly o Text enclosed in < and > signifies where you should supply some information, eg a filename o Items in square brackets, ie [ and ], are optional o Items separated by a bar (|) mean you can enter ONE of the separated items o An ellipsis (...) means that the last item can be repeated several times Do not confuse the < and > above with the redirection operators, or the | sign with the piping operator. Example: cat [<filespec> ... ] ^ ^ ^ type supplied may be directly value repeated \______ ______/ \/ optional System 2 operating environment User's Guide starting --------------------------------------------------------------------------- STARTING UP SYSTEM2 ------------------- To start up System2, insert the disk and double click on the SYSTEM2.TOS icon. System2 will only work in medium or high resolution. System 2 operating environment User's Guide general usage --------------------------------------------------------------------------- GENERAL USAGE OF SYSTEM2 ------------------------ When you first load up System2, an introductory message will appear, and a prompt (a $ sign) will appear, which means that the computer is telling you it's waiting for you to type something (the prompt can be changed with the set command). At this prompt, you can type in a command line. A command line takes the following form: command [<qualifiers>] [<parameters>] [< <input>] [> <output>] After a command line is typed, the RETURN key is pressed in order to carry out a command. The command is the name of the command which you want to carry out, which can be either the name of an in-built command (see the internal commands section of the manual), or the name of an external command (ie a program on a disk that you wish to run. The following are examples of valid commands: cat dir a:\bin\test utils\abc External commands are assumed to have the filename extension .tos, .ttp or .prg. Note that GEM programs (ie that use the mouse) cannot be run under System2. The parameters are values that are supplied to a command, such as filenames and data. The qualifiers are only used in some commands, and are a special type of parameter: they start with a '-' and consist of a set of letters which dictate the ways in which the commands work. For example, in the dir command, dir -w *.c the w qualifier sets the dir command to work in wide mode. The <input and >output parts define any redirection that may take place, and are discussed in the section on redirection & piping. More than one command line can be placed on one line. Command lines are separated by a ; or a | character. A ; allows several commands to be entered on one line as if they had been typed consecutively on several lines, for example dir -w ; cat is the same as typing dir -w cat System 2 operating environment User's Guide general usage page 2 --------------------------------------------------------------------------- If the | (pipe) character is used, then the output of one command is fed into the next. See the section on redirection & piping for more details. A few control keys will work whilst typing, which allows simple editing. Pressing BACKSPACE deletes the last character entered. Pressing CONTROL and A restores deleted characters one by one, and CONTROL R will move back through the last 10 command lines typed, allowing you to repeat commands. For example, if you had typed "cobmands" instead of "commands", you could press BACKSPACE 6 times, type "m", then press CONTROL A five times, to restore the other deleted characters. By default, all characters on the line are converted to upper case, and items of text cannot contain spaces (as these would be interpreted as separating parameters, etc). To remedy this, items may be placed in quotes (either double or single) which allows spaces, and text in quotes is not put into upper case. Also, items in quotes will not be treated as potential variables or be subject to macro substitution (see section on macros & variables). For example, the echo command displays it's parameters on the screen, so echo hello would display HELLO on the screen. However, echo "hello" or echo 'hello' would display hello on the screen. If you wish to include a quote character within quotes, use the opposite type of quotes for the text. For example, echo "This is 'some' text" displays This is 'some' text and echo 'This is "some" text' displays This is "some" text A command line may only be 80 characters long. Unpredictable results may occur with lines longer than this. System 2 operating environment User's Guide special characters --------------------------------------------------------------------------- SPECIAL CHARACTERS & CONTROL CHARACTERS --------------------------------------- CHARACTER USE " or ' For enclosing literal text ; Separates commands on a line | Pipes commands together < Allows input redirection > Allows output redirection % Starts a variable name BACKSPACE Deletes last character entered CONTROL A Undelete character CONTROL R Recall command line System 2 operating environment User's Guide devices --------------------------------------------------------------------------- DEVICES ------- When using System2, there are three reserved filenames which correspond to actual physical devices - the screen, the RS232 port and the printer. The device names may be used in place of file names, and allow the devices to be treated as files. The devices are: CON: Refers to screen for output & keyboard for input AUX: Refers to a device connected to the RS232 port PRN: Refers to the printer for output. Inputting from this device is not possible. These devices are especially useful in redirection, for example, echo "Hello" > prn: prints "Hello" on the printer. By default, input and output is to the CON: device. System 2 operating environment User's Guide redirection & piping --------------------------------------------------------------------------- REDIRECTION AND PIPING ---------------------- Most commands allow data to output to a theoretical device called the standard output (stdout) and input from a theoretical standard input (stdin). By default, the stdin and stdout are mapped to the CON: device (see section on devices), corresponding to keyboard for input and the screen for output, but these can be changed. This is known as redirection. A device can be permanently set for stdin or stdout by using the set command. For example, after typing set stdin=AUX: all input will be taken from a device, such as a terminal, connected to the RS232 port. Correspondingly, set stdout=PRN: will send all output to the printer instead of the screen. Issuing a set stdout=CON: command will return back to normal screen output. There is another method of redirection, which allows a single command to output to either a device or a disk file, and input from either a device or disk file. It is carried out using the '<' and '>' symbols; '<' stands for input redirection and '>' for output redirection. These symbols, if given, should come after the command and it's parameters. The symbols are followed by either the name of a disk file, or the name of a device (CON:, AUX:, or PRN:). For example, echo "Hello" > prn: prints "Hello" on the printer cat > fred.doc Takes input from the keyboard, & puts it into file fred.doc cat <bill.doc >fred.doc Takes input from the file bill.doc and puts it into fred.doc (effectively copying file bill.doc to file fred.doc. System2 is not fussy about whether spaces are present or not between the command and the '<' or '>' symbol, or between the symbol and the filename. There is a special kind of output redirection to a file: if two '>' symbols are placed together, then output will be added to the end of an existing file, instead of a new file being created. For example, cat bill.doc >> fred.doc will append file bill.doc onto the end of file fred.doc. System 2 operating environment User's Guide redirection & piping page 2 --------------------------------------------------------------------------- There is yet another kind of redirection - piping. Piping allows the output of one command to be taken as the input of another. The commands are separated by the '|' (bar) symbol. For example, dir | pr -i10 will display a disk directory with a left margin of 10 spaces - the output of dir (a directory listing) is fed in as the input to the pr command which, in this case, displays it on the screen with a left margin. Piping & redirection can be mixed, so dir | pr -i10 > neatdir.doc would do the same as above, but it sends the output to a file called neatdir.doc. Pipes can be used together, for example, if you had a disk program called uniq.ttp which removed identical lines from a file, then you could type dir | uniq | pr -i10 > neatdir.doc You cannot both redirect and pipe the output of a command - for instance, dir > fred.doc | pr is not valid. The pipe has to create a temporary file while in use, which is deleted when no longer needed (named PIPE.TMP). The place where this is created can be set by setting the TMPPATH system variable. Another theoretical device, stderr, exists within System2, which determines where error messages are sent. For example set stderr=AUX: sends all System2 error messages to the AUX: device. Note that this may not work with external TOS programs, since stderr is not normally defined on the ST. Also look at - set, system variables System 2 operating environment User's Guide macros --------------------------------------------------------------------------- MACROS ------ Suppose you wanted the dir command to split it's output into pages of length 20 lines with 2 lines between pages. You can do this by typing dir | pr -l20s2 but it is tedious typing this every time. However if you type in set neatdir:"dir | pr -l20s2" then every time you type in neatdir, you will get a split listing - try it! The name 'neatdir' is called a macro. Once a macro has been set as above, then EVERY occurrence of this string on the command line (except text in quotes) is replaced by the supplied string. For example, after typing set much:"a load of" then echo "This is "much" rubbish" would display This is a load of rubbish and echo thismuchrubbish would display THISALOADOFRUBBISH Care should be taken - if you defined a macro, for example, set in:"set stdin=aux:" then typing echo i-think-we-made-a-mess would display I-THSETSTDIN=AUX:K-WE-MADE-A-MESS Macros can be unset by the mkill command or by using unset. Note that the macro name should be placed in quotes, eg unset "much" or else the name of the macro to be unset will be taken as the VALUE of much! Commands to look at - set, unset, mkill, incr, decr, eval, echo System 2 operating environment User's Guide variables --------------------------------------------------------------------------- VARIABLES --------- Variables are a special type of macro, and in most instances, a macro can be used in place of a variable. Variables are set up in exactly the same way as a macro, but they are distinguished from macros by putting a % sign at the start of the name, for example, set %age=19 The main differences from macros are: o In the input, unset, incr, etc. commands, the name of the variable does not need to be put in quotes, eg incr %age instead of incr "age" o Substitution of the value only occurs if the variable is given on its own as a parameter, eg set age="fred" echo 123age456 displays 123fred456 but set %age="fred" echo 123%age456 displays 123%age456 Variables' values can be easily changed with the set, incr and decr commands. See the relevant sections for details. System 2 operating environment User's Guide system variables --------------------------------------------------------------------------- SYSTEM VARIABLES ---------------- There are several variables which are already defined in System2. These can be split into two types - ones which can be set with the Set command, and ones which cannot. If system variables are being set with the set command, then the % sign is not entered - eg to set the %stderr system variable to AUX:, you would enter set stderr=aux: but you would still type echo %stderr System variables which can be set: ---------------------------------- NAME POSSIBLE VALUES DESCRIPTION %colour 0-3 Sets colour pen used for text output %echo ON or OFF Determines whether text input is echoed on the standard output (useful for entering passwords and on echoing terminals %lf ON or OFF Sets if linefeeds contain LF character %paper 0-3 Sets colour pen used for background %prompt any string Contains system prompt %stderr CON: AUX: or PRN: Standard error device %stdin CON: AUX: or PRN: Standard input device %stdout CON: AUX: or PRN: Standard output device %syscol 0-3 Colour pen used for text input %tmppath pathname place where temporary pipe files are stored System variables which can't be set: ------------------------------------ %result Contains returned result of last command screenres Contains screen resolution - 0=low, 1=medium, 2=high System 2 operating environment User's Guide xsl-programs --------------------------------------------------------------------------- XSL PROGRAMS ------------ System2 has a batch programming facility known as XSL (eXternal Script Language). This allows System2 commands to be placed in sequence in a file, and this file is read in using the xsl command, and the commands are executed as if they had been typed into System2. Simple programming constructs are catered for, namely IF and GOTO. Files containing XSL programs should have the extension .XSL. Some sample XSL files are provided in the directory SAMPLE.XSL. XSL programs can be created with any text editor, such as the micro emacs editor. XSL programs can be passed parameters like programs. These paramaters are assigned to variables %1, %2, ... etc up to %9. So if an XSL program was run as follows (assuming it was called fred.xsl): XSL fred hello there then %1 would equal HELLO and %2 would equal THERE. Another variable, %argc, contains the number of parameters supplied. If a file PROFILE.XSL exists in the same directory as System2, then when System2 is executed, this XSL program is read in and executed. See also: xsl, if, goto System 2 operating environment User's Guide oddments --------------------------------------------------------------------------- The Little things in life... ---------------------------- Here are some handy uses of System2 which may not be immediately obvious... Printing out files ------------------ Often, you want to print a file on the printer to put into a binder, say. Unfortunately, the GEM printing function does not have any formatting capabilities. Using the pr command, you can set the left hand margin, and split the file into neat pages for printing. Sending control codes to the printer ------------------------------------ If you wish to set your printer to a certain print mode, then this can easily be done using the putc command. Copying files ------------- The cp and cat commands are much more powerful than the GEM equivalents Putting control codes at the start or end of files -------------------------------------------------- To do this, use the putc command to create a file with the control codes in, and use the cat command to join the files, or use the appending redirection (>>). ~ System 2 operating environment User's Guide technical --------------------------------------------------------------------------- Writing programs to run under System2 ------------------------------------- When System2 loads up an external program, it passes to it a command line containing the parameters, and also an environment string which contains: (i) The name of a file used for input redirection, or a space if non exists (ii) A space (iii) The name of the current stderr device (CON:, AUX:, or PRN:) These can be used in C by the following main construct: main(argc,argv,envp) int argc; char *argv[]; char *envp[]; { /* your program */ } argc contains the number of parameters, argv[1]..argv[argc] contains the parameters, and envp[0] contains the environment string. SYSTEM 2 COMMAND REFERENCE GUIDE System 2 operating environment User's Guide - Internal Commands baud --------------------------------------------------------------------------- Command baud Syntax baud <rate> The baud command allows the baud rate for the RS232 port (referenced as AUX: under System2) to be set. The <rate> parameter refers to the baud rate, and can be one of the following values: 19200,9600,4800,3600,2400, 2000,1800,1200,600,300,200,150,134,110,75,50. The default baud rate on the ST is 9600 baud. Examples: baud 9600 baud 75 ~ System 2 operating environment User's Guide - Internal Commands cat --------------------------------------------------------------------------- Command cat Syntax cat [<filespec> ... ] The primary function of the cat command is to join files together (concatenation, hence the command name cat). However, it serves many other purposes. The cat command can be supplied with one or more parameters, each of which can be a filename or a file specification containing wildcards. All files which match the file specifications are joined together, and the result is sent to standard output. If no parameters are supplied, then input is taken from the standard input. cat is very useful for use with redirection, as shown in the examples below: Examples: cat > fred.doc Copies input from the keyboard to fred.doc cat fred.doc Displays the file fred.doc on the screen cat fred.doc bill.doc Displays fred.doc and bill.doc cat fred.doc > bill.doc Copies file fred.doc to file bill.doc cat a*.* b*.* Displays all files starting with a or b cat *.c fred.doc Displays all files ending in .c, followed by fred.doc cat ch1.wp ch2.wp > book.wp Makes a new file book.wp containing ch1.wp and ch2.wp joined together. cat ch3.wp >>book.wp Adds ch3.wp on to the end of book.wp cat fred.doc > prn: Sends file fred.doc to the printer cat < fred.doc Displays the file fred.doc on the screen cat <aux: >prn: Takes input from a console connected to the RS232 port, and sends it to the printer. Notes: If input is taken from the keyboard and redirected to another output, as in the first example above, the typed information will still be displayed on the screen to allow for verification. If input is taken from the keyboard, or a redirected input, then as soon as a CONTROL Z character is encountered (character 27), then input is terminated. So, in the first example above, you would type the information that you wished to be in the file fred.doc, then hold down the CONTROL key and press Z to end the input. CONTROL Z's in unredirected files are treated as any other character. Pressing CONTROL S and CONTROL Q during displaying a file on the screen will cause the screen to freeze and be released, enabling text to be viewed before it scrolls off the screen. Do not press CONTROL C during output, or else you may be aborted to the desktop. Note that pressing return while typing into a file using cat will only result in a carriage return being sent (sending the cursor to the left of the screen). To send a line feed (go to next line), press CONTROL J. See also: type, cp, echo System 2 operating environment User's Guide - Internal Commands cd --------------------------------------------------------------------------- Command cd Syntax cd <path> This command changes the current directory to the given path. All further commands (eg ls) will now operate on files in this directory. It is similar to double clicking on a folder from GEM. To return to the root directory (the default, top level directory that contains all other directories and files), enter cd \ Examples: cd \bin cd database\customer See also: mkdir, rmdir, pwd, drive System 2 operating environment User's Guide - Internal Commands chmod --------------------------------------------------------------------------- Command chmod Syntax chmod <hrw> file The chmod command allows the read/write and visibility status of a file to be altered. The first parameter consists of three flags, each of which can be the character shown above, or a dash ('-'). If the character is supplied, then the status corresponding to that character is set to on, otherwise it is set to off. h stands for hidden (ie not shown on the desktop), r for read access, and w for write access. Examples: chmod -rw fred.doc Sets fred.doc to be visible, readable, and writable chmod hrw fred.doc Sets fred.doc to be hidden, readable, and writable chmod -r- fred.doc Sets fred.doc to be visible and read only chmod hr- fred.doc Sets fred.doc to be hidden and read only Notes: If a file is set to read only (ie r- as opposed to rw) then it cannot be altered or erased unless it's status is set back to rw. All files must be readable, so the r flag is compulsory, and only included for familiarity with Unix users. Any other characters apart from h, r & w in their appropriate positions are treated as being equivalent to a dash. System 2 operating environment User's Guide - Internal Commands clear --------------------------------------------------------------------------- Command clear Syntax clear The clear command clears the screen, and sets the cursor position to the upper left hand corner of the screen. Example: clear See also: locate System 2 operating environment User's Guide - Internal Commands commands --------------------------------------------------------------------------- Command commands Syntax commands This commands produces a list of all the built-in System2 commands. Example: commands Notes: The list does not include the commands command! System 2 operating environment User's Guide - Internal Commands contains --------------------------------------------------------------------------- Command contains Syntax contains <string1> <string2> The contains command returns a value of true (0) if <string2> is contained in <string1>, or false (-1) if it isn't. It is intended for use with the if command, for example, if contains %birdname "gull" ; echo "Seabird" ; echo ; endif would print 'Seabird' on the screen if the variable %birdname contains the string 'gull'. All tests are case sensitive. Examples: contains "this is some text" "some" returns 0 contains "this is some text" "SOME" returns -1 contains "this is some text" some returns -1 contains "this is SOME text" some returns 0 contains thisissometext some returns 0 Notes: All tests are case sensitive, so "FRED" will not match 'Fred','fred', etc. See also: equal, notequal, istrue System 2 operating environment User's Guide - Internal Commands cp --------------------------------------------------------------------------- Command cp Syntax cp <filespec> <destfilespec> The cp command is used to copy files from one place to another (akin to dragging files using the GEM desktop, only more powerful). The <filespec> parameter describes the source file(s), and can contain wildcards. The <destfilespec> parameter either specifies the path to which the files are to be copied, or supplies the path/file name of a single file. Except in the latter case, files will be given the same names as the files that are being copied. Examples: cp a:*.c b:\source cp *.c source cp fred.dat b: cp fred.dat b:john.dat cp a:\source\*.c d:\src Notes: Copying multiple files to one destination file (eg cp *.c b:fred.dat) is allowed, but will result in only the last file being copied. If you wish to create a composite file, use the cat command. See also: cat, type System 2 operating environment User's Guide - Internal Commands date --------------------------------------------------------------------------- Command date Syntax date [<dd> <mm> <yyyy>] The date command will display the current date, or will allow the date to be set if the three parameters (corresponding to day, month, year) are supplied. The month is in numeric format (1-12) and the year is in four digit format (1980-2099). Examples: date date 2 4 1989 date 14 8 1985 Notes: Validity checking is carried out on the dates, but this does not extend to preventing the date being set to 30 February, 31 September, etc. See also: time System 2 operating environment User's Guide - Internal Commands decr --------------------------------------------------------------------------- Command decr Syntax decr <variable> The decr command will subtract 1 from the value held in a variable. Examples: decr %count decr %value decr is very useful if used in a loop in an xsl program. For example, the xsl program: set %count=10 . loop echo "Hello" echo decr %count if istrue %count}0 ; goto loop ; endif exit will display "Hello" 10 times Notes: All arithmetic is in two byte integer form; decrementing below -32768 will cause spurious results. This command is equivalent to a two byte form of set <variable>=<variable>-1 See also: incr, set, xsl System 2 operating environment User's Guide - Internal Commands del --------------------------------------------------------------------------- Command del Syntax del <filespec> This command is used to remove disk files that are no longer needed. A removed file CANNOT BE RECOVERED. The filespec parameter can be a single filename, in which case the given file is deleted, or a wildcard, in which case all files that match the specification are deleted. Obviously, this command must be used with great care. If you wish, the command RM can be used in place of DEL. Examples: del fred.doc del *.c See also: rm, rmdir System 2 operating environment User's Guide - Internal Commands dir --------------------------------------------------------------------------- Command dir Syntax dir [-[aw]] [<filespec>] This command displays a list of all the files that are stored on a disk. It is basically the same as the ls command, except that it produces an MS-DOS(tm) style directory. If the -w (wide) qualifier is specified, only the names of the files or directories that match the filespec are output, and no distinction is made between subdirectories and files. If the -w qualifier is not given, then the output is of the form: <name> <file size> <date & time of creation> <file status> The file status is given as a decimal number. This is the standard ST attribute byte. If the -a qualifier is specified, then all files that match the filespec are shown, including system files that are normally hidden from the directory list. After the file list, the number of files matching the specification is shown together with the number of bytes consumed by these files. The optional filespec parameter can be (i) a filename with wildcards, (ii) a disk drive letter followed by a colon, or (iii) a combination of disk drive letter and filename. Examples: dir dir *.c dir -w a:\data\*.bak dir -aw c: See also: ls,cd,drive,pwd System 2 operating environment User's Guide - Internal Commands diskfree --------------------------------------------------------------------------- Command diskfree Syntax diskfree [<drive letter>] This command will show the amount of free space left on the specified drive, or the current drive if none is specified. The message returned is of the form: n bytes free out of m where n is the disk space free, and m is the total storage capability of the disk. Notes: The amount of space used is displayed with the dir or ls commands. See also: dir, ls System 2 operating environment User's Guide - Internal Commands drive --------------------------------------------------------------------------- Command drive Syntax drive <drive letter> The drive command sets the default disk drive that is used by all commands. <drive letter> must be in the range A-P, and the drive must exist. Drive A corresponds to the first disk drive, and drive B to the second if you have one fitted. Examples: drive a drive d See also: cd System 2 operating environment User's Guide - Internal Commands echo --------------------------------------------------------------------------- Command echo Syntax echo [<string1> <string2> ...] This command outputs it's parameters to the standard output. No carriage return is issued after the text is written. To issue a carriage return, use echo without any parameters. It is advisable to put direct text within quotes, otherwise it will be converted to upper case, and will be subject to macro substitution. Example session: $ echo Hello HELLO$ echo "Hello World" Hello World$ echo "Hello World"; echo Hello World $ set %fred="Hello World" $ echo %fred Hello World$ echo Hello There World HELLOTHEREWORLD$ System 2 operating environment User's Guide - Internal Commands else --------------------------------------------------------------------------- Command else Syntax else The else command is intended for use with the if statement. It will execute all commands up to the corresponding endif statement, if the result of the last if operation was false (ie non zero). For further details, see the if command. Example: else See also: if, endif System 2 operating environment User's Guide - Internal Commands endif --------------------------------------------------------------------------- Command endif Syntax endif The endif command signifies the end of a conditional block of code controlled by an if statement. For further details, see the if command. Example: endif See also: if, else System 2 operating environment User's Guide - Internal Commands equal --------------------------------------------------------------------------- Command equal Syntax equal <string1> <string2> The equal command returns a value of true (0) if <string2> is the same as <string1>, or false (-1) if it isn't. It is intended for use with the if command, for example, if equal %birdname "puffin" ; echo "Seabird" ; echo ; endif would print 'Seabird' on the screen if the variable %birdname was equal to the string 'puffin'. All tests are case sensitive. Examples: equal "fred" "fred" returns 0 equal "Fred" "fred" returns -1 equal "fred" fred returns -1 equal "fred" "james" returns 0 equal fred fred returns 0 Notes: All tests are case sensitive, so "FRED" will not match 'Fred','fred', etc. See also: notequal, contains, istrue System 2 operating environment User's Guide - Internal Commands eval --------------------------------------------------------------------------- Command eval Syntax eval <expression> [<expression> ...] The eval command will evaluate a number of supplied expressions, and will print the results out on the standard output. An expression can consist of any one of the following: (i) A numeric value, which is a number or a variable that gives a number. Examples: 5, 300000, 12345678, %age, %value (ii) A number of numeric values separated by operators Examples: 5*8, 3+2*5, %age*2+71, %age/2=%value*50 Valid operators are (in order of precedence): * (multiply) / (divide) + (add) - (subtract) = (equal) { (less than) } (greater than) If a non-numeric & non-variable string is found, it will yield a value of zero. Examples: eval 3*8+%age %age}17 3*3=9 - which, supposing age=15, results in 39 0 1 being displayed on the screen. Notes: All arithmetic is integer, ie no decimal points are allowed. The = operator yields 1 if the expressions to either side are equal, or 0 if they are not. Similarly { and } yield 1 if the left expression is less or greater than the right expression respectively, otherwise 0. These symbols were chosen instead of the more common < and > in order to avoid possible confusion with the redirection symbols < and >. See also: istrue, echo System 2 operating environment User's Guide - Internal Commands exists --------------------------------------------------------------------------- Command exists Syntax exists <filespec> This command returns true (0) if a file exists that matches the given file specification, otherwise it returns false (-1). Examples: exists fred.doc exists *.c exists *.* Notes: The primary use of exists is in conjunction with the if statement in xsl program. For example, the xsl segment if exists "database.def" * do nothing else echo "You need to create a database.def file!" echo exit -1 endif would exit with a suitable error message if the file database.def does not exist. See also: if, xsl, $ System 2 operating environment User's Guide - Internal Commands exit --------------------------------------------------------------------------- Command exit Syntax exit [<value>] The exit command will stop execution of an xsl procedure, and return the user to the System2 prompt. If a value is specified, this will be returned to System2 as the return value of the xsl command, zero being returned by default. Examples: exit exit -1 See also: xsl, quit System 2 operating environment User's Guide - Internal Commands false --------------------------------------------------------------------------- Command false Syntax false This command returns the value false (-1). See also: true System 2 operating environment User's Guide - Internal Commands getc --------------------------------------------------------------------------- Command getc Syntax getc The getc command allows a single character to be input from the standard input (the keyboard in most circumstances). It returns a value between 0 and 255 corresponding to the ASCII value of the character that was typed. If the input is from the keyboard (CON:, the default), then the character is echoed on the screen. Example: getc See also: putc, input System 2 operating environment User's Guide - Internal Commands goto --------------------------------------------------------------------------- Command goto Syntax goto label The goto command is for use in xsl procedures, and causes a branch to a part of the program that is labelled with the given label. A label consists of a line in the program that contains a decimal point followed by a space and the label name. See the decr command for a demonstration of goto. Example: goto loop See also: xsl,. ,decr System 2 operating environment User's Guide - Internal Commands if --------------------------------------------------------------------------- Command if Syntax if <command-line> The if command allows commands to be executed only in certain circumstances. The if command is followed by any System2 command line, and it executes all commands up to the corresponding else or endif statement only if this command line returns a value of true (0). This makes it especially useful with the contains, equal, exists, false, istrue, and true commands. Any commands between an else and an endif command are executed only if the command line returns false (non zero). After the endif, all processing carries on as normal. The if command is usually used in two ways, either directly typed into System2, as in if istrue %age}17 ; echo "you can vote" ; echo ; endif which displays "you can vote" if %age is greater than 17 (note the use of the semicolon to separate the commands), or in an xsl program, such as the segment below: if istrue %age}17 echo "you can vote" echo else echo "you can't vote" echo endif Notes: Nested ifs are allowed, provided they are all finished off with a corresponding endif. See also: else, endif, contains, equal, exists, false, istrue, true, xsl System 2 operating environment User's Guide - Internal Commands incr --------------------------------------------------------------------------- Command incr Syntax incr <variable> The incr command will add 1 to the value held in a variable. Examples: incr %count incr %value incr is very useful if used in a loop in an xsl program. For example, the xsl program: set %count=0 . loop echo "Hello" echo incr %count if istrue %count{10 ; goto loop ; endif exit will display "Hello" 10 times Notes: All arithmetic is in two byte integer form; incrementing over 32767 will cause spurious results. This command is equivalent to a two byte form of set <variable>=<variable>+1 See also: decr, set, xsl System 2 operating environment User's Guide - Internal Commands input --------------------------------------------------------------------------- Command input Syntax input <variable> [<prompt>] The input command allows a line of text to be input from the keyboard, and this text is assigned to the specified variable, as if the set command had been used. If the prompt parameter is supplied, then this prompt is displayed on standard output before the user is allowed to input. If no prompt is supplied, then a dash ('-') is output as a prompt. Examples: input %name input %name "Please enter your name>" Notes: If you do not wish a prompt to be output, then use input <variable> "" See also: getc System 2 operating environment User's Guide - Internal Commands istrue --------------------------------------------------------------------------- Command istrue Syntax istrue <expression> This command yields a value of true (0) if the given expression is true, else it returns a value of false. For a description of an expression, see the eval command. The istrue command is very useful if used in conjunction with the if command, as shown in the example below: if istrue %size}1000 ; echo "Size too large" ; endif Examples: istrue %fred+2=%bill-1 istrue %fred See also: eval, equal, notequal System 2 operating environment User's Guide - Internal Commands locate --------------------------------------------------------------------------- Command locate Syntax locate x y The locate command will allow the cursor to be positioned on the screen. The given x and y coordinates begin at 0, and are relative to the top left of the screen. Usually, x should be from 0 to 79 and y from 0 to 24. See also: clear System 2 operating environment User's Guide - Internal Commands ls --------------------------------------------------------------------------- Command ls Syntax ls [-[la]][<filespec>] This command displays a list of all the files that are stored on a disk. Unless the -l (long) qualifier is specified, only the names of the files or directories that match the filespec are output, and no distinction is made between subdirectories and files. If the -l qualifier is given, then the output is of the form: <file status> <file size> <date & time of creation> <name> The file status is given as three characters. An r indicates that the file can be read (always the case), a w indicates that the file can be written to (not read only), and a d indicates a subdirectory. If the -a qualifier is specified, then all files that match the filespec are shown, including system files that are normally hidden from the directory list. After the file list, the number of files matching the specification is shown together with the number of bytes consumed by these files. The optional filespec parameter can be (i) a filename with wildcards, (ii) a disk drive letter followed by a colon, or (iii) a combination of disk drive letter and filename. Examples: ls ls *.c ls -l a:\data\*.bak ls -al c: See also: dir, cd, drive, pwd System 2 operating environment User's Guide - Internal Commands mcat --------------------------------------------------------------------------- Command mcat Syntax mcat <macro> <string> The mcat command will append a string to the end of a macro or variable, and reassigns the resulting string to the macro or variable. An example use of this in an xsl procedure is shown below: * Input full name input %initials "Enter initials>" input %surname "Enter surname>" set %name=%initials mcat %name %surname exit Examples: mcat %fred "abc" mcat %fred %bill See also: set, unset, mkill System 2 operating environment User's Guide - Internal Commands mkdir --------------------------------------------------------------------------- Command mkdir Syntax mkdir <subdirectory> The mkdir command creates a new subdirectory on the disk with the given name. By default, the directory is created within the current directory. This is similar to choosing 'Create New Folder' under the GEM desktop. Examples mkdir user mkdir b:\database\files.dat See also: cd, rmdir System 2 operating environment User's Guide - Internal Commands mkill --------------------------------------------------------------------------- Command mkill Syntax mkill The mkill command will remove all macros and variables. It is equivalent to using unset on each individual macro or variable Example: mkill See also: unset, set, mcat System 2 operating environment User's Guide - Internal Commands mv --------------------------------------------------------------------------- Command mv Syntax mv <oldfilename> <newfilename> The mv command (standing for move) allows files to be renamed. The specified file <oldfilename> is given the name <newfilename>. The contents of the file remain unchanged. No wildcards are allowed. Examples: mv fred.wp fred.doc mv thing.tmp prog.c Notes: Files cannot be renamed across physical devices (ie disk drives), so the command mv a:fred.doc b:fred.doc would not be valid. This command is exactly equivalent to ren. See also: ren, cp System 2 operating environment User's Guide - Internal Commands notequal --------------------------------------------------------------------------- Command notequal Syntax notequal <string1> <string2> The notequal command returns a value of false (-1) if <string2> is the same as <string1>, or true (0) if it isn't. It is intended for use with the if command, for example, if notequal %birdname "puffin" ; echo "Not puffin" ; echo ; endif would print 'Not puffin' on the screen if the variable %birdname was not equal to the string 'puffin'. All tests are case sensitive. Examples: notequal "fred" "fred" returns -1 notequal "Fred" "fred" returns 0 notequal "fred" fred returns 0 notequal "fred" "james" returns -1 notequal fred fred returns -1 Notes: All tests are case sensitive, so "FRED" will not match 'Fred','fred', etc. See also: equal, contains, istrue System 2 operating environment User's Guide - Internal Commands path --------------------------------------------------------------------------- Command path Syntax path [<pathname>] The path command changes the default directory for executable programs (such as bombs) to the given pathname. For example, if you had a utility fred.ttp in subdirectory \bin, then after typing path \bin you could just type fred to execute the program, instead of \bin\fred Note that if any colons(:) or backslashes (\) appear in the program name when typed in to be executed, the default pathname will be overridden See also: pwd System 2 operating environment User's Guide - Internal Commands pr --------------------------------------------------------------------------- Command pr Syntax pr [-[l<x>s<x>i<x>t] [<title>]] [<filespec>] pr is a flexible command that allows a text file to be formatted. The output is of a form particularly suitable for printing. The filespec consists of a filename which can contain wildcards. There are four qualifiers which can be specified, details of which are given below. The output is by default to standard output. l The number following this qualifier specifies the length of a page of output, which is used by the s qualifier. The default is 66. The length is given in printed lines. s The number following the s qualifier specifies the number of lines that are to be left blank at the end of each page (for instance to skip over a page break). The default is 0. i The number following the i qualifier specifies the number of spaces that are to be output before each line of text, ie the left margin indent. The default is 0. t Specifies that a title & page numbers are to be printed. If this qualifier is given, then the <title> parameter must be specified, which is the title. Examples: pr fred.dat The same as cat fred.dat pr -i5 fred.dat Show fred.dat with a left margin of 5 spaces. pr -l70s10i15 fred.dat Show fred.dat with a left margin of 15 spaces, and use a page length of 70 lines, missing the last 10 lines on each page. pr -l60s5t "Data file" fred.dat Show fred.dat on the screen and use a page length of 60 lines, skipping 5 lines at the end of each page, and putting the title "Data file" & the page number at the top of each page. pr -l60s5t "Data file" fred.dat > prn: As above, but send to the printer help index | pr -l70s10 Pipes output of help into pr for formatting. Notes: pr cannot accept input from the keyboard like cat, since it is line orientated. See also: cat, type System 2 operating environment User's Guide - Internal Commands putc --------------------------------------------------------------------------- Command putc Syntax putc <n> [<n> <n> ...] The putc command translates the given number(s), which should be in the range 0-255, into their ASCII character equivalents, which are then sent to the standard output. For example, putc 72 69 76 76 79 displays HELLO on the screen, since ASCII 72='H', ASCII 69='E', etc. One major application of putc is in the writing of control codes. For example, in order to be put into emphasised text mode, most Epson compatible printers need to be sent a sequence of control codes as ASCII characters, namely character 27 followed by character 69 (ESC E). So, to put your printer into emphasised mode, you could type putc 27 69 > prn: See also: getc, echo, cat, pr System 2 operating environment User's Guide - Internal Commands pwd --------------------------------------------------------------------------- Command pwd Syntax pwd The pwd command displays the letter of the current disk drive, and the current subdirectory that you are in. It basically reminds you which subdirectory you are in, if any. Example session: $ pwd Current directory path is A:\ $ drive b $ pwd Current directory path is B:\ $ cd bin $ pwd Current directory path is B:\BIN\ Notes: pwd is a 'Unixism', and stands for print working directory. See also: cd, drive System 2 operating environment User's Guide - Internal Commands quit --------------------------------------------------------------------------- Command quit Syntax quit The quit command will restore the colours to their values before System2 was started, and will return to the desktop or calling program Example: quit System 2 operating environment User's Guide - Internal Commands ren --------------------------------------------------------------------------- Command ren Syntax ren <oldfilename> <newfilename> The ren command allows files to be renamed. The specified file <oldfilename> is given the name <newfilename>. The contents of the file remain unchanged. No wildcards are allowed. Examples: ren fred.wp fred.doc ren thing.tmp prog.c Notes: Files cannot be renamed across physical devices (ie disk drives), so the command ren a:fred.doc b:fred.doc would not be valid. This command is exactly equivalent to mv. See also: mv, cp System 2 operating environment User's Guide - Internal Commands result --------------------------------------------------------------------------- Command result Syntax result The result command displays on the standard output the value returned by the last command executed.System2 commands usually return 0 or more to mean successful completion, -1 to mean error, and -2 to mean that a syntax message was output. Example: result Notes: This command is equivalent to typing echo %result. System 2 operating environment User's Guide - Internal Commands rm --------------------------------------------------------------------------- Command rm Syntax rm <filespec> This command is used to remove disk files that are no longer needed. A removed file CANNOT BE RECOVERED. The filespec parameter can be a single filename, in which case the given file is deleted, or a wildcard, in which case all files that match the specification are deleted. Obviously, this command must be used with great care. If you wish, the command DEL can be used in place of RM. Examples: rm fred.doc rm *.c See also: del, rmdir System 2 operating environment User's Guide - Internal Commands rmdir --------------------------------------------------------------------------- Command rmdir Syntax rmdir <subdirectory> The rmdir command removes an empty subdirectory from the disk. To delete a subdirectory with files in it, the files within the subdirectory must first be removed (using the rm command) before the rmdir command is issued. Examples: rmdir documents rmdir source\c_code See also: cd, mkdir, rm System 2 operating environment User's Guide - Internal Commands set --------------------------------------------------------------------------- Command set Syntax set [<macro>[ = | : ][<value]] The set command controls the assigning of variables and macros, and is a fairly complex command. If issued without any parameters, set will respond with a list of the current values of all system variables, followed by a list of all macros and user defined variables if any exist. Set allows values to be assigned to either system variables, macros or user defined variables. The single parameter consists of a variable name, followed by an = or a : , then the value that the variable is to take. If the separator is an = sign, then an attempt will be made to evaluate the value to a numeric expression (see eval), so, for example, 3*6 would yield a value of 18. However, if the separator is a colon (:), the value will be interpreted as a direct string, so 3*6 would yield a value of "3*6". If a value is being assigned to a system variable, then the separator type is arbitrary: the value is interpreted according to the sort of value the system variable holds. If no value is given, then the specified macro or variable is de-assigned, as with the unset command. Examples: set Produces a list of variables set edit:"a:\bin\me" Make macro edit equal to the string "a:\bin\me" set %fred=%age+20 Makes variable %fred with a value 20 more than the value of %age set %fred:"%age+20" Makes variable %fred equivalent to the string "%age+20" set %fred= De-assign variable %fred Notes: There must be no spaces around the = or : sign. See also: unset, mcat, mkill,incr, decr, eval System 2 operating environment User's Guide - Internal Commands time --------------------------------------------------------------------------- Command time Syntax time [<hh> <mm> <ss>] The time command will display the current time, or will allow the time to be set if the three parameters (corresponding to hours, minutes, seconds) are supplied. The hours are given in 24 hour format (0-23) Examples: time time 7 41 30 time 23 31 28 See also: date System 2 operating environment User's Guide - Internal Commands true --------------------------------------------------------------------------- Command true Syntax true This command returns the value true (0). See also: false System 2 operating environment User's Guide - Internal Commands type --------------------------------------------------------------------------- Command type Syntax type <filename1> [<filename2> ... ] The type command displays the contents of each disk file specified. The filenames cannot contain any wildcards. Examples: type customer.rec type test1.c test2.c test3.c type test4.c > prn: Notes: Pressing CONTROL S and CONTROL Q during displaying a file on the screen will cause the screen to freeze and be released, enabling text to be viewed before it scrolls off the screen. Do not press CONTROL C during output, or else you may be aborted to the desktop. See also: cat, pr System 2 operating environment User's Guide - Internal Commands unset --------------------------------------------------------------------------- Command unset Syntax unset <macro> The unset command allows a macro or variable to be disposed of. The contents and store are lost. Examples: unset %fred unset edit Notes: System variables cannot be unset See also: mkill, set System 2 operating environment User's Guide - Internal Commands xsl --------------------------------------------------------------------------- Command xsl Syntax xsl <filename> [<param1> ... <param9>] The xsl command will execute an xsl program with the given filename. The file must have the extension .XSL. The optional parameters are passed to the program as variables %1 to %9. There can be between 0 and 9 parameters, the number of which is stored in a temporary variable %argc. Examples: xsl dobackup xsl deldir cprogs.c xsl newecho "ABC" 123 ABC123 %fred Notes: This command is exactly equivalent to $. This command cannot be used within an XSL program. See also: $ System 2 operating environment User's Guide - Internal Commands . --------------------------------------------------------------------------- Command . Syntax . <label> The . command is followed by a label which is used by the goto command in xsl programs. See goto for more details. Examples: . loop . do_exit See also: goto, xsl System 2 operating environment User's Guide - Internal Commands $ --------------------------------------------------------------------------- Command $ Syntax $ <filename> [<param1> ... <param9>] The $ command will execute an xsl program with the given filename. The file must have the extension .XSL. The optional parameters are passed to the program as variables %1 to %9. There can be between 0 and 9 parameters, the number of which is stored in a temporary variable %argc. Examples: $ dobackup $ deldir cprogs.c $ newecho "ABC" 123 ABC123 %fred Notes: This command is exactly equivalent to xsl. See also: xsl System 2 operating environment User's Guide - Internal Commands * --------------------------------------------------------------------------- Command * Syntax * <string> The * command completely ignores any parameters that follow it. It is meant for placing comments in xsl programs, like the good old BASIC REM statement. Examples: * This is a load of rubbish * Interesting comments See also: xsl System 2 operating environment User's Guide - External Commands help --------------------------------------------------------------------------- Command HELP Syntax HELP <topic>|FULL Displays help information on the specified topic, or shows the full manual if FULL is specified. A topic of ? gives a title page, and INDEX shows an index to the manual. The file MANUAL. must be in the root directory of the current disk. System 2 operating environment User's Guide - External Commands bombs --------------------------------------------------------------------------- Command BOMBS Syntax BOMBS This produces an exception analysis after a 68000 bomb out. System 2 operating environment User's Guide - External Commands tl50 --------------------------------------------------------------------------- Command TL50 Syntax TL50 This changes the screen to 50 line mode. It is for MONO MONITOR use only, and should be followed by a CLEAR command. See also: tl25 System 2 operating environment User's Guide - External Commands tl25 --------------------------------------------------------------------------- Command TL25 Syntax TL25 The TL25 command restores the screen to a 50 line mode after a tl50 command. It should be followed by a CLEAR command. See also: tl50 System 2 operating environment User's Guide - Internal Commands glossary --------------------------------------------------------------------------- GLOSSARY -------- Directory Either the 'root directory' which is the default, top level directory that contains all subdirectories, and is referenced by the name '\', or a subdirectory Filename The name given to a file on the disk, displayed under it's icon in GEM. Filespec A filename or pathname that can contain wildcards Pathname A filename that also specifies the drive &/or directory where a file lies. The general format is [<drive>:][<directory>\ ...]<file> eg: a:\bin\me or \bin\fred or d: or a:\ or \ Most filenames in System2 can be given as pathnames Stdin,Stdout, Stderr See section on redirection String A string is a collection of characters, numbers, etc. Subdirectory Same as a folder under GEM. A subdirectory has the same format as a pathname. Wildcard A special character - * or ? - used in a filespec, to enable more than one file to be referenced by one filespec. * stands for any number of any character, and ? stands for one of any character. So *.* matches all files, *.doc matches all files with extension doc, a*.* matches all files starting with a, chapt?.doc matches chapt1.doc, chapt2.doc, chaptx.doc, etc.