LoganBerryToolsDoc.tioga
Doug Terry, July 17, 1992 5:08 pm PDT
Swinehart, February 18, 1987 6:14:41 pm PST
Brian Oki, June 19, 1990 1:08 pm PDT
LOGANBERRY TOOLS
CEDAR 10.1 — FOR INTERNAL XEROX USE ONLY
LoganBerry Tools
Doug Terry
© Copyright 1985, 1987, 1990, Xerox Corporation. All rights reserved.
Abstract: LoganBerry is a simple facility for managing databases. LoganBerry tools include commands for invoking operations from a CommandTool, and the LoganBerry Browser, which permits one to browse (and update) a LoganBerry database interactively.
Created by: Doug Terry
Maintained by: Doug Terry <Terry.pa>
Keywords: database, queries, browsing, pattern-matching
See also: LoganBerryDoc.tioga, LoganQueryDoc.tioga
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
Introduction
LoganBerry tools include commands for invoking operations from a CommandTool, and the LoganBerry Browser, which permits one to browse (and update) a LoganBerry database interactively. These are described in more detail in the following sections. For more information on the LoganBerry data management system, see LoganBerryDoc.tioga and LoganQueryDoc.tioga.
To create a new LoganBerry database, use the LBCreate command described below. WARNING: The PCedar version of LoganBerry requires databases to reside in an "ux" directory; LoganBerry will not work in a "vux" directory. All files comprising a LoganBerry database must reside in the same directory.
LoganBerry Browser
Basics
A tool exists for interactively browsing and updating LoganBerry databases. Think of the browser as a convenient way of performing LoganBerry commands. To run the browser, type:
LoganBerryBrowser some-database-schema-name
The convention for naming databases is the same as that used by LoganBerryStub (see LoganBerryDoc.tioga); both local and remote databases may be browsed concurrently. The browser reads the database schema to discover what indices exist for the database. It then builds an input form in which values for the various attribute keys can be entered. These values are treated as patterns against which database entries are compared.
For example, [PCedar2.0]<LoganBerryTools>LoganBerrySampleDB.df is the schema for a sample database storing names and phone numbers. Typing "LoganBerryBrowser [PCedar2.0]<LoganBerryTools>LoganBerrySampleDB.df" (then clicking "AdminOps") produces a viewer that looks something like the following:
[Artwork node; type 'Artwork on' to command tool]
Feel free to run queries on this sample database by typing in patterns for names and/or phone numbers and then clicking on "Browse". If you want to update the database in any way, by clicking "Update", "Delete", "UnDelete", "BuildIndices", or "CompactLogs", please do a bringover first and then run the browser on your local copy of the database. In other words, type: Cd some-local-directory; Bringover -f [PCedar2.0]<LoganBerryTools>LoganBerrySampleDB.df; LoganBerryBrowser LoganBerrySampleDB.df.
The LoganBerry browser also allows one to browse several databases simultaneously; simply type in one or more database names as arguments to the LBBrowser command. The databases should have identical (or at least similar schemas). The user can select which databases to browse for each query. If more than one database is selected, then the results obtained from the multiple databases will be merged together in the output.
User interface
The browser has several areas or subviewers. At the very top is the caption indicating the name of the database being browsed. Right below this is a menu with one or two lines (the display of the second line is controlled by the "AdminOps" button). The function of each menu button is explained in the next section.
Below the menu is the input form. Each line of the input form allows the user to type in a pattern for a given attribute. For instance, the browser tool shown above has an input form with two attributes: "Name" and "Phone".
Preceding each attribute name on the input form is a choice button that allows the user to select what pattern matching is too be applied to the attribute value. Clicking on this choice button cycles through the various options (see the section on pattern-matching options below).
The last line of the input form is a text viewer with the label "other attributes:". For Browse and Delete operations, an optional boolean query can be type in this area; this query is ANDed to the patterns in the input form. See "Boolean Queries" in LoganQueryDoc.tioga for a description of the LoganBerry Query Language. For Update operations, this area can be used to type values for attributes that are not keys of the database.
Feedback concerning the execution of a query is printed to the right of the input form when the "Browse" button is clicked.
If the browser is being used to browse multiple databases, a collection of buttons, one for each database, will appear immediately below the menu and above the input form (these are not present in the browser above). A database is selected and deselected by clicking on the button with its name; a database is selected when the name in the button appears white on black. Any operation invoked via the browser is performed only on the set of selected databases.
Below the input form is another choice button that allows users to select on which attribute the output should be ordered. To speed up queries it is best to order the output on some attribute that has a well-specified pattern. Unless you really care about the order in which database entries are retrieved, leave the choice on "ANY" and the browser will attempt to optimize the execution of the query. The pattern-selection and order-by choice buttons comprise the details subviewer.
The history window optionally resides below the input form and details subviewer (it is not shown in the browser above). Whether or not it is currently displayed is governed by the "History" menu button. This area contains a list of the operations that have been executed in the past; these operations are given in a format that could be typed into a CommandTool as arguments to the LBQuery command to get identical results (except the database name is omitted). Clicking on one of these "history commands" fills in the input form with the values that previously existed and also sets the previous details. Thus, a query can be re-executed by selecting a line in the history window and clicking "Browse" again. The user is also free to change any of the values once they are refreshed.
At the bottom of the browser tool is the output area where the results of queries are displayed. This area is scrollable.
Menu buttons
The LoganBerry Browser Tool displays the following menu buttons:
STOP!: terminates a currently executing database query.
Browse: initiates a database query to retrieve all entries matching the input form. That is all database entries whose attribute values match the corresponding pattern in the input form (according to the selected pattern matching style) are displayed in the output area of the browser. Left or middle clicking clears the output area before executing the query; right clicking this button appends the query results to the output area. (The semantics are the same as LBQuery.)
Update: writes a database entry consisting of all the non-null values in the input form. (Same as LBWrite.)
Replace: similar to Update. Writes a database entry consisting of all the non-null values in the input form, replacing any previous entry.
Delete: initiates a database query to retrieve all entries matching the input form; then deletes all of these entries. (Same as LBDelete.)
UnDelete: rewrites all of the entries deleted by the last "Delete" operation.
History: toggles whether or not the history of past queries is displayed.
Details: toggles whether or not the details that govern how a query is performed are displayed.
AdminOps: displays (or hides) a second menu line that contains buttons for performing administrative operations on the database.
The second menu line offers the following buttons (intended mostly for advanced users):
Open: opens the database. (This is automatically done when the browser is created and on every browse operation; thus a user should never have to use this button).
Close: closes the database and its associated files. (Same as LBClose.)
BuildIndices: rebuilds the database indices. (Same as LBBuildIndices.)
CompactLogs: compacts the database logs. (Same as LBCompactLogs.)
Pattern-matching options
Users can select the pattern matching that should be applied to various fields of a database entry using the choice buttons in the browser's input form. For each field in the input form, the user types in the desired pattern and type of pattern matching; these patterns are in turn compared against values obtained from the database. The types of pattern matching provided are those described above under "Pattern matching".
In addition, the user may select "DWIM". In this case, the browser attempts to deduce an appropriate filter type from the given pattern. The logic is as follows:
pattern-matching ←
IF pattern contains a dash THEN
IF start and end are integers THEN "numrange"
ELSE IF start and end are dates THEN "daterange"
ELSE "subrange"
ELSE
IF pattern contains a * THEN "wildcard"
ELSE IF pattern is a date then "date"
ELSE "prefix"
Warning: The "numrange", "daterange", and "date" pattern-matching filters are problematic since they assert that the attributes in the database are of a certain type other than simply ropes. The LoganBerry data management system treats all attribute values as ropes and does not enforce any constraints on the these values. If the browser encounters an attribute value that can not be converted to the type desired by the filter, then the entry is deemed to not match. Also, the "DWIM" option has the obvious problem that its semantics are not easy to predict or determine. For these reasons. "numrange", "daterange", "date", and "DWIM" are provided on an experimental basis only and should be used with caution.
A simple example
As an example, suppose one wants to find all of the people in the LoganBerrySampleDB database whose phone number starts with "494". To fill in the input form, the user first clicks on "Name:", which places the input cursor next to this field so the user can type in a pattern for the names of the people to match; the user types "*". Next, the user next clicks on "Phone:" and types "494". Together, "Name: *" and "Phone: 494" specifies the desired query. At the point the browser looks like:
[Artwork node; type 'Artwork on' to command tool]
The user leaves the pattern matching as "DWIM" and the "Order by" field set to "ANY" so that the system will figure out the best way to process this query. Now if the user clicks "History" to display the history viewer followed by "Browse" to execute the query, the matching entries are retrieved from the database and the browser looks like the following:
[Artwork node; type 'Artwork on' to command tool]
Two matching entries were found and displayed; the specification of the query was added to the history viewer. Notice that the browser's feedback indicates that "wildcard" pattern-matching was selected for names and "494" was treated as a phone number prefix. The query feedback also indicates that the "Phone" index was selected to execute the query with an expected cost of 0.00 (i.e. negligible cost).
Customized browsers
LoganBerryBrowser.mesa provides a programmer's interface that allows one to create a customized LoganBerry Browser; see the interface for details.
LoganBerry Commands
Overview
Several commands are available for invoking operations on a LoganBerry database from a CommandTool. These are described below. All of the commands, except for LoganBerryBrowser, can run in a "non-viewers" Cedar world, e.g. CedarTools.
All of the LoganBerry CommandTool commands have a similar syntax, "<cmdname> <dbname> <attributes>", a command name followed by a database name followed by a boolean query or zero or more attribute-pattern specifications. The database name may be for a remote database, see "Convention for naming remote databases", or may be the special name "#", which is a shorthand notation for the last database name given. An extension of ".df" is assumed for database names without explicit extensions.
An attribute-pattern specification is of the form: "<attribute-type>(<pattern>): <attribute-value>". The attribute value may be either a token or a rope literal. The currently supported types of patterns include "exact", "prefix", "wildcard", "re", and "soundex" (see above for a description of these patterns). The pattern, along with its surrounding parenthesis, is optional. A missing pattern defaults to "DWIM".
name LBBrowser or LoganBerryBrowser:
syntax
LBBrowser {switches} dbname dbname ...
description
Creates a tool to browse the given LoganBerry database(s).
The only switch currently recognized is:
-ti where i is an integer in [1..LAST[INT]]: creates a LoganBerry browser tool with a different display procedure. When displaying a query with many entries, only the first i-1 entries will be displayed in the TypeScript associated with the tool; any additional entries are collected and diverted to a viewer called LB Query. The entries are not shown in the viewer until they are all collected, or the query is aborted with the STOP! button. (This is much faster for queries that retrieve large numbers of entries.)
examples
% LBBrowser LoganBerrySampleDB.df
% LBBrowser -t4 LoganBerrySampleDB.df OtherLB.df
name LBBuildIndices:
syntax
LBBuildIndices dbname
description
Rebuild the indices for a LoganBerry database.
examples
% LBBuildIndices #
stop/undo
You can not stop this operation once it starts. It could take awhile for a large database.
name LBClose:
syntax
LBClose dbname
description
Close a LoganBerry database. (You may want to do this to release the write locks on the log files, for instance.)
examples
% LBClose #
name LBCompactLogs:
syntax
LBCompactLogs dbname
description
Compact a LoganBerry database.
examples
% LBCompactLogs #
stop/undo
You can not stop this operation once it starts. It could take awhile for a large database.
name LBCreate:
syntax
LBCreate dbname primaryKey secondaryKey ...
description
Creates a new LoganBerry database with the given name, primary key, and zero or more secondary keys. In particular, two files are generated: a schema file and an empty log file. Use LBBuildIndices to create the index files. These files are all created in the current directory, which must be an "ux" directory in PCedar. Note: If you want to use the schema file as a DF file, then you will likely need to edit it so that it smodels files to the desired place.
examples
% mkdir NewDirectory
% cd NewDirectory
% LBCreate SampleDB.df Name Phone Address
Created database schema file SampleDB.df and log file SampleDB.lblog
% LBBuild SampleDB.df
name LBDelete:
syntax
LBDelete dbname query
description
Deletes all entries in the LoganBerry database that match the attribute patterns.
examples
% LBDelete # Integer: -10 Rope: "minus ten"
Deleted Integer: -10
warnings
This operation could delete many database entries so be careful!
stop/undo
STOP! halts the delete operation; there is no undo facility.
name LBDescribe:
syntax
LBDescribe dbname
description
Get schema information about a LoganBerry database. Returns a list of the keys, indices, and logs.
examples
% LBDescribe #
Database: []<>Users>Terry.pa>LoganBerry>testdb.schema!1
keys: Integer Rope
index files: []<>Users>Terry.pa>LoganBerry>Integer.index
[]<>Users>Terry.pa>LoganBerry>Rope.index
log files: []<>Users>Terry.pa>LoganBerry>TestDB.log
name LBFlushCache:
syntax
LBFlushCache {dbname | ALL}
description
Causes LoganBerry to flush its cache of open database handles for either the named database or all databases. This is useful if the schema file has been edited, for instance, and you want to force LoganBerry to read the new schema.
examples
% LBFlushCache SampleLB.df
% LBFlushCache ALL
name LBQuery:
syntax
LBQuery dbname query
description
Retrieves entries in the LoganBerry database that match the attribute patterns.
examples
retrieve all database entries for integers that start with "1" and include the word "ten" when written in English:
% LBQuery testdb.schema Integer(prefix): 1 Rope(wildcard): *ten*
Integer: 10
Rope: ten

Integer: 110
Rope: one hundred ten
stop/undo
STOP! halts the query.
name LBRead:
syntax
LBRead dbname attributes
description
Synonym for LBQuery.
name LBWrite:
syntax
LBWrite dbname attributes
description
Writes an entry into the LoganBerry database. Any patterns given with the list of attributes are ignored.
examples
% LBWrite # Integer: -10 Rope: "minus ten"