

                                Command Control
                                ===============


Documentation for  !ComndCTRL application version 2.60 18-Jun-1998,
requires RISC OS 3.1 or later.

Issue: 2.60 18-Jun-1998, replaces:      0.10 10-Jul-1990
                                        0.90 30-Jul-1990
                                        1.00 31-Aug-1990
                                        1.01 18-Jun-1991
                                        1.10 22-Apr-1992
                                        1.11 23-Nov-1992
                                        2.00 01-Feb-1994               
                                        2.50  04-Apr-1994     
                                        
Author: David J Ruck

Copyright  DEEJ Technology PLC 1990-1998
 


Overview
========


The Command Control application (!ComndCTRL) is designed to provide an  easy
to use and consistent RISC OS front end to a wide range of module  *commands
and command line based programs.

The aim being to replace the typing of long command strings and path names 
at the command line prompt, with the intuitive RISC OS file dragging and 
menu selection operations.

In this document a command is name of something that can be typed at the 
operating system prompt. It can be a command provided by a module, the  name
of a program or obey file, but not an application.

!ComndCTRL allows any number of command to be accessible from the icon 
bar at one time, each having its own icon and menu.

When typing in a command at the operating system prompt, several different 
different parts of the command must be assembled (according to its syntax)
in  order to make the whole command string, these are described below along 
with how !ComndCTRL can help in this process.

Firstly if the command is not from a module and is not in the current
directory  or Run$Path, the full path to the command must be given each
time.  !ComndCTRL will store this path so that the command can be run
without  having to set the current directory.


Parameters
----------
After the path and the command names can come a number of parameters to  the
command, only some of which will be needed each time. Parameters are of 
three types  flags, input files and output files. !ComndCTRL allows up to 10 
parameters in any combinations of the three types.

Flags (sometimes call options) are usually of the form -c or -list are used 
to switch on or off various features of the command. They may be followed by 
a value e.g. -lines 100. !ComndCTRL allows the selection of flags and 
values from easy to use menus. Each flag parameter allows a number of flags 
to be placed in the command, or to restrict the choice to one from a group.

Input files, i.e. existing files that the command process in some way, can
just  be dragged onto the commands icon, removing the need to type in long
path  names. The file types that will be accepted can be restricted so that
commands  are only given files that they can cope with. If the command
requires more  than one input file each can be dragged to the icon in turn
and the command  will be automatically run when enough input files have been
provided. A  selection of files can be dragged from a filer window, in which
case all the  files will be delivered to the command, causing it to run
every time it has  received the correct number.

Output files are file generated by the command while running, a standard 
RISC OS saver box is used to obtain the name for each output file, so again 
the need to type in full path names is removed. A command may have any 
number of output files. When the command is run a choice of multitasking or
single tasking is  available, and textual output from the command can be
stored in a window and  later saved to a file. For further information see
the section Running  Commands later in this document.



Using !ComndCTRL
================


To start
--------
To start,  double click on either the !ComndCTRL application or on any 
command configuration (type 'ComndCFG') file after !ComndCTRL has been 
seen by the filer.

An icon will then appear on the icon bar with the name of the command 
underneath or "<Command>" in grey if you double clicked on the application, 
this signifies a new blank command ready to be configured.

More commands can be installed by double clicking on any command 
configuration files (note, not by dragging to one of the icons), only one
copy  of the program is held in memory.

Before explaining how to use command control with existing commands, it 
will be useful to discuss the setting up of a new command to become familiar 
with the terms used, and to see how the executable command string is formed 
from its flag and file parameters.


Setting up a command
--------------------
To enable a new command to be used or to alter an existing one, select the 
configure option from the commands menu. This can be found by clicking the 
menu button of the mouse over the commands icon on the icon bar.

Command name:             The name of command, which should be the name of a
                          module *command or  the leaf name of a program may
                          be entered in the name field. Only 10  characters
                          are allowed so in the case of long module commands
                          abbreviate the  name with a dot after the ninth
                          letter.

OK:                       The OK button must be pressed after any alterations
                          to setup dialog box, to  allow the program to
                          update its internal state, and for the command to
                          be used.  The window close icon has the same
                          effect, i.e. any changes will be applied.

