This is a description of the VMS qi server and how it is different from the
CSO implementation.

First, there is no code in common with CSO.  Second, the file structure is
completely different.  Other than that, they're pretty much identical.

Lets start with the configuration (.cnf) file.  It is similar to the
prod.cnf CSO file, except the field numbers are completely different, the
max size and merge option fields (fields 3 and 5) are ignored but kept for
CSO compatability.  It looks like:

2:name:120:Full name.:O:Indexed:Lookup:Public:Default:

Version 1 limits the attributes to Indexed, Lookup, Public and Default.

There are two database files: the index (.index) and the data (.data)
files. The index file is a fixed-length indexed file that contains the
contents of data fields with the Indexed attribute.  It has 3 fields:

Keyword:    25 character keyword (name, etc.) to look up
Field:      2 digit field number that the keyword came from
ID:         8 digit foreign key to data file

A single key is made up of the Keyword+Field fields.

The data file is a variable-length indexed file that contains the various
data elements to retrieve.  It has 4 fields:

ID:         8 digit identifier
Field:      2 digit field number
Sequence:   2 digit sequence number (00-99, probably can overflow to ZZ)
Attributes: 1 digit encoded attribute set
Data:       1-120 characters of data

A single key is made up of the ID+Field+Sequence fields.

The maximum size of a field is 120 x 100 characters, usually organized as
up to 100 lines of up to 120 characters each, although clients may add a
layer of encoding that allows concatenation of records.

Getting started.

The QI_BUILD program expects to see a file in the same format as the data
file described above.  There are a couple of reasons for this:

* there are going to be lots of raw data file formats and I can only pick one
* programs (such as build) can act on the .dat file or the .data file
* a dump program is not necessary

The QI_MAKE program will convert most fixed-length field sequential data
files to the QI_BUILD data file format.  The MAKE program reads a data file
(input.QI_MAKE) that describes the input file format and the translations
of fields to field number/data.

The format of MAKE.DAT is:
start character, length, field number, capitalize, blank when zero, pre, post,

start character is the start column of the field
length is the length of the field
field number is the .CNF field number associated with this field
capitalize is 1 or 0; if 1, a capitalization algorithm is applied to the field
blank when zero will omit the field if it contains only zeros
pre places a character string at the start of the field
post places a character string at the end of the field

Fields that are blank are not written.


Procedure to create a database:

The command to run MAKE read the file INPUT and write the file OUTPUT is
MAKE := $device:[path]QI_MAKE.EXE
MAKE INPUT OUTPUT [sequence]

Sequence is the base of the internal ID numbers given to each record.  It
can be up to 8 digits and if omitted defaults to 0.  [For the California
Community Colleges, I strongly suggest you use your college or district
number as the first three digits of the id field followed by 00000.]

As it runs, QI_MAKE prints the ID number every hundred input records.


Given a data file that has a record format something like:
811000010200Tanner Bruce


You can then run the build program that will build the .INDEX file with all
the indexable fields.  If you wish, build will also create the .DATA file
(although running convert may be faster).

The syntax for build is
BUILD := $device:[path]QI_BUILD.EXE
BUILD input [/DATA] [/OUTPUT=output]

QI_BUILD reads the field definitions (input.CNF), input data (input.DAT)
and creates an index file (output.INDEX) and optionally a data file
(output.DATA).


The nameserver uses four logical names that must be defined /system/exec.
These logical names are not used by QI_MAKE or QI_BUILD.

CSO_CONFIG points to the .CNF file
CSO_INDEX points to the .INDEX file
CSO_DATA points to the .DATA file
CSO_LOG points to the usage log file
CSO_SITEINFO points to a file that gives the siteinfo output.

The nameserver is designed to run as a "forked" or "inetd" style process
under MULTINET_SERVER.  To do this, you run the MultiNet server
configuration program:

$ multinet config/server
SERVER-CONFIG>add cso
[Adding new configuration entry for service "CSO"]
Protocol: [TCP] 
TCP Port number: 105
Program to run: device:[path]qi.exe
[Added service CSO to configuration]
SERVER-CONFIG>exit

You may also perform a RESTART command to restart the MULTINET_SERVER with
the new CSO definition.

At this point you should be able to access the namserver via telnet, ph, or
gopher (with the appropriate link entry).  The server currently supports
the 'anonymous' (read-only) mode commands.  The query command semantics are
a little different from those of the CCSO nameserver.

There are two 'modes' that the query command will operate under.  In 'exact'
mode, an Indexed field is searched exactly and whatever is found is returned.

If 'exact' mode is off, an Indexed field is searched first exactly; if nothing
is found, it is searched for any keys that start with the query value.  A name
field is then searched on soundex value if the first two searches don't find
anything.

Name field searches also automatically perform a nickname search.

There are two global modes thet qi runs under: exact and debug.  These modes
are defined by the SET command.  SET EXACT=ON sets the exact mode described
above.  SET DEBUG=ON tells qi to emit internal debugging information.
SET EXACT=OFF and SET DEBUG=OFF reset these modes.

.