URL: http://www.firstbasesoftware.com/man/man1/dbshell.htm
Last modified: 21 September 1995
Copyright © by FirstBase Software.
[
Index of Contents] [
FirstBase RDBMS Overview]
The dbshell dictionary is more of a free form text file created with your favorite editor (like vi(1)). This file will be 'executed' by dbshell(1), allowing a smooth interface between menu selections and the Bourne shell.
Using this dictionary, dbshell(1) paints the screen and then provides a prompt for user input. At this prompt, the user issues commands. The command must be known by dbshell(1) or have been built into the dictionary being executed. Dbshell(1) has a few built in commands. These are summarized in the COMMANDS section below.
The default menu for dbshell(1) is menu/MAIN located in the firstbase home directory.
To execute a command, the entire selection does not need to typed -- just enough to distinguish it from other commands. This feature can be disabled using the environment variable MENUMATCH. See setup(5) for more.
There are two major divisions to the dictionary/text file: the screen section and the actions section. The screen section of the dictionary file is all of the beginning lines of the file, up to a line with a single percent sign. A maximum of 21 lines are allowed.
This screen section will appear on the terminal exactly as depicted in the file with one exception. To display words or tokens in reverse video prepend a dollar sign ($) to the token. A dbshell screen will have the standard FirstBase header and footer lines, and an "Enter Selection" prompt on the 24th line.
A token is defined as a series of alphanumeric characters plus the underscore, or as punctuation. This means characters like ampersand and comma must be marked individually. Use an underscore to force reverse video of a blank. For instance, in the example presented at the end of this section, the areas 'Major Functions' and 'Minor Functions' will be displayed in reverse video, as well as the '1' and the '2' (but not the periods).
The actions part of the dictionary/text file used with dbshell(1) consists of simple shell commands or scripts that are executed when their labels are selected. These commands are located after the '%' marker in the file.
A label consists of a series of alphanumeric characters, with a dollar sign ('$') prepended to the label. In the example file presented, there are five labels: $1, $2, $mail, $ls and $print. Each of the associated actions connected to these labels will be executed as a shell script by the Bourne shell.
So, an entry of '1' (and a <RETURN>) at the "Enter Selection: " prompt would echo 'choice one' to the terminal. A '2' would change to another directory and run the database editor. Etc.
There are three special flags that can be placed after a label. A negative one (-1), as used in the '$ls' label, will cause dbshell(1) to NOT pause after returning to the menu before the screen is redrawn.
The '*' flag is used to denote a sub menu dictionary/text file. In this case, the sub menu is selected by issuing the command 'print' (since it is tied to the $print label). In the example, the actual menu file is PRINT. Note that a full path name to PRINT is not needed as long as it exists in the same directory as the calling menu. Thus, systems of menus can be written using relative pathnames. Also, the menus can be kept in one directory and invoked from another.
In this case, the initial command would be something like
dbshell menu_directory/MAIN.This MAIN menu can then invoke the PRINT submenu as in the example below. Again, dbshell will remember the menu_directory of the first invoked menu. This directory name will be prepended to all submenu names that are NOT full pathnames, i.e. that do not begin with a slash.
Optionally, after the '*', a directory name can be supplied. Using this feature, dbshell(1) will change directories to the supplied place, and then invoke the submenu. See the work submenu choice below.
The optional working directory can also be a true UNIX environment variable, prepended with a $ like standard shell variable. For example, if $CTSHOME was used, dbshell(1) will substitute in the contents of the UNIX environment variable CTSHOME.
The third special flag that can be placed after the label is the meta command $EXIT. Furthermore, this line can contain a number that will be used to exit, i.e. $EXIT 31 would use the exit value 31 upon termination.
This special meta command will cause a forced exit from dbshell(1). Any attached normal menu commands are executed before the exit takes place.
$Major_Functions $Minor_Functions
$1. Choice One $mail - Send system mail
$2. Edit Database $ls - list directory
$Sub_Menus
$print - Printout Sub Menu
$work - Work Menu
$quit - Quit
%
$1
echo choice one
$2
cd /usr/databases/work
dbedit -d master -i coname -s invoice
$mail
echo -n "Send mail to who? "
read MAILTO
echo "Enter mail message now. End with a '.'."
mail $MAILTO
$ls -1
ls -F
$print *
PRINT
$work * /usr/work
WORK
$q $EXIT 0
echo Good Bye
Security Note: The standard locking method used to disable dbedit(1) visual, filter and shell commands is implemented in dbshell(1) as well. This disabling lock, .cshell_lck, must appear in either the current directory or the system directory, /usr/lib/firstbase.
Dbshell(1) supports special meta-tokens that can be embedded within shell actions. These tokens are listed below.
This feature enables referencing of the FirstBase menu system from within other application menu systems using
$FIRSTBASEHOME/menu/MAINas the menu file referenced.
FirstBase User's Guide and Reference Manual