Path:                     If your command is a program rather than a module
                          command, and it is not  accessible via your
                          Run$Path you may wish to give it a filing system
                          path.  This is done by clicking on the box to the
                          left of the word path so that a tick  appears, the
                          path name (excluding the final dot) can then be
                          entered into the  box to the right. The path can be
                          removed by clicking on the path box again. Path
                          variables can be used as well as absolute paths,
                          e.g. <Prog$Path>
                          File system abbreviations can be also used,
                          e.g. '%' for the current library.

Memory min & max:         The values entered in the memory maximum and memory
                          minimum box  determine the amount of application
                          memory given to a command. They are  used in a
                          *WimpSlot before the command is run, see the RISC
                          OS User  Guide for further details. 
 
                          Experimentation may be necessary to find the
                          correct values for different  programs. Most
                          commands provided by modules do not require
                          application  memory and zero can be entered in
                          these fields.  

Task and Window options:  Clicking on the popup menu icon will lead to a
                          dialog box allowing the type of task used to run
                          the command, and the type of window in which output
                          is placed to be set up. The dialog is explained
                          fully below.

Flag, In, Out:            Commands may have up to ten parameters of three
                          different types; flags, input  files and output
                          files, which determines what is placed after the
                          command  name when it is run.

                          The order and types of parameters are dependant on
                          the syntax of the  command. Documentation on the
                          command should be studied to allow the  syntax of
                          the command matched with the facilities offered by
                          !ComndCTRL.

                          To select the type of parameter, click in the
                          relevant radio icon. It may appear  as a round or
                          diamond shaped icon, depending on your machines
                          setup.
 

Name:                     The name box contains the name of the parameter
                          which will appear on the  commands icon bar menu,
                          you may alter it from the default names given on 
                          creation. In the case of input files the name will
                          have a number after it, this  determines the order
                          in which files dragged onto the commands icon will
                          be  placed in the parameters. The number will
                          change if you alter the parameter  type of a lower
                          numbered input file.

Setup:                    To the right of the name is an icon which will pop
                          up another dialog box for  further configuration of
                          the parameter, as described below.


Task and Window Options
-----------------------
This dialog effects how the command will be run and what sort of window its 
output will appear in.

Multi-tasking:            Running a command as multi-tasking will allow
                          other desktop applications to  continue running at
                          the same time as the command. It is similar to
                          running the  command from the prompt within a
                          standard RISC OS task window (which  can be
                          brought up by pressing CTRL-F12).

                          Running multi-tasking is suitable for most
                          commands which produce output,  but not ones which
                          use graphics or commands that must be run outside
                          the  desktop. It is not recommended for certain
                          filer operations such as  *checkmap or *format.

Multi-tasking with input: This option also runs the command in a
                          multi-tasking manor with the addition  that input
                          may be given to a command which requires the user
                          to type  something (e.g. *GOS). While the command
                          is running clicking on the  window will cause a
                          caret to appear and characters typed at the
                          keyboard will  be given to the task.

                          The standard multitasking option should be used in
                          preference for command  which don't need input, as
                          the window handling is quicker and more suitable 
                          for large amounts of output.

Single Tasking:           Running a command single tasking will cause all
                          other applications on the  desktop to stop until
                          the command is finished. It is of most use with 
                          commands that execute quickly without producing
                          any output (e.g. *LIB). If  any output is produced
                          it will appear in a static (non movable) window.

                          Single tasking can also be used to run programs
                          that take over the whole  screen and use graphics
                          etc, as long as they return to the desktop cleanly 
                          afterwards.

Confirm:                  If your command performs a destructive action or
                          generally requires a  complex set of parameters,
                          you may wish to be asked for confirmation before 
                          running the command, if so click on the confirm
                          box. When the command is  run a window will appear
                          showing the full command and giving the 
                          opportunity to run or cancel the command.

Run in minimised window:   Instead of the full sized output window thisClose
                           window after running option for commands that
                           take a long time to  execute but produce little
                           output, this will enable the state of the command
                           to be seen while not taking up much room on the
                           desktop.

Close window after         If you do not wish the output window to remain
running:                   on screen after the command  has finished
                           running, this option can be used. It is useful
                           for commands that print simple progress
                           information which can be discarded after running.
                           
Only if empty:             Allows the window to close only if there has been
                           no output from the command.                           


Flags Parameter Dialog
----------------------
A flag type of parameter is used to hold one or more flags or options which
the  command requires. Flags are usually of the form two main forms but can
be  any textual strings.

