home *** CD-ROM | disk | FTP | other *** search
-
-
- 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 (don’t
- 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.
-