This is Info file database.info, produced by Makeinfo-1.55 from the input file database.texi.  File: database.info, Node: Making changes permanent, Next: Adding and removing records, Prev: Undoing all changes to a record, Up: Database view mode Making changes permanent ======================== The user edits a copy of a database record; the database itself is not changed until the user commits the changes. This occurs automatically whenever any command causes a different record to be displayed, when the database is saved, when a report is generated, and so forth. It does *not* occur when the user switches from edit mode to view mode, though the field modification flag (in the mode line) will become a percent sign and the record modification flag, an asterisk. When the record is committed, the record modification flag will become a dash and the database modification flag will become an asterisk. The user can manually install the current record, as modified, into the database. The following two functions are identical: `RET' (`db-accept-record') Install the current record in the database; make any changes permanent. `M-x db-commit-record' Install the current record in the database; make any changes permanent. Committing a record makes the changes permanent only insofar as they become part of the in-memory representation of the database. The on-disk version is not affected unless the user overwrites it by using `db-save-database' or `db-write-database' (*note Invoking EDB::.), or otherwise indicates that the database should be written to disk (say, by responding to a question about saving the database).  File: database.info, Node: Adding and removing records, Next: Exiting database mode, Prev: Making changes permanent, Up: Database view mode Adding and removing records =========================== `a' `i' (`db-add-record') Add a new record to the database immediately before the current record. `c' (`db-copy-record') Insert a copy of the current record in the database immediately after it. The second of the two records is made the current record. With a prefix arg, inserts that many copies. `o' (`db-output-record-to-db') Copy the current record to DATABASE. dATABASE must be read in and compatible with the current database. `d' `k' (`db-delete-record') Remove the current record from the database. With a prefix arg, doesn't verify. By default, deleting a record marks the database as modified. Set the following variable to change this behavior. `db-delete-record-modifies-database-p' Non-`nil' if deleting a record should mark the database as modified.  File: database.info, Node: Exiting database mode, Prev: Adding and removing records, Up: Database view mode Exiting database mode ===================== `q' (`db-quit') Quit editing the database for now; bury its buffers. `x' (`db-exit') Be done with the database; like `db-quit', but offers to save any changes. With prefix arg, kills the data display buffer, and the database, if that was its only data display buffer. You can also kill a database buffer in the usual way (for instance, by using `kill-buffer'); this causes `db-kill-buffers' to be called. If the database's last buffer is killed this way, the database itself is also killed. No offer is made to save changes; call `db-exit' in order to do that. `db-kill-buffers' Kill this buffer, and the associated summary or data display buffer, if any. If its last data display buffer is killed, the database is killed too. Does not offer to save changes to the database or to this record; use `db-exit' with optional argument to do so.  File: database.info, Node: Database edit mode, Next: Searching, Prev: Database view mode, Up: Top Database edit mode ****************** In database edit mode, point is always in the field currently being edited. The database is not modified as soon as changes are made in edit mode. A copy of the record in question is displayed and edited, and only when the user moves to a new record, initiates some other global action (not specific to the edited record), or explicitly commits the changes (*note Making changes permanent::.). This permits easier undoing of incorrect modifications. In order to perform most record-level operations, the user exits edit mode, switching to view mode, and then performs them there. Several commonly used commands, however, such as searching and moving from record to record, are accessible directly from edit mode. Commands that move from field to field check the validity of the current field before moving off it; commands that move from record to record do this as well, then make any changes in the current record permanent (though the database file on disk is not changed). Basic operations are described here; more complicated ones are given sections of their own. * Menu: * Exiting edit mode:: Exiting edit mode * Undoing changes to a field:: Undoing changes to a field * Moving from record to record:: Moving from record to record * Moving from field to field:: Moving from field to field * Movement within a field:: Movement within a field * Editing a field:: Editing a field * Getting help:: Getting help  File: database.info, Node: Exiting edit mode, Next: Undoing changes to a field, Up: Database edit mode Exiting edit mode ================= `C-c C-c' (`db-view-mode') Switch to database view mode. With an argument, toggle between view and edit modes.  File: database.info, Node: Undoing changes to a field, Next: Moving from record to record, Prev: Exiting edit mode, Up: Database edit mode Undoing changes to a field ========================== You can undo changes to the current field via Emacs' usual undo facility; use `C-x u' or `C-_' to undo changes made since entering the current field. You can also revert the current field to its original value; this is useful if you made a change, moved off the field, and then moved back onto it. `C-x U' (`db-revert-field') Replace the onscreen text in this field with that of the underlying record. In other words, undo any changes made since entering this field. From database view mode, you can simultaneously revert every modified field of a record to its original value; see *Note Undoing all changes to a record::.  File: database.info, Node: Moving from record to record, Next: Moving from field to field, Prev: Undoing changes to a field, Up: Database edit mode Moving from record to record ============================ These commands make any changes to the current record permanent. `M-n' (`db-next-record') Go to the ARGth next record. In that record, go to the current field, if any. `M-p' (`db-previous-record') Go to the ARGth previous record. In that record, go to the current field, if any.  File: database.info, Node: Moving from field to field, Next: Movement within a field, Prev: Moving from record to record, Up: Database edit mode Moving from field to field ========================== `TAB' (`db-next-field') Move to ARGth next reachable field, wrapping if necessary. When called interactively, ARG defaults to 1. `M-TAB' (`db-previous-field') Move to ARGth previous reachable field, wrapping if necessary. When called interactively, ARG defaults to 1. `M-<' (`db-first-field') Move to first field. `M->' (`db-last-field') Move to last field. Also see the keystrokes `C-n' and `C-p', described below.  File: database.info, Node: Movement within a field, Next: Editing a field, Prev: Moving from field to field, Up: Database edit mode Movement within a field ======================= Many Emacs cursor motion commands retain their standard meanings, except that they do not move outside the field; among these are `C-f' (`forward-char'), `C-b' (`backward-char'), `M-f' (`forward-word'), `M-b' (`backward-word'), `C-a' (`beginning-of-line'), and `C-e' (`end-of-line'). The line-movement commands have slightly changed meanings: if the motion would take the cursor out of the current field, then they move to the next field. `C-n' (`db-next-line-or-field') Move to ARGth next line. If that would move out of the current field, move to the closest field to that, but not the current one, wrapping if necessary. `C-p' (`db-previous-line-or-field') Move to ARGth previous line. If that would move out of the current field, move to the closest field to that, but not the current one, wrapping if necessary.  File: database.info, Node: Editing a field, Next: Getting help, Prev: Movement within a field, Up: Database edit mode Editing a field =============== Many Emacs editing commands retain their standard meanings; for instance, printing characters insert themselves and deletion commands work as usual, except that they will not make changes outside the field; among these are `C-d' (`delete-char'), `DEL' (`backward-delete-char'), `M-d' (`kill-word'), `M-DEL' (`backward-kill-word'), and `C-k' (`kill-line').  File: database.info, Node: Getting help, Prev: Editing a field, Up: Database edit mode Getting help ============ You can get some information about the current field, such as what type of value it expects or what its contents signify, by using the following command. `M-?' (`db-field-help') Display help for current field using the recordfieldspec help-info field. If this is a string, display it. If it is a form, eval it and display the result.  File: database.info, Node: Searching, Next: Sorting, Prev: Database edit mode, Up: Top Searching ********* A useful and commonly used database operation is searching for records that meet some criteria: for instance, finding a particular record or indicating that following operations should only apply to records that correspond to an address in greater Boston. EDB provides several functions to support such operations. To perform a search pertaining to the contents of only one field, move to that field and use the following command: `M-s' (`db-search-field') Search for occurrences of PATTERN in the current field of any record. Finds the first match after the current record; wraps around automatically. With prefix arg, marks all matches in addition to going to the first one. If omitting is in effect, omitted records are ignored. The same keystroke in view mode permits specification of patterns which depend upon the contents of several fields: `s' `M-s' `M-S' (`db-search') Please do not use `db-search', which is unimplemented; use `db-search-field'. In a future version of EDB, `db-search' will permit searching on all fields of a record simultaneously. For a description of marking, see *Note Marking and omitting::. * Menu: * Search patterns:: Search patterns  File: database.info, Node: Search patterns, Up: Searching Search patterns =============== Search patterns can be as simple as a datum to match exactly or as complicated as the conjunction, disjunction, and negation of tests to be performed on field contents. Basic patterns -------------- A basic search pattern has the same form as the data that is kept in the field; for instance, to search in a string field for a particular string, use that string; to search for the date March 14, 1967, use `3/14/67' or `14 March 1967' or any other accepted date format. A basic pattern is treated somewhat more richly than a literal, however. In a string field, typing a string results in a match for any element which contains it as a substring; typing `ail', without the quotes of course, will match both "ailment" and "fail". In a date field, `3/67' will match any date in March of 67, not just those March 67 dates which specifically exclude a day of the month. Comparisons ----------- A search pattern may also be a comparison prefix (<, >, or =) plus a datum which is treated exactly like any other element of that field. In a string field, `3/14' will match dates after March 14 in any year, and `=3/67' will match only dates in March 67 whose day of month is not specified. For more information about the interpretation of patterns, see the documentation for the particular types. Logical connectives ------------------- More complicated patterns can be built up out of simpler ones via the logical connectives AND, OR, and NOT. These work in the obvious way. One pattern which finds any date between the ides of March and Christmas, inclusive, is `> 3/14 AND < 12/26'; two patterns which find dates except March 14 are `NOT 3/14' and `< 3/14 OR > 3/14'. To find strings that either contain the substring "ail" or start with a, b, or c, use `ail OR < d'. The precedence of these connectives is: NOT, which is most tightly bound to its test, then OR, then AND. There are no provisions for grouping or otherwise overriding this ordering. Connectives (and REGEXP, described below) consume all surrounding spaces and tabs. Other pattern operations ------------------------ One other pattern operation of interest is the regexp operator for string fields. This is invoked by either using REGEXP with surrounding spaces, or / without a trailing space. For instance, `/^[ace]' matches any string field starting with a, c, or e; `/.' matches any nonblank string field; and `NOT REGEXP a.*b.*c' matches any string which does not contain the letters a, b, and c in order. This last example shows that EDB's search commands are more powerful than general regular expression searching.  File: database.info, Node: Sorting, Next: Summary mode, Prev: Searching, Up: Top Sorting ******* `M-x db-sort' Sort the database. With a prefix arg, don't confirm the sort order. Ordinarily, calling this function invokes a graphical field ordering tool which permits easy specification of which fields are significant and what their order of importance as sort keys is. In a database whose records had fields foo, bar, baz, bum, and bee, and in which records should first be sorted on baz in increasing order, then on foo in decreasing order, and finally on bum in increasing order, ignoring bar and bee entirely for the purposes of the sort, the display would look like ==== Significant fields: baz increasing foo decreasing bum increasing ==== Nonsignificant fields: bar increasing bee increasing ==== Omitted records to end: No In addition to which fields should be sorted by, the sort interface permits specification of how omitted records should be treated. `t' (`dbsi-toggle-omitted-to-end') Toggle the boolean value of dbsi-omitted-to-end-p. This controls whether omitted records should all be placed at the end of the sorted order or should be sorted according to the same criteria as non-omitted records. To change the relative order of fields, and whether they're significant or not, use the following commands. `C-k' (`dbsi-kill-line') Kill field on current line, placing it in the sort interface kill stack. `C-y' (`dbsi-yank-line') Yank most recently killed (lifo ordering) field, inserting it before point. This removes the field from the sort interface kill stack. To specify how a particular field should be ordered, use the following commands. `i' (`dbsi-increasing') Specify that the field at point should use an increasing ordering. `d' (`dbsi-decreasing') Specify that the field at point should use a decreasing ordering. `o' (`dbsi-ordering-function') Specify an ordering function for the field at point. An "ordering function" returns -1, 0, or 1 depending on whether its first argument is less than, equivalent to, or greater than its second argument. `s' (`dbsi-sorting-function') Specify a sorting function for the field at point. A "sorting function" returns `t' if its first argument is less than its second argument and `nil' otherwise. Each database has a default sort order in its `field-priorities' slot (*note The database structure::.) which is used when setting up the sort interface (and is used for sorting when no other ordering information is specified). When the user exits the sort interface, that slot can be set to the ordering depicted on the screen (see below). Each data display buffer also has a default sort order: the database's `field-priorities' slot is ignored if the variable `dbf-field-priorities' is `nil'. The sort interface permits the setting and clearing of this value as well; when it is cleared, the default sort order is once again taken from the database's `field-priorities' slot. Setting the database's sort order automatically clears the buffer-local sort order. `dbf-field-priorities' The list of field priorities for this database in this data display buffer. If non-`nil', overrides the database's field-priorities slot. `dbf-omitted-to-end-p' The default, local to this data display buffer, for the omitted-to-end-p database slot. Only used if dbf-field-priorities is non-`nil'. The following commands are used to exit the sort interface; most of them also cause the database to be sorted. Some of them set the default ordering for the database or the data display buffer. `RET' `C-c C-c' (`dbsi-use-ordering-make-database-default') Use the current ordering to sort, and make it the default for future sorts of this database. The user is warned if there are killed, non-yanked fields. `A' `U' (`dbsi-use-ordering-make-buffer-default') Use the current ordering to sort, and make it the default for future sorts in this data display buffer only. The user is warned if there are killed, non-yanked fields. `a' `u' (`dbsi-use-ordering') Use the current ordering for this sort only. `!' (`dbsi-this-field-only') Sort according to only the field at point. All editing of other fields is ignored. `q' (`dbsi-quit') Abort the sort and exit the sort interface. `c' (`dbsi-quit-clear-buffer-default') Clear the default sort order for this buffer and exit the sort interface without sorting. In the future, the default sort order will come from the database. The sort interface returns a field priorities list to be used when sorting; when the sort interface is entered, either the value of the `dbf-field-priorities' variable, or the database's `field-priorities' slot, is being used. For information about the format of the field priorities list, see *Note The database structure::. Sorting does not ordinarily mark the database as modified, because not the data itself, but only the way it is arranged, has been changed. If you can set `db-sort-modifies-p' to non-`nil', then whenever a database is sorted (even if the resulting order is the same as the original one), the database will be marked as modified. `db-sort-modifies-p' If non-`nil', then sorting a database marks it as modified too. * Menu: * Sorting functions:: Sorting and ordering functions  File: database.info, Node: Sorting functions, Up: Sorting Sorting and ordering functions ============================== In order to specify the relative order of two field values (for the same field, but from different records), the database designer provides a sorting function, an ordering function, or both. If only one is provided, the other is automatically generated from it. In any event, only one of them is used for a given field on any particular sort. A sorting function takes two field values as arguments and returns `t' if its first argument is less than its second argument (that is, the first argument appears previous to the second in the sorted order). The sorting function returns `nil' if the arguments are equal or if the first argument is greater than the second (appears later in the sorted order). An ordering function, on the other hand, returns complete information about the relative order of its two arguments: it returns -1, 0, or 1 depending on whether its first argument is less than, equivalent to, or greater than its second argument. Use of an ordering function can result in fewer comparisons in some cases, because it returns more information. This is worthwhile if a significant amount of processing is required before the comparison is done. For example, suppose that two addresses are being carefully checked for equality and some of the steps leading up to that are expansion of abbreviations, standardization of spelling, capitalization, and spacing, etc.; then it is better to return the exact relative ordering than to possibly require another time-consuming operation to determine it. If it is possible to canonicalize the values beforehand, that may be even more efficient, but that is not always possible; consider the case of a small (but tedious to extract) part of the information in each field being compared. Therefor, the user is permitted to specify an ordering function.  File: database.info, Node: Summary mode, Next: Marking and omitting, Prev: Sorting, Up: Top Summary mode ************ A summary is a listing containing abbreviated information about every record; it permits many records to be viewed at once. This is available in view mode via the following command: `D' `H' `h' (`db-summary') Display a summary (or directory) of all database records according to the variable `dbf-summary-function', which is set by `dbf-set-summary-format'. The summary appears in a separate buffer. When called from the summary buffer, this updates the summary. When a summary is created, the summary display format appears in the summary buffer once for each record, with appropriate values substituted for its display specifications. Omitted records are included in the summary only if the data display buffer variable `dbf-summary-show-omitted-records-p' is non-`nil'. `dbf-summary-show-omitted-records-p' Nil if omitted records should be omitted from the summary, `t' otherwise. The entire format is indented by two characters; the first and second columns contain `+' and `[', respectively, if the record is marked or omitted. For information about marking and omitting records, see *Note Marking and omitting::. The summary buffer is not updated whenever a record value changes; in the interest of efficiency, it remains as is until the next `db-summary' command is issued, at which time the summaries are redisplayed after all, some, or none of them have been recomputed. For the same reason, when a single mark or omit bit changes, the summary is updated; when many change, it is usually not. [[[Describe exceptions. This may change soon in any event.]]] When point is in the summary buffer, the associated data display buffer (nearly) always displays the record under point. (Some Emacs commands can move point without EDB noticing.) Movement in the summary buffer is by any of the ordinary Emacs commands, including searching. Most view mode commands also work in the summary buffer. The summary display format defaults to the first non-literal line in the database display format--that is, the first line which contains a display specification. Summary display formats can display information any way that an ordinary display format can, including showing more than one field of the record in question or spanning several lines. The only restriction is that the summary display format must cover a specific number of lines: each display specification must have its `min-height' and `max-height' slots set to equal values. For more information about display formats, *Note How information is displayed::. The following command may appear in a format file or an auxiliary file, or it can be invoked directly by the user. When it appears as an Emacs Lisp form, remember the special meaning of the backslash character and double it where necessary. `M-x dbf-set-summary-format' Specify the format used in the Database Summary buffer. Argument SUMMARY-FORMAT is a string containing display specifications. Call this in the data display buffer, or in a format file or auxiliary file.  File: database.info, Node: Marking and omitting, Next: Reports, Prev: Summary mode, Up: Top Marking and omitting ******************** The marking facility permits operations to be performed on only certain records of a database. For instance, to create a report which describes only some of the database records, you would first mark the records of interest. Then you would call `db-report' with a prefix argument (do so by pressing `C-u' first), or would make optional second argument MARKEDP non-`nil'. See the documentation of the individual operations to see whether they support operation on only the marked records. The omitting facility is similar to the marking facility in that it restricts attention to a subset of the current database; however, omitted records are ignored by most operations. By default omitted records are skipped by the record-motion commands, excluded from searches, reports, and other functions, and so forth. Omitting is useful when the user wishes to concentrate on a subset of the database without being distracted by other records that may be present; while the records are still present in the database, they are not seen by the user. Mark and omit bits are associated only with the version of a database being operated upon. They are never saved in the database file, and when a database is first read in, all of its mark and omit bits are unset; that is, they are boolean false. (When a database is written to disk, although the disk version of the data will not contain the mark and omit information, that information is not lost from the working copy of the database.) This behavior is a feature, not a bug. Marking and omitting are intended to help the user temporarily group database records for operations upon it; if there is information that cannot be recreated from a record's fields, then the user should consider adding another field for that information. On the other hand, mark or omit criteria may be complicated. If such a pattern is used often, then the user may wish to write a function to set the bits appropriately, which function could be bound to a keystroke or automatically executed when the database is read in. * Menu: * Setting the mark and omit bits:: Setting the mark and omit bits * Movement among marked and omitted records:: Movement among marked and omitted records * Details of omitting:: Details of omitting  File: database.info, Node: Setting the mark and omit bits, Next: Movement among marked and omitted records, Up: Marking and omitting Setting the mark and omit bits ============================== Every record may be thought of as having a pair of bits or boolean values indicating whether it is marked and whether it is omitted. The most straightforward way to set these bits is to use an operation to mark, unmark, omit, or unomit a particular record; these are bound to keystrokes in database view mode. `m' (`db-mark-record') Toggle whether the current record is marked. With a nonzero prefix argument, set it to be marked. With a zero prefix argument, set it to be unmarked. `O' (`db-omit-record') Change whether the current record is omitted. With a nonzero prefix argument, set it to be omitted. With a zero prefix argument, set it to be unomitted. The searching commands, when called with a prefix argument, mark each matching record; *Note Searching::. Once all records of interest have been marked, through one or more marking and/or searching commands, unmarked records can be omitted from consideration. This is useful if you want to work on only a small number of records, or if specifying the records of interest is easier than specifying those not of interest: instead of omitting all the uninteresting records, simply mark the interesting ones, then use the following command to cause the unmarked ones to become omitted. `M-x db-omit-unmarked-records' Omit all unmarked records. Also clears all mark bits and sets `dbc-omit-p'. The converse operation transfers information from the omit bits to the mark bits. `M-x db-mark-unomitted-records' Mark all unomitted records. Also clears all omit bits. It is also possible to clear all the mark or omit bits. `M-x db-unmark-all' Clear the mark bit of every record. `M-x db-unomit-all' Clear the omit bit of every record.  File: database.info, Node: Movement among marked and omitted records, Next: Details of omitting, Prev: Setting the mark and omit bits, Up: Marking and omitting Movement among marked and omitted records ========================================= Ordinarily, record movement commands (those which move from one record to another) ignore omitted records, so that the user never lands on an omitted record. Marked records, on the other hand, are not treated specially by the record movement commands. The following database view mode keystrokes permit you to move to omitted records or to move directly to marked records. `M-n' (`db-next-record-ignore-omitting') Go to the ARGth next record, ignoring omissions. That is, all records, even those which are omitted, are counted. `M-p' (`db-previous-record-ignore-omitting') Go to the ARGth previous record, ignoring omissions. That is, all records, even those which are omitted, are counted. `M-C-n' (`db-next-marked-record') Go to the ARGth next marked record. Omitted records are treated according to db-omit-p. `M-C-p' (`db-previous-marked-record') Go to the ARGth previous marked record. Omitted records are treated according to db-omit-p.  File: database.info, Node: Details of omitting, Prev: Movement among marked and omitted records, Up: Marking and omitting Details of omitting =================== The "omitted" bit of each record has no effect unless the following variable is set: `dbc-omit-p' Non-`nil' if omitting is in effect, `nil' otherwise. Use function `dbc-set-omit-p', which works in either a data display buffer or a summary buffer and sets the variable's value in both, instead of setting this directly. Setting this to `nil' is cheaper than changing the omit function to the empty one, since no omit bits are recomputed. This variable is automatically set by the omitting functions. When `dbc-omit-p' is `nil', the values of records' omit bits are remembered, and they may still be set and unset, but they have no effect on any operations until `dbc-omit-p' is once again set to non-`nil'. When `dbc-omit-p' is non-`nil', "Omit" will appear in the mode line of the database buffer. The following operations work in either database view mode or database summary mode. `M-o' (`db-omitting-toggle') Change whether omitting is in effect. With a nonzero prefix argument, turn omitting on. With a zero prefix argument, turn omitting off. This does not change the current omit-function, and an omit bit is always computed for each record, but omit bits have no effect on any operations if omitting is not in effect. `M-C-o' (`db-toggle-show-omitted-records') Toggle whether omitted records are shown in the summary. With a nonzero prefix argument, show omitted records in the summary. With a zero prefix argument, don't show omitted records in the summary. `M-O' (`db-omitting-set') Set the criteria for automatically determining whether to omit a record. This isn't implemented yet.  File: database.info, Node: Reports, Next: Specifying the display format, Prev: Marking and omitting, Up: Top Reports ******* Reports can be generated from a database by using the following command in view mode: `r' (`db-report') Create a report according to REPORT-FILENAME. Prefix argument MARKEDP, if non-`nil', means report on only marked records. If omitting is in effect, omitted records are not reported upon. When called interactively, prompts for REPORT-FILENAME. The way a report looks is specified in precisely the same as are display formats and summary formats (*note How information is displayed::.). This information must be placed in a file; the user cannot type it directly when creating a report. This restriction makes errors in the report format easier to correct. The report is placed in the `*Database Report*' buffer, which is in Text mode. The information may then be edited, saved to disk, or otherwise manipulated. The buffer is in Text mode and is not yet a file; you must save it to make it a file. To create a report which mentions only marked records (*note Marking and omitting::.), supply a prefix argument to the report command by typing `C-u' first. * Menu: * Bugs in report generation:: Bugs in report generation  File: database.info, Node: Bugs in report generation, Up: Reports Bugs in report generation ========================= There are currently a few unfortunate bugs in EDB's handling of reports. The most noticable of these are errors in the handling of format information: primarily, indentation is not respected. These problems will be corrected in a future release of EDB.  File: database.info, Node: Specifying the display format, Next: Designing a database, Prev: Reports, Up: Top Specifying the display format ***************************** Different layouts and on-screen arrangements of the values stored in database records are appropriate when the user is concentrating on different aspects of the data. Sometimes the user would prefer to see just a few of the fields; at other times he may want to see the records in full detail. It may also be appropriate for the display format of a record to depend on the record's field values. This section describes how to choose a different display format for the record being displayed, either manually or automatically. * Menu: * Changing display formats:: Changing display formats * Execution of format file eval expressions:: Execution of format file eval expressions * Making additional data display buffers:: Making additional data display buffers  File: database.info, Node: Changing display formats, Next: Execution of format file eval expressions, Up: Specifying the display format Changing display formats ======================== EDB permits the creation and use of a variety of display formats with a single database; the user can also conveniently change the way that a particular record is displayed by using `db-alternate-format' and specifying the filename of the new display format, or a nickname for the format that has been specified by the user or the database designer. Choosing a different format does not create a new data display buffer; it changes the way that records are displayed in the current one. `M-x db-alternate-format' Select and use an alternate display format to view the database. If neither FORMAT-NAME nor FILENAME is specified (as is the case when this is called interactively), the user is prompted for them. In Emacs Lisp code, if `dbf-alternate-format-names' has been been set, usually only one of the arguments is specified. If both are specified, then FORMAT-NAME becomes a name for the format FILENAME specifies; if FORMAT-NAME is already associated with a different format file, an error is signalled. If the current format is unnamed, the user is prompted for a name to give it, so that it can be conveniently restored if need be. This behavior is suppressed, and the record is not displayed, if the function is not being called interactively. Selecting the current format does not cause any work to be done. Some databases automatically set the format of the record being displayed, usually by setting `dbf-before-display-record-function' to a function that overrides the format in effect when a record is about to be displayed. This may cause this function to appear not to be doing any work. In actuality the format is being set, then reset. `dbf-alternate-format-names' Association list of format names and format specifiers. Each format name is an arbitrary string. A format specifier is a filename or a list of values for format variables. The user sets the format specifier to a filename, and after that format file has been read, EDB replaces the filename with a list of values for format variables, so that the file need not be read again. It is convenient for a database designer to set this, pre-assigning format names to files so that the user only needs to remember the format names, not the filenames. `dbf-format-name' The string representing the format currently in use. `dbf-format-file' The format file from which this format was built. These values can be set in the auxiliary or format files so that the user can choose a format name (with completion) instead of having to remember a filename. If the selected format's specifier is a filename, then after the file is read in, the format-spec is modified by replacing the filename with information about the format such as the displayspecs, the invariant text between them, and so forth. Subsequent selections of that format will not cause disk accesses. For an example of the use of `db-alternate-format', see *Note Record display hooks::. While it is not currently possible to selectively omit certain fields from a data display buffer, judicious use of alternate formats can result in nearly the same effect.  File: database.info, Node: Execution of format file eval expressions, Next: Making additional data display buffers, Prev: Changing display formats, Up: Specifying the display format Execution of format file eval expressions ========================================= Often the "local variables" section of a format file contains code that should only be executed once, or should only be executed before the database is read in, because of either efficiency or correctness constraints. Because of this, the "local variables" section of a format file is executed only when it is read in from disk (which is usually only once). In order to cause an expression to be evaluated every time that a particular display format is selected, use the `dbf-always' macro: `dbf-always' Execute BODY, and place its forms in `dbf-always-forms'. They will be executed each time that this format replaces another. `dbf-always-forms' Forms executed every time that the format is selected. These forms are only executed when a different format is replaced, not every time that a record is displayed (or even every time that `db-alternate-format' is called). See also `dbf-before-display-record-function'. Of course, it is often valuable to overwrite a value when the display format changes; this is the purpose of `dbf-always'. It is always safe to set variables whose name begins with `dbf' in such forms, though changes to some such values--none of which the user should be changing anyway--will not take when a display format is being returned to (though they will work when it is first chosen). This will affect the user only in that a call to `dbf-set-summary-format' will have an effect only the first time that a format file is read in, not every time that it replaces another, even if it is enclosed in a `dbf-always' form. The forms in `dbf-always-forms' are not executed every time that a record is displayed, or even every time that `db-alternate-format' is called, but only when a format replaces another one (that is, `db-alternate-format' is called and its first argument is not equal to `dbf-format-name'). Here is an example of a common problem with an expression which causes an error if evaluated every time that the format is selected. The primary format file (the one that is used when the database is read in) is permitted to set the `fieldnames' slot of the database structure to a list; other parts of the database initialization code propagate that information into other slots of the database structure and change the list into a vector, which is its proper representation. If the user switches to another display format and back to the primary one, and the `database-set-fieldnames' expression was evaluated, then the next attempt to access the `fieldnames' slot of the database as a vector would cause an error. In this case, the proper solution is to use `database-set-fieldnames-to-list' (*note The database structure::.) instead, but such functions are not provided for every slot that it would be dangerous to set. If several format files all set a value which is dangerous to change, then another possibility is to check the value before setting it: if it is already set, then don't do anything. Another possibility is to move all assignments to database slot values from the format file to the auxiliary file.  File: database.info, Node: Making additional data display buffers, Prev: Execution of format file eval expressions, Up: Specifying the display format Making additional data display buffers ====================================== In addition to changing the display format of an existing data display buffer, it is sometimes useful to have two different data display buffers both examining the same database, either so that two different records can be viewed or edited simultaneously or so that two different formats can be used at the same time--or both. Use the following function to create a second (or additional) data display buffer for the current database. `M-x db-additional-data-display-buffer' Create another data display buffer in which to view this database. If you edit the same record in more than one data display buffer, only the last one committed (by calling `db-commit-record', moving to another record, saving the database, etc.) will have an effect. (Simply switching from database edit mode to database view mode does *not* commit the changes; failing to commit changes will make it appear that changes in one data display buffer are not being communicated to the other ones associated with the same database. For more on committing, see *Note Making changes permanent::.) It is perfectly safe, however, to edit different records of the same database in different data display buffers, or to perform any other database manipulations. This section does not describe how to specify a new format, only how to use multiple data display buffers. To learn about formatting directives and specification of display format files, see *Note How information is displayed::.  File: database.info, Node: Designing a database, Next: Record field types, Prev: Specifying the display format, Up: Top Designing a database ******************** Preceding chapters have discussed the use of an already-existing database. However, before a user can manipulate a database using EDB, a database designer (who will possibly also be a user later on) must have specified pertinent information about the database, including * the number of fields per record and the type of each one (*note Record field types::.); * the layout of the file containing the database (*note Database file layout::.); * how each record should be displayed on the screen when it is being viewed or edited (*note How information is displayed::.); and * special actions to be performed, such as updating the last-edit-date field of a record whenever any other field is modified (*note Customization::.). Detailed information about the database's internal representation is supplied in *Note Database representation::. * Menu: * Creating a new database:: Creating a new database * Manipulating database fields:: Manipulating database fields  File: database.info, Node: Creating a new database, Next: Manipulating database fields, Up: Designing a database Creating a new database ======================= This section tells you how to quickly create a trivial database; please don't be satisfied with this, but follow the references to learn how to access EDB's more sophisticated features. Another good way to learn about EDB is to look at the example databases provided with EDB (*note Installation::.). First, you must decide how many fields the database shall contain, and what their names are. The names are Lisp symbols, and they are primarily used internally--most users will never be aware of how EDB refers to the fields. Let us make a name database with three string fields called "first", "middle", and "last" and one integer field called "age". As mentioned in *Note Invoking EDB::, you need three files to run EDB: a data file, a format file, and an auxiliary file. The auxiliary file is optional; its functionality can be placed in the format file. The data file may have any one of a number of layouts. Perhaps the simplest is tab-delimited text, which is also the default: fields are separated by tab characters and records are separated by newlines. EDB doesn't deal well with empty databases (because it always tries to display a record in the data display buffer), so create a file with at least one record. For instance, we could create a file `names.dat' containing Harry S Truman 88 where a single tab character separates the words. It doesn't matter whether the file contains a final newline. The easiest way to create a database file laid out in EDB's internal representation, which permits faster reading and writing of the data file, is the following. Create a database in some simpler format (such as tab-delimited text), read it in the usual way, set database slot `internal-file-layout-p' to `t' (for instance, via `C-u M-x db-toggle-internal-file-layout RET'), and finally save the database. It will be saved in EDB's internal file layout; for details, *note Internal file layout::.. For more information about different data file layouts, *note Database file layout::.. The format file specifies how a record is displayed on the screen; a backslash followed by a field name indicates that the field's contents should be inserted there. For instance, here is a format for our names database: Family: \last Given: \first Middle: \middle Age: \age For more information about specifying display formats, *note How information is displayed::.. The auxiliary file is used to customize EDB for a particular database; the only information that it absolutely must contain is the names (and possibly types) of the database fields. They are set by function `database-set-fieldnames-to-list' (*note The database structure::.); by providing additional information to this call, you can specify types other than string (which is the default) for your record fields. Any auxiliary file customization may instead appear in the "Local variables" section of the format file (*note Reading from disk::.). So our format file `names.fmt' would look like this: Family: \last Given: \first Middle: \middle Age: \age Local Variables: eval: (database-set-fieldnames-to-list database '(first middle last (age . integer))) End: For more information about customizing EDB for your application, *note Customization::.. Now that we have the two files `names.dat' and `names.fmt', we are ready to invoke the database. Simply call `db-find-file' on `names.dat'; `names.fmt' will be automatically used as the format file, and you can begin editing the database and adding new records.