@code{(require 'databases)} @ftindex databases @noindent This enhancement wraps a utility layer on @code{relational-database} which provides: @itemize @bullet @item Identification of open databases by filename. @item Automatic sharing of open (immutable) databases. @item Automatic loading of base-table package when creating a database. @item Detection and automatic loading of the appropriate base-table package when opening a database. @item Table and data definition from Scheme lists. @end itemize @subsubheading Database Sharing @noindent @dfn{Auto-sharing} refers to a call to the procedure @cindex Auto-sharing @code{open-database} returning an already open database (procedure), rather than opening the database file a second time. @quotation @emph{Note:} Databases returned by @code{open-database} do not include wrappers applied by packages like @ref{Embedded Commands}. But wrapped databases do work as arguments to these functions. @end quotation @noindent When a database is created, it is mutable by the creator and not auto-sharable. A database opened mutably is also not auto-sharable. But any number of readers can (open) share a non-mutable database file. @noindent This next set of procedures mirror the whole-database methods in @ref{Database Operations}. Except for @code{create-database}, each procedure will accept either a filename or database procedure for its first argument. @defun create-database filename base-table-type @var{filename} should be a string naming a file; or @code{#f}. @var{base-table-type} must be a symbol naming a feature which can be passed to @code{require}. @code{create-database} returns a new, open relational database (with base-table type @var{base-table-type}) associated with @var{filename}, or a new ephemeral database if @var{filename} is @code{#f}. @code{create-database} is the only run-time use of require in SLIB which crosses module boundaries. When @var{base-table-type} is @code{require}d by @code{create-database}; it adds an association of @var{base-table-type} with its @dfn{relational-system} procedure @cindex relational-system to @var{mdbm:*databases*}. alist-table is the default base-table type: @example (require 'databases) (define my-rdb (create-database "my.db" 'alist-table)) @end example @end defun @noindent Only @code{alist-table} and base-table modules which have been @code{require}d will dispatch correctly from the @code{open-database} procedures. Therefore, either pass two arguments to @code{open-database}, or require the base-table of your database file uses before calling @code{open-database} with one argument. @deffn {Procedure} open-database! rdb base-table-type Returns @emph{mutable} open relational database or #f. @end deffn @defun open-database rdb base-table-type Returns an open relational database associated with @var{rdb}. The database will be opened with base-table type @var{base-table-type}). @defunx open-database rdb Returns an open relational database associated with @var{rdb}. @code{open-database} will attempt to deduce the correct base-table-type. @end defun @defun write-database rdb filename Writes the mutable relational-database @var{rdb} to @var{filename}. @end defun @defun sync-database rdb Writes the mutable relational-database @var{rdb} to the filename it was opened with. @end defun @defun solidify-database rdb Syncs @var{rdb} and makes it immutable. @end defun @defun close-database rdb @var{rdb} will only be closed when the count of @code{open-database} - @code{close-database} calls for @var{rdb} (and its filename) is 0. @code{close-database} returns #t if successful; and #f otherwise. @end defun @defun mdbm:report Prints a table of open database files. The columns are the base-table type, number of opens, @samp{!} for mutable, the filename, and the lock certificate (if locked). @end defun @example (mdbm:report) @print{} alist-table 003 /usr/local/lib/slib/clrnamdb.scm alist-table 001 ! sdram.db jaffer@@aubrey.jaffer.3166:1038628199 @end example @subsubheading Opening Tables @defun open-table rdb table-name @var{rdb} must be a relational database and @var{table-name} a symbol. @code{open-table} returns a "methods" procedure for an existing relational table in @var{rdb} if it exists and can be opened for reading, otherwise returns @code{#f}. @end defun @deffn {Procedure} open-table! rdb table-name @var{rdb} must be a relational database and @var{table-name} a symbol. @code{open-table!} returns a "methods" procedure for an existing relational table in @var{rdb} if it exists and can be opened in mutable mode, otherwise returns @code{#f}. @end deffn @subsubheading Defining Tables @defun define-domains rdb row5 @dots{} Adds the domain rows @var{row5} @dots{} to the @samp{*domains-data*} table in @var{rdb}. The format of the row is given in @ref{Catalog Representation}. @example (define-domains rdb '(permittivity #f complex? c64 #f)) @end example @end defun @defun add-domain rdb row5 Use @code{define-domains} instead. @end defun @defun define-tables rdb spec-0 @dots{} Adds tables as specified in @var{spec-0} @dots{} to the open relational-database @var{rdb}. Each @var{spec} has the form: @lisp (@r{} @r{} @r{} @r{}) @end lisp or @lisp (@r{} @r{} @r{} @r{}) @end lisp where @r{} is the table name, @r{} is the symbol name of a descriptor table, @r{} and @r{} describe the primary keys and other fields respectively, and @r{} is a list of data rows to be added to the table. @r{} and @r{} are lists of field descriptors of the form: @lisp (@r{} @r{}) @end lisp or @lisp (@r{} @r{} @r{}) @end lisp where @r{} is the column name, @r{} is the domain of the column, and @r{} is an expression whose value is a procedure of one argument (which returns @code{#f} to signal an error). If @r{} is not a defined domain name and it matches the name of this table or an already defined (in one of @var{spec-0} @dots{}) single key field table, a foreign-key domain will be created for it. @end defun @subsubheading Listing Tables @defun list-table-definition rdb table-name If symbol @var{table-name} exists in the open relational-database @var{rdb}, then returns a list of the table-name, its primary key names and domains, its other key names and domains, and the table's records (as lists). Otherwise, returns #f. The list returned by @code{list-table-definition}, when passed as an argument to @code{define-tables}, will recreate the table. @end defun