The first form of flags is a set of options form which one or more can be 
chosen, a commands syntax may specify flags as   -file -notabs -f -c   etc.
The flags parameter should contain a list of the possible flags, more than 
one flags parameter can be used to group similar flags, and enable just one 
from a group to be chosen.

The other form is a prefix flag flowed by a value, and example of this
syntax is   -bpp <value> where <value> is 1,2,4   etc. The flag prefix field
should be  used to hold the flag, and the flags field used to give a range
of possible  values. The user can chose other values using the menu as
described later.

Enter flags:               In the bottom box any flags, option or value
                           strings may be entered, each  separated by a
                           space. These will appear as individual entries on
                           the commands  parameter sub-menu. Any number of
                           flags can be entered up to 224 characters  in
                           total.

Flag prefix:               If the parameter is a -flag value form, the -flag
                           (keyword) part should be  entered by clicking on
                           the box to the left so that it is ticked, the
                           keyword can  then be entered in the box to the
                           right. If there should be a space between the 
                           keyword and the value, it must added to the end.
                           If no values are chosen when  the command is run
                           the keyword part will not be used.

Exclusive selection:       When set this will only allow one flag to be
                           selected from the list of flags.  When unset any
                           number of flags can be selected. The -flag
                           <value> form  usually requires this so as to
                           prevent more than one value be used.

No spaces in command:      If set the program will not put spaces between
                           any selected flags when the  command is run. This
                           enables parameters such as   -fcv   instead of
                           -f -c -v   (using '-' as the flag prefix). 


Input & Output files
--------------------
An input file parameter is a file which the command will use when run, the 
name is obtained by dragging a file onto the commands icon on the icon bar.
An output file is the file used for output from the command, the name is 
obtained from a standard RISC OS saver box when the command is run. For
either an input file or an output file the file setup dialog box is used.

Prefix:                   If a prefix flag is required immediately before
                          the filename, click on the prefix  box and enter
                          the flag in the box to the right. If a space is
                          needed before the  filename it must be entered as
                          part of the prefix.

                          e.g. the commands syntax calls for either;
                                  -f <filename>  or
                                  -f<filename>

                          If your commands syntax asks for a comma separated
                          list of input files, set the prefix flag to a comma
                          (only, no spaces) on the second and subsequent input 
                          files to achieve this.
                          e.g.    -f<file1>,<file2>,...

Default name:             The default name is useful on output files, as it
                          will appear as the leaf name in  the RISC OS saver
                          box on running the command. On input files it will
                          be  overwritten by the name of the file dragged
                          onto the icon unless it is selected  on the menu
                          (see later).

File types allowed:       The file type fields on an input file parameter
(Input files)             will determine what file types  the command will
                          recognise for this parameter when dragged onto its
                          icon. Files of other types will be ignored.

                          All Types:  will allow all types of regular files,
                                      i.e. not applications and  directories.

                          Dir or App: means that directories or application
                                      directories my be used. This  can be
                                      selected with or without all types.

                          The last option is for a user selectable file type
                          which you enter in the box to  the right, either
                          as a hex number (e.g. 'FFF' or '&FFF') or a
                          textual name (e.g.  'Text' or 'DrawFile') if it is
                          recognised by the machine. Only files of this type 
                          will be recognised when dragged onto the icon.

File types allowed:       For output files these fields determine the type
(Output files)            of the file produced by the  command, the file
                          type will be set after the command has finished
                          running  even if the command does not do this for
                          itself. 

                          As input:  causes the type of the output file to
                                     be taken from the first input file 
                                     given to the command, useful for
                                     commands which can perform a processing 
                                     operation on several types of file.

                          Directory: this option should only be used for
                                     commands which produce a  directory as
                                     output e.g. *CDIR.

                                     Note some versions of RISC OS may not 
                                     display a directory icon in the saver
                                     box when using this option.


OK:                       To finish the file setup click in the OK box. If
                          you have entered a bad Hex  value or unrecognised
                          name in the user file type box, an error dialog
                          will be  displayed and the file setup will remain
                          on screen.


Input/Output redirection
------------------------
Under the parameter fields of the command setup dialog box are the Input and 
output redirection fields.

If input redirection is used any characters the command would normally ask 
for from the keyboard are taken from a file. Setting up the input
redirection  file is identical to that for an input file parameter described
above. If output redirection is used anything normally printed on the screen
by the  command is sent to a file. Setting up the output redirection file is
identical to  that for an output file parameter described above.

