COSmanager User Man pages
From Documentation
Contents |
asgroup
NAME
- asgroup — Run a program with another group's permissions
SYNOPSIS
asgroup <group> [<command>]
DESCRIPTION
- Asgroup changes the effective group ID of the user to the specified group while running command. If no command was specified, an interactive Shell will be started, either using the program defined by the SHELL environment variable, or /bin/sh if SHELL is not defined. Asgroup will only permit execution to proceed if either:
- The user is part of the specified group; or
- The command's group is the one specified, and it has the set group ID bit enabled [see chmod(1)], and the user has execute access to the command.
All attempts (both successful and not) are logged to an audit trail.
FILES
- /usr/spool/log/asgroup
- Audit log file. Every execution of asgroup is logged here detailing the user, terminal, date andtime, the command and whether it was successful.
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
asuser
NAME
- asuser - Run a program as another user
SYNOPSIS
asuser [-12cdosu] <user> <command>
DESCRIPTION
- Asuser runs a command in the context of another user. It is normally only run by a process with the effective user ID of the superuser.
- Switching to the specified user causes the process to switch to that user's ID and Groups, plus the following environment variables to be set: LOGNAME, USER, HOME and FULLNAME.
OPTIONS
- -c
- Check that the caller's effective ID is superuser before running the command. By default, if the caller is not superuser, the command is still run, but without switching users.
- -d
- Change into the user's home directory before running the command, and before creating any output files (see the -o, -1 and -2 options). Normally the command is run in the current working directory.
- -s
- Run the command using the shell. This allows arbitrary shell syntax to be used in the command. Normally the command must be a single program name, optionally followed by its parameters.
- -u <ulimit>
- Set the ulimit to the specified value prior to running the command.
- -o <file>
- Redirect both STDOUT and STDERR to the given file after switching to the new user. If the file does not exist, it will be created with the ownership of the given user. Note that if you use:
- asuser <user> <command> > <file>
- the file will be opened by the shell prior to running asuser, causing it to be created with "root" ownership.
- -1 <file>
- Redirect STDOUT to the given file after switching to the new user. Please refer to the discussion under -o.
- -2 <file>
- Redirect STDERR to the given file after switching to the new user. Please refer to the discussion under -o.
EXAMPLE
asuser mike weekly_report -d prodn- Runs the command "weekly_report -d prodn" as user "mike".
WARNINGS
- This program must not be installed with the SETUID flag set, otherwise system security would be compromised.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
audcycle
NAME
- audcycle - age and recycle audit trails and log files
SYNOPSIS
audcycle [-v] [-D]
DESCRIPTION
- COSmanager provides support for maintenance and viewing of Audit Trails and Log files. Audcycle is the command used by COSmanager to age and recycle audit trails and log files.
- Audcycle checks each audit trail defined in COSmanager and, if it is due to be archived, copies it to an archive directory according to the appropriate archive method. Audcycle also removes old archived audit trails if they have expired.
- Audcycle should only be invoked once per day, usually by adding an entry to the root crontab. The following fragment from the root crontab sets audcycle running at five minutes to midnight each day.
55 23 * * * FShome=<COS-dir>; export FShome; $FShome/bin/cos -u cosmos cosmos -c audcycle -v
- You should substitute the COSmanager home directory for <COS-dir>, for example, /usr/cosmos/COS_4.2.
OPTIONS
- -D
- Debug mode. The commands to cycle the audit trail (from the audit method table) are displayed but not executed.
- -v
- Verbose mode - displays messages as the audit trail cycling is performed.
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
audit
NAME
- audit - write audit trail
SYNOPSIS
audit [-d <directory>] <auditname> [<text>]
DESCRIPTION
- COSmanager provides support for maintenance and viewing of Audit Trails and Log files. Audit is the command used to write a time-stamped message to an audit trail. It is documented here to allow System Managers to add auditing to the duty lists.
- Audit writes a single line to the specified audit trail comprising a timestamp, the user's Login Name, Fullname, the current terminal line or workstation IP address, and the optional text message.
- By default, the audit trail is stored in the directory /usr/spool/log in the file named auditname.
- If audit trail cycling is enabled (see the audcycle(1) command) then there may be several addition versions of the audit trail. These are usually stored in the directory /usr/spool/log/archive/auditname.
OPTIONS
- -d <directory>
- Store the audit trail in the named directory.
- <auditname>
- The name of the audit trail.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
audview
NAME
- audview - view audit trail
SYNOPSIS
audview [-l] [-f <filename>] [<auditname>]
DESCRIPTION
- COSmanager provides support for maintenance and viewing of Audit Trails and Log files. Audview is the command used by COSmanager to display an audit trail. It is documented here to allow System Managers to customise the duty list to include reviewing of specific audit trails.
- Audview allows the user to choose between different versions of the audit trail, displayed most recent first.
- Some audit trails have Functional Database table definitions (eg: FSadmin, root) and these will be displayed with column headings, etc. Other audit trails are displayed with a heading indicating the version and date of the audit trail.
OPTIONS
- -l
- Display the latest version of the audit trail.
- -f <filename>
- Displays the audit trail contained in filename.
- <auditname>
- Display the named audit trail. If more than one version exists the user will able to choose the one to view. If auditname is not specified then the user is able to choose one of the audit trails defined to COSmanager.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
browser
NAME
- browser - Display HTML or simple text documents
SYNOPSIS
browser [-n <msg>] [<file>]
DESCRIPTION
- Browser is a simple HTML rendering program, displaying an HTML or simple text document in a window. It supports a subset of full HTML, in particular a link to another document cannot be a full URL, rather a simple filename which must be found on the local host.
- If <file> is omitted or is "-", data read from standard input is displayed.
- If <file> is not a full pathname, then browser will search for it in the doc or local/doc directory of the current application.
- If the -n option is specified, then should the file (or standard input) be empty, the given message will be displayed on standard error, and browser will terminate with an exit status of 1, with no window being displayed.
- Note that browser only functions under the GUI version of the Functional Toolset, not under the CUI (Character User Interface).
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
cos
NAME
- cos - Invoke COSmanager
SYNOPSIS
cos [-apD] [-d <db>] [-u <user>] [-v <version>] [<appl> [-C] [-v <version>] [-c <command> | <table> [<method>]]]
DESCRIPTION
- Cos is the command that invokes COSmanager and COSmanager applications.
- Cos performs security checks on the invoking user, asking for passwords if necessary, sets up the appropriate security profile and environment for the user, and then invokes either the main COSmanager menu, a COSmanager application, a method or a command.
OPTIONS
- -D
- Invoke the demonstration mode of COSmanager. (See below for more details).
- -d <database>
- Specifies a database holding the Functional Database table data. If the name specified does not end with .db, then this suffix will be appended to form a directory name, which must be located under both the $FShome and $APPL_HOME directories. If not specified, the default database (db) is used.
- -v <version>
- Specifies an alternate version of the COSmanager framework to invoke. The directory of the specified COSmanager version determines the value of the FShome variable, the base directory of the COSmanager framework.
- The following three options are only available if the user is super-user or cosmos:
- -a
- Ask "Who are you?". Normally cos automatically determines the ID of the invoking user, which in turn determines their security profile. If this option is specified, the user is prompted to enter his or her login ID, and password. If this is validated correctly, the user will be allowed into COSmanager with that user's security profile.
- -p
- Forces the user to enter the appropriate COSmanager application passwords. Normally when cos is invoked as super-user, password checking is bypassed.
- -u <user>
- Use the security profile of the specified user rather than that of the invoking user.
- <appl> specifies the COSmanager application to invoke. If omitted, the main COSmanager menu (or buttonbar) is invoked. After the application name the following options can appear:
- -C
- Invoke the application in configuration mode. This may cause further security checks and authentication to occur.
- -v <version>
- Specifies an alternate version of the application to run. The directory of the specified version of the application determines the value of the APPL_HOME variable. Normally the default version of the application is run.
- -c <command>
- Specifies the command to run under the given application.
- <table> [<method> [<params>]]
- If a table is specified with no subsequent parameters, db_methtool(1) is invoked upon that table. This provides an interactive, user-friendly interface to the methods defined for the table. If a method and optionally parameters to that method are given, then that method is invoked directly. See db_meth(1) for details of the format of the parameters.
APPLICATION INVOCATION
- When cos invokes an application, it first searches the applictn table in the COSmanager framework, looking for the specified application. If no version was specified by the user, the entry with the Default column set to yes will be used. This entry determines the base directory (APPL_HOME) of the application, the capabilities required by the user to access it, how the application is to appear in the COSmanager menu or buttonbar, and the commands to invoke the application itself.
- Once the entry is found, the user's capabilities are checked to ensure that he or she has access to the application. The application's environment variables (see below) are then set, and if $APPL_HOME/profile exists, it is sourced as a Bourne shell script. Finally the command to invoke the application is executed.
DEMONSTRATION MODE
- In this mode, any modification to tables which are not under the specified database directory, will cause them to be copied there, and the modification performed on the copy. Thus real system tables (eg: passwd, group, hosts, networks) will not be modified directly, rather the user will operate on copies of them.
- Although most COSmanager applications normally run as root or cosmos, demonstration mode forces them to be run as the normal UID of the invoking user. In addition, certain system commands are replaced with scripts that enable the demonstration or training to be run without needing special privileges.
- It is possible to create a self contained demonstration of a COSmanager application by copying the tables from the COSmanager framework database directory ($FShome/db) and the application's database directory ($APPL_HOME/db) to another directory and using the -d flag to reference the alternate database.
- For example, the following commands create a new duty3G database called training:
cos duty -c sh
cd $FShome
mkdir training.db
cd db
find . -print | cpio -pdumv ../training.db
cd $APPL_HOME
mkdir training.db
cd db
find . -print | cpio -pdumv ../training.db
exit
- The command:
cos -D -d training duty
- would be used to invoke duty3G in demonstration mode using the training database.
- Such a scheme could be used for training new operators.
ENVIRONMENT VARIABLES
- COSmanager sets and uses the following environment variables:
- APPL_HOME
- The base directory of the application being run under cos. The application programs, menus, prompt forms and database files etc, are in subdirectories under $APPL_HOME.
- FShome
- The base directory of the COSmanager framework, which contains the Functional Toolset. By default this is the home directory of the cosmos user.
- PATH
- Cos automatically includes the directories $APPL_HOME/bin and $FShome/bin in the PATH variable. Furthermore, in demonstration mode, PATH also includes $APPL_HOME/dbin and $FShome/dbin to allow special demonstration versions of programs to be written.
- DBTABDIR
- This determines the search path used to locate data for database tables within the COSmanager framework and applications. Unless the -d option is used, this variable is not set, thus defaulting the search path to the db and distrib.db directories. If, for example, "-d training" is specified, the search path is changed to the training.db and distrib.db directories.
- FS_CUSTOMER
- The Customer name to appear at the right side of the title bar on menus, forms, etc under the CUI, and in the "about" box under the GUI. This should be kept fairly short (say 20 characters), or it may be overwritten by the title.
- PRINTCMD
- A command which is used to send output to a printer. It must be able to read its input from standard input, and should not write anything to standard output (or standard error), unless there is an error condition. Using the System V spooler as an example, PRINTCMD should be set to "lp -s", which is the default.
- DBPRINT
- A command that takes (as standard input) output from the Functional Database and send it to a printer. This allows pre-formatting of database tables before printing. One utility that provides this is page(1). This will take the header line and repeat it at the top of each printed page and place the page number on the bottom line. An example of the setting of this variable would be:
DBPRINT="page -C | lp -s"
- PRINTYPE
- The printer type to be used by the page(1) command. This is only necessary if the DBPRINT variable is set to use the page command. A terminfo(4) entry must exist for this printer type.
- These variables are automatically set when the cos command is run. Most can be changed by using the "Global Parameters" menu under "COSmanager Configuration".
SEE ALSO
WARNINGS
- COSmanager runs most of the time with root privileges. The startup scripts and profiles as supplied are written extremely carefully to eliminate the possibility of "trapdoors" or other means of compromising system security. If the files $FShome/bin/COSstartup, $FShome/bin/APstartup or $APPL_HOME/profile are modified, be very careful not to introduce such "trapdoors". In particular, always use full pathnames when specifying directories, especially within PATH variables. Also make sure that the file permissions on such scripts are not changed which may allow access by "hostile" users.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
daemon
NAME
- daemon - Run a command as a daemon
SYNOPSIS
daemon [-fps] <command>
DESCRIPTION
- Daemon executes an arbitrary operating system command as a daemon process, in other words, it initiates the command and runs it in the background, in its own process group or session ID, and disconnected from the current TTY. In addition it also closes any open files which are not regular files (ie: those that are not files on disk).
- This means that daemon programs started under the Functional Toolset will not hold dialog windows open, and will not be killed when the user exits.
OPTIONS
- -f
- Run the command in the foreground, rather than the background. This is useful if the command forks and runs in the background itself.
- -p
- Do not create the new process in its own process group or session ID.
- -s
- Run the command using the shell. This allows arbitrary shell syntax to be used in the command. Normally the command must be a single program name, optionally followed by its parameters. Note that when using this option, an extra "sh" process will be created, and you may have to use "exec" in the command to prevent it from staying around.
EXAMPLES
daemon test_service -l > /tmp/log- Run the command "test_service -l" as a daemon, with its standard output redirected to the file /tmp/log.
daemon -s "cd /usr/spool; exec test_service -l > test_log"- Because this command is more than a simple program invocation, you need to use the -s option. The "exec" prevents the "sh" process from staying around while the daemon is running. Note that if the "cd" was done before calling daemon, the "-s" flag could be avoided in this example.
WARNINGS
- Because all non-regular files are closed, you cannot pipe data into the daemon command.
- Messages from the command written to STDOUT or STDERR may be lost unless these file descriptors are redirected to a file on disk.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
fs_tools
NAME
- fs_tools - the Functional Toolset
SYNOPSIS
- The Functional Toolset is a suite of tools, to enable sophisticated applications to be built quickly and easily. It consists of a suite of user interface tools, database access tools, and various miscellaneous tools. The Functional Database tools are described under db(1). This manual page describes the user interface tools, the environment variables that the toolset uses, and some common facilities which the toolset uses (such as path lists).
USER INTERFACE TOOLS
- These are full-screen, interactive programs, each with a distinct function and they support both a Graphical User Interface (GUI) and a Character User Interface (CUI), the latter can run on virtually any terminal.
- These functions include:
- Picking an item from a menu
- Filling in a form
- Browsing through output, and optionally printing sections
- Choosing one or more items from a list
- Hitting one of a number of function keys in answer to a request
- Although these functions are implemented as separate programs, the "look and feel" of each of the tools is the same, so the user interface remains uniform throughout an application built with these tools.
- Below are brief descriptions of the functions and features of each user interface tool. Further details can be found in the appropriate manual entry for each.
MENU
- Menu implements a hierarchical menu structure. The user simply arrows down to the desired item, and hits Enter or Accept. If that item is an action then the program corresponding to that action is executed. If it is a submenu, then that menu will be entered. Hitting Exit will take the user up a level in the menu hierarchy, or exit Menu completely if it was the Main or Top-level menu.
- Other features of Menu are:
- Conditional menu items. If the condition is not true, the user will not see that item.
- "Self-modifying" menu text. The menu description can contain references to Shell environment variables. If these variables change, so will the text of the menu.
- A full hierarchy of every menu in the system is available by hitting the Index key. The user can then search through the hierarchy, and jump directly to any menu.
PROMPT
- Prompt allows a user to fill in a form and when complete, it outputs Shell commands to set environment variables to the values entered in each field. Optionally, prompt can also load default values for each field from environment variables of the same names. This association of Shell variables to fields on a form, and the association between database column values and Shell variables [see db(1)], means that prompt can be readily used to input and manipulate database column values.
- Prompt is also capable of doing extensive validation of user input, and of doing database "lookups" to ensure consistency, and to provide useful feedback to the user.
SCROLL
- Scroll is a sophisticated version of more(1) or pg(1). It provides up and down, left and right scrolling through any output data. The user can search for arbitrary patterns, and can spool any range of pages to a printer. Scroll can also interpret print control codes for the Epson LQ printer range.
CHOOSE
- Choose is a "pick-and-point" selection utility. It displays lines of data to the user and allows him or her to choose one (or more) lines, which it then writes to standard output. The user has similar features to move within the data as Scroll provides.
CONFIRM
- Confirm displays a message (which may consist of a number of lines) on the screen, and asks the user to make a decision. The user is presented with a fixed number of alternatives, each is selectable by a different function key, which is labelled accordingly.
METHTOOL
- Db_methtool provides an interface to perform actions (or methods) upon data in a database table. It allows the user to select one or more items, then to choose a method to perform. When the method has completed, control is returned so that the whole process can be repeated. It can be considered similar to a combination of choose and menu.
CHARACTER INTERFACE
- Each of these tools presents a uniform user interface. This consists of:
- A title bar on the top line of the screen, with a title in the middle, the customer name at the right, and the tool name, or menu name at the left.
- A row of 8 function key labels on the bottom line of the screen, with F1 being Help, F2 Extended Help, F3 Exit, and F8 Accept. Other function keys may change depending on the particular tool.
- A message line on the second bottom screen line. Error or informative messages appear on this line.
- If the keyboard supports them, the following keys can also be used:
- PAGE DOWN or ^F
- On tools that support scrolling, scroll forward to the next page.
- PAGE UP or ^B
- On tools that support scrolling, scroll back to the previous page.
- HOME
- Move the cursor to the "home" position on the screen.
- ARROW KEYS
- Move the cursor or scroll in the direction indicated.
- ^L or ^R
- Redraw the screen.
- ^D
- Exit the tool. Same as F3. This can always be used to exit any tool, and is useful if the terminfo(4) definition of the function keys is incorrect.
GRAPHICAL INTERFACE
- The graphical interface provides extra flexibility in that several actions can be executed simultaneously, and run in different windows. Where possible the interface is similar to the character interface in terms of the actions of the function and other keys. Selection of items and scrolling of data, however, is achieved by use of the mouse and scrollbars, rather than using keystrokes.
- From the programming point of view, the use of the character and graphical interfaces is identical.
ENVIRONMENT VARIABLES
- The following list of environment variables is used by the Functional Toolset. Note that these are generally set in the file $FShome/profile.
- FShome
- The parent directory of all Functional Software files. The toolset executable programs live in $FShome/bin, which should be included in the user's PATH.
- TITLE
- The title to place at the centre of the title bar which is on the top line of the screens of all the tools. This variable is overridden by the -t option, or by any other mechanism that each tool may have to specify a title.
- FS_CUSTOMER
- The Customer name to appear at the right side of the title bar. This should be kept fairly short (say 15 characters), or it may be overwritten by the title.
- PRINTCMD
- A command which is used by the tools to send output to a printer. It must be able to read its input from standard input, and should not write anything to standard output (or standard error), unless there is an error condition. Using the System V spooler as an example, PRINTCMD should be set to "lp -s". Note that the db(1) tools also use another similar variable, DBPRINT. There is also an associated variable, PRINTYPE, which is the terminfo name for the type of printer used by the page(1) command.
- PAGER
- The name of a program through which large streams of terminal output (such as manual pages) are sent. This could be pg(1) or more(1) or preferably:
scroll -p66 -H1 -s- which will give the user a print capability, and similar "look-and-feel" to the other tools.
- LOGNAME
- Should always be set to the login name of the user. This is done automatically on most systems.
- TERM
- Should be set to the terminfo name for the type of terminal being used.
- TERMINFO
- See below.
PATH LISTS
- A number of tools access files either to control their operation, or to read or update data. The tools which do this can search for the file(s) in a search path, similar to the standard PATH variable.
- Path lists are a list of directories separated by colons, each of which is searched in turn. If the path begins with "+:", this search algorithm is extended as follows: the directories pecified in the path are then relative to the application directory path (specified by the APPL_PATH variable). If APPL_PATH is not set, then APPL_HOME is used, and if this is not set, HOME is used.
- Consider the example of searching for the file "media" and the path list is specified as "+:db:distrib.db", and APPL_PATH is "/usr/fs1:/usr/fs2". The following directories would be searched in order:
/usr/fs1/db
/usr/fs1/distrib.db
/usr/fs2/db
/usr/fs2/distrib.db
- The path list variables all have reasonable default values, so in most circumstances they will not need to be set.
- The following is a list of path lists used by the Functional Toolset:
- DBDIR
- Used by the database tools to locate the data dictionary file (.dc) for the table. Default: "+:dict"
- DBTABDIR
- Used by the database tools to locate the data file for the table. Default: "+:db:distrib.db"
- MENUDIR
- Used by Menu to find the menu description files. Default: "+:menu"
- METHDIR
- Used by the database method tools to locate the list of methods for the table. Default: "+:method"
- PROMPTDIR
- Used by prompt to find the prompt description file. Default: "+:prompt"
- REPDIR
- Used by the report generation tools to locate the report description file. Default: "+:report"
TERMINFO
- Because the character interface tools of the Functional Toolset uses the facilities of terminfo(4) in a far more extensive way than most of the standard utilities like vi(1), often the distributed terminfo definitions are inadequate. Therefore the Functional Toolset comes with its own terminfo directory, $FShome/lib/terminfo, which contains source of tested definitions for several common terminals.
- In order to use these supplied definitions, it is preferable to set the TERMINFO environment variable to $FShome/lib/terminfo so that the standard system definitions are not lost, when the new ones are compiled with tic(1).
SEE ALSO
- fs_appl(1), db(1), Menu(1), prompt(1), scroll(1), choose(1), confirm(1), methtool(1), page(1), terminfo(5).
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
Menu(1)
NAME
- menu - Function Toolset Menu System
SYNOPSIS
menu [-cfsDI] [-S <pgm>] [-t|T <timeout>] [<file>]
DESCRIPTION
- Menu is an interactive full-screen tool which implements a hierarchical menu structure. Menu options may either be a submenu or an action, which is the execution of a program. Menus are defined in menu description files, which should end with .menu.
OPTIONS
- -c
- The user will be prompted for confirmation when he or she attempts to exit from the top level menu.
- -D
- Turn the "Debugging" mode on. This is useful when developing a menu hierarchy, since as well as providing extra warning messages, it allows the user to edit the current menufile. See 'Function Keys' below for details.
- -f
- Use menu as a filter. In this mode, menu terminates after executing an action.
- -I
- Disable the Index key [see below].
- -s
- Disallow access to the Shell. Normally a user is able to escape to a Shell, and later return to menu. This is available in the CUI from a function key button labelled "Shell", and in the GUI under the left button on the menu bar. If this option is enabled, the user will be unable to escape from menu, except by leaving via the top level menu, or by executing a noreturn option [see below]. If menu is exec'ed from the user's .profile file, then the user will be logged off the computer when he or she leaves menu. This means that the user will be constrained to only execute options on his or her menu.
- -S <pgm>
- Specifies the program to run when the Shell escape is performed. If the program name begins with '+', and Menu is running with an effective user ID of super-user, the shell escape will be run as root. Otherwise the shell escape will be run as the ID of the invoking user. The default is $MENU_SHELL or $SHELL [see ENVIRONMENT VARIABLES].
- -t|-T <timeout>
- Specifies a timeout period in seconds. If there has been no terminal I/O activity within this period, menu will terminate. Normally, this timeout only applies when the user is inactive within a menu. If -T is used instead of -t, then the timeout also applies to programs that menu initiates. This is implemented by sending a hangup signal (SIGHUP) to menu's process group. Note: some programs which do terminal I/O via >/dev/tty (instead of the actual tty device), or which cannot safely be terminated by SIGHUP, may not support the -T <timeout> facility. [See the notimeout keyword below]. This feature is currently implemented under the CUI only.
- The optional filename <file> specified after these options is the menu description file of the top-level, or main menu. If this is omitted, the file .menu will be used.
USER INTERFACE
- Menu supports both a Graphical User Interface (GUI) and a Character User Interface (CUI), depending on the type of display device you are using.
- The GUI menu shows the top level menu as either a buttonbar or an application menu (ie: a permanently posted menu with window decoration). The name of the menu is shown in the Window Manager decoration area (usually the frame above the menu title). Submenus are displayed as transient pulldown windows. These are posted when the user selects the corre sponding option and unposted when an action is selected.
- The CUI menu uses the top line of the screen as a title bar. At the left is shown the name of the current menu description file (without the trailing .menu), at the right the customer name, and in the centre, the current menu title [see the menu statement below]. The bottom line consists of the function key labels [see below for descriptions]. The second bottom line is a message line.
- The user is presented with a screen showing the allowed options in the current menu. The user selects the desired option either by clicking on it with mouse button 1 (GUI version) or by moving the cursor (indicated by a small arrow) up or down to the desired option, then pressing Accept or Return to execute it (CUI version). Options which are not available to that user will not be shown.
- An option may be either an action or a submenu. If it is an action, the corresponding program is executed. Upon completion of an action, menu redisplays the current menu, allowing the user to make another selection. Should it be a submenu, then that menu will be entered, and the user will be able to select another option from the new menu. Pressing Exit (F3 in the CUI; File | Exit in the GUI) leaves the current menu, returning to the level above. Pressing Exit from a top-level menu exits the application.
FUNCTION KEYS (CUI only)
- Down Arrow
- Move the cursor down to the next option. This is circular: moving down from the bottom option moves back to the top.
- Up Arrow
- Move the cursor up to the previous option. This is circular: moving up from the first option moves down to the last one.
- Help (F1)
- Displays a single line help message for the option that the cursor is currently pointing to. If the user hits Help again, a panel showing the usage of the function keys is displayed.
- Manual (F2)
- On options where this label is on, a full description of the action is available by hitting this key. Usually this description is a MAN page.
- Exit (F3)
- Exit from the current menu. If this is a submenu, then the user is returned to the parent menu. If this is the top-level menu, then menu terminates.
- Index (F4)
- A full menu hierarchy is displayed to the user. The user can then move the cursor to the desired menu, and hit Accept. Menu will then jump straight to that menu.
- Top (F5)
- Causes menu to jump directly to this user's top-level (main) menu.
- Shell (F6)
- This key is only operative when the -s flag is not specified. Hitting this key will start an interactive Shell session. When this ends, the user will be returned to the current menu. [See also the -S flag above].
- Edit (F6)
- This key is operative only if the -D flag was specified. This allows the user to edit the current menu description file.
- Accept (F8) or Return
- Select the item that the cursor is currently pointing to.
- Any Printable Character
- Menu will advance the cursor to the next option starting with that character.
PROMPTING FOR VALUES
- Sometimes menu may prompt the user for one (or more) values, before executing an action. When in this prompt mode, a box appears at the bottom of the screen (CUI) or a popup prompt window appears next to the option (GUI). The box/window contains an input field where the user can input the requested information. In this mode the following function keys apply:
- Exit (F3)
- Abort the option.
- Insert/Overtype (F5)
- Toggle insert/overtype mode. When in insert mode, characters typed will "push" any following characters to the right.
- Del Char (F6)
- Delete the character under the cursor. Subsequent characters are moved left.
- Clr Fld (F7)
- Delete all characters from the cursor to the end of the field.
- Accept (F8) or Return
- The user has finished entering the value, and the action should proceed.
- The GUI editing key bindings are described in the prompt(1) manual page.
DESCRIPTION FILE
- Each menu in the hierarchy is described by a single description file. This file is a series of statements, each on a separate line, and each starting with a keyword followed by at least one white space character. Statements may be continued over several lines by terminating all but the last with backslash (\).
- Menu description files may contain any of the keywords described below, but some only take effect in either the CUI or GUI versions of menu.
- The keywords marked with * are applicable both at the menu level or option level. If they appear at the menu level (ie before the first option), they apply to the menu as a whole, or to every option in the menu. If they appear at the option level, they apply to that option only. A particular keyword at the option level will override the same one at the menu level.
- #
- The rest of the line is ignored.
- action
- After this keyword is the operating system command to execute. Each option may have only one action or submenu.
- after
- Execute the following command on exit from this menu. Note that CUI users potentially can jump straight to a menu via the Index button. In this case the after keyword will not be run if it is on the submenu statement of the calling menu.
- application
- Force this menu to become a top-level application menu window (GUI only).
- audit*
- Audit this menu or action using the audit(1) command. This will cause a record to be written to an audit logfile when the user enters the menu, or selects the option (depending where the audit is specified). This audit trail should be specified by the APPL_NAME environment variable. If this is not specified, the file "menu.log" in the current directory will be used.
- before
- Execute the following command on entry to this menu.
- button
- Specifies the label to use if this option is displayed in a button bar. The default behaviour is to display submenu options using the menu file (less the .menu extension) with the first letter capitalised and the rest in lower case. This option must be specified if you want "action" options to appear on the button bar (GUI only).
- buttonbar
- Tells menu to display this menu as a button bar. Only submenu options will be displayed unless the button keyword is specified on action options (GUI only).
- cd*
- Change to the specified directory before executing the menu or action.
- choose*
- Set an environment variable to the output of a command (usually choose or db_choose). The next word after the choose keyword is the name of the variable to set. The rest of the line is the command to run. If this command is successful (ie returns an exit status of 0), its output is assigned to the variable. If not, execution of the action or menu does not proceed (depending whether the choose appears at option or menu level), and any error output is displayed to the user in menu's output window (CUI) or a pop-up dialog window (GUI).
- clear
- Forces the screen to be cleared before executing the action. Clear is implied if window none is specified. If output windowing [see window below] is enabled, menu normally assumes that the command will either be a full-screen application (which clears the screen itself), or one that directs all output to menu's output window (CUI only).
- conditional
- Only display this option to the user if the specified command is an executable file, or can be found by searching the current PATH variable. The condition can be negated if the command is prefixed with "!".
- confirm
- Ask the user for confirmation before executing the action. This keyword is optionally followed by a message to request confirmation. If this is not present, a reasonable default message will be used.
- eval*
- The rest of the line is globbed, and the result, which should be a list of the form:
- variable=value
- either separated by newlines or semi-colons, is evaluated and variables are set and exported to the environment. Note that explicit "export" statements are not required. Statements other than variable assignments are ignored.
- help*
- The rest of the line is taken to be a help message, which will be displayed when the user hits the Help key.
- icon
- Specifies an icon to represent this option on the buttonbar. The icon should be an X pixmap, and either be a full path name or refer to a file in the $FShome/GUI/icons directory (GUI only). If omitted, the button name is used as the icon name, and if no such icon exists, a default icon is displayed.
- if*
- The rest of the line is a condition, which is evaluated, returning TRUE on zero exit status, FALSE otherwise. If the condition is FALSE then execution of the action or menu does not proceed (depending whether the if appears at option or menu level).
manual* Following this keyword is a command to invoke when
the user hits the Manual key. This is used where
the highlighted option runs a command for which a
manual page exists; Typically it would be someﾭ
thing like "man 1 xxx | scroll" (CUI only).
menu This should be the first non-comment line in the
file. The rest of the line is taken to be the
menu's title, which will be displayed in the cenﾭ
tre of the title bar.
needtty Specifies that this option requires the presence
of a terminal device. If specified, the GUI menu
will start an xterm attach the action to it (GUI
only).
noredraw This parameter is normally not required. It is
only needed on systems which do not support
AUTOREDRAW, which gives menu the ability to autoﾭ
matically tell if the screen needs to be
refreshed. If this facility is not available, then
this parameter tells menu whether the screen must
be redrawn after execution of the option. Noreﾭ
draw takes the following options:
error If the action returns an error status, do
not redraw the screen. This is useful if
you know that on error, the action simply
writes a message to the output window and
then terminates [see window below].
all Never redraw.
If no parameter is specified, then all is assumed
(CUI only).
noreturn This instructs menu to start the action, and then
terminate. This is used if you want the user to be
logged off after the action is complete, without
going back to menu (CUI only).
notimeout This tells menu to disable any timeout specified
via the -T flag while executing this action (CUI
only).
- option
- This keyword introduces a new option. All subsequent lines will be assumed to pertain to this option, until the next option statement. The rest of the line is taken to be the text to be displayed on the screen, which the user sees as one of the options to select.
pause If output windowing is not enabled for this option
[see window below], pause causes the message:
Press RETURN to Continue ...
to be displayed after the action is complete, but
before redrawing the menu. This is required for
programs that write output to the screen, but are
not interactive. If the pause is not present, the
output would be immediately erased before the user
has a chance to look at it. Note that a pause will
also be executed after any action that returns a
non-zero exit status, to allow error messages to
be read (CUI only).
prompt* Prompt the user to enter a value, and then set an
environment variable to that value. Optionally,
after the prompt keyword is a format [see
prompt(1) ], which is used to determine the maxiﾭ
mum length of the input field, and its type. Folﾭ
lowing is the name of the environment variable to
set. The rest of the line is a prompt request
that will be displayed when the user is asked to
enter the value. An example would be:
prompt 6N pid Enter the Process ID to kill:
If the variable currently has a value, that value
will be displayed, and the user given the chance
to alter it.
pulldown Specifies that the menu should be implemented as a
pulldown menu. Menu uses a reasonable algorithm
to decide if a menu can be a pulldown or not.
Mostly it gets it right, but sometimes it isn't
sure and so errs on the side of caution and forces
an application menu. If this occurs the developer
can specify "pulldown" and override Menu, however
the results may be interesting if the Menu should
really have been an application menu (GUI only).
- redraw
- Forces the menu screen to be redrawn after execution of the action. Normally menu determines whether the screen has been written to by the action, and hence it knows whether the screen needs redrawing. This option should normally not be used. It is implied when either clear or window none is specified (CUI only).
set* Set an environment variable to a value. The next
word after the set is the name of the variable to
set. The rest of the line is the value to set it
to. Note that as all strings in menu are globbed,
the value may contain environment variables (preﾭ
fixed by $) or output of a command enclosed by
grave accent quotes (`).
submenu This indicates that this option is a submenu
rather than an action (program execution). Folﾭ
lowing the keyword should be the name of the menu
description file for the submenu.
tip The rest of the line is taken to be a tooltip mesﾭ
sage, which will be displayed in the tooltip for
this option, if the menu is a GUI buttonbar. In
all other cases it is ignored.
verify* This is similar to the if keyword, except that it
also followed by an error message, which should
appear on the next line of the description file.
If the condition is FALSE, then execution does not
proceed and the error message is displayed to the
user. Example:
verify [ "$val" -ge 1 -a "$val" -le 99 ]
Error - must be between 1 and 99
wait This causes menu to write out the message:
Please wait ...
before executing the option. This is useful feedﾭ
back for the user if the action is likely to take
some time before giving any response to the user
(CUI only).
when Only display this option to the user if the condiﾭ
tion following the when keyword evaluates to TRUE.
The condition should be a command, which is exeﾭ
cuted (throwing away any output). An exit status
of 0 is TRUE. Typically the command would be a
test(1). An example is:
when [ $LOGNAME = root ]
- window
- This instructs menu how to handle the standard output (stdout) and standard error output (stderr) of the action. Menu implements an output window which can capture output from an action, and display it in a window on the menu screen. This gives a very pleasing user interface, allowing actions to easily give useful feedback to the user, minimising both keystrokes and screen refreshes. Window takes one of 3 parameters:
- none
- Causes menu to leave stdout and stderr directed to the terminal.
- error
- This is the default. Stdout is left directed to the terminal. Stderr is directed to the output window.
- all
- Both stdout and stderr are directed to the output window (CUI only).
ENVIRONMENT VARIABLES
- Menu understands the following environments variables (apart from the standard ones [see fs_tools(1)]):
- MENUDIR
- A colon separated list of directories to find the menu description files. Menu will first look for the file in the current directory, and if not found, then search $MENUDIR.
- APPL_NAME
- The name of the user's application using Menu. It is also used as the audit trail name to be used by the audit statement [see above]. If this is omitted, the file menu.log will be used.
- MENU_SHELL
- This variable can be used instead of the -s and -S command line options. If its value is "false", then the Shell escape is disabled (equivalent to -s). If it is set and not NULL, then its value is the command to run when the user performs a shell escape. If it begins with '+', it will run as user root. If not set, $SHELL is used.
- Menu also sets some environment variables for use by the programs called:
- MENU_TITLE
- The title as it appears at the top of the current menu.
- MENU_OPTION
- The name of the current option selected, as it appears to the user.
- TITLE
- The same as MENU_OPTION. This is used by several programs in the Function Toolset.
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
methtool
NAME
- db_methtool - Interactively invoke methods on a database table
SYNOPSIS
db_methtool [-CFKklRSt] <table> [<col>...]
DESCRIPTION
- Db_methtool is an interactive tool which allows the user to run methods on a database table or on row(s) within a database table. Functionally it works like a continuously running db_choose, combined with a menu facility.
- Upon entry, the contents of the specified table are displayed, and in exactly the same manner of operation as db_choose -m (multiple), the user can select one or more items (or rows). A method is then invoked under the GUI by either:
- selecting from a pulldown menu,
- clicking on a toolbar button,
- double-clicking on a row, or
- typing a shortcut letter [see below for details].
- Under the CUI, a method is invoked either from a popup menu or by using a shortcut letter.
- After the method has run, control is returned back to the "choose" display, and the user can repeat the whole operation. The display is refreshed any time the data in the table is changed. Furthermore, the list of methods available will also be updated if the method list file is changed.
OPTIONS
- The options that db_methtool understands are a subset of those of db_choose and their meanings are identical. The only exceptions to this are:
- -C <classes>
- Restrict the available methods to the classes given, which should be a list separated by commas and/or spaces. The default is that all methods in non-null classes are available.
- -R <secs>
- Check whether the data needs to be re-displayed every <secs> seconds. A value of zero disables this checking. It defaults to 5 seconds for a "real" table (ie one whose data is stored in a file), and to zero for a "virtual" table (or view). Also, no matter what the value of -R is, the displayed data is always refreshed after performing a method which updates the table.
- -S <method>
- Run the specified method on startup. Typically this method will be a view, allowing a default view to be specified. Without -S, if one of the methods has the tool_startup attribute, that method will be run.
- If column names are specified after the table name, then only those particular columns are displayed. Note, however, that the method itself will still be passed all the column values in the table for the selected items.
USER INTERFACE
- The user interface is very similar in operation to that of choose(1) and scroll(1). Items are selected in the same way as choose multiple. The search and print facilities are identical to those of scroll, and the function keys work the same way. Under the character interface (CUI) there are 2 additional function keys:
- Menu (F8)
- Invokes the Method menu (see below).
- Options (F7)
- Invokes the Options menu (see below).
- Under the graphical interface (GUI), the row of function key buttons has been removed, with the functions moved to pulldown menus, and toolbar buttons. Function keys, however, can still be used in the standard way (eg F3 Exit, F4 Search etc).
METHOD INVOCATION
- Each database table optionally has a set of methods defined. A method is an action which is usually performed on item(s) in the table, or upon the table as a whole. The method definition determines, amongst other things, what the method does, who can perform the method, what class the method is in, and what, if any, its shortcut letter is.
- The methods for the table are arranged in one or more menus from which the user can pick one to perform. All methods of the same class are placed in the same menu, whose name is the class name. For example, the standard table maintenance methods (add, change, clone and remove) are all defined to be in class "maintain". Therefore db_methtool will display these 4 methods under the one menu called "Maintain". If other methods are defined in other classes, then they will appear in separate menus. If a user cannot perform a particular method, it will not appear in the menu. Furthermore, if a user cannot access any methods in a particular class, the menu for that class will not appear. Note also that methods which have a null class cannot be accessed at all from db_methtool. Typically there should be a maximum of 4 different classes of methods for any table.
- Under the GUI, each class name is displayed as a menubutton at the top of the window which, when invoked, displays a pulldown menu containing the methods in that class. You can then choose the method to perform as you normally would select any option from a pulldown menu. Some methods may also appear as buttons on a toolbar, which when pushed, invoke the method.
- Under the CUI, all the menus appear simultaneously when you hit the Menu (F8) button. To select the method to perform, use the arrow keys to highlight the required method, and hit <Return> or <Enter>. You can also jump direct to a particular method by hitting its lowercase shortcut letter, displayed as a capital letter in the method name. If you decide not to invoke a method, hit Exit (F3) to make the menu disappear.
- In both the GUI and CUI you can execute a method without having to display the method menu, using the method's uppercase shortcut letter. In the GUI, the shortcut letter is underlined, and is also displayed to the right of the method name in the menu. Please note that not all methods necessarily have shortcut letters.
- Depending on their requirements not all methods can be run at all times. This may be because the method:
- requires items to be selected, but none have been;
- requires only one item to be selected, but more have been; or
- the Disable field evaluates to TRUE.
- In the GUI method menu, methods that cannot run appear "greyed out". In the CUI you will be given an error message if you try to execute such a method.
USER OPTIONS
- The Options (F7) function key (CUI), or the planet menubutton (GUI) invoke a menu of user-options and miscellaneous actions. These are:
- Multiple prompt
- When enabled this causes certain methods (such as add) to repeatedly display a prompt form, allowing multiple items to be entered. To terminate, exit prompt with the Exit (F3) button. By default this option disabled, causing only one form to be displayed, and hence only allowing one item to be entered.
- Confirm actions
- When enabled (the default), causes certain methods (such as remove) to require user confirmation before performing the action.
- Print data
- Invokes the print facility (see scroll(1)), to enable you to print all or part of the data displayed.
- Search
- Invokes the search facility to search the data displayed for a string or pattern. (GUI only - use function key F4 under the CUI).
SEE ALSO
- choose(1), db_choose(1), db_meth(1), db_meth(4), scroll(1).
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
page
NAME
- page - paginate output for a printer
SYNOPSIS
page [-C] [-h] [-P <printype>] [-H <headlines>] [-t <title>] [-l <lines>] [-c <columns>] [<filename>]
DESCRIPTION
- Page is part of the Functional Toolset and is documented here to assist Systems Managers to customise the printing functions of COSmanager. Page is typically used to paginate the output from the Functional Database tools prior to printing.
- Page prints a title line followed by a number of header lines, which are read from the start of the input file. The title and header lines are then repeated at the top of each printed page. The page number is also printed, centred at the bottom of each page.
- Page uses the terminfo(5) terminal information database to support features of various printers.
OPTIONS
- -C
- print in compressed mode. If the printer supports a compressed mode, the escape sequence defined in terminfo to initiate compressed printing (see below) is output before printing commences and the sequence to restore normal printing after printing finishes. Printers supporting both a normal and compressed mode should define 2 terminfo entries, the one for compressed printing should end in -c. This option will automatically append a -c to the printype (see below).
- -h
- do not output a title line. The header line(s), if any, are still printed.
- -P <printype>
- use the terminfo entry for printype. Usually the environment variable PRINTYPE is used.
- -H <headlines>
- Used to specify an alternate number of lines for the input header. Normally the first line only is used as a heading. Use -H0 to disable the header lines.
- -t <title>
- Used to specify a title to appear centred on the title line. Normally the environment variable TITLE is used. At the left of the title line is the date, and to the right the contents of the FS_CUSTOMER environment variable, which would normally contain the name of the user's organisation.
- -l <lines>
- Used to specify the number of lines on a page. Normally this is obtained from the terminfo entry for the printer.
- -c <columns>
- Used to specify the number of columns in a line. Normally this is obtained from the terminfo entry for the printer.
- <filename>
- Specifies the file to read. Normally standard input (stdin) is used.
TERMINFO REQUIREMENTS
- In order to support attributes such as emboldening and underline in a device independent manner page makes use of the terminfo database. A definition for each printer should (at least) contain the following variables:
Capname Description
cols number of columns in a line
lines number of lines on a page
smso Start standout mode
rmso End standout mode
smul Start underline mode
rmso End underline mode
is1 Initialise the printer to compress mode
rs1 Reset the printer to normal mode
- For further information refer to the terminfo(5) manual page.
EXAMPLES
- Typically, page is used in the specification of the print command for the Functional Database, as shown in the following extract from a user profile.
PRINTYPE=dumb_132
PRINTCMD="page -C | lp -s"
export PRINTYPE PRINTCMD
- The -C flag tells page to use the dumb_132-c terminfo entry if it exists. If not, it will default to the non-compressed dumb_132 entry.
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
root
NAME
- root - Super User access with extra security
SYNOPSIS
root [command]
DESCRIPTION
- Root enables a user to become Super User or execute a command as Super User, but with more stringent security controls than su(1). Root ensures that the user attempting to become Super User is in a list of secure users. Also all attempts (both successful and not) are logged to an audit trail.
- If the user is on the list of secure users, then root will prompt for the Root Password. If this is entered successfully, the command specified will be executed. If no command was specified, an interactive Shell will be started, either using the program defined by the SHELL environment variable, or /bin/sh if SHELL is not defined.
- Should the user not be in the list of secure users, root will prompt:
Who are you:
- To this a user name in the secure list must be given. The user will then be prompted for that user's password as well as the root password, before gaining Super User access. This facility allows a user to become Super User from another user's session. This is sometimes required when the Administrator or System Manager is assisting a user and needs Super User access to complete a task on behalf of that user.
RECOMMENDATION
- In order to ensure that all Super User accesses are controlled and logged, it is highly recommended to remove general access to the su(1) command, by removing all Public permissions, using chmod(1):
chmod o-rwx /bin/su
- DO NOT REMOVE /bin/su as it is required by some Systems Programs.
FILES
- /etc/sulist
- List of secure users, one per line.
- /var/spool/log/root
- Audit log file. Every execution of root is logged here detailing the user, terminal, date and time, the secure user and whether it was successful.
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
runopt
NAME
- runopt - Run a specified menu option
SYNOPSIS
runopt [-D] <menu> <pattern>
DESCRIPTION
- Runopt runs the first menu option in menu <menu> whose text (ie: option field) matches <pattern>.
- It does this by generating the equivalent shell script, including support for any set, prompt, if, eval, pause, confirm and when directives on the selected option.
- Global directives (ie: directives before the first option) are recognised, as are global prompts (ie: prompts that do not have an associated action).
- All directives are executed in the order that they are declared, but prompted variables are combined into a single prompt form.
- The wait directive is always on. The pattern may be any valid awk(1) regular expression.
- The -D flag tells runopt to print the commands and not to run them.
EXAMPLES
runopt -D perf '(sar)'
interval=5 ; export interval
Menu -s -I sar.menu
runopt -D ops "Set system date"
TZ=`[ -r /etc/TIMEZONE ] && . /etc/TIMEZONE; echo $TZ` ; export TZ
timeset
pause
runopt -D ops Shutdown
TZ=`[ -r /etc/TIMEZONE ] && . /etc/TIMEZONE; echo $TZ` ; export TZ
delay=300 ; export delay
confirm 'Shutdown to single user after delay' || exit
eval `prompt -d <<- EOF
title Shutdown to single user after delay
field delay
format 27s
prompt Number of seconds before shutdown
EOF` || exit $?
cd / ; shutdown -y -i0 -g$delay ; sleep 1000
WARNINGS
- Runopt is likely to be replaced in the near future by an option to Menu(1).
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.
scroll
NAME
- scroll - Browse through a file or program output
SYNOPSIS
scroll [-DFHknpRrstvw] [<file>|!<pgm>]
DESCRIPTION
- Scroll is an interactive full-screen tool which allows the user to browse through a file or report. It provides facilities to scroll up and down, left and right (should the data be wider than the screen), to search for a regexp-type pattern, and to send a range of pages to a printer. Scroll can operate in "refresh" mode, checking the data every N seconds and updating any fields that have changed.
- As the user scrolls through the data, scroll can retain some key information on the display, such as header lines, column names and key fields.
OPTIONS
- -D
- Display only mode. Disable the Print key [see below].
- -F [<file>|!<pgm>]
- This is used with the -R option [see below] when the data is generated by executing a program. Often it is too expensive to re-run the data generation program often, especially when the data doesn't change often. The -F option allows you specify a way by which scroll can test whether the data has changed. If a file name is specified then scroll will run stat(2) on it periodically. If it has been modified, the data generation program is re-run, and the updated data re-displayed. If the form !<pgm> is used, then pgm is executed periodically. If it returns exit status 0, the data is re-displayed. The -R option determines how often this test occurs.
- -H N
- Take the first N lines of input to be the header. These lines will be displayed in bold and will be kept on the screen when scrolling up and down. If in paged mode, (-p specified), then take the first N lines on every page to be a header. If this option is omitted, scroll will assume no header in paged mode, and a 1 line header if not. -H0 can be used to suppress the header.
- -k N
- Keep the left hand N columns on the screen when the user scrolls left and right. This is sometimes useful when browsing columnar data.
- -n <message>
- If there is no data after the optional header lines, write out message to standard error and exit with status 1. The default message is "Scroll: No data to display".
- -p N
- This flag says to use paged mode, and that the input isin pages, each N lines long. Scroll will recognise the FORMFEED character (\f or CTRL L) as indicating a new page. If this option is specified then the following changes to the normal functionality take place:
- The Page Up & Page Down keys will move to the previous or next page of data, rather than one screenful at a time. The Up & Down arrow keys will still move one screen at a time.
- It is assumed that each page has a new header [See the -H option].
- As well as showing the current page number, in CUI scroll will also display the line number on the page at the top the screen. In GUI, page up and down buttons appear, as well as a page number field.
- -R N
- This tells scroll to operate in "refresh" mode. In this mode the data is checked every N seconds, and if it has changed, it is re-displayed. This mode cannot be used when reading data from STDIN. [See also -F option]. If N is zero, refreshing is disabled.
- -r N
- This option indicates that the data is in records consisting of N lines, and that records should not be split across screens. All records must contain the same number of lines for this to work properly.
- -s
- Squash multiple blank lines down to a single blank line. This is useful for looking at nroff(1) output.
- -t <title>
- Display title on the title bar at the top of the screen. The default is to display the contents of the TITLE environment variable, or if it is not defined, the name of the file.
- -v
- Like cat -v, display unprintable characters.
- -w N
- No line of data is wider than the specified number of characters. Should there be a line longer, it will be truncated. The default is 150 characters. This parameter is purely used to size internal data structures to cope with the longest possible line.
- If <file> is omitted or is "-", standard input will be used. If the form !<pgm> is used, then <pgm> is executed, and its standard output is used.
USER INTERFACE
- The CUI and GUI versions of scroll are quite similar in the way they look and work; the data area, where the records are displayed, is virtually the same. However, there are some differences in the window decoration.
- Scroll uses the top line of the screen as a title bar. The CUI version also contains to the left of the title the word "Scroll" and to the right the customer name.
- The bottom line consists of the function key labels (see below for descriptions).
- The second bottom line is a message line. In the CUI, it is also used to display user responses entered from the keyboard (e.g. page numbers or search strings).
- The CUI version has a line between the title and the first row of data. It displays the current page number, the column number of the left hand column of the screen (when scrolling left and right), and also if in paged mode (-p specified), the line number of the current page that is at the top of the screen. If there is data off the right hand side of the screen, a small arrow (usually ">") will appear at the far right of the second line. Similarly a small left arrow ("<") will appear at the far left is there is data to the left.
- Using the GUI, vertical and horizontal scroll bars indicate that there are more rows or columns of data than are shown in the current window. Clicking in the vertical scroll bar above or below the slider box moves the display one 'windowful' up or down. Clicking in the horizontal scroll bar to the left or right of the slider box moves the display one 'windowful' left or right. In paged mode, the scrollbars allow you to scroll around the current page only, and page up and down buttons allow you to move between pages. The page number field also allows you to enter the desired page number, much like the "Go To" button in the CUI.
FUNCTION KEYS
- Unless otherwise specified the following keys only function in the CUI version of scroll. When using the GUI, most of these functions are performed using the mouse and the scrollbars.
- Down Arrow
- Move to the next screen.
- Up Arrow
- Move to the previous screen.
- Right Arrow
- Scroll the screen right.
- Left Arrow
- Scroll the screen left.
- Page Down
- Move to the next page. Equivalent to Down Arrow unless in paged mode (-p specified).
- Page Up
- Move to the next page. Equivalent to Up Arrow unless in paged mode (-p specified).
- Help (F1)
- Under the CUI, lets the user hit any key to get a one line message about the function of that key. Under the GUI, displays on-line help about the use of scroll.
- Exit (F3)
- Exit scroll.
- Search (F4)
- Prompts the user for a case-insensitive reg exp-type pattern, and then searches forward for it from the current position. Should it not be found, scroll will start back at the top of the data, and search to the current position. If the pattern is found, the cursor will be moved to the line containing the pattern. Under the GUI, the user has the choice of searching using simple string matching, or regexp-type patterns, as well as case-sensitive or insensitive search.
- Print (F5)
- The user will be prompted for the first and last page to print. The data is the selected pages will then be printed (with header if any) by piping the data into the command specified by the PRINTCMD environment variable. To print the entire file, specify from page 1 to page 99999.
- Go To (F6)
- (CUI only) The user is prompted for a page number. The viewing window will then be moved to the top of the specified page.
EXAMPLES
scroll -H0 /etc/termcap- displays the contents of the file /etc/termcap.
nroff -man scroll.1 | scroll -H1 -p66 -s- runs the manual entry through nroff(1), removing multiple blank lines, using the top line of each page as the header.
ps | scroll- displays the output of the ps command, holding the first line on the screen as the data is scrolled up and down.
scroll -H0 -R5 !df- displays the output of the df command, re-running it and updating the screen every 5 seconds.
SEE ALSO
COPYRIGHT
- Copyright © 1990-2006 Functional Software. All rights reserved.