                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 ibility ibility ibility ibility                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 ge 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 <arguments> 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

=========================================================================