If the output of a command which is running in a multitasking window can be 
saved to a file without using output redirection by using the window menu. 
Output redirection can be used when it desired to keep any control
characters in the output which would be filtered out by the task window.


The Command Main Menu
---------------------
Each command has its own icon installed on the icon bar, clicking the menu 
mouse button over it will display the command menu. The entries are 
described below.

Information:              Displays program information and version number.

New:                      Creates a new command, installing a new icon on
                          the icon bar with the name  "<untitled>" below it.
                          The new command is ready to be set up as 
                          described in the previous section.

Run:                      This entry runs the command with the current flags
                          and input files, see the  section on Running
                          Commands below.

Configure:                Brings up the configure command dialog box, see
                          the Setting up a Command  section.

Save:                     The save option brings up a standard RISC OS saver
                          box to save all the  command's configuration
                          information.

                          Commonly used flags and filenames may be selected
                          and this information will  also be saved.

                          The file is of type ComndCFG (&BAE), and can be
                          reloaded by double clicking  on it in a filer
                          window, but not by dragging onto another
                          !ComndCTRL icon.

Parameters:               If the command has any parameters the names of
                          each will appear in the  section of the menu
                          between the dotted lines.

                          A sub menu is provide for each  parameter
                          described below. 

Remove / Remove All:      The last entries on the menu are used to remove
                          the commands from the icon  bar, if it is the last
                          command the command control application itself
                          will exit.

                          Any windows and memory allocated to multitasking
                          commands will also be  freed by the removal. Use
                          the Remove All option to quickly exit the program 
                          when many commands are loaded.


Parameter menus
---------------
The sub menus for each for the different types of parameter are described 
below.

Flags sub-menu            If the parameter is a flag type the sub menu will
                          contain entries corresponding  to all the flags
                          entered in the flag setup dialog box. In addition,
                          at the bottom of the sub menu is a writable entry
                          which you  can use to quickly enter a flag which
                          is not displayed above, or a numeric  value to be
                          used in addition to a flag. 

                          Using select mouse button (or adjust to keep the
                          sub menu on the screen) the  flags can be selected
                          or de-selected. Only selected flags, shown by a
                          tick, are  included in the command when run, The
                          writable flag must also be selected to  be included.

                          If a flag prefix is used for this flag parameter
                          it is not shown the sub menu but will be included
                          in the command if one (or ore) of the value flags
                          is selected.

                          If exclusive selection has been set on the setup
                          dialog only one flag may be  selected at a time.
                          If no spaces is used then no spaces will be put
                          between each  selected flag.

                          It is also perfectly valid to have no selected
                          flags, in which case nothing from this parameter
                          will be given to the command.

Input/Output files        For a input/output file or input/output redirection
sub-menu:                 type the sub-menu will have  just one entry
                          containing a filename. This will either be the
                          default name or  the name of a file dragged onto
                          the icon. The entry is writable allowing the  user
                          to enter or modify the filename (e.g. to add
                          wildcard characters).

                          If select or adjust is pressed in the sub-menu the
                          filename will become ticked  meaning that it is
                          fixed. If it is an input file the name will not be
                          modified by  dragging files to the icon, for an
                          output file a saver box will not be displayed 
                          when the command is run. This is useful if you
                          want to run the command  many times with the same
                          input or output files. Pressing select or adjust
                          again  cancels this action.


Running a command
-----------------
To run a command with the current input files (or if the command does not 
have any) click on the commands icon with the select mouse button or choose 
run from its menu. Clicking on the icon with the adjust button will run the 
command with the same input files but will ask for the names of output
files,  as below.

Input files &            If the command has input files or input redirection
Input redirection:       you can drag files onto its  icon. If the file is
                         of a type agreeable with those chosen during , its
                         name will  be used as a parameter.

                         The file is offered to the next input file
                         parameter in the order used when  setting up,
                         starting at the first. If the next input file has
                         been selected (ticked on  menu) it will be passed
                         over and the file is given to the next input file
                         after  that.

                         If all the input files have been filled or
                         selected, the file is offered to the input
                         redirection if that is set.

                         After all files have been given the command is run. 

                         Files can be dragged singly or as a selection. If
                         more files than needed are  dragged onto the the
                         extra files will fill up the parameters again for
                         more runs  if there enough. When this occurs a
                         number of instances of the command will  be run one
                         after the other.
 
