.\" XXX standard disclaimer belongs here....
.\" $Header: /private/postgres/ref/files/RCS/bki,v 1.8 1992/07/14 05:54:17 ptong Exp $
.SP BKI FILES 6/14/90
.XA 1 "Backend Interface \*- BKI"
.uh NAME
.lp
\&.../src/support/{local,dbdb}.bki \*- template scripts
.uh DESCRIPTION
.lp
Backend Interface (BKI) files are scripts that describe
the contents of the initial \*(PP database.
This database is constructed during system installation,
by the
.b initdb
command.
.b Initdb
executes the \*(PP backend with a special set of flags,
that cause it to consume the BKI scripts and bootstrap
a database.
.lp
These files are automatically generated from system header
files during installation.
They are not intended for use by humans,
and you do not need to understand their contents in order
to use \*(PP.
These files are copied to .../files/local1.bki
and .../files/global1.bki during system installation.
.lp
All new user databases will be created by copying the template
database that \*(PP constructs from the BKI files.
Thus,
a simple way to customize the template database is to
let the \*(PP initialization script create it for you,
and then to run the terminal monitor to make the changes
you want.
.lp
The \*(PP backend
interprets BKI files as described below.
This description will be easier to understand
if the example in  .../files/global1.bki is at hand.
.lp
Commands are composed of a command
name followed by space separated arguments.
Arguments to a command which begin with
a
.q $
are treated specially.
If
.q $$
are the first two characters, then
the first
.q $
is ignored and the argument
is then processed normally.
If the
.q $
is followed by space,
then it is treated as a
.A NULL
value.
Otherwise, the characters following the
.q $
are interpreted as the name of a macro
causing the argument to be replaced with the macro's value.
It is an error for this macro to be undefined.
.lp
Macros are defined using
"define macro macro_name = macro_value"
and are undefined using 
"undefine macro macro_name"
and redefined using the same syntax as define.
.sp
Lists of general commands and macro commands
follow.
.uh "GENERAL COMMANDS"
.lp
.ft C
open classname
.ft
.sp
Open the class called
.i classname
for further manipulation.
.sp
.ft C
close [classname]
.ft
.sp
Close the open class called
.i classname.
It is an error if 
.i classname
is not already opened.   If no
.i classname
is given, then the 
currently open class is closed.
.sp
.ft C
print
.ft
.sp
Print the currently open class.
.sp
.ft C
insert [ oid= oid_value ] '(' value1 value2 ...')'
.ft
.sp
Insert a new instance to the open
class using
.ul
value1,
.ul
value2,
etc. for its attribute values and oid_value for it's OID.
If
.ul
oid
is not \*(lq0\*(rq, then this value
will be used as the instance's
object identifier.
Otherwise, it is an error.
To let the system generate a unique object identifier (as opposed to the
"well-known" object identifiers which we specify) use 
insert '(' value1, value2, ... valuen ')' .

.sp
.ft C
create classname '(' name1 = type1,
                     name2 = type2, ...name n = type n ')'
.ft
.sp
Create a class named
.ul
classname
with the attributes given in parentheses.
.sp
.ft C
open '('name1 = type1, name2 = type2,...name n = type n ')'
    as classname
.ft
.sp
Open a class named
.ul
classname
for writing 
but do not record its existence
in the system catalogs.  (This is primarily to aid in bootstrapping.)
.sp
.ft C
destroy classname
.ft
.sp
Destroy the class named
.ul
classname.
.sp
.ft C
define index <index-name> on <class-name> using <amname>
    ( <opclass> <attr> | function({attr}) )
.ft
.sp
Create an index named
.ul
index_name
on the class named
.ul
classname
using the
.ul
amname
access method.
The fields to index are called
.ul
name1,
.ul
name2,
etc. and the operator
collections to use are
.ul
collection_1,
.ul
collection_2,
etc., respectively.
.uh "MACRO COMMANDS"
.lp
.ft C
define function macro_name
       as rettype function_name ( args )
.ft
.sp
Define a function prototype for a function named
.ul
macro_name
which has its value of type
.ul
rettype
computed from the
execution
.ul
function_name
with the
.ul
arguments
.ul
args 
declared in a C-like manner
etc.
.sp
.ft C
define macro macro_name from file filename
.ft
.sp
Define a macro named
.ul
macname
which has its value 
read from the file called
.ul
filename.
.sp

.\" .uh "DEBUGGING COMMANDS"
.\" .sp
.\" .in .5i
.\" r
.\" .br
.\" Randomly print the open class.
.\" .sp
.\" m	-1
.\" .br
.\" Toggle display of time information.
.\" .sp
.\" m	0
.\" .br
.\" Set retrievals to now.
.\" .sp
.\" m	1 Jan 1 01:00:00 1988
.\" .br
.\" Set retrievals to snapshots of the specfied time.
.\" .sp
.\" m	2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
.\" .br
.\" Set retrievals to ranges of the specified times.
.\" Either time may be replaced with space
.\" if an unbounded time range is desired.
.\" .sp
.\" \&.A	classname natts name1 type1 name2 type2 ...
.\" .br
.\" Add attributes named
.\" .ul
.\" name1,
.\" .ul
.\" name2,
.\" etc. of
.\" types
.\" .ul
.\" type1,
.\" .ul
.\" type2,
.\" etc. to the
.\" .ul
.\" class
.\" classname.
.\" .sp
.\" \&.RR	oldclassname newclassname
.\" .br
.\" Rename the
.\" .ul
.\" oldclassname
.\" class to
.\" .ul
.\" newclassname.
.\" .sp
.\" \&.RA	classname oldattname newattname
.\" .br
.\" Rename the
.\" .ul
.\" oldattname
.\" attribute in the class named
.\" .ul
.\" classname
.\" to
.\" .ul
.\" newattname.
.uh EXAMPLE
.lp
The following set of commands will create the
OPCLASS class containing
the
.i int_ops
collection as object
.i 421,
print out the class, and then close it.
.sp
.nf
.ft C
create pg_opclass (opcname=char16)
open pg_opclass
insert oid=421 (int_ops)
print
close pg_opclass
.ft

.fi
.uh "SEE ALSO"
.lp
initdb(unix),
createdb(unix),
createdb(commands),
template(files).