URL: http://www.firstbasesoftware.com/man/man1/dbedit.htm
Last modified: 4 April 1996
Copyright © by FirstBase Software.
[
Index of Contents] [
FirstBase RDBMS Overview]
Dbedit(1) and dbvedit(1) are similar in most all respects -- any feature that dbedit(1) contains is also a feature of dbvedit(1). In fact, unless otherwise noted, all of the following comments apply equally to dbvedit(1) and dbvscan(1).
But, there is one major difference between these FirstBase tools: the screen displays. Dbedit(1) will display fields of a database record in a fixed manner, one per line, double spaced. Dbvedit(1) allows the added dimension of customizing the display of fields and text on the screen. This additional feature requires a view dictionary that defines the visual screen requirements for that database. See view(5) for details.
Furthermore, dbvedit(1) allows the use of larger than normal windows to be used as the display screen. Using a larger window allows subscreens within dbvedit(1) to display more text per page. See terminals(5).
The -a option is used to force dbedit(1) to automatically begin add mode (as described below). In other words, with the use of the -a flag, only new records are entered and edited. In this case, exit from add mode will exit out of the editor completely. Note that for dbvedit(1), the -a can also be used to add exactly count records before automatically exiting.
The -e option is used to force dbvedit(1) to automatically begin editing record number Nrec. The -ex option is used to force dbvedit(1) to automatically begin editing the first indexed record matching the given pattern. Exit from record level using either of these options will exit out of the editor completely.
The -w flag is used to suppress the warning message generated when the editor is used without an index.
If an index is present, very fast record searching allows real time information scanning. Dbedit attempts to verify that the index being used was generated from the indicated database. If an identification error occurs, or dbedit(1) is invoked without a FirstBase index, dbedit(1) will warn that there is 'no index', but will proceed. Sequential searching for records can occur without an index.
Dbscan and dbvscan are the exact same as dbedit and dbvedit except that records cannot be created or updated with either of the scanners. If a password file exists (.passwd), dbedit(1) and dbvedit(1) prompt for a password before access is allowed.
Dbedit(1) begins by displaying an empty window of field names, field types and field sizes as defined by the FirstBase database dictionary. (See dbdbas(1) for details).
The field at the top of the screen is the first database field as defined in the index dictionary. If an index dictionary is not present, dbedit(1) assumes there is no index and the field at the top is the first field of the database as defined in the database dictionary.
With the use of the screen file and the -s option, dbedit(1) will use a FirstBase screen file to possibly change the order of the fields as they are being displayed. This mechanism is used as a physical-to-logical mapping. See dbdscr(1) for more details.
The cursor is placed on the field at the top of the screen awaiting user commands. A summary of these 'command level' commands appears below:
If the editor was invoked without an index, the > command will move the sequential search field to the next field on the screen. Further searches will be done using this new field. The optional N argument is used to jump straight to field number N.
The screen is redrawn to reflect the new search field selected.
If the editor was invoked without an index, the < command will move the sequential search field to the previous field on the screen. Further searches will be done using this new field. The dot does not change.
First, a new record is created and the user is allowed to enter data into each database field (even if the field is defined as locked -- see dbdbas(1) for details). Fields longer than 300 require some kind of a visual UNIX editor, for instance vi(1). The user will be asked whether to go into visual mode now or not. If not, that field remains empty.
If at any time the user wants to keep this record, but not enter the rest of the fields in the database, a special autodefault mode can be signaled using <CTL>-D (control-D). This signal will put the defaults described in the database dictionary into each field without asking questions. However, if any fields are defined as forced entry from the user, then dbedit(1) pauses briefly for this entry before continuing with its autodefault assignment. Autodefault works for only one record at a time.
The special editing features of the Auto Field Level (described in this manual page under the commands used for record level mode) apply while in Add Mode. These commands are very useful for correcting simple typos not seen until after a <RETURN> is hit. The major win is that you do not have to wait until the end of the record to make your corrections. Again, see Auto Field Level below.
After all fields are completed, the user is given a chance to modify and correct any fields within this new record via the record level command set (see below). When this record level is ended, add mode takes over, a new record is created, and the process starts again.
The standard END signal (-) from the first field of a record within add mode ends add mode. These records will be appended to the database, but have no effect on any existing simple indexes. However, autoindexes will be updated to reflect new record entries, although such indexes will not be reorganized. <FUNCTION>-END works also.
If a pattern is provided, the record search behaves exactly like that listed below for <pattern> (without the '/').
Alternately, <CTL>-S can be used to to search forward for the remembered pattern.
Note: here, as in all searches, the uppermost record, i.e. the record that is first in the index, is returned.
pwd - print current working directory set variable value variable is one of PUTFILE, REGEXP, VIPAUSE, WRAPSCAN and value is as defined in setup(5).
If the editor is invoked without an index, all record searches are sequential, and can be painfully slow. The standard UNIX <INTERRUPT> signal can be used during these sequential searches to regain control of the editor. Note that sequential searches are necessary for regular expression pattern location anyway, i.e. for interactively searching very large text fields. See the >, < and <CTL>-X <CTL>-X commands for more information on this topic.
When using the regular expression mathing facility (REGEXP=ON), the -C flag can be used for case-insensitive searching. All tests for string matches are done using UPPERCASE so that matches are case insensitive.
Note that during regular expression matching, some machines allow the meta character '.' to match a newline character and some do not. Typically, BSD UNIX allows this match and UNIX System V does not. The -N flag can be used to force FirstBase to map newlines to blanks so that the '.' within regular expressions will match a newline.
Searches will wrap at the top or bottom of the file by default. This means that forward searching will not stop at the bottom of the database if the record is not found, but will continue searching from the top of the database.
This wrapping feature can be turned off by setting the environment variable "WRAPSCAN" to 0.
Note that numeric fields are blank padded before the search. Also, if a date field is to be searched and is given six (6) characters, then it is formatted into the YYMMDD format before the search since this is how date indexes are generated. If less than six characters are given, the scan uses the pure form, meaning that years are searched, then months, then days.
If a record is found through a search or other means of addressing, it is pulled from the database for display. The current index field is used as the top of the page, and one page of the current record is displayed.
If using dbedit(1), the record is write locked at this point. Of course, others using dbscan(1) can still access the record.
In this completed display window field names, types, and sizes are seen, as well as the contents of the fields on that 'page'. If a field has non-white characters beyond the edge of the display window, it is marked with a '\'. These extra long fields may be viewed by typing the number of the field if the field is less than 300 characters long. Otherwise, visual mode must be used (see below).
At this point of record display, dbedit(1) is allowed to modify database fields, where dbscan(1) is not given this privilege. If the record has been marked as deleted, the user is given a chance to restore the record (if in dbedit(1)), and control goes back to the command level.
Otherwise, the cursor is placed on the 24th line along with a simple list of commands, and the editor awaits commands at this record level. The following is a summary of commands available for use when editing/scanning a particular database record. Again, this is called "record level" mode.
If visual/filter is not locked, dbedit(1) tries to get the visual/filter command from a simplified path sequence of directories. First the database directory is searched, then the users home directory, then the system directory. If a file named .visual exists in any of these places, the first line is read and used as the visual command (or .filter for the filter command).
Alternately, the standard UNIX environment variable EDITOR can be used to override the .visual file.
After successfully reading the command, dbedit(1) places the field into a temporary file. Note: dbscan(1) puts the field in a read-only file. Then the command with this temporary file name as an argument is submitted to the system. If using dbedit(1), the contents of the temporary file are reformatted and placed back into the proper field upon completion of the visual/filter command.
For example, if /usr/ucb/vi was in the .visual file, then the command v2 would invoke the UNIX editor vi(1) on field two. After the user is done with vi, all changes are put back into the field.
Filter/Visual commands not only provide a mechanism for using any text editor on any database field, but also allow a convenient method of pumping selected data from a FirstBase data file through user defined programs that can change or modify the data before it is placed back into the FirstBase record.
One handy use of the filter command, and the default setting, is to invoke a standard UNIX paging tool on a visual field, like more(1). The default FirstBase filter, as defined in $FIRSTBASEHOME/.filter, is fb_pager. Note that the filter command substitutes in standard UNIX environment variables if needed.
If no command is given, one is asked for. If the command is itself an exclamation mark (as in csh history), then the most recent command is re-submitted.
Before writing the record, dbedit(1) will check for fields that are not allowed to be empty. If any are found, dbedit(1) will complain and remain in Record Level. In this case, dbedit(1) will also fall into Field Level editing on the first field that needs to be edited. <FUNCTION>-END works also.
However, in dbvedit(1) each page has its own set of numbered, addressable fields, starting with the number '1'. These numbers are derived from the physical ordering of fields in the view dictionary. Using this ordering, and the entered "field number", a field on the current page will be edited. As in dbedit(1), the cursor is moved to that field and input is allowed. Again, this is called "field level" mode.
At this point, a standard help signal (<CTL>-H or <FUNCTION>-HELP) will display any user defined help file (see dbdbas(1)). When done, FirstBase continues allowing user input into the field. At any time input may be aborted using <CTL>-X, <CTL>-C or <FUNCTION>-ABORT (see input(5)), and the field will not be altered.
Extra long fields that will not fit into the dbedit(1) display window are given special attention. Such fields are longer than 50 or 80 characters (dbedit(1) or dbvedit(1)), and less than or equal to 300 characters. These fields can be seen in their entirety by addressing them from this inner "record level" command line. (Or by using the 'd' command. And for even longer fields, use the visual command).
On the long field screen, a special display area is shown with the full contents of the field (maximum is 300 characters). Then the user is asked about making changes to this field (y=yes, any other character means no). Standard help (<CTL>-H) and abort (<CTL>-X) signals are available here, also. Modifications using this long field screen allowable only in dbedit(1)
During modifications of these long fields, the user is allowed to enter input into the field in segments. The first segment is what will appear within the normal dbedit(1) display window.
A <CTL>-X during this entry will pull the matching line from the display area (if it exists) into the input area, thus allowing pieces of the field to be changed without having to retype the entire mess.
Normally, dbedit(1) will store a blank between each line of input from these long fields. To override this feature, use the backslash character as the last character on the previous line. This will put the two lines together without a separating blank when the field and record are written to the database.
To END out of input into a long field without filling the field, a <RETURN> is required on the first column of one of the input segments.
If entry to a field is allowed to be defaulted (see dbdbas(1)) then entering a <RETURN> during the input of a field will enter the default into the field.
However, if RECORD_LEVEL is OFF, then a <RETURN> will only behave this way if the field is empty -- otherwise it behaves like <FUNCTION>-NEXT. If a default value is truly required, use <FUNCTION>-DEFAULT.
A few meta-defaults are defined, allowing incrementing of a numeric field, pulling in the previous entry to that field, defaulting to today's date, or even to the current time.
If the field requested is of type choice or extended choice (see dbdbas(1), choice(5), xchoice(5), and the chapter on dbedit(1) in the FirstBase User's Guide and Reference Manual), then a sub screen will be displayed. This screen will allow the user to enter a single choice, and the meaning of that choice will then be input into the field by dbedit(1).
Note that the sub screen display can be disabled by using the type C for choice instead of c. In this case, the field editing behaves like macro expansion, i.e. all other choice field behavior will stay the same.
Under normal operation a selection of a value for a choice field fails if the choice is undefined. However, dbvedit(1) has the ability to add new choices defined by the user during record entry to the proper choice file. To enable this feature, the AddChoice Flag (-A) for the individual field must be set from dbdbas(1).
If the field requested is not on the screen, the page with that field on it is displayed.
Of course, formula fields cannot be edited, as they are merely calculated from the contents of other fields. Note: If the contents of an indexed field is changed, the index is not updated (unless it is an autoindex).
The behavior of this "field level" mode can be modified by using a macro field definition. This feature allows fields to contain very complex defaults, or be used as trigger fields, providing conditional editing of other fields. See macro(5).
There are also other keystrokes that are used to move around while in Auto Field Level. <CTL>-X and <CTL>-C will move past a field. <CTL>-E, <CTL>-N, <TAB>, and <FUNCTION>-NEXT will move to the next field, and <CTL>-Y, <CTL>-P and <FUNCTION>-PREV will move to the previous field. Each of these keystrokes will not disturb any field data already in place.
If you get to the end of the record, Auto Field Level will stop, and the editor will go back into Record Level Mode.
Note: the put command attempts to verify that previous 'puts' came from the same database, but no effort is made to verify that the index being written to is the same size and shape of the current index. This index can later be used for printouts, or any other place a FirstBase index is used.
The name of the file that the put command deposits the index references defaults to "putidx". This name can be changed using by setting the environment variable "PUTFILE" to some other file name. However, do not use any file name extensions.
Note that unlike autoindexes, the put mechanism does not create an index dictionary, but only an index and an index header.
The idea is to set one of the ten environment variables, CCOMMAND0 through CCOMMAND9, to be the name of an executable file. Naming of commands is done using the standard methods of tuning the FirstBase environment. See setup(5) for more.
When invoked from the Record Level of dbvedit(1), a CCOMMAND will cause two temporary files to be generated for use by the designated executable: a token-separated version of the current database record (along the lines of dbemit(1)), and a tiny FirstBase index representing the current record. NOTE: The invocation of dbvedit(1) must also use a FirstBase index of some kind.
The two temporary file names are passed on to the executable file as command line parameters. For example, if CCOMMAND=print was set up in the command line or in the setup file, then using the keystrokes print from Record Level will invoke the print script file from the CCOMMAND working directory with proper arguments. In shell parlance, $1 will be the data file, $2 the index file.
Both temporary files are deleted when the executable exits and control returns to Record Level. Explicit control is given over the working and home directories of the CCOMMAND. See setup(5) for more.
Also, the -s option for dbvedit(1) can be used to impose a screen dictionary layout to the emission of the temporary datafile. Other controls over this data file include the -c option to control the field separator, and the -f and -V options to produce formula fields and verbose formatting of dollar/date fields.
Note: if needed, the current record will be written to disk before the custom command is run.
Dbedit(1) does interactive error checking on all input. Simple editor commands for the current command level are displayed on the 24th screen line at all times, with a full summary only a help signal away (<CTL>-H).
One of the tunable features supported by dbvedit(1) is a blended record level and autofield level that in effect hides record level during editing. This feature, enabled by turning RECORD_LEVEL OFF, means that some of the functionality of record level is disabled, but the effect is a more modeless editing environment.
FirstBase User's Guide and Reference Manual
The database editors (and FirstBase tools in general) must have write
access to the map file since this file is used as the lock file.
Note: this lock file also applies to the database
scanners,
dbscan(1) and
dbvscan(1).
A different segment of the map file is used to lock each record.
The record header information is also locked using the map file.
So, to enable cooperating processes to properly block each other on lock
requests, the map file must have write permissions.