Output files &           On running by either methods, if there is are any
Output redirection:      unselected output files or output redirection, a
                         saver box will be displayed for each, the. The
                         title of the  saver box will be that of the
                         parameter name, and the icon will reflect the type 
                         of the output file that will be produced. The icon
                         in the saver this can only be  dragged to a filer
                         window, not an application as the file is not saved
                         at this  point, only the name is obtained to be
                         passed to the command.

Confirmation:            After this if confirmation has been set a window
                         will appear showing the full command that will be
                         run, the  command can be run or cancelled at this
                         stage if the  parameters are not correct.

File selections:         If a selection of files were dragged to the icon
                         and there is enough for more  than one run, the
                         cycle of asking for any out files and confirmation
                         will repeat. 

                         After this the command(s) will be run as described
                         below.

Running single-tasking:  If single tasking is selected from the task and
                         window options when setting the  command up, the
                         command will run pausing the desktop briefly. If
                         any output  is produced it will appear in a fixed
                         window, you will be asked to press space  before
                         the desktop can be used normally again.

Running multi-tasking:   Running a multitasking command will cause an task
                         window  to appear similar to that provided by RISC
                         OS when pressing  CTRL-F12. The command will run
                         whilst other desktop tasks  continue as normal.

                         For a multi-tasking window the output will be shown 
                         appending to the bottom of window unless it has
                         been  scrolled up using the scroll bar.

                         If the Running Multitasking with Input option has
                         been  chosen in the setup, you may give keyboard
                         input to the  command by selecting the window and
                         typing at the caret.

                         If several commands are to be run after dragging a
                         selection they will run one  after the other,
                         appending their output to the window. 

                         More instances of the command can be run while the
                         task window is active, by  starting them in the
                         same way as described above. A new task window will 
                         appear each time as long as there is enough memory
                         available.

                         When the command has been completed the title of
                         the window will change to  reflect this. The window
                         will remain on screen for the output to be examined 
                         unless the close after running option was selected.

Task Window menu:        Pressing the menu button over the task window pops
                         up a menu.

                         Save:     allows the contents of the window to be
                                   saved to a file using a RISC OS  saver
                                   box. It may be used at any time, even
                                   while the command is running.

                         Kill:     kills the running command, the option is
                                   greyed out if the command has  completed.

                         Suspend   can be used to pause and un-pause the 
                         &Resume:  command while it is running.

                         Minimise: will cause the main task window to be
                                   replaced with a small window giving brief
                                   details of the command, it is described
                                   further below.  Clicking on the close
                                   icon of the window is a short cut for
                                   minimise.

The minimise window:     If running minimised has been chosen or the task
                         window is minimised at any time the minimise window
                         is displayed.

                         The advantage of the minimised window is that
                         commands run much quicker  when it is displayed and
                         it takes up less room on the desktop than the full
                         task  window. The title bar gives the name of the
                         command and its status, the time it  was started
                         and the number of lines of output produced are
                         displayed in the  window.

                         The task window can be brought up at any time by
                         clicking on the Full  Window button or clicking on
                         close with the adjust mouse button. Kill Task and
                         Suspend buttons work in the same way to the task
                         window  menu items, the Suspend button changes to
                         Resume while the command is paused.



Supplied Command CFG files
==========================


Command configuration files for a large number of module *commands and 
utility programs from the Acorn developers toolkit and C-tools have been 
provided for the users reference. Parameters and memory requirements 
contained in the supplied files may not be suitable for different versions
of  modules and utility programs the user may have.

 
!CommandC
---------
A utility program !CommandC is included to help manage the supplied  command
configuration (ComndCFG) files. It should be located in the same directory
as !ComndCTRL, and is best used by placing it on the icon bar or backdrop
using Pinboard.

Either drag !CommandC onto the backdrop, or put an AddTinyDir command in
your desktop boot file (see RISC OS User Guide for details).

To use !CommandC click on its icon, two filer windows will appear, one for 
commands built into RISC OS and one for other commands/programs (dont 
worry if you don't have all the programs). Any commands you wish to use can 
be started by double clicking on the appropriate ComndCFG file.

You may save any new ComndCFG files in the filer windows using the save 
option from the !ComndCTRL menu. To close the filer windows, click on the 
!CommandC icon again.


End of !ComndCTRL.!Help.
