ARM Club 3

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

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / misc / command / !ComndCTRL / !Help < prev next >

Wrap

Text File | 1998-06-18 | 34.2 KB | 673 lines

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.