L This is a description of the VMS qi server and how it is different from the J CSO implementation.  See the files in the CCSO documentation directory forG the  base documentation.  A new command (select) and a modified command 3 (change) are described at the end of this document.   L First, there is no code in common with CCSO.  Second, the file structure is G completely different.  Other than that, they're pretty much identical.    D Lets start with the configuration (.cnf) file.  It is similar to theJ prod.cnf CCSO file, except the field numbers are completely different, theJ max size and merge option fields (fields 3 and 5) are ignored but kept for# CCSO compatability.  It looks like:   6 2:name:120:Full name.:O:Indexed:Lookup:Public:Default:  G Version 1 limits the attributes to Indexed, Lookup, Public and Default. A Version 2 adds Encrypted, Change, Unique and Localpub attributes.   E There are two database files: the index (.index) and the data (.data) G files.  The index file is a fixed-length indexed file that contains the E contents of data fields with the Indexed attribute.  It has 3 fields:   8 Keyword:    30 character keyword (name, etc.) to look up; Field:      2 digit field number that the keyword came from , ID:         9 digit foreign key to data file  : The primary key is made up of the Keyword+Field+ID fields.0 The secondary key is made up of ID+Field fields.  I The data file is a variable-length indexed file that contains the various , data elements to retrieve.  It has 4 fields:   ID:         9 digit identifier  Field:      2 digit field numberH Sequence:   2 digit sequence number (00-99, probably can overflow to ZZ)) Attributes: 1 digit encoded attribute set $ Data:       1-120 characters of data  8 A single key is made up of the ID+Field+Sequence fields.  I The maximum size of a field is 120 x 100 characters, usually organized as I up  to 100 lines of up to 120 characters each, although clients may add a 8 layer of encoding that allows concatenation of records.      Getting started.  I 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:  N * There are going to be lots of raw data file formats and I can only pick one.J * Programs (such as qi_build) can act on the ASCII file or the .data file." * A dump program is not necessary.  J The QI_MAKE program will convert most fixed-length field, sequential data C files to the QI_BUILD data file format.  QI_MAKE reads a data file  I (input.QI_MAKE) that describes the input file (input.DAT) format and the  - translations of fields to field number/data.    . QI_MAKE is described in detail in QI_MAKE.DOC.     Procedure to create a database:   I 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]  E As it runs, QI_MAKE prints the ID number every hundred input records.     D QI_MAKE creates a data file that has a record format something like: 81100132701000Tanner Bruce    K You can then run the build program that will build the .INDEX file with all I the indexable fields.  If you wish, build will also create the .DATA file ) (although running convert may be faster).    See QI_BUILD.DOC for details.   H QI_BUILD reads the field definitions (input.CNF), input data (input.DAT)C and creates an index file (output.INDEX) and optionally a data file  (output.DATA).    D The nameserver uses logical names that must be defined /SYSTEM/EXEC.8 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. J CSO_DOMAIN contains your domain name; the minimum amount of a host addressO            that must match to be considered a local host for 'localpub' fields.  CSO_APISHR points to QI_API.EXE 6 CSO_HELPLIB points to the CSO help file directory rootJ CSO_MAILDOMAIN contains your mail domain displayed by the siteinfo command  D The nameserver is designed to run as a "inetd" style process under aK server.  To do this for MultiNet, you run the MultiNet server configuration 	 program:     $ multinet config/server SERVER-CONFIG>add cso 2 [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  J You must also perform a RESTART command (or run MULTINET:START_SERVER.COM); to restart the MULTINET_SERVER with the new CSO definition.   H At this point you should be able to access the namserver via telnet, ph,H gopher (with the appropriate link entry) or some web browsers. The queryK command semantics are a little different from those of the CCSO nameserver.   A There are four 'modes' that the query command will operate under:   H 1. In 'exact' mode, an indexed field is searched exactly and whatever is    found is returned. L 2. In 'approximate' mode, if an exact match fails the field is searched for ,    any keys that start with the query value.M 3. In 'soundex' mode, if an exact match fails the name field is searched via  J    a soundex (phoneme hashing) function to return all entries that 'sound     like' the query value. 6 4. A combination of 'approximate' and 'soundex' modes.  A Name field searches also automatically perform a nickname search.   H Approximate searches can be forced by wildcard queries (e.g. 'query a*')G and soundex searches can be forced by performing a query on the soundex & field (e.g. 'query soundex=stephen').   F There are six global mode flags that can be set: approximate, soundex,C debug, record, wild and remote.  These modes are defined by the SET I command. SET APPROXIMATE=ON and SET SOUNDEX=ON sets the 'approximate' and H 'soundex' modes described above.  SET DEBUG=ON tells qi to emit internalK debugging information, SET RECORD=ON tells qi to record all reponses in the H log file, SET WILD=ON/OFF defines whether non-indexed fields are matched@ partially or exactly (qi.h is sent out with WILD on by default).I SET REMOTE=ON tells qi to treat the client as non-local even if it passes J all the local checking; this is for on-behalf-of gateways to deny localpub access.   ) SET command keywords may be abbreviated.  9 SET <flag>=OFF, will reset the mode for all of the flags. > SET EXACT=ON is a synonym for SET APPROXIMATE=OFF SOUNDEX=OFF.     Troubleshooting:  A Your client won't work and you swear that you've followed all the + directions.  Here are some things to check:   6 1. Run qi interactively and see if you can do a query. $ run device:[path]qi.exe 
 qi> status qi> query some name  qi> exit  F If you have problems in step 1, check your database files contents andH protections and your CSO_* logical names for exec mode and system table.  # 2. run qi over a telnet connection.  $ telnet our.host/port=105 query some name  exit  I If you have problems with step 2, check your server configuration, qi.exe = protection.  Have you restarted the server after changing the  configuration?  L 3. Use your nameserver client (ph, mail system, etc.) and issue SET DEBUG=ONH LOG=ON prior to a query and then check the contents of the CSO_LOG file.     New command:  K Due to the relationship between the index and data files, a unique key (the E ID) is necessary.  Before an ADD comand may be given, this ID must be ; selected; either directly or from a range of available IDs.   	 select id   1 Prepares a subsequent 'add' with an available ID.    Example        select 812000123  C will create any fields made with the next 'add' command with the ID K 81200123.  Selecting an ID of 0 will invalidate any previous 'select'ed ID.    select field=value  G Performs a lookup of the entry for 'field' (which must be Unique) which J contains 'value'.  The value of the field defined in qi.h by CONTROL_FIELDJ (by default field 95, labeled 'next_id') is retrieved for use by the 'add': command and then incremented and placed back in the field.   Example        select alias=control  I will get the 'next_id' field (e.g. 1000) for the entry that has the alias I "control".  This field is then incremented (next_id becomes 1001) and the 5 next 'add' command will create an entry with ID 1000.   J The 'select field=value' is so useful that it is automated by default.  IfJ an 'add' is performed without a valid ID prepared by a 'select', the aliasE field is searched for the value DEFAULT_SELECT (defined in qi.h to be  "control").      Modified command:   H The change command has been modified to allow you to set attributes on aI per-field basis.  This allows you to raise or lower the 'visibility' of a @ specific field instead of the default for a field that is in the configuration file.   , change [field=]value ... set field=attribute  B The "set" clause will apply an attribute to a field instance.  TheD attributes are Public, Local, Suppress, None and Unchanged.  Case is* ignored and attributes may be abbreviated.   Example   *     change alias=joe.smith set phone=local  I will only allow display of the joe.smith 'phone' field for local queries.   ;  Public is analogous to the configuration attribute Public. <  Local is analogous to the configuration attribute LocalPub.,  Suppress only allows owner and Hero access.@  None reverts the field to the default configuration attributes.F  Unchanged will reset the 'changed' flag and will not modify the other  attributes.    Default is an alias for None.  C The configuration file field attribute 'ForcePub' will override the : per-field attributes and always treat the field as public.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              