2 Getting Started

 

This short chapter is for readers who do not want to know any more about the software than is absolutely necessary; you simply want to do your work. We understand your situation, so we are spending some time making sure this chapter will help you with your quest. We show you a nice small example, take you through creating the database, writing the schema, then adding/editing tuples. You will want to learn more about the generic user interface, Qddb file structures, and stabilization, but that can wait until the next chapter.

The problem:

You want to keep track of your extensive home library. Sometimes people borrow your books, so you'd like to be able to find out who has borrowed books in the past and who currently has your books. You need to have a friendly user interface that provides operations such as adding, updating, querying, and deleting data. In particular, you don't want to write any code and would like to have the application up and running in five minutes (not counting the time it takes to read this chapter!).

The first step is to choose a directory to keep all your Qddb databases. For concreteness, let's say that you want to store all your databases in ~/Databases.

Your application only needs a single relation. The qnewdb command will create the relation files for you in a new subdirectory of ~/Databases. Next, you edit the schema file. The sequence of commands looks like this:

    1$ cd ~
    2$ mkdir Databases
    3$ QDDBDIRS=~/Databases; export QDDBDIRS
    4$ cd ~/Databases
    5$ qnewdb Library
    6$ vi Library/Schema

Lines 1 and 2 set up your databases directory. Line 3 establishes a search path so Qddb programs can find any relations in that directory. Lines 4 and 5 create a new relation in a subdirectory called Library. Line 6 invokes a text editor (you could use any editor you like) to initialize the schema (more on that soon).

The following contents belong in the Schema file:

    # Qddb relation for personal library
    Book (
        ISBN Title Authors * Subject
        Keywords verbosename "Key Words"
        Publisher *
        Series verbosename "Book Series"
        Year Edition Printing Abstract
    )
    Borrowers (
        Name
        Address (
            Street City State
            Zip verbosename "Zip Code"
        )*
        Phones (
            Desc verbosename "Description"
            Number (
                Area type integer
                Prefix type integer
                Suffix type integer
            )
        )*
        Borrowed verbosename "Date Borrowed" type date
        Returned verbosename "Date Returned" type date
    )*

The schema indicates that each tuple is a combination of information about a particular book and a history of who has borrowed it. The Book attribute is structured; its subattributes identify information such as its title. Some of this information, such as Author, is expandable (marked with an asterisk `*'), because a book may have multiple authors. The Borrowers attribute may itself have multiple instances (over time, a book may be borrowed more than once). It has subattributes for the borrower's name, address (there could be several), and other identifying information. A particular tuple may have empty attributes (that is, attributes whose values are empty). Not every book has an edition number, and not every borrower has a phone number.

If you have designed databases before, you will find several aspects of this schema surprising. First, although some attributes are constrained to hold date or integer data, many attributes have no associated type. They will hold arbitrary character strings.

Second, both book and borrower information are stored in the same relation. A classical relational database would most likely use two relations, one for books and another for borrowers, with unique borrower identifiers linking them. Qddb databases often avoid multiple relations and the concomitant need to invent unique identifiers. However, if the same person borrows several books, the schema shown here will cause borrower information to be repeated for each book.

Third, attributes may optionally have verbose names. These longer and more descriptive names are used by the graphical user interface to display a user-oriented, instead of an implementation-oriented, attribute name. The internal workings of the program use the more cryptic single-word names.

All Qddb programs use the QDDBDIRS environment variable to establish a search path for your relations. You can name a relation by an absolute path name to its directory, or you can use a relative path from your current directory, but you may also use a relative path from any directory in QDDBDIRS, which is a colon-separated list of absolute path names, such as this:

    $ QDDBDIRS=~/Databases:~/NewDatabases:/usr/databases

Now your ~/Databases/Library relation can be referred to just as Library.

You can now start using user-interface programs. Try these:

    1$ EDITOR=`which vi`; export EDITOR
    2$ qadd Library
    3$ qedit e Library <a list of words to search on>
    4$ nxqddb Library

Line 1 establishes that vi is your preferred editor. If you prefer emacs or something else, you can modify line 1 appropriately. Line 2 shows how to invoke qadd to let you put a tuple in the Library relation. Line 3 shows how to edit the tuples that match all the words that you list. If you prefer a graphical user interface, line 4 shows how to invoke nxqddb, which allows you to add, modify, and search for tuples. You can most likely guess how it works by playing with it. Both the text-based and the graphical user interfaces are described fully in Chapter 3.

You are now ready to begin. Try making a simple database and play with the programs we have described. Soon you will be ready for a more detailed look at these programs and at Qddb in general.