.TH index "" "" "/rdb Command"
.PC "Set up table for search"
\fBindex [\-m[bhirs]] [\-x] [-hsl [2> \fIlocation\fB]] \fItableorlist \fB[\fIkeycol ...\fB] [ < \fIkeytable\fB ]\fR
.PP
.II "table^index"
The command
.B index
sets up a table for the program
.BR search .
The indexing it performs increases the speed with which
.B search
can find a row in a table or list file.
This is very important for large files.
.PP
Exactly what
.B index
does depends upon the method of indexing you choose.
For some methods, it builds another table, called a
.IR "secondary index file" ,
that the specified method requires.
It is possible to index
one file by all five methods.
Some methods can index all of a table's columns.
.PP
Please note that these fast-access methods are static.
If the table or list
is changed \(em by a text editor, for example \(em it may have to
be reindexed.
Applications should manipulate the table
or list files and their secondary index to update them together.
Forms packages should dynamically maintain these files.
.PP
There is a trick to allow you to index any or all of the columns in a file.
.II ln
Simply use the COHERENT command
.B ln
to link the file to as many different names as you have columns to index.
Then index the table through each of its link aliases.
For details, see the COHERENT Lexicon's entry for
.BR ln .
.SH Options
The following options control the method of indexing that
.B index
produces:
.IP \fB\-m\fR
Index using the default method, which is sequential.
See
.BR \-ms ,
below.
.IP \fB\-mb\fR
.II "index^binary"
Binary indexing.
.B index
simply sorts the file on the specified key column.
No secondary file is created.
Because a file can only be sorted on one column,
only one column can be indexed using this method.
The command
.B sorttable
gives the same result as this option.
.IP \fB\-mh\fR
.II "index^hash table"
Hash indexing.
.B index
builds a secondary-index file, named
\fBtableorlist\fB.h\fR,
hashes all of the key-column's values,
and writes them and their offsets to the secondary-index file.
Please note that because the COHERENT system places a limit of 14
characters on a file name, the name of
.I tableorlist
must not exceed 12 characters, or
.B index
will not be able to name correctly the secondary-index file.
.IP \fB\-mi\fR
.II "index^inverted"
Inverted or indexed indexing.
.B index
builds a secondary-index file of keys and offsets, then sorts on the keys.
The secondary file is named
\fItableorlist\fB.i\fR.
The trick to index more than one column, previously discussed,
alsos work for the inverted method.
.sp \n(pDu
If you plan on using the incomplete-match feature of
search (which works only with the inverted method), you
must specify the \fB-x\fR flag, so the secondary index is sorted properly.
.IP \fB\-mr\fR
.II "index^record number"
Record-number indexing.
.B index
builds a secondary file named
\fItableorlist\fB.r\fR,
which is one fixed-length column of row offsets.
.IP \fB\-ms\fR
.II "index^sequential"
.II "index^linear"
Sequential or linear indexing.
.B index
does nothing in this case, because
.B search
simply looks through the whole file.
.PP
The following options control details of
.BR index 's
output:
.IP \fB\-h\fR
No head line on the output table.
.IP \fB\-l\fR
Write to the standard error the starting and stopping location of each row,
and the offset entry in the secondary-index file.
.II replace
.II lock
.II unlock
These numbers are used by the commands
.BR replace ,
.BR lock ,
and
.BR unlock .
.II seek
The command
.B seek
uses this option to find the locations of rows.
The locations are sent to standard-error device, which under the
Bourne and Korn shells is file descriptor 2;
thus, you can redirect them into a file by using the shell operator \fB2>\fR.
You can store these data until they are needed by your shell programs.
.sp \n(pDu
This option produces four integers.
If there is no secondary-index file, the start location is zero.
.IP \fB\-s\fR
Only one row is found.
This speeds up some of the methods
because they do not have to continue searching
after they find the first match.
The sequential method will, on average, run twice as fast;
whereas the hash, binary, and inverted methods will run slightly faster.
The record-access method will not change, as it only finds one match anyway.
.SH "Methods and Suffixes"
The following gives suffixes that
.B index
appends to names of tables, in order to name its secondary-index files.
.DS
.ta 1.25iC 2.5iC
\fIMethod	Suffix	Example\fR
\fB\-b\fR	None	...
\fB\-h\fR	.h	inventory.h
\fB\-i\fR	.i	inventory.i
\fB\-r\fR	.r	inventory.r
\fB\-s\fR	None	...
.DE
.SH Example
Let's look at the first ten lines of an accounts chart, named
.BR chart :
.DM
Account Name
------- ----------------------
100     Assets
101     Cash
111     Accounts Receivable
111.1   Allowance for Bad Debt
115     Notes Receivable
120     Deposits
130     Parts Inventory
150     Equipment
.DE
.PP
Access to the data in
.B chart
can be sped up by indexing it and using the command
.B search
to find the row you want.
To index
.B chart
using the binary (sorted) search method, type:
.DM
	index -mb chart Account
.DE
.PP
.B index
quietly returns when it finishes.
You are now ready to use
.B search
to find an
.B Account
number in the
.B chart .
.SH "See Also"
.B
append,
delete,
lock,
replace,
search,
unlock,
update
.R
.br
COHERENT Lexicon:
.B
ln
.R