Documentation for JonDOS CLI Version 1.07 ----------------------------------------- JonDOS is a command line interface (CLI) for the Atari ST/STe/TT computers. This program is considered FREEWARE and may be copied freely providing the following conditions are met; 1) This manual is included unaltered with every distributed copy of JonDOS. 2) No fee is charged for the copy without the author's prior written consent, with the sole exception of duplication costs for public domain and shareware libraries. 3) The program or this manual is not included with any commercial product or publication of any kind without the author's prior written consent. Whilst every care has been taken in developing this product the author makes no warranties of any kind with respect to this manual or the JonDOS program. Any damage or loss incurred accidentally or otherwise by this program or by the use of this program is solely the responsibility of the user. I am always happy to receive comments, suggestions and news of problems with respect to this product, and I can be contacted at this address; Jon Marshall 28 Holbrook Road Stratford London E15 3EA England ---------------------------------------------------------------------- Introduction ------------ JonDOS is designed to be a user-friendly CLI for those who require a CLI to be as small and efficient as possible. Unlike most popular Atari CLIs which take up over 100K of memory, JonDOS takes less than 24k. This makes it ideal for 520 and 1040 ST users. The reduction in size has been accomplished in 2 ways; 1) JonDOS has been programmed in 100% assembly language. This also makes it one of the quickest CLIs available. 2) BASIC-like structures, such as 'for' loops, have been removed because the majority of ST users do not require this from a CLI. JonDOS is not a PC MS-DOS compatible system although it employs common PC commands, such as 'DIR' and 'CD'. JonDOS includes full line editing, command aliases and Mini-MAKE facility. Using JonDOS ------------ JonDOS can be run in several ways. The simplest way is to double-click on the file JONDOSV1.PRG. If JonDOS can find a batch file called AUTOEXEC.BAT in the ** current ** directory or in a directory specified by the PATH environment string (both of which are explained more fully later) JonDOS will execute that. You can also install JonDOS under the 'Install Application' menu on the desktop. This will allow you to pass a program name or a batch file name to JonDOS which will be executed instead of AUTOEXEC.BAT. Finally you can rename JonDOS to .TTP or .GTP (Gem Takes Parameters. This works like a .TTP but the program will be run as a GEM program as opposed to a TOS one. It is available only on Mega STe/TTs or NeoDESK). If you run JonDOS as a .TTP then the first characters entered in the command line box MUST be '-T ' - this will ensure that JonDOS will not attempt to access GEM. The command line entered will be executed as if you typed it in at a JonDOS prompt. After JonDOS has finished executing its initial command, file or AUTOEXEC.BAT you will be be taken to the user prompt. This is the heart of JonDOS and the place where you enter your commands. The user prompt displayed is the current disk drive and directory, e.g. A:\JONDOS> Commands are typed in the form; > [space] JonDOS provides a set on built-in commands which are mainly for disk maintenance and configuring your Atari to your specifications. A list of the built-in commands can be shown by typing HELP. It does not matter whether the commands are typed in upper case, lower or a mixture of the two, but for this manual commands shall be denoted by upper case. If the command you type in is not built-in JonDOS will perform a disk search to try and locate a program with that name. If only the filename was given, e.g. 'FRED.PRG', the search will start with your current directory and then proceed through the directories listed in the PATH environment variable (described later). If you pass a full pathname, e.g. 'A:\PROGS\FRED.PRG' JonDOS will search only for that file. If the command is not built-in or a program cannot be found you will be issued an error message such as; 'Command > FRED.PRG < not known or found'. The extension of a program need not be supplied - JonDOS will automatically search all valid ST/TT extensions for you. E.g. 'DEVPAC.PRG' could be run merely by typing 'DEVPAC'. The search is performed in this order; 1) .TTP ( Highest priority ) 2) .TOS 3) .BAT ( Batch files ) 4) .GTP 5) .PRG 6) .APP ( Lowest priority ) If you supplied the extension and it was not one of the above types JonDOS will treat the program as a .PRG. If you have 2 files with different extensions, e.g. a 'FRED.TOS' and 'FRED.PRG', by default JonDOS will execute 'FRED.TOS'. You can force JonDOS to execute 'FRED.PRG' by including the '.PRG' in the program name. If the program's extension was a .TTP or .TOS the program's output will be shown on the screen below your command. If the program's extension was a .PRG, .APP or .GTP the screen will be cleared to the standard ST GEM background and the mouse pointer will be made visible. People who 'type ahead' should be aware that your ST can easily get confused with keypresses when it switches from a GEM (mouse) orientated system to a TOS (cursor) orientated one. It is possible that your ST might lose or 'misplace' a few kepresses. You can force a program to be run in TOS or GEM mode by the commands TOS and GEM. The choice can be restored to JonDOS with the DEFAULT command. On termination of the program you will be returned to JonDOS. The on a command line is a string to be passed to the executing program or command. It is identical to the string you would type when running a .TTP from the Desktop. Most JonDOS commands, .TTP and .GTP programs require arguments. If a GEM program can be installed under the 'Install Application' menu of the Desktop then it too will allow arguments to be passed to it in the form of files to be loaded. You can leave JonDOS by typing EXIT or QUIT Limits ------ The entire command line entered is not allowed to exceed 256 bytes. Any parameters passed to programs or commands cannot exceed 126 bytes. Line Editing ------------ JonDOS employs a full line editor with the following pre-defined keys. Arrow Left/Right Move Cursor Left/Right on the line Shift-Left/Right Word Left/Right Control-Left/Right Start/End of line Backspace Erase character to left of cursor Delete Erase character under cursor Control-Backspace Erase from start of line to cursor Control-Delete Erase from cursor to the end of line JonDOS also provides the Wordstar compatible keys; CONTROL-G Same as DELETE CONTROL-Y Delete ENTIRE line CONTROL-E Same as arrow Up CONTROL-X Same as arrow Down CONTROL-A Word left CONTROL-S Arrow left CONTROL-D Arrow right CONTROL-F Word right CONTROL-M Return Commands entered are stored in a 1500 byte 'recall' buffer. They can be recalled at will by pressing the Up/Down arrow keys. The following special commands also concern the recall buffer >RE >RE number >RE string RE will display all commands stored in the recall buffer. The display might look something like this; Recall buffer; 1: cd \freeda\jon 2: dir 3: devpac file.s Command 1 would represent the last command entered, 2 - the command before that, and so on. The commands can be recalled (brought to the current editing line) by specifying its number or the first few letters of the command. E.g. RE 2 would recall the DIR command RE d would recall the DIR command RE dev would recall the DEVPAC command Should you enter a number that is out of range or a string which could not be found JonDOS will 'beep' you and will not allow you to enter the command. In the case where a string entered matches two or more commands, the most recently entered command will be recalled. The differences between upper and lower case and trailing spaces are significant to RE commands. RE commands and blank lines are never entered in the recall buffer. . If two or more consecutive, identical commands are entered only one copy will be placed in the recall buffer. If the recall buffer fills up, which for a typical user will happen after 60 or more commands, commands at the bottom of the buffer will be removed to make room for new commands. The GEM file selector box can be displayed by pressing CONTROL-Ins. If you click OK or select a file, the filename (including the directory) will be copied to the cursor position in the line you are editing. Function keys can be defined with the SET KEY command (described later). SETS and SHOWS -------------- SETs provide a convenient way of configuring your machine to your taste. JonDOS divides SETs into two types, internal and external. Internal SETs comprise of command substitutions (COM), environments (ENV) and function key equivalents (KEY). They are set in the following way; >SET type name [=] [string] The '=' is optional. If you do not include the 'string' the set will be deleted. Command substitutions simply make one command equal to another. For example: MKDIR is the JonDOS command to create a new directory. People who are more used to the command MD could use the following line; >SET COM MD=MKDIR If you now entered the command MD, JonDOS would automatically convert it MKDIR. >SET COM MD= would remove the definition MD. SET COM can also be used to quickly find programs without having to create small batch files or have JooDOS search through a large PATH environment. E.g. >SET COM FCOPY=C:\UTILS\COPIERS\FCOPY_3.PRG would execute c:\utils\copiers\fcopy_3.prg on typing fcopy. JonDOS would not have searched the PATH environment because the full pathname was supplied. Environments are a set of strings which are passed to executing programs. This allows you to give all executing programs details of your machine configuration in a single go. The most used environment is PATH - this tells executing programs where to find files it may need. JonDOS also uses this environment to search for files you've requested to run. E.g. >SET ENV PATH=C:\DOS;F:\MUSIC; Multiple directories are separated by a semi-colon ';'. Please note that with * environments * the case is important - 'PATH' is not the same is 'path'. Currently JonDOS will only pass the first 512 bytes of environment strings to programs. Function keys can be set with SET KEY, and are in the form >SET KEY [A-|S-|C-]F1..10 [=] [string] where A- denotes and ALT assignment, S- for SHIFT and C- for CONTROL. Examples; >SET KEY A-F5 = cd a:\text >SET KEY F2 = DIR The character '`' (the apostrophe on the TOP row of the ST keyboard) is used as a place-holder for RETURN. This allows multiple commands to be joined together in one keypress and the automatic execution of commands. E.g. >SET KEY C-F10 = print jones.txt`dir` would print the file 'jones.txt' and then perform a DIR on pressing CONTROL-F10. All internal SETs are stored in a 2500 byte buffer. You will be issued the error message 'Out of memory' should this buffer fill up, though I doubt this will happen to the vast majority of users. SHOW is used to display previously defined data and is best explained by some examples. >SHOW ENV PATH would show the environment PATH >SHOW ENV would show ALL environments >SHOW would show all keys, environments and commands. External SETs directly configure aspects of you ST. Currently these consist entirely of colour control. >SET PEN xx Set foreground text pen to xx (0-15) >SET BACK yy Set background text pen to yy (0-15) >SET COL A RGB [rgb ...] Sets pen A to RGB, A+1 to rgb, etc. Usually BACK has a value of 0 and PEN has a value of 15. SET COL allows one or more colours to be set at once. This allows the entire colour palette to be set in one go. E.g. >SET COL 0 000 Would set the background to black >SET COL 0 000 333 555 777 would set the first 4 colours >SET COL 12 700 733 755 777 Would set colours 12-15 External SETs cannot be SHOWn. Batch Files ----------- Batch files are a sequence of commands stored on seperate lines in a file. The file must be in the standard ASCII Carriage return/line feed format which is created by most text editors. You can pass arguments to batch file which can be accessed from within the file by the special macro %. E.g. You could have a batch file called SETPEN.BAT which sets the foreground and background pens; SET PEN %1 SET BACK %2 You can run the batch file by typing >SETPEN 0 15 The commands in the batch file would then be expanded to; SET PEN 0 SET BACK 15 The first 9 argument strings can be reached with %1 to %9 %^ denotes the entire argument line passed to the batch file. %\ denotes the current directory at the time batch job was executed. All parameters passed to a batch file and the batch file directory are stored in the 2500 byte SET buffer and are removed when the batch file terminates. This should not cause a problem unless your SET buffer is nearly full. It is possible to call batch files from within other batch files. Up to 5 batch files can be opened at once in this manner. Should you run a command or program which returns a value to JonDOS, as programs tend to do if they encounter a serious error, JonDOS will present you with an option to terminate the batch file. You might see a display such as; Program returned with code -1 Terminate batch job? (Y/n) If you answer the prompt with a key other than 'N' or 'n', JonDOS will terminate the batch file. A batch file will be closed at either the end of the file or at an EXIT command. This will take you back to the previous batch file opened or the prompt if it is the only one opened. STOP will close all batch jobs and return you to the prompt. QUIT is equivalent to a STOP followed by an EXIT. It will cause JonDOS to be terminated without return to the prompt. Shell Mode ---------- JonDOS can be called from the programs which it executes. Most notable of these are the HiSoft editors which feature a 'Run with Shell' option. Commands can then be passed back to JonDOS for it to execute. If no command is given you will be presented with the user prompt, type EXIT or QUIT to return to the running program. If the program features a 'Run Shell with TOS/GEM' switch it is advisable to set this to GEM. Be careful about stacking too many programs in memory when using this feature. Internal Commands ----------------- Internal commands, as with TOS programs, can have their output suspended by pressing CONTROL-S and restarted with CONTROL-Q. They can also be stopped with CONTROL-C, though you should be careful when using it. Helpful bits: Internal commands can have their output redirected to a file or other device. The '>' character denotes a file to create, '>>' denotes a file to append output to. E.g. DIR *.S >NEW.LIS DIR *.T >>APPENDED.LIS JonDOS does not currently support the forceful redirection of output from another programs. Some commands have switches which can be set. These switches must always be between the command and the first non-switch argument. A switch is denoted by a '-' or a '/' followed by a letter, e.g. '-c'. This manual denotes switches by '-' and uses lower case letters, although JonDOS does not distinguish between upper and lower case. Most disk commands offer a '-c' switch forces confirmation to be required on each file before performing its operations. For every file they process you will receive a prompt such as; Delete FILE.C ?(yes/No/all/quit) YES will perform the operation on this file only. NO will skip this file. This is the default answer - if you press any key other than Y, A, Q or CONTROL-C the file will be skipped. ALL will perform the operation over this file and all subsequent files (i.e. confirmation is turned off). QUIT will stop the command. If you have answered YES to any file that JonDOS has not completed its actions on then those actions will be concluded before returning you to the user prompt. There is also an unseen option, CONTROL-C, which will stop the command without further disk access and return you to the user prompt. In the case of COPY, some files may not be written correctly if you use this option. JonDOS supports the wildcards '*' and '?'. List of Internal Commands =========================----------------------------------------------- Command: ! Description: Any line beginning with this character is ignored. This allows comments to be placed in batch files and is a alternative to REM. Examples: ! this is a comment. See Also: REM ------------------------------------------------------------------------ Command: ACC Parameters: None Description: Allows the user to select desktop accessories. Select 'Return' under the 'JonDOS' menu to return to the prompt. ------------------------------------------------------------------------ Command: BELL Parameters: None Description: Output the ST bell if this function is enabled at the operating system level. ------------------------------------------------------------------------ Command: BIG Parameters: None Description: Force the text to be drawn in a 8x16 monochrome font. The conjugate function, SMALL, can be used to get 50 lines on a screen in ST High rez. See Also: SMALL ------------------------------------------------------------------------ Command: CD Parameters: Directory Description: Changes the current directory. Examples: CD \ - Change to root directory CD FRED - Change to sub-directory 'FRED' CD .. - Move back one directory ------------------------------------------------------------------------ Command: CHKDSK Parameters: Optional drive Description: Displays details about the current drive, such as the amount of free disk space. Caveats: This command can take a long time on TOS versions prior to 1.4 Examples: CHKDSK c ------------------------------------------------------------------------ Command: CLS Parameters: None Description: Clears the screen to the background text colour. ------------------------------------------------------------------------ Command: COPY [-c] Parameters: Source search path, optional destination path Description: Copies the files from the source search area to the destination. If no destination area is specified the files are copied to the current directory. COPY uses all available memory to minimise the number of disk swaps required on floppy based systems. If '-c' is specified COPY will ask confirmation on each file before reading copying it. It is advisable not to press CONTROL-C at the confirmation prompt - this could leave some files unwritten or partially written. Should the disk you are copying to run out of space it is probable that the last file processed by COPY will only be partially written. Examples: COPY -c *.c a:\ Copy all files with extension .C to a:\. Confirmation will be asked on every file before it is copied. COPY b:\JON*.* Copy all files starting with the letters 'JON' to the current directory. See Also: DEL, RENAME ------------------------------------------------------------------------ Command: DEFAULT Parameters: None Description: Forces JonDOS to decide whether a program is of a TOS or GEM type by its extension. .TOS and .TTP are considered TOS types .PRG, .APP and .GTP are GEM types See Also: GEM, TOS ------------------------------------------------------------------------ Command: DEL [-c] Parameters: File search mask Description: Delete files specified by the search mask. Examples: DEL A:\*.* Delete all files on the root directory of A. This will NOT delete all files on the disk as it does on PC compatibles. DEL -c *.s Delete with confirmation file with the extensiin .S See Also: COPY, RENAME ------------------------------------------------------------------------ Command: DIR [-w] [-p] Parameters: File search mask Description: Lists all files and directories in the search mask. -w forces a compressed mode where 1 file is listed every 20 characters as opposed to the standard 1 per line. -p causes the display to be halted after the displaying of a screen of information, usually 24 lines. JonDOS will automatically add wildcards such as *.* Examples: DIR a:\ List root directory of A DIR a: List current diretory of A DIR .acc List all files or folders with extension .ACC DIR -w JON* List all files or folders starting with first 3 letters = JON, in compressed mode. ------------------------------------------------------------------------ Command: DRIVEB Parameters: None Description: Toggles the recognition of an external floppy drive. Useful if you forget to switch your drive on and do not wish to reboot your computer. Please note that the ST was designed to be turned on AFTER connecting and powering up periphals, so I do not encourage the use of this command. ------------------------------------------------------------------------ Command: ECHO Parameters: String to be printed. Description: Echoes a string to the screen. The special strings @ON and @OFF (upper case only) switches on or off the automatic echoing of batch file instructions. See Also: TIME, WAIT ------------------------------------------------------------------------ Command: EXIT Parameters: None Description: If used from within a batch file EXIT causes the batch file to be closed. If used from the user prompt JonDOS will terminate. ------------------------------------------------------------------------ Command: GEM Parameters: None Description: Force all programs to be run in GEM mode. See Also: DEFAULT, TOS ------------------------------------------------------------------------ Command: HELP Parameters: None Description: Gives a list of the internally available commands. Note that only a list is displayed and you should refer to this manual for explanations. ------------------------------------------------------------------------ Command: MAKE Parameters: destination file ~ source file(s) ~ make command Description: MAKE is a command based file maintainer which is generally used by programmers to automatically compile, assemble and link files. If you consider the case where you have some source files which when assembled make a .PRG file. Should you change any of the source files the .PRG will be out of date - you would need to re- assemble. MAKE can automatically do this by detecting if any of the source files have changed since the last time you made the .PRG file - it compares the time and date stamps on the source files with that on the .PRG. Caveats: Requires the system clock to be accurate. All parameters have to be less than 126 characters, so it is best to split a large make command into several smaller ones. Due to the number of parameters required it is advisable to use this command from a batch file. Examples: MAKE fred.prg ~ file1.s file2.s ~ build fred - The command 'build fred' will be executed if file1.s or file2.s have been altered since fred.prg was made. MAKE ste.o ~ ste.c header.h list.h ~ lc ste - The command 'lc ste' will be executed if ste.c, header.h or list.h have been altered since ste.o was made. ------------------------------------------------------------------------ Command: MEM Parameters: None Description: Returns the largest system and alternative (fast) memory blocks available. ------------------------------------------------------------------------ Command: MKDIR Parameters: directory Description: Create a new directory. Examples: MKDIR a:\folder MKDIR source 'source' will now be a sub- directory inside your current directory. ------------------------------------------------------------------------ Command: PRINT [-c] [-f] Parameters: List of file masks to print Description: PRINT outputs a list of files to the printer. -c will request confirmation on files before printing. -f causes a form feed to be printed after every file. Caveats: PRINT uses only a small internal buffer. The ST will be held up while the files are printing so this command can take some time to execute. I suggest the use of a print spooler (available from all good public domain libraries) to avoid this. Examples: PRINT -f -c *.c *.s Causes all files with the extension .C and .S to be output to the printer with form feeds and confirmations. PRINT -f output a form feed. See Also: TYPE ------------------------------------------------------------------------ Command: QUIT Parameters: None Description: Closes all batch jobs and terminates JonDOS See Also: EXIT, STOP ------------------------------------------------------------------------ Command: RE Parameters: Optional name or number Description: JonDOS uses a 1500 byte recall buffer to stores commands. RE is used to interrogate this buffer. See the main body of text for a full description. ------------------------------------------------------------------------ Command: REM Parameters: None Description: This command is ignored. It allows comments to be placed in batch files and is a psuedonym for "!". Examples: REM this is a comment. See Also: ! ------------------------------------------------------------------------ Command: RENAME [-c] Parameters: Source file mask, destination mask Description: Give files a new name. They can be moved to other directories provided they are on the same drive. -c enforces confirmation on all files. Examples: RENAME jon*.* fred\*.s Rename all files beginning with the letters 'JON' to the sub-directory 'FRED', giving them all the extension '.S' See Also: COPY, DEL ------------------------------------------------------------------------ Command: RMDIR Parameters: Directory Description: Remove a directory. Caveats: On early STs, if the directory has just been created it may take two RMDIRs to remove it. RMDIR will fail if the directory has any files in it. See Also: MKDIR ------------------------------------------------------------------------ Command: SET Parameters: set type, something to set Description: SET configures items on your machine. See the main text for a full description. Caveats: An internal SET executed while JonDOS is processing a function key press will cause the function key press to be terminated. i.e. >SET KEY A-F10 = SET ENV PATH=...`SET ENV LIB=...` will not work properly on pressing ALT-F10 See Also: SHOW ------------------------------------------------------------------------ Command: SHOW Parameters: Optional type and string Description: SHOW displays the internal SETs. See the main body of text for a full description. See Also: SET ------------------------------------------------------------------------ Command: SMALL Parameters: None Description: Small causes text to be output in the 8x8 font. This enables monochrome and TT users to get 50 lines of text on a screen. See Also: BIG ------------------------------------------------------------------------ Command: STOP Parameters: None Description: STOP will terminate all batch jobs. If you are running JonDOS from within a shell only those batch jobs opened since the shell started will be terminated. See Also: EXIT, QUIT ------------------------------------------------------------------------ Command: TIME Parameters: Optional string Description: TIME displays the current date and time. If a string is present that will be printed first. Examples: TIME It is now: Would display something like. It is now: Wednesday July 24, 1992 12:43:02 PM Caveats: It is advisable to leave a trailing space at the end of the string. The STs internal clock can only work in 2-second increments. See Also: ECHO, WAIT ------------------------------------------------------------------------ Command: TOS Parameters: None Description: Force executing programs to be run in TOS mode. This is useful for programs with a .PRG extension which really do not use GEM features. See Also: DEFAULT, GEM ------------------------------------------------------------------------ Command: TYPE Parameters: Filename Description: TYPE will output a file to the screen. The display can be halted with CONTROL-S, restarted with CONTROL-Q and terminated with CONTROL-C. See Also: PRINT ------------------------------------------------------------------------ Command: VER Parameters: None Description: Outputs TOS and JonDOS version numbers. ------------------------------------------------------------------------ Command: WAIT Parameters: Optional string Description: WAIT prints the string, if present, and then waits for a keypress. Example: WAIT Press any key to continue... See Also: KEY, TIME =========================================================================