       
                                        Ref:    DXS/DSAP/L1
                                        Date:   06-Dec-91
                                        Author: Paul Sanders
       
       
               CD-ROM Data Exchange Standard (DXS)
                 Database Server Access Protocol
                           Version 1.0
       
       
            Paul Sanders
            SilverPlatter Information Ltd.
            10 Barley Mow Passage
            Chiswick
            London W4 4PH
            England
       
            Tel: +44 (0) 81-995 8242
            Fax: +44 (0) 81-995 5159
       
            This document is available in Microsoft Word 5.5
            format from the above address.


































                                   1

                        Table of Contents
       
       .Begin Table C.

1.     Introduction                                        4
  1.1    Change History                                    4

2.     Message Sequences and Formats                       5

3.     Logging in                                          7
  3.1    'Get Server Information' Request                  8
  3.2    'Login' Request                                   9

4.     Database Selection                                 10
  4.1    'Database List' Request                          11
  4.2    'Open Database' Request                          12
  4.3    'Close Database' Request                         13

5.     Database Information                               14
  5.1    'Get Database Information' Request               15
  5.2    'Get Field Information' Request                  19
  5.3    'Get Stopwords' Request                          22
  5.4    'Get Help Topics' Request                        23
  5.5    'Get TOC-Level Name' Request                     25

6.     Index Access                                       26
  6.1    'Read Index' Request                             26
  6.2    Pattern Interpretation in Index Lookups          28
  6.3    'Map Search Terms' Request                       30

7.     Cursors                                            31
  7.1    'Create Cursor' Request                          31
  7.2    'Delete Cursor' Request                          31

8.     Searching                                          32
  8.1    'Execute Search' Request                         32
  8.2    'Discard Search' Request                         33
  8.3    'Sort Current Search' Request                    34
  8.4    Search Request Syntax                            35
  8.5    Referbacks                                       38
  8.6    'Progress' Request                               40

9.     Data Retrieval                                     41
  9.1    'Read Data' Request                              41
  9.2    'Get Hits' Request                               45
  9.3    'Set Hits' Request                               47
  9.4    Format of Marked-Up Items in Returned Data       48

10.    Table of Contents                                  54
  10.1   'Read Table of Contents' Request                 54

11.    Read-Only File Access                              56
  11.1   'Get File Information' Request                   57
  11.2   'Open File' Request                              58



                                   2

  11.3   'Close File' Request                             59
  11.4   'Read File' Request                              60

A.     Message Summary                                    61

B.     Example Message Sequence                           63

C.     Algorithms and Code Fragments                      71
  C.1    Password Encryption                              71

D.     Well Known Identifiers                             72
       .End Table C.













































                                   3



1.     Introduction

       This document describes the communications protocol used
       to access database servers conforming to the CD-ROM Data
       Exchange Standard (DXS).
       
       A working knowledge of the following related documents is
       assumed:
          - 'CD-ROM Data Exchange Standard Specification'
            (DXS/SPEC)
          - 'CD-ROM Data Exchange Standard Client-Server Transfer
            Syntax' (DXS/CSTS)
          - 'CD-ROM Data Exchange Standard Platform Dependent
            Implementation Details' (DXS/PLAT)
       
       This document offers flexibility and extensibility in a
       number of ways, principally:
          - the client-server syntax allows keywords and item-
            list names to be added to existing request ID's
            without affecting existing clients; new request ID's
            can also be added, of course
          - various optional features are supported via the 'Get
            Database Information' request (section 5.1)
          - a few general purpose mechanisms are specified but
            not (yet) used, or used only sparingly (read-only
            file access, for example, section 11)
       
       Vendor-unique extensions are catered for by:
          - reserving a range of request ID's for vendor-specific
            requests
          - requiring that all vendor-unique keywords and item-
            list names, and their 2 character abbreviations,
            start with the vendor's prefix (including the '$')
          - allowing vendor-unique markup codes in returned data
            (section 9.4)
       
       These mechanism should ensure that the Data Exchange
       Standard is able to respond to future requirements whilst
       remaining compatible with older clients.


1.1    Change History

       This is the first live version of this document.











                                   4

2.     Message Sequences and Formats

       Requests and responses use the transfer syntax and obey
       the rules described in 'Client-Server Transfer Syntax'
       (DXS/CSTS).  This document also describes basic BYTE, WORD
       and DWORD data types used for communicating between
       machines with different native byte orders.
       
       In general, the client issues a request to the server and
       awaits one or more responses.  While a request is being
       executed, any subsequent request (except for a 'Cancel
       Request' request) issued by the client may be queued by
       the server, rather than being executed immediately.  If
       the server has no space to queue the request, it will
       reject it (with error EC_BUSY).
       
       The following general rules apply to the message formats
       in the following sections:
          - the two character keyword and item name abbreviations
            precede the full name, separated by a space
          - required keywords are marked with an asterisk (*)
          - lists of keywords and values use the format described
            in 'Client-Server Transfer Syntax' (DXS/CSTS)
          - numeric values in requests are passed as decimal-
            ASCII strings unless otherwise stated
       
       The following applies to all requests:
            Protocol Type  NWP_DBSRVR
            Request ID     as required
       
       All successful requests return a response (failed requests
       cause an 'error request' to be returned).  If an info_list
       is specified, this contains the requested information;  if
       there is no info-list specified, the response serves to
       confirm successful completion of the request.  The
       following applies to all responses:
            Protocol Type  NWP_DBSRVR
            Response Type  the corresponding request type with
                           the MS bit set
            Request ID     same as corresponding request
            No. of records as specified in the info-list of the
                           corresponding request
            Response data  see info-list of corresponding request
       
       Data sizes given in info-lists describe the maximum length
       of the data item (excluding length and terminator bytes).
       If the item is binary numeric, the size is preceded by
       'I'.  If the maximum length is undefined, an advisory
       maximum is given, preceded by a question mark.
       
       Error and warning requests are detailed in document
       'Client-Server Transfer Syntax' (DXS/CSTS).  Additional
       information is given for specific requests, where
       relevant.



                                   5

       
       Many requests only offer a First/Next interface.  This is
       intentional - to minimise network traffic (with its
       inherent delays), the client should read the information
       that it requires from the server and buffer it locally.
       Database-specific help topics (section 5.4) are a good
       example of this.


















































                                   6

3.     Logging in

       The way in which the client locates the available servers
       is described in 'CD-ROM Data Exchange Platform Dependent
       Implementation Details' (DXS/PLAT), since this is
       implementation-dependent.
       
       The client must first establish a transport connection to
       the server that it wants to access; all requests and
       responses are then issued over this connection.
       
       If the server requires it, the client must login in order
       to use the services of the database server (there are some
       exceptions to this rule; they are noted for the requests
       to which they pertain).  A server which requires a login
       will reject all requests (with error EC_SECURITY) until
       the client has logged in except where stated.
       
       Logging in requires the client to provide a username and
       password.  Note that this information might be supplied by
       the user's client workstation, rather than the end-user
       himself, if the workstation is in a secure environment (a
       library, say).  Maintenance of usernames and passwords on
       the server is outside the scope of this specification.
       
       A client might establish several connections to different
       servers (or indeed to the same server) at the same time.
       It is necessary to log in on each connection separately.





























                                   7

3.1    'Get Server Information' Request

       This request returns information about the server on this
       connection.  The client need not be logged in to issue
       this request.
       
       Request Type:            DB_SRVRINFO
       Keywords and values:
            PR PREFIX           client's vendor prefix, ending
                                with a '$' symbol (e.g. UMI$)
            MV MARKUPVERSION    maximum markup version supported
                                by the client (see section 9.4);
                                currently, must be 1
       
       Info-list (1 record returned in response):
            16  SI SERVERID     unique server ID
            80  SN SERVERNAME   server name (e.g. 'Science
                                Department')
            I2  ST SERVERTYPE   numeric server type (meaning of
                                this is vendor-specific)
            40  SD SERVERDESC   server type description (e.g.
                                'Acme DXS Database Server')
            4   PR PREFIX       server vendor prefix, ending with
                                a '$' symbol (e.g. SP$)
            I2  VR VERSION      server version (integer; 100 =
                                1.00)
            I1  LR LOGINREQ     1 if the client must login to
                                issue other requests
            I2  ND NDBS         number of databases available on
                                this server
       Notes:
          - The server ID should start with the server vendor's
            vendor prefix, e.g. SP$SERVER1.  Vendors can then
            ensure that each server they supply has a unique ID.
          - Vendor prefixes must be centrally administered (by
            NISO?).





















                                   8

3.2    'Login' Request

       This request logs this connection into the server with the
       specified username.
       
       Request Type:            DB_LOGIN
       Keywords and values:
          * UN USERNAME         username
            PA PASSWORD         if required; one-way encrypted
                                and passed as hex-ASCII
            SC SECURE           1 if this is a secure workstation
                                (i.e. the user id and password
                                are configured into the
                                workstation rather than being
                                typed in by the user)
       
       Noteworthy error returns:
            EC_SECURITY         if USERNAME is valid but the
                                login is rejected for some other
                                reason (e.g. invalid PASSWORD)
       Notes:
          - The password is sent in encrypted form.  The
            encryption algorithm (described in section C.1)
            generates a 4 byte 'hashed' version of the original
            password.  Even if the algorithm is known, the
            encrypted form cannot be reverse engineered (other
            than by exhaustively trying all possible passwords)
            to discover the original password.





























                                   9

4.     Database Selection

       This section describes the mechanisms by which the client
       asks a database server for a list of available databases,
       and how it opens a database in order to access it.
       
       Note that, for local servers, the list of available
       databases is obtained by reading the file of installed
       databases (see 'CD-ROM Data Exchange Platform Dependent
       Implementation Details' (DXS/PLAT), section 5), since the
       user must select the desired database before loading the
       server.
       
       If there are several network servers available, the client
       needs to interrogate each one in turn.
       
       To create a combined list of databases hosted on local and
       network servers, the client must use both methods.
       
       Several database can be opened at once, either on one
       connection or on several connections, as the client wishes
       (although opening several connections to the same server
       may hog server resources).  On non multi-tasking
       platforms, only one local server can be loaded at a time.

































                                   10

4.1    'Database List' Request

       This request obtains a list of the databases available on
       this server, from which the client can build a menu of
       databases for the user to pick from.  The client need not
       be logged in to issue this request, but it should supply
       it's userID and password if it is not (to allow the server
       to decide what this user is allowed to see).
       
       Request Type:            DB_DBLIST
       Keywords and values:
            UN USERNAME         username (if not logged in)
            PA PASSWORD         if required; one-way encrypted
                                and passed as hex-ASCII
            FR FIRST            read first database if 1, else
                                read next
            MR MAXRECS          maximum number of database
                                information records to return
                                (default = as many as will fit in
                                one response)
       Info-list (1 or more records returned in response):
            8    DI DBID        database ID (A-Z, 0-9,
                                underscore)
            36   DN DBNAME      database name
            36   IP IPNAME      information provider
            36   PU PUBLISHER   publisher
            160  DT DETAILS     database details
       
       Notes:
          - DBDETAIL may contain line break characters (value
            0x0A)
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last database is returned.  If there are no (more)
            databases, a response containing zero records is
            returned.

















                                   11

4.2    'Open Database' Request

       This request opens the specified database.
       
       Request Type:            DB_OPENDB
       Keywords and values:
          * DI DBID             database ID
       Info-list (1 record returned in response):
            I4  DH DBHANDLE     4 byte handle to the database
                                opened (used to specify this
                                database in subsequent requests)














































                                   12

4.3    'Close Database' Request

       This request closes the specified database.
       
       Request Type:            DB_CLOSEDB
       Keywords and values:
          * DBHANDLE            database handle (as a hex-ASCII
                                string)

















































                                   13

5.     Database Information

       This section describes the mechanisms by which the client
       asks the database server for information about an open
       database.
       
       A database is a collection of records.  Each record is
       broken into 1 or more fields which provide access points
       for searching and display.
       
       A field is identified by its 9 character abbreviation
       (which is unique within each database).  A list of fields
       (consisting of their abbreviations and other attributes)
       can be obtained from the server, using the 'Get Field
       Information' request (section 5.2).  This list can be
       presented to the user to allow him to, for example,
       specify which field(s) he wishes to search in.
       
       A particular record need not (and in general will not)
       contain all of the fields defined for the database.  A
       record may also contain more than one instance of the same
       field.
       
       A database may also define sets of fields (called
       'fieldsets').  These do not describe the structure of the
       records directly, but define mappings or groupings of
       fields which are helpful to the user.  Each fieldset is
       also identified by an abbreviation.  A fieldset can
       contain fields and/or other fieldsets.
       
       At the discretion of the server, records may also be
       divided into chapters, sections, sub-sections and so-on,
       and accessed via a table of contents.
























                                   14

5.1    'Get Database Information' Request

       This request obtains information about the specified open
       database.
       
       Request Type:            DB_DBINFO
       Keywords and values:
          * DBHANDLE            database handle (as a hex-ASCII
                                string)
       Info-list (1 record returned in response):
            16   DI DBID        unique database ID
            36   DN DBNAME      database name
            36   IP IPNAME      information provider
            36   PU PUBLISHER   publisher
            160  DT DETAILS     database details
          ?160   CR COPYRIGHT   Title and copyright information
                                for this database
            40   SR SRECNAME    singular name for a record (e.g.
                                'Article' or 'Company')
            40   PR PRECNAME    plural name for a record (e.g.
                                'Articles' or 'Companies')
            40   SF SFLDNAME    singular name for a field (e.g.
                                'Field')
            40   PF PFLDAME     plural name for a field (e.g.
                                'Fields')
            40   RF RFNAME      name for reference fields (e.g.
                                'Summary')
       ---
            I2   NF NFLDS       number of fields
            I4   NR NRECS       number of records in the database
            I1   MC MAXCURSORS  maximum number of cursors that
                                can be created for this database
                                (see section 7.1) (minimum 1)
       ---
            I1   RE RECORDS     1 if the RECORDS operator is
                                supported in search requests (see
                                section 8.4)
            I1   FN FNEAR       1 if the FNEAR proximity operator
                                is supported in search requests
            I1   RT RTRUNC      1 if right truncation is
                                supported
            I1   LT LTRUNC      1 if left truncation is supported
            I1   WC WILDCARDS   1 if wildcards are supported
            I1   CS CASESENS    1 if searches are case-sensitive
            40   FT FREETEXT    list of fields to search for
                                'free text' search requests (i.e.
                                when no field(s) are explicitly
                                specified) (*A = all searchable
                                fields)
            I1   SN SNEAR       1 if the SNEAR proximity operator
                                is supported in free text search
                                requests





                                   15

            I1   WN WNEAR       1 if the WNEAR proximity operator
                                is supported in free text search
                                requests
            I1   WS WSEQ        1 if the WSEQ proximity operator
                                is supported in free text search
                                requests
       ---
            I1   MH MARKHITS    1 if hits can be highlighted in
                                retrieved records (see section
                                9.4)
            I1   TC TOC         1 if database has a table of
                                contents (see section 10)
            I1   RV RELEVANCE   1 if ranking retrieved records by
                                relevance is supported (see
                                section 9.1)
            I1   RS RELSORT     1 if sorting retrieved records by
                                relevance is supported (see
                                section 8.3)
            I1   FS FLDSORT     1 if sort by field is supported
                                (see section 8.3)
       ---
            I2   IT INACTIVITY  inactivity timeout, in minutes,
                                after which the client should
                                close the database, 0 = infinite
                                (the server does not enforce
                                this)
            I2   MS MAXSESSION  maximum session time, in minutes,
                                after which the client should
                                close the database, 0 = infinite
                                (the server does not enforce
                                this)
            I1   CP CANPRINT    1 if user is allowed to print
                                records (the server does not
                                enforce this)
            I1   CD CANDOWNLOAD 1 if user is allowed to download
                                records (the server does not
                                enforce this)
            ?40  SD SHOWDFLT    comma-delimited list of field
                                abbreviations to display by
                                default (as supplied in the
                                FLDLIST of a 'Read data' request)
            ?40  PD PRINTDFLT   comma-delimited list of field
                                abbreviations to print by default
            ?40  DD DNLOADDFLT  comma-delimited list of field
                                abbreviations to download by
                                default
     
       Notes:
          - DBID's should start with the database vendor's vendor
            prefix, e.g. CDP$MEDLINE.
          - COPYRIGHT may contain line break characters (value
            0x0A); a maximum of three lines is strongly
            recommended.




                                   16

5.2    'Get Field Information' Request

       This request returns information about the specified
       field(s) and/or fieldsets.  The client should cache this
       information locally.
       
       The order in which fields are returned is undefined, but
       it should be suitable for displaying a list of fields to
       the user.
       
       'Universal' field abbreviations are used to facilitate
       cross-database searching (by virtue of being the same for
       all databases to which they reasonably apply).  These will
       need to be centrally administered.  These will usually be
       fieldsets of one field, this being the mechanism to
       support two different abbreviations for the same field.
       
       Request Type:            DB_FLDINFO
       Keywords and values:
          * DH DBHANDLE         database handle (as a hex-ASCII
                                string)
            FR FIRST            read first field if 1, else read
                                next
            FS FIELDSET         if supplied, return only the
                                fields in this fieldset
            MR MAXRECS          maximum number of information
                                records to return (default = as
                                many as will fit in one response)
       Info-list (1 or more records returned in response):
            1   FY FLDTYPE      F = field, S = fieldset
            9   FA FLDABBREV    field/fieldset abbreviation
            9   SA SHOWABBREV   field/fieldset abbreviation to
                                use when displaying records
            80  FN FLDNAME      field/fieldset name
            I1  IN INDENT       indent level (0, 1, ...) to use
                                when displaying in a list of
                                fields
            15  HT HELPTAG      tag of file containing help text
                                for this field/fieldset (empty =
                                none)
            I1  HI HIDDEN       1 if the client should omit this
                                field/fieldset from the list of
                                fields presented to the user
            I1  DI DISPLAY      1 if field/fieldset should be
                                displayed in retrieved records
            I1  FT FULLTEXT     1 if this is a 'full text' field
                                (usually the last field, with
                                several instances in each record)
            I1  SR SEARCH       1 if field/fieldset is searchable
            I1  FS FLDSEARCH    1 if the server can do field-
                                specific searches in this field
                                (i.e. the 'IN' operator can be
                                used, section 8.4)




                                   17

            I1  SN SNEAR        1 if the SNEAR proximity operator
                                is supported in searches in thie
                                field
            I1  WN WNEAR        1 if the WNEAR proximity operator
                                is supported in searches in thie
                                field
            I1  WS WSEQ         1 if the WSEQ proximity operator
                                is supported in searches in thie
                                field
            I1  AL ALPHA        1 if non-numbers are indexed in
                                this field
            I1  NU NUMBERS      1 if numbers are indexed in this
                                field       
            I1  NO NORMALISED   1 if numbers are indexed in this
                                field in 'normalised' form (so
                                searching ranges of numbers gives
                                sensible results)
            I1  IT INTEGER      1 if numbers are indexed as
                                integers (i.e. any decimal part
                                is discarded)
            I1  IS IXSTOPW      1 if stopwords are indexed in
                                this field
            I1  IX INDEX        1 if this field has its own index
                                (see section 6)
            I1  UV UNIVERSAL    1 if fieldset represents a
                                'universal' field abbreviation
       
       Noteworthy error returns:
            EC_MISSINGKW        if neither FLDINDEX nor FLDABBREV
                                supplied (both keywords are
                                reported in the developer error
                                string)
            EC_MULTKEY          if both FLDINDEX and FLDABBREV
                                specified
       Notes:
          - A field may contain numeric data, alpha-numeric data
            or both; the exact form in which a particular word is
            indexed in a particular field can be obtained via the
            'Map Search Terms' request (section 6.3)
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last field or fieldset record is returned.











                                   18

5.3    'Get Stopwords' Request

       This request returns stopwords for the specified database.
       It is anticipated that the client will cache this
       information locally.
       
       Request Type:            DB_STOPWORD
       Keywords and values:
          * DH DBHANDLE         database handle (as a hex-ASCII
                                string)
            FR FIRST            read first stopword if 1, else
                                read next
            MR MAXRECS          maximum number of stopword
                                records to return (default = as
                                many will fit in one response)
       Info-list (1 or more records returned in response):
            80  SW STOPWORD     stopword
            ?80 FA FLDABBREV    comma-delimited list of field
                                abbreviations to which the
                                stopword applies, or *A for all
                                searchable fields
       Notes:
          - stopwords are returned in alphabetical order
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last stopword is returned.



























                                   19

5.4    'Get Help Topics' Request

       This request returns database-specific help topics.  The
       client should cache this information locally.
       
       Request Type:            DB_HELPTOPIC
       Keywords and values:
          * DH DBHANDLE         database handle (as a hex-ASCII
                                string)
            FR FIRST            read first topic if 1, else read
                                next
            MR MAXRECS          maximum number of topic records
                                to return (default = as many as
                                will fit in one response)
       Info-list (1 or more records returned in response):
            40  TN TOPICNAME    topic name
            1   TT TOPICTYPE    topic type: L = fieldlist,
                                F = field information, T = Title
                                Screen, O = other
            I1  IN INDENT       indentation level (0, 1, ...) to
                                use when displaying in a list of
                                topics
            I1  HI HIDDEN       1 if the client should omit this
                                topic from the list of topics
                                presented to the user
            15  HT HELPTAG      tag of file containing help text
                                for this topic (empty = none)
            
       Notes:
          - A topic of type L (fieldlist) contains a list of the
            fields in the database; topics of type F contain
            information about a specific field or fieldset.
            Clients may elect to suppress these topics in the
            list displayed to the user in favour of some other
            way of providing access to the list of fields.
          - A topic of type T (title screen) contains some
            introductory text to the database
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last topic is returned.
          - To retrieve the text associated with the topic, issue
            an 'Open file' request using HELPTAG.  This file may
            contain the following markup codes (as defined in
            section 9.4):









                                   20

                 <LI> <NL> <SHIFT1>..<SHIFT8>
                 <ENDSHIFT1>..<ENDSHIFT8> <V1>..<V8>
                 <ENDV1>..<ENDV8> <BOLD> <ENDBOLD> <UNDERLINE>
                 <ENDUNDERLINE> <ITALIC> <ENDITALIC> <REVERSE>
                 <ENDREVERSE> <RED> <GREEN> <BLUE> <YELLOW>
                 <CYAN> <PURPLE> <BLACK> <WHITE> <NORMAL>
                 <BACKGROUND> <ENDBACKGROUND> <LEFTJUST>
                 <CENTRED>

















































                                   21

5.5    'Get TOC-Level Name' Request

       This request returns the names of one or more levels in
       the Table of Contents.
       
       The table of contents (TOC) is viewed as two hierarchies
       of entries.  Each entry in the first hierarchy describes a
       sub-set of the database (representing a range of absolute
       record numbers).  Each entry in the second hierarchy
       indicates a section within a record.  Either hierarchy may
       be empty, in which case the client should behave sensibly.
       
       Each level in each hierarchy is named, so that the segment
       of the database that these levels represent can be
       displayed by the client.  Servers may return empty names,
       in which case clients should behave sensibly.
       
       Request Type:            DB_TLNAME
       Keywords and values:
          * DH DBHANDLE         database handle (as a hex-ASCII
                                string)
            FR FIRST            read first TOC level name if 1,
                                else read next
            MR MAXRECS          maximum number of TOC level-names
                                to return (default = as many as
                                will fit in one response)
       Info-list (1 or more records returned in response):
            1   HY HIERARCHY    D = entry represents a sub-set of
                                the database, R = entry
                                represents a section within a
                                record
            I1  LV LEVEL        level within this hierarchy (1,
                                2, ...; 1 = top level)
            I2  NE NENTRIES     number of TOC entries at this
                                level in this hierarchy
            ?80 SN SLNAME       singular form of database sub-set
                                or record section name
            ?80 PN PLNAME       plural form of NAME
            
       Notes:
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last level-name is returned in the specified
            hierarchy.









                                   22

6.     Index Access

       This section provides mechanisms for the client to access
       lists of indexed words.  An index can either cover the
       entire database, or just the contents of a single field or
       fieldset.


6.1    'Read Index' Request

       This request retrieves terms from the specified index.
       
       POSITION contains one of the following values:
          G=position index to TERM specified
          F=position the index at the first entry
          L=position the index just beyond the last entry
       
       DIRECTION contains one of the following values:
          N=return next term(s) matching the last PATTERN
            specified until no more matching terms are found; the
            first term returned is the current term; the current
            term is advanced
          P=return previous term(s) matching the last PATTERN
            specified until no more matching terms are found; the
            first term returned is the term immediately preceding
            the current term; the current term is backed up
       
       Within each response, terms are returned in the same
       order, irrespective of whether retrieving next or previous
       terms.  The collating sequence of the index is undefined.
       
       
       Request Type:            DB_READIX
       Keywords and values:
          * DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string)
            FA FLDABBREV        field or fieldset abbreviation
                                (default = *A = all searchable
                                fields)
            PO POSITION         see above; default = read next
                                term (or previous term, if
                                DIRECTION = P)
            DC DIRECTION        see above; default = Next
            PT PATTERN          pattern to match (see section
                                6.2); default = use previous
                                pattern, * = return all terms.
                                Note that, if a pattern is
                                specified, the index is
                                positioned to the first matching
                                term
            TM TERM             term to position to; a trailing
                                asterisk can be used to position
                                the index to the first term >=
                                the term specified



                                   23

            MR MAXRECS          maximum no. of terms to return
                                (default = as many as will fit in
                                one response)
       Info-list (1 or more records returned in response):
            128 TM TERM         term found
            I4  NH NHITS        number of occurrences of this
                                term in the database (empty =
                                unknown)
            I4  NR NRECS        number of records containing hits
                                (empty = unknown)
       Noteworthy error returns:
            EC_BADKEY           if FLDABBREV specifies a field
                                for which no index exists
            EC_MISSINGKW        if POSITION = G and TERM is
                                missing
       Notes:
          - rather than just returning a single word, TERM may
            return a string containing spaces and punctuation
            (e.g. Smith, J).
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when the
            last (or first if DIRECTION = P) matching term is
            returned.  If PATTERN fails to match any index
            entries, or TERM does not match PATTERN, a response
            containing zero records is returned.




























                                   24

6.2    Pattern Interpretation in Index Lookups

       Interpretation of lower case letters, punctuation and
       spaces in PATTERN is at the discretion of the server.  The
       client can use the 'Map search terms' request (see below)
       to determine (for the user's benefit) how a particular
       search term entered by the user is looked-up in the index
       (and hence searched for).
       
       The collating sequence is undefined (and may vary for
       different fields).
       
       Support for truncation and wildcards is optional (section
       5.1).
       
       PATTERN may contain the following special constructs:
            *     - wildcard match (0 or more characters)
            ?     - wildcard match (0 or 1 characters)
            $     - wildcard match (exactly one character)
            x:    - match words >= x; x may not contain
                    wildcards, a set construct ([...]) or another
                    range operator (:)
            x^:   - match words > x
            :y    - match words <= y; y may not contain
                    wildcards, a set construct ([...]) or another
                    range operator (:)
            :^y   - match words < y
            x:y   - match words in the range x..y inclusive
            x^:y  - match words greater than x and less than or
                    equal to y
            x:^y  - match words greater than or equal to x and
                    less than y
            x^:^y - match words greater than x and less than y
            [x,y,z,...]
                  - match any of the strings in the set x, y, or
                    z; an empty string is acceptable; the set
                    construct may not be nested and may not
                    contain a range operator (:)
            \     - treat the following character as a literal
            \H    - means a literal hash symbol (#)
            \Q    - means a literal double quote (")
            \S    - means a literal single quote (')
            \\    - means a literal backslash (\)
       
       Hash symbols and quotes are not allowed in PATTERN.  Use
       \H, \Q and \S instead.
       
       Examples:
            WOOD*     matches WOOD, WOODS, WOODEN
            WOOD?     matches WOOD, WOODS but not WOODEN
            WOOD$     matches WOODS, but not WOOD, WOODEN
            APPLE*S   matches APPLES, APPLE-TREES
            S?IP      matches SHIP, SLIP, SIP
            S$IP      matches SHIP, SLIP, but not SIP



                                   25

            *IP       matches HIP, SHIP, SLIP, SIP
            SODIUM[DI,TRI,]PHOSPHATE
                      matches SODIUMDIPHOSPHATE,
                      SODIUMTRIPHOSPHATE, SODIUMPHOSPHATE
            A:^B      matches A, APPLE, AZTEC, but not B
            1:10      matches the numbers from 1 to 10 inclusive
                      (in a numeric field)
            A\*B      matches A*B
            \QAB\Q    matches "AB"
















































                                   26

6.3    'Map Search Terms' Request

       This request converts the pattern(s) supplied into the
       form in which they are looked up in the index (and hence
       searched for).  This may involve conversion to upper case,
       stripping punctuation, mapping plurals to singulars,
       automatic stemming, and so on.  Wild card characters are
       left in the converted terms, unless preceded by a
       backslash, in which case they are treated as literals and
       converted accordingly; the backslash is removed.
       
       Request Type:            DB_MAPTERMS
       Keywords and values:
          * DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string)
            PT PATTERNS         comma-delimited list of field
                                abbreviations and patterns to
                                convert
       Info-list (1 or more records returned in response):
            80  TM TERM         converted search term (first
                                record = first pattern, second
                                record = second pattern, etc)
       Notes:
          - the format of each entry in PATTERNS is:
                 <field abbrev>=<value>
            where '<field abbrev>=' is optional; examples:
                 Muffins
                 PY=86
                 AU=Smith, J.
          - the format of the TERM returned is similar
          - Several responses may be returned, the last of which
            will have the 'request complete' flag set.
       
       Examples (// precedes a comment):
            In: Apple       Out: APPLE      // map to upper case
            In: PY=86       Out: PY=1986
            In: AU=Jones,E. Out: AU=JONES-E // normalise name
            In: Appl*s      Out: APPL*S     // * = wild card
            In: Appl\*s     Out: APPLS      // literal * stripped
            In: Appl-s      Out: APPL-S     // hyphen is srchable
            In: 100         Out: 0000000100 // normalise number
            In: 100.1       Out: 0000000100 // search as integer















                                   27

7.     Cursors

       Cursors provide a mechanism for a client to maintain
       several independent 'contexts' in an open database.
       Associated with each cursor is:
          - a current search
          - a current 'position' from which a 'Read data' request
            will return data if no explicit re-positioning
            information is supplied
          - the information supplied in the last 'set hits'
            request
       
       Cursors do not keep track of the current position in the
       indexes or table of contents; the client must re-position
       these explicitly, using the mechanisms provided.
       
       Cursors are 4 byte values, generated by the server when
       requested to do so by the client.


7.1    'Create Cursor' Request

       This request creates a new cursor.
       
       Request Type:            DB_CURSOR
       Keywords and values:
          * DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string)
       Info-list (1 record returned in response):
            I4  CU CURSOR       cursor
       
       If no more cursors are available, 0 is returned in CURSOR.


7.2    'Delete Cursor' Request

       This request deletes a cursor.
       
       Request Type:            DB_DELCURSOR
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
       
       All cursors associated with an open database are
       automatically deleted when the database is closed.












                                   28

8.     Searching

       This section provides mechanisms for the client to submit
       search requests and retrieve the number of hits.


8.1    'Execute Search' Request

       This request submits a search request to the server.
       
       Request Type:            DB_SEARCH
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
          * SR SEARCHREQ        search request (see section 8.4)
            SF SORTFIELDS       Comma-delimited list of field
                                abbreviations by which to sort
                                retrieved records (sort by the
                                first field, then by the next,
                                etc.); *V = sort by relevance;
                                default = do not sort
       Info-list (1 record returned in response):
            I1  BR BROADENED    1 if the search has been
                                broadened by the server, in some
                                undefined way (section 8.4)
            I4  NH NHITS        total number of hits
            I4  NR NRECS        number of records containing hits
       Noteworthy error returns:
            EC_BADVALUE         if SEARCHREQ is invalid
            EC_BADKEY           if any SORTFIELDS are invalid
       
       While the search is in progress, the server will
       periodically send a 'progress request' to the client as
       described in section 8.
       
       If SEARCHREQ is invalid, a string of the form:
            ERRORPOS='31' (or EP='31')
       is appended to the developer error string, reporting the
       first character in the string in error.


















                                   29

8.2    'Discard Search' Request

       This request informs the server that a previously
       submitted search request is unlikely to be needed again.
       This is a courtesy to the server.  See section 8.5 for an
       explanation of why this request exists.
       
       Request Type:            DB_KILLSEARCH
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
          * SR SEARCHREQ        search request (see section 8.4)













































                                   30

8.3    'Sort Current Search' Request

       This request asks the server to sort (or re-sort) the
       current search for the specified cursor.
       
       Request Type:            DB_SORT
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
            SF SORTFIELDS       Comma-delimited list of field
                                abbreviations by which to sort
                                retrieved records (sort by the
                                first field, then by the next,
                                etc.); *V = sort by relevance;
                                default = unsorted










































                                   31

8.4    Search Request Syntax

       A term in a search request is either:
          - a search term, in double quotes, for example:
                 "DOG"
                 "APPLE*"
                 "Jones, E"
          - an operator, with it's associated parameters in
            brackets, for example:
                 AND ("CAT", "DOG")
                 AND ("CAT", OR ("DOG", "HAMSTER"))
          - the word ALL, representing all records in the
            database
       
       Outside quotes, all keywords must be in upper case and
       spaces are not allowed (but are shown in examples for
       clarity).
       
       Search terms are patterns which are looked up in index
       (for the specified field, if the IN operator is used).
       They may contain wildcard characters as specified in
       section 6.2, and must not contain a hash symbol or a quote
       (use \H, \Q or \S).  Note that wildcards also provide
       support for inequality and range searching.
       
       The server maps each search term before looking it up in
       the index, as described in section 6.3.
       
       
       The server is required to support the following operators:
            AND (term1, term2, ..., termN)
                 finds records containing all of the specified
                 terms
            OR (term1, term2, ..., termN)
                 finds records containing one or more of the
                 specified terms
            NOT (term1, term2, ..., termN)
                 finds records containing term1, but none of
                 term2, ..., termN
            
       The following operators must be recognised, but support
       for them is optional:
            FNEAR (term1, term2, ..., termN)
                 finds records containing all of the specified
                 terms in the same field
            SNEAR (term1, term2, ..., termN)
                 finds records containing all of the specified
                 terms in the same sentence; a sentence may not
                 cross a field boundary
            WNEAR (x, term1, term2, ..., termN)







                                   32

                 finds records where term1 is within x words of
                 term2, term2 is within x words of term 3, and so
                 on; x = 0 means adjacent terms; whether or not
                 WNEAR works across sentence boundaries is
                 undefined
            WSEQ (x, term1, term2, ..., termN)
                 finds records where term1 precedes term2 by x
                 words or less, term2 precedes term3 by x words
                 or less, and so on; x = 0 means adjacent terms;
                 whether or not WSEQ works across sentence
                 boundaries is undefined
            IN (term, field1, field2, ..., fieldN)
                 finds records containing the specified term in
                 any of the fields specified.  Fields are
                 identified by their abbreviation (see section
                 5); fieldset abbreviations can also be used
            RECORDS (term, range1, range2, ..., rangeN)
                 finds records falling within any of the
                 specified ranges of absolute record
                 numbers; a range takes the form "1:100"
                 (including the quotes), meaning (in this
                 example) absolute record numbers between 1 and
                 100 inclusive
       
       Examples (extend):
            "CAT"
                 finds records containing the word CAT
            AND ("DOG", "CAT", "ANT-EATER*")
                 finds records containing all of the words DOG,
                 CAT and any word beginning with ANT-EATER
            OR ("DOG", "CAT", "ANT-EATER")
                 finds records containing any of the words DOG,
                 CAT, ANT-EATER
            NOT (ALL, "POLITICS")
                 finds all records except those containing the
                 word POLITICS
            FNEAR ("STRANGE", "BEDFELLOWS")
                 finds records containing both STRANGE and
                 BEDFELLOWS in the same field
            SNEAR ("MAGIC", "MARKER")
                 finds records containing both MAGIC and MARKER
                 in the same sentence
            WNEAR (1, "MICHAEL", "FOX")
                 finds records with MICHAEL and FOX in either
                 order, with at most 1 intervening word, e.g.
                 "MICHAEL J. FOX" or "FOX, MICHAEL"
            WSEQ (0, "THE", "QUICK", "BROWN", "FOX")
                 finds records containing the phrase THE QUICK
                 BROWN FOX
            IN ("TRIFLE", "TI", "AB")
                 finds records containing the word TRIFLE in
                 either the TItle or ABstract fields
            RECORDS ("ENCYCLOP?EDIA?", "1:100")




                                   33

                 searches the first 100 records for those
                 containing any of the words ENCYCLOPEDIA,
                 ENCYCLOPAEDIA, ENCYCLOPEDIAS, ENCYCLOPAEDIAS,...
            NOT (AND (OR ("DOG", "CAT"), "PET"), "AARDVARK")
                 finds records containing either DOG or CAT, as
                 long as they also contain the word PET, but not
                 the word AARDVARK (let's face it, Aardvarks make
                 lousy pets)
       
       The server should not reject a search which is
       syntactically correct.  It may, however, broaden a search
       which it could not otherwise process.  For example, a
       server which cannot execute:
            WSEQ (0, "BROWN", "SUGAR")
       may (internally) transform this into:
            WNEAR (0, "BROWN", "SUGAR")
       The server must then return the 'BROADENED' flag in it's
       response to the 'Execute Search' request (section 8.1).
       The client cannot determine the search that was actually
       executed.  Of course, the client should really ask the
       server what its capabilities are and act accordingly.
       
       The server should transform semantically incorrect
       searches like:
            SNEAR (AND ("EGGS", "BACON"), "BEANS")
       and:
            IN (AND ("EGGS", "BACON"), "AB")
       into the nearest reasonable equivalent, and the
       'BROADENED' flag set in the response.  The above searches
       could be converted to:
            AND (SNEAR ("EGGS, "BEANS"), SNEAR ("BACON, "BEANS"))
       and:
            AND (IN ("EGGS", "AB"), IN ("BACON", "AB"))
       respectively.  Again, the client should really translate
       all searches submitted by the user into something which is
       semantically correct.





















                                   34

8.5    Referbacks

       Most retrieval systems offering boolean searching also
       offer a means to refer back to previous searches, e.g.
            #1:  CAT
            #2:  #1 or DOG
       
       Our deliberations on this issue led us to conclude that
       supporting referbacks in the search request syntax would
       require the client and the server to maintain parallel
       search histories.  This in turn causes significant
       complications in the client when searching across multiple
       databases.
       
       Instead, the client expands all referbacks entered by the
       user, and the onus is placed on the server to recognise
       searches or search fragments which it has executed
       previously.  The server is expected to cache searches (and
       their results) on (say) a least-recently used basis.  It
       is free to discard these cached searches at any time if it
       needs the space; the penalty of doing so is, of course,
       that that search will need to be repeated if it is
       referred to later.
       
       This caching scheme has the beneficial side-effect that
       if, as commonly happens, a user re-types a search instead
       of referring back to it, he gets the same response time.
       
       
       Here is an example of how this process works, assuming
       that the server is able to cache all previous searches (//
       introduces a comment):
       
            User enters:        DOG                 // as #1
            DXS search request: "DOG"
            Server executes:    "DOG"
            Server caches:      "DOG"               // as S1
            
            User enters:        CAT                 // as #2
            DXS search request: "CAT"
            Server executes:    "CAT"
            Server caches:      "CAT"               // as S2
            
            User enters:        #1 or #2            // as #3
            DXS search request: OR ("DOG", "CAT")
            Server replaces:    "DOG" with S1, and "CAT" with S2
            Server executes:    OR (S1, S2)
            Server caches:      OR ("CAT", "DOG")   // as S3
            
            User enters:        #3 and FLEA         // as #4
            DXS search request: AND (OR ("DOG", "CAT"), "FLEAS")
            Server replaces:    OR ("DOG", "CAT") with S3
            Server executes:    AND (S3, "FLEAS")
            Server caches:      AND (OR ("DOG", "CAT"), "FLEAS")



                                   35

                                                    // as S4
       
       Notes:
          - #1, #2 etc. refer to entries in the client's search
            history; they are the user's record of his activities
            to date, and he may delete them when he chooses (if
            the user interface allows this)
          - S1, S2 etc. refer to searches cached by the server;
            the server is free to discard these at any time
          - the client's search history and the server's search
            cache are not required or expected to stay in step
       
       
       The simplest way for the server to recognise previous
       requests embedded in a new request is something like:
       
            for (i = number_of_cached_searches, i > 0; --i)
            {
                 while (strstr (new_request, cached_request[i]))
                      replace matched part of new_request with a
                      reference to cached_search[i]
            }
       
       Simple string matching should be effective, since the
       search requests are machine generated (by parsing the
       user's input).
       
       The fact that search terms are enclosed in double quotes,
       and cannot themselves contain a double quote, avoids the
       possibility of faulty recognition of a cached request.
       Search terms cannot contain a hash symbol, so the server
       can use this internally to prefix a reference to a cached
       search (or for any other purpose).
























                                   36

8.6    'Progress' Request

       While a search is in progress, the server will
       periodically send a 'progress request' to the client (this
       is really a response, but a request has a more suitable
       format than a response for this purpose).
       
       Request Type:            DB_PROGRESS
       Request ID               the ID of the request for which
                                progress is being reported
       Keywords and values:
            DH DBHANDLE         handle to the database being
                                searched
            CU CURSOR           the cursor on which the search
                                was issued
            PC PERCENT          percent complete (empty =
                                unknown)
            NR NRECS            number of records found so far
                                containing hits (empty = unknown)
       
       The server does not expect the client to send a response
       to this request.



































                                   37

9.     Data Retrieval

       This section provides mechanisms for the client to
       retrieve data records from the database.


9.1    'Read Data' Request

       This request positions the specified cursor to the
       specified record and field and/or reads data from the
       current record.
       
       POSITION contains one of the following values:
          A=position to ABSREC, where 1 is the first record in
            the database, 2 the second and so on; database
            records are returned in ABSREC order
          R=position to RELREC, where 1 is the first record in
            the set retrieved by the last 'Execute Search'
            request; database records are subsequently returned
            in RELREC order
          H=position to start of record or field specified in the
            last 'Set Hits' request (see section 9.3); only one
            database record is returned
          T=position to TOCID (see section 10); database records
            are subsequently returned in ABSREC order
       
       
       DIRECTION contains one of the following values:
          N=retrieve next data, starting from current position;
            the current position is advanced
          P=retrieve previous data, starting from (but excluding)
            current position; the current position is backed up
       
       Within each response, fields and records are returned in
       the same order, irrespective of the value of DIRECTION.
       
       A single response may contain data from several field
       and/or records.
       
       
       Request Type:            DB_READDATA
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
          * PU PURPOSE          S = show, P = print, D = download
                                (for usage statistics)
            PO POSITION         see above; default = return data
                                from current position
            DC DIRECTION        see above; default = Next
            AR ABSREC           absolute record number
            RR RELREC           relative record number
            TI TOCID            table of contents entry ID





                                   38

            FL FLDLIST          comma-delimited list of required
                                fields and/or fieldsets (see
                                notes below)
            SO SORT             if 1, return fields in the order
                                supplied in FLDLIST; default =
                                return fields in the order in
                                which they are stored on the
                                record
            FA FLDABBREV        if specified, position to this
                                field abbreviation before
                                returning data
            SO STARTOFFSET      if specified, position to this
                                offset from start of field before
                                returning data
            ML MARKUPLEVEL      how the returned data should be
                                marked up (see notes below)
            ND NONDISPLAYABLE   if 1, return non-displayable
                                fields (by default, these will
                                not be returned)
            MR MAXRECS          maximum number of database
                                records to return (default = as
                                many as will fit in one response)
            MF MAXFLDS          maximum number of fields to
                                return (default = as many as will
                                fit in one response)
       
       
       Info-list (1 or more records returned in response):
            I4  AR ABSREC       absolute record number
            I4  RR RELREC       relative record number in the
                                current search (1..), or 0
            I2  RH RHITS        number of hits in this record
                                (empty = unknown)
            9   FA FLDABBREV    field abbreviation
            9   SA SHOWABBREV   field abbreviation to use when
                                displaying records
            80  FN FLDNAME      field name
            I2  FH FHITS        number of hits in this field
                                (empty = unknown)
            I2  RV RELEVANCE    estimate of relevance of this
                                record to the last search
                                executed (1..100, 100 = most
                                relevant) (empty = unknown)
            I4  SO STARTOFFSET  offset of start of data from
                                start of field
            I4  EO ENDOFFSET    offset of just past end of data
                                from start of field
            1   MO MORE         1 if there is more data to come
                                in this record; 2 if there is
                                more data to come in this field
            ?   DA DATA         data in field (possibly continued
                                from previous response)
       Noteworthy error returns:




                                   39

            EC_MISSINGKW        if POSITION = A and ABSREC is
                                missing, or POSITION = R and
                                RELREC is missing, or POSITION =
                                T and TOCID is missing
       
       Notes:
          - FLDLIST is a comma-delimited list of field and/or
            fieldset abbreviations to be returned by subsequent
            'Get Data' requests.  If no FLDLIST is specified, the
            previous value defined for this cursor remains in
            force.  The following abbreviations have special
            meanings:
                 *A - all fields
                 *R - all non full-text fields
                 *T - all full-text fields
                 *H - all fields containing a hit (from the last
                      'Execute Search' or 'Set Hits' request)
            
          - STARTOFFSET can only be used to reposition the cursor
            within a field to a position returned in STARTOFFSET
            or ENDOFFSET in a previous response.
          - MARKUPLEVEL allows the client to specify how the
            returned data should be marked up.  If no MARKUPLEVEL
            is specified, the previous value defined for this
            cursor remains in force.  The client supplies a
            string containing any or all of the following:
                 W - mark word starts
                 S - mark sentence starts
                 H - mark hits
                 C - mark style and colour changes
            
          - If the client specifies MAXRECS, several responses
            may be returned, the last of which will have the
            'request complete' flag set.  If the client does not
            specify MAXRECS, a single response will be returned
            with the 'request complete' flag set.
          - 'More records available' is returned false when there
            is no more data available.  If POSITION = A or T,
            this marks the end (or start if DIRECTION = P) of the
            database; if POSITION = R, this marks the end (or
            start) of the records retrieved by the last search.
            If ABSREC or RELREC is too large, a response
            containing zero records is returned.
       
       The format of each of the marked-up items in the returned
       data is described in section 9.4.











                                   40

9.2    'Get Hits' Request

       This request positions the cursor to the specified record
       (and field, if specified) and returns binary data
       representing the position of the hits in that record (or
       field).  This is used when the client wishes to save a
       record or field marked by the user and later display it
       with the hits highlighted correctly.
       
       The information representing the position of the hits can
       subsequently be passed back to the server in a 'Set hits'
       request, so that hits will be marked up correctly by the
       server when record data is subsequently requested.
       Servers which cannot perform markup under these
       circumstances should still support these requests, but
       'Get hits' need not actually return any data to the
       client.
       
       Note that this mechanism allows the user to mark records
       from several different searches.
       
       POSITION contains one of the following values:
          A=position to ABSREC, where 1 is the first record in
            the database, 2 the second and so on
          R=position to RELREC, where 1 is the first record in
            the set retrieved by the last 'Execute Search' or
            'Set Hits' request
          T=position to TOCID (see section 10)
       
       A single response will contain hits from one database
       record (or field) only.
       
       
       Request Type:            DB_GETHITS
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
          * PO POSITION         see above
            AR ABSREC           absolute record number
            RR RELREC           relative record number
            FA FLDABBREV        if specified, return hits in this
                                field only; otherwise, return
                                hits in all fields
            TI TOCID            table of contents entry ID
       Info-list (1 record returned in response):
            I4  AR ABSREC       absolute record number
            9   FA FLDABBREV    field abbreviation (*A = all)
            ?   HI HITS         binary data representing hits
                                (possibly continued from previous
                                response)
       Noteworthy error returns:
            EC_MISSINGKW        if POSITION = A and ABSREC is
                                missing, or POSITION = R and




                                   41

                                RELREC is missing, or POSITION =
                                T and TOCID is missing
       Notes:
          - Several responses may be returned, the last of which
            will have the 'request complete' flag set.




















































                                   42

9.3    'Set Hits' Request

       This request supplies hits in the specified record or
       field to the server, so that hits will be marked up
       correctly by the server when record data is subsequently
       requested (section 9.4).  This request also positions the
       cursor to the record or field specified.
       
       The server remembers the hits until another 'Set Hits'
       request is issued (with CONTINUED not set to 1), or until
       a 'Read Data' request is issued with POSITION specified.
       
       
       Request Type:            DB_SETHITS
       Keywords and values:
          * CU CURSOR           a previously created cursor (as a
                                hex-ASCII string)
          * AR ABSREC           absolute record number
            FA FLDABBREV        if specified, hits are in
                                specified field only; default (or
                                *A) means hits are in all fields
            CO CONTINUED        1 if this is a continuation of
                                the previous 'Set Hits' request
            HI HITS             binary data representing hits
                                (passed as a hex-ASCII string)
































                                   43

9.4    Format of Marked-Up Items in Returned Data

       This section describes how things like hits are marked up
       in the data returned by the 'Read Data' request.  Much of
       this markup can be enabled or disabled by calling
       SetMarkupLevel.  Help-topic text (section 5.4) also uses
       some of the following markup.
       
       This document describes markup version 1.  The client can
       specify the latest markup version that it understands in
       the 'Get Server Information' request (section 3.1).
       Currently, only markup version 1 is specified.
       
       Each marked-up item is preceded by a 'lead in' character
       (value 0x1B), shown in the following discussion as <LI>.
       <LI> is followed by a single character 'markup code', e.g.
       <HIT> (value 'H').  This in turn may be followed by data
       whose format and meaning depends on the markup code.
       
       Line-ends are marked by a linefeed character (value 0x0A),
       shown as <NL>.  This is not preceded by <LI>.
       
       To cater for the inevitable day (in later markup versions)
       when the available markup code values run out, up to eight
       alternative markup sets are supported, bracketed by
       <SHIFTn> and <ENDSHIFTn> (where n = 1..8).  These may be
       freely nested.  These alternate markup sets are currently
       undefined.
       
       Up to eight sets of vendor-unique markup codes are
       supported by including them between <Vn>..<ENDVn>; these
       can also be nested.  Between <Vn> and <ENDVn>, the meaning
       of all markup codes is vendor-unique.  These markup codes
       will only be returned if the client's vendor prefix
       matches the server's vendor prefix.  The client advises
       the server of its vendor prefix in the 'Get Server
       Information' request (section 3.1).
       
       The effect of many other markup codes persists until the
       corresponding 'end' markup code is encountered, or until
       the end of the current field.  Such markup codes can be
       freely nested.
       
       At the start of each field, the client's state must be
       reset to:
          - not <SHIFTn>
          - not <Vn>
          - not <BOLD>, <UNDERLINE>, <ITALIC> or <REVERSE>
          - <LEFTJUST> (left justified)
          - <NORMAL> text and background colour
          - not in a hit
       
       
       Markup Code  Value  Description



                                   44

       
       <NL>         0x0A   End of line; this is not preceded by
                           <LI>.
       <LI>         0x1B   Indicates that one of the following
                           markup codes follows.
                           <LI><LI> represents a literal <LI>.
                           <LI><NL> represents a literal <NL>.
       
       <SHIFT1>     0xE0   Start alternate markup set 1
       <ENDSHIFT1>  0xE8   End alternate markup set 1
       <SHIFT2>     0xE1   Start alternate markup set 2
       <ENDSHIFT2>  0xE9   End alternate markup set 2
            .
            .
       <SHIFT8>     0xE7   Start alternate markup set 8
       <ENDSHIFT8>  0xEF   End alternate markup set 8
       
       <V1>         0xF0   Start vendor unique markup set 1
       <ENDV1>      0xF8   End vendor-unique markup set 1
       <V2>         0xF1   Start vendor unique markup set 2
       <ENDV2>      0xF9   End vendor-unique markup set 2
            .
            .
       <V8>         0xF7   Start vendor unique markup set 8
       <ENDV8>      0xFF   End vendor-unique markup set 8
       
       The following markup codes are 'atomic' (i.e. they are
       complete in themselves):
       
       Markup Code  Value  Description
       
       <SENTENCE>     S    Marks the start of a sentence (as
                           determined by the database builder).
                           Sentence ends are not marked.
       <WORD>         W    Marks the start of a word (as
                           determined by the database builder).
                           Word ends are not marked.
       
       
       The following codes allow control of style and colour.
       These codes may be nested, but setting a new text or
       background colour 'forgets' the previous one.  Other
       markup can appear between (for example) <BOLD> and
       <ENDBOLD>.  Colours and styles are advisory - the client
       can actually display them in whatever way it chooses (or
       is capable of).  The client should avoid doing unhelpful
       things like displaying blue text on a blue background.
       
       Markup Code  Value  Description
       
       <BOLD>         B    Start displaying emboldened text.
       <ENDBOLD>      b    End displaying emboldened text.
       <UNDERLINE>    U    Start displaying underlined text.
       <ENDUNDERLINE> u    End displaying underlined text.



                                   45

       <ITALIC>       I    Start displaying italic text.
       <ENDITALIC>    i    End displaying italic text.
       <REVERSE>      R    Start displaying reverse video text.
       <ENDREVERSE>   r    End displaying reverse video text.
       
       <BLACK>        0    Start displaying text in black.
       <RED>          1    Start displaying text in red.
       <GREEN>        2    Start displaying text in green.
       <BLUE>         4    Start displaying text in blue.
       <YELLOW>       3    Start displaying text in yellow.
       <CYAN>         6    Start displaying text in cyan.
       <PURPLE>       5    Start displaying text in purple.
       <WHITE>        7    Start displaying text in white.
       <NORMAL>       9    Revert to the client's default text
                           colour.
       
       <BACKGROUND>   K    Set the background colour. This markup
                           code is followed by one of the above
                           colours or <NORMAL>
       
       <LEFTJUST>     [    Display text left justified (default).
       <CENTRED>      ^    Display lines of text centred (for
                           headings).  This is only useful for
                           short lines.
       
       
       The following codes mark hits.  Hits can contain other
       markup, but it is not necessary for the server to specify
       that they be displayed in a particular style and colour -
       the client will decide how to display them.  Hits cannot
       be nested.
       
       Markup Code  Value  Description
       
       <HIT>          H     Marks the start of a hit.
       <ENDHIT>       h     Marks the end of a hit.
       
       
       The following codes mark section titles.  Section tiles
       can contain other markup, but it is not necessary for the
       server to specify that they be displayed in a particular
       style and colour - the client will decide how to display
       them.  Section titles cannot be nested.
       
       Markup Code  Value  Description
       
       <SECTIONTITLE> E    Marks the start of a section title.
       <ENDTITLE>     e    Marks the end of a section title.
       
       
       Examples
       
       Text with sentence and word starts marked:




                                   46

            <LI><SENTENCE><LI><WORD>The <LI><WORD>quick
            <LI><WORD>brown <LI><WORD>fox.
       
       Text with colour and style changes:
            <LI><BOLD>The <LI><RED>quick <LI><GREEN>green
            <LI><NORMAL>fox.<LI><ENDBOLD>
       
       A hit, with word starts marked:
            <LI><HIT><LI><WORD>ouch!<LI><ENDHIT>, <LI><WORD>that
            <LI><WORD>hurt!
       














































                                   47

10.    Table of Contents

       This section provides mechanisms for the client to
       navigate within the table of contents.
       
       The table of contents (TOC) is viewed as two hierarchies.
       Each entry in the first hierarchy describes a sub-set of
       the database (representing a range of absolute record
       numbers).  Each entry in the second hierarchy indicates a
       section within a record.
       
       A database need not have a table of contents, or need only
       implement one or other of the two possible hierarchies.


10.1   'Read Table of Contents' Request

       This request positions and/or reads the table of contents.
       
       POSITION contains one of the following values:
          1=position to the first TOC entry at the top level
          T=position TOC to TOCID specified
          A=position TOC to ABSREC and FLDABBREV specified
          U=go up one level from the current entry.  The parent
            of the current entry becomes the current entry
          D=go down one level from the current entry.  The first
            entry at the new level becomes the current entry
          F=position to the first entry at the current level
          L=position to the last entry at the current level
       
       DIRECTION contains one of the following values:
          N=return next entry(s) at the current level, until
            there are no more entries at this level; the first
            entry returned is the current entry; the current
            entry is advanced
          P=return previous entry(s) at the current level, or
            until there are no more entries at this level; the
            first entry returned is the entry immediately
            preceding the current entry; the current entry is
            backed up
       
       Within each response, entries are returned in the same
       order, irrespective of whether retrieving next or previous
       entries.
       
       
       Request Type:            DB_READTOC
       Keywords and values:
          * DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string)
            PO POSITION         see above; default = start from
                                current entry
            AC DIRECTION        see above; default = Next
            TI TOCID            ID of entry to position to



                                   48

            AR ABSREC           absolute record number to
                                position to
            FA FLDABBREV        field abbreviation to position
                                to; for a full-text field, #n
                                where n is the full-text field
                                number (starting from 256)
            MR MAXRECS          maximum no. of TOC entries to
                                return (default = as many as will
                                fit in one response)
       Info-list (1 or more records returned in response):
            I4  TI TOCID        ID of this TOC entry (for future
                                reference)
            1   HY HIERARCHY    D = entry represents a sub-set of
                                the database, R = entry
                                represents a section within a
                                record
            I1  LV LEVEL        Level within this hierarchy (1 =
                                top level)
            I4  FR FIRSTREC     if HIERARCHY=D, the first
                                absolute record number in the
                                sub-set of the database defined
                                by this entry; if HIERARCHY=R,
                                the record number pointed to by
                                this entry
            I4  LR LASTREC      if HIERARCHY=D, the last absolute
                                record number in the sub-set of
                                the database defined by this
                                entry
            9   FA FLDABBREV    if HIERARCHY=R, the field
                                abbreviation pointed to by this
                                entry
            ?   TX ENTRYTEXT    The text of this entry
       Noteworthy error returns:
            EC_MISSINGKW        if POSITION = A and ABSREC is
                                missing, or POSITION = T and
                                TOCID is missing
       
       If ABSREC and FLDABBREV are specified, the table of
       contents is positioned to the entry which points to that
       record and field, or the first preceding entry.
       
       If the client specifies MAXRECS, several responses may be
       returned, the last of which will have the 'request
       complete' flag set.  If the client does not specify
       MAXRECS, a single response will be returned with the
       'request complete' flag set.
       
       'More records available' is returned false when the last
       (or first if DIRECTION = P) entry is returned at the
       specified level.  If ABSREC is too large, a response
       containing zero records is returned.






                                   49

11.    Read-Only File Access

       This section describes a general purpose mechanism for the
       client to read text or binary files on the database
       server.
       
       All files on the server are identified by a 15 character
       tag.  These files are generally (but not necessarily),
       specific to an open database and the tag is hence local to
       that database.
       
       Reserved file tags (i.e. those with a pre-defined meaning
       specified by the standard) are preceded by a '#'; there
       are currently no such tags.  Vendor-unique reserved file
       tags should start with a '#', followed by the vendor
       prefix, e.g.
            #SP$MAGICFILE
       
       Text files are currently used for database-specific help
       text (see section 5.4).





































                                   50

11.1   'Get File Information' Request

       This request returns file size and update date
       information.
       
       Request Type:            DB_FILEINFO
       Keywords and values:
            DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string)
          * TG TAG              file tag
       Info-list (1 record returned in response):
            I4  FS FILESIZE     length of file (in bytes)
            I2  FD FILEDATE     last update date (days since
                                01/01/80)
            I2  FT FILETIME     last update time (pairs of
                                seconds since midnight)
       Notes:
          - If DBHANDLE is not specified, a non database-specific
            file is assumed (i.e. the file tag is valid
            independently of any database).  There are currently
            no such files.




































                                   51

11.2   'Open File' Request

       This request opens the specified file in the specified
       database.
       
       Request Type:            DB_OPENFILE
       Keywords and values:
            DH DBHANDLE         handle to an open database (as a
                                hex-ASCII string); default = non
                                database-specific file
          * FT FILETAG          file tag
            MO MODE             B = binary, L = text (line end
                                character = linefeed), C = text
                                (line end character = carriage
                                return)
       Info-list (1 record returned in response):
            I4  FH FILEHANDLE   4 byte handle to open file
            I4  FS FILESIZE     length of file (in bytes)
       Notes:
          - For files opened in text mode, line ends are marked
            with a a linefeed character (0x0A) or carriage return
            character (0x0C), depending on the value supplied for
            MODE.


































                                   52

11.3   'Close File' Request

       This request closes the specified file.
       
       Request Type:            DB_CLOSEFILE
       Keywords and values:
          * FH FILEHANDLE       handle to an open file (as a hex-
                                ASCII string)

















































                                   53

11.4   'Read File' Request

       This request reads data sequentially from the current file
       position.  It can also be used to change the current
       position in the file.
       
       Request Type:            DB_READFILE
       Keywords and values:
          * FH FILEHANDLE       handle to open file (as a hex-
                                ASCII string)
            SK SEEKTO           signed offset in file to seek to
                                (if specified)
            SH SEEKHOW          A = absolute (default), R =
                                relative to current position, E =
                                backwards from the end of the
                                file
            NB NBYTES           number of bytes to read (default
                                = as many as possible in a single
                                response)
            RA READAHEAD        number of bytes to read ahead (to
                                allow the server to cache data in
                                advance of the client taking it)
       Info-list (1 record returned in response):
            I4  FP FILEPOS      file position at end of read
            I2  NB NBYTES       number of bytes returned
            ?   DA DATA         the data read from the file
       Notes:
          - If the file was opened in text mode (section 11.2),
            several lines may be returned in a single response).
            A line may cross a response boundary.
          - If SEEKTO is not specified, data is read from the
            current file position.  Use this with NBYTES = 0 to
            determine the current file position.  Seeking past
            end of file is not an error, but will return end-of-
            file if any data is read.
          - Only one response is returned.  'More records
            available' is returned false at end-of-file.




















                                   54

A.     Message Summary

       Request             Section  Description
       
       Get Server Information 3.1   Returns information about the
                                    server on this connection.
       Login                  3.2   Logs this connection into the
                                    server with the specified
                                    username.
       Database List          4.1   Obtains a list of the
                                    databases available on this
                                    server.
       Open Database          4.2   Opens the specified database
       Close Database         4.3   Closes the specified
                                    database.
       Get Database Inform'n  5.1   Obtains information about the
                                    specified open database
       Get Field Information  5.2   Returns information about the
                                    specified field(s) and/or
                                    fieldsets.
       Get Stopwords          5.3   Returns stopwords for the
                                    specified database.
       Get Help Topics        5.4   Returns database-specific
                                    help topics.
       Get TOC-Level Name     5.5   Returns the names of the
                                    levels in the Table of
                                    Contents.
       Read Index             6.1   Retrieves terms from the
                                    specified index.
       Map Search Terms       6.3   Converts the pattern(s)
                                    supplied into the form in
                                    which they are looked up in
                                    the index (and hence searched
                                    for).
       Create Cursor          7.1   Creates a new cursor.
       Delete Cursor          7.2   Deletes an existing cursor.
       Execute Search         8.1   Submits a search request to
                                    the server.
       Discard Search         8.2   Informs the server that a
                                    previously submitted search
                                    request is unlikely to be
                                    needed again.
       Sort Current Search    8.3   Asks the server to sort (or
                                    re-sort) the current search
                                    for the specified cursor.
       Progress               8.6   Sent periodically from the
                                    server to the client while a
                                    search is in progress.
       Read Data              9.1   Positions the specified
                                    cursor to the specified
                                    record and field and/or reads
                                    data from the current record.
       Get Hits               9.2   Positions the cursor to the
                                    specified record (and field,



                                   55

                                    if specified) and returns
                                    binary data representing the
                                    position of the hits in that
                                    record (or field).
       Set Hits               9.3   Supplies hits in the
                                    specified record or field to
                                    the server, so that hits will
                                    be marked up correctly by the
                                    server when record data is
                                    subsequently requested.
       Read Table of Contents 10.1  Positions and/or reads the
                                    table of contents.
       Get File Information   11.1  Returns file size and update
                                    date information.
       Open File              11.2  Opens the specified file in
                                    the specified database.
       Close File             11.3  Closes the specified file.
       Read File              11.4  Reads data sequentially from
                                    the current file position.
                                    Can also be used to change
                                    the current position in the
                                    file.



































                                   56

B.     Example Message Sequence

       This section contains a sequence of messages which:
          - request information of the databse server
          - log in to the database server
          - request a list of databases
          - open a database
          - read database and field information
          - show some help text
          - show part of the title index, starting at DECORATING
          - perform a search
          - show some of the results
          - close the database
       
       Comments follow '//'; these do not form part of the
       messages.
       
       Note that all possible keywords are shown in the requests,
       and all possible info-list items are shown in the
       responses.  In practise, the requester supplies only those
       keywords for which the default value needs to be
       overridden, and the responder only returns the info-list
       items that the requester asked for.
       
       Note also that the keywords identifying the info-list
       items are not actually returned in the responses; they are
       shown in the examples for clarity.
       
       It is recommended that this section be read in conjunction
       with the definitions of the appropriate request types.
       
       
       Request: 'Get Server Information'
            PREFIX=ABC$         // client's vendor prefix
            MARKUPVERSION=1     // client's max. markup version
            
       Response (record 1 of 1):
            SERVERID=ACM$PUBLIC1
            SERVERNAME=Public 1
            SERVERTYPE=1
            SERVERDESC=Acme Database Server GTi 16v
            PREFIX=ACM$         // server's vendor prefix
            VERSION=100
            LOGINREQ=1          // must login
            NDBS=2              // two databases available
       
       
       Request: 'Login'
            USERNAME=JMajor
            PASSWORD=A3DF19CC   // Encrypted
       
       
       
       Request: 'Database List'



                                   57

            FIRST=1
            MAXRECS=9999
       Response (record 1 of 2):
            DBID=SZ$BBANK
            DBNAME=BookBank
            IPNAME=J. Whitaker and Sons Ltd.
            PUBLISHER=J. Whitaker and Sons Ltd.
            DETAILS=Contains more than 500,000 books in print ...
            
       Response (record 2 of 2):
            DBID=MVD$FAME
            DBNAME=FAME - Financial Analysis Made Easy
            IPNAME=Jordan and Sons
            PUBLISHER=Bureau Marcel van Dijk
            DBDETAIL=Contains reports and accounts of 75,000 ...
            
       
       
       Request: 'Open Database'
            DBID=SZ$BBANK
       Response (record 1 of 1):
            DBHANDLE=1
       
       
       Request: 'Get Database Information'
            DBHANDLE=1
       Response (record 1 of 1):
            DBID=SZ$BBANK
            DBNAME=BookBank
            IPNAME=J. Whitaker and Sons Ltd.
            PUBLISHER=J. Whitaker and Sons Ltd.
            DETAILS=Contains more than 500,000 books in print ...
            COPYRIGHT=Data Copyright (c) J. Whittaker and Sons...
            SRECNAME=Record
            PRECNAME=Records
            SFLDNAME=Field
            PFLDAME=Fields
            RFNAME=
            NFLDS=10            // for example
            NRECS=500000
            MAXCURSORS=1
            RECORDS=0
            FNEAR=1
            RTRUNC=1
            LTRUNC=0
            WILDCARDS=1
            CASESENS=0
            FREETEXT=*A
            SNEAR=0
            WNEAR=0
            WSEQ=0
            MARKHITS=1
            TOC=1
            RELEVANCE=0



                                   58

            RELSORT=0
            FLDSORT=0
            INACTIVITY=10
            MAXSESSION=0
            CANPRINT=1
            CANDOWNLOAD=1
            SHOWDFLT=TI,AU,PU
            PRINTDFLT=*A
            DNLOADDFLT=*A
            
       
       
       Request: 'Get Field Information'
            DBHANDLE=1
            FIRST=1
            MAXRECS=9999
       Response (record 1 of 11):
            FLDTYPE=S           // Fieldset
            FLDABBREV=CITN
            SHOWABBREV=CITN
            FLDNAME=Citation
            INDENT=0            ; display at left margin
            HELPTAG=HELP_CITN
            HIDDEN=0
            DISPLAY=0
            FULLTEXT=0
            SEARCH=1
            FLDSEARCH=1
            SNEAR=0
            WNEAR=0
            WSEQ=0
            ALPHA=1
            NUMBERS=1
            NORMALISED=0
            INTEGER=0
            IXSTOPW=0
            INDEX=0
            UNIVERSAL=0
            
       Response (record 2 of 11):
            FLDTYPE=F
            FLDABBREV=TI
            SHOWABBREV=TITLE
            FLDNAME=Title
            INDENT=1            ; display indented under CITN
            HELPTAG=HELP_TI
            HIDDEN=0
            DISPLAY=1
            FULLTEXT=0
            SEARCH=1
            FLDSEARCH=1
            SNEAR=0
            WNEAR=0
            WSEQ=0



                                   59

            ALPHA=1
            NUMBERS=1
            NORMALISED=0
            INTEGER=0
            IXSTOPW=0
            INDEX=1
            UNIVERSAL=0
            
       Response (record 3 of 11):
            FLDTYPE=F
            FLDABBREV=AU
            SHOWABBREV=AUTHOR
            FLDNAME=Author
            INDENT=1            ; display indented under CITN
            HELPTAG=HELP_AU
                 .
                 .
       Response (record 4 of 11):
            FLDTYPE=F
            FLDABBREV=PU
            SHOWABBREV=PUBL
            FLDNAME=Publisher
            INDENT=0            ; display at left margin
            HELPTAG=HELP_PU
                 .
                 .
       
            .
            .
       
       
       Request: 'Open File'     // Open help file for TI field
            DBHANDLE=1
            FILETAG=HELP_TI
            MODE=L              // Text file, line-end = LF
       Response (record 1 of 1):
            FILEHANDLE=1
            FILESIZE=nnn
       
       
       Request: 'Read File'     // Read start of help text
            FILEHANDLE=1
            SEEKTO=0
            SEEKHOW=A
            NBYTES=             // Return 1 response
            READAHEAD=          // No read-ahead
       Response (record 1 of 1):
            FILEPOS=978         // Assuming 978 bytes read
            NBYTES=978
            DATA=Help on Title Field (TI) ...
       
       
       Request: 'Close File'    // Close help file
            FILEHANDLE=1



                                   60

       Response:
            none
       
       Request: 'Read Index'
            DBHANDLE=1
            FLDABBREV=TI        // Title index
            POSITION=G
            DIRECTION=N
            PATTERN=*           // match all index entries
            TERM=DECORATING*    // go to >= DECORATING
            MAXRECS=            // return as many records as will
                                // fit in one response
       Response (record 1 of n):
            TERM=Decorating for Beginners
            NHITS=              // no. of occurences unavailable
            NRECS=1
       Response (record 2 of n):
            TERM=Decorating for Experts
            NHITS=
            NRECS=1
            .
            .
       
       
       Request: 'Create Cursor'
            DBHANDLE=1
       Response (record 1 of 1):
            CURSOR=1
       
       
       Request: 'Execute Search'
            CURSOR=1
            SEARCHREQ=AND("BRAINS","BEAUTY")
            SORTFIELDS=
       Response (record 1 of 1):
            BROADENED=0
            NHITS=4
            NRECS=2
       
       
       Request: 'Read Data'
            CURSOR=1
            PURPOSE=S
            POSITION=R          // position by relative record
            DIRECTION=N
            ABSREC=
            RELREC=1            // retrieve first hit record
            TOCID=
            FLDLIST=*A
            SORT=0
            FLDABBREV=
            STARTOFFSET=
            MARKUPLEVEL=H       // mark hits in retrieved data
            NONDISPLAYABLE=0



                                   61

            MAXRECS=            // return 1 response
            MAXFLDS=
            
       Response (record 1 of 3):
            ABSREC=12998
            RELREC=1
            RHITS=2             // number of hits in this record
            FLDABBREV=TI        // this is the Title field
            SHOWABBREV=TITLE
            FLDNAME=Title
            FHITS=2             // number of hits in this field
            RELEVANCE=          // no relevance info available
            STARTOFFSET=0       // at start of field
            ENDOFFSET=39
            MORE=1              // more to come in this record
            DATA=Beauty and Brains: My Two Best Features
       Response (record 2 of 3):
            ABSREC=12998
            RELREC=1
            RHITS=2
            FLDABBREV=AU        // this is the Author field
            SHOWABBREV=AUTHOR
            FLDNAME=Author
            FHITS=0
            RELEVANCE=
            STARTOFFSET=0       // at start of field
            ENDOFFSET=15
            MORE=0              // no more to come in this record
                                // this one contains TI, AU only
            DATA=Frank N. Steinsmonster
       Response (record 3 of 3):
            ABSREC=17223
            RELREC=2
            RHITS=2
            FLDABBREV=TI
            SHOWABBREV=TITLE
            FLDNAME=Title
            FHITS=2
            RELEVANCE=
            STARTOFFSET=0
            ENDOFFSET=36
            MORE=2              // more to come in this field
            DATA=Beauty and Brains: Problems in Surgi
       
       Request: 'Read Data'     // read more data
            CURSOR=1
            PURPOSE=S
            POSITION=           // read from current position
            DIRECTION=N
            ABSREC=
            RELREC=
            TOCID=
            FLDLIST=            // use current field list
            SORT=0



                                   62

            FLDABBREV=
            STARTOFFSET=
            MARKUPLEVEL=H       // mark hits in retrieved data
            NONDISPLAYABLE=0
            MAXRECS=            // return 1 response
            MAXFLDS=
            
       Response (record 1 of n):
            ABSREC=17223
            RELREC=2
            RHITS=2
            FLDABBREV=TI
            SHOWABBREV=TITLE
            FLDNAME=Title
            FHITS=2
            RELEVANCE=
            STARTOFFSET=40
            ENDOFFSET=72
            MORE=1              // more to come in this record
            DATA=cal Procedures and How to Avoid Them
            .
            .
       
       
       Request: 'Close Database'
            DBHANDLE=1
       Response:
            none





























                                   63

C.     Algorithms and Code Fragments



C.1    Password Encryption

       The password encryption algorithm is as follows:
       
            long encrypt (char *password)
            {
                 static int multiplier [8] =
                      { 0x1081, 0x2102, 0x3183, 0x4204,
                        0x5285, 0x6306, 0x7387, 0x8408 };
                 long l;
                 int  i;
                 int  c;
            
                 l = 0;
                 for (i = 0; i < strlen (password); ++i)
                 {
                      c = toupper (password [i]);
                      l += (long) c * (long) multiplier [i % 8];
                 }
                 return l;
        }
































                                   64

D.     Well Known Identifiers

       The following request and response types are currently
       defined for the database server protocol:
       
       Request types:
         0..255                 reserved
         256 - DB_SRVRINFO      'Get Server Information' Request
         257 - DB_LOGIN         'Login' Request
         258 - DB_FILEINFO      'Get File Information' Request
         259 - DB_OPENFILE      'Open File' Request
         260 - DB_CLOSEFILE     'Close File' Request
         261 - DB_READFILE      'Read File' Request
         262 - DB_DBLIST        'Database List' Request
         263 - DB_OPENDB        'Open Database' Request
         264 - DB_CLOSEDB       'Close Database' Request
         265 - DB_DBINFO        'Get Database Information' Req
         266 - DB_FLDINFO       'Get Field Information' Request
         267 - DB_FLDSET        'Get FieldSet Information' Req
         268 - DB_STOPWORD      'Get Stopwords' Request
         269 - DB_HELPTOPIC     'Get Help Topics' Request
         270 - DB_TLNAME        'Get TOC-Level Name' Request
         271 - DB_READIX        'Read Index' Request
         272 - DB_MAPTERMS      'Map Search Terms' Request
         273 - DB_SEARCH        'Execute Search' Request
         274 - DB_KILLSEARCH    'Discard Search' Request
         275 - DB_SORT          'Sort Current Search' Request
         276 - DB_SUBSET        'Set Subset' Request
         277 - DB_PROGRESS      'Progress' Request
         278 - DB_CURSOR        'Create Cursor' Request
         279 - DB_DELCURSOR     'Delete Cursor' Request
         280 - DB_READDATA      'Read Data' Request
         281 - DB_GETHITS       'Get Hits' Request
         282 - DB_SETHITS       'Set Hits' Request
         283 - DB_READTOC       'Read Table of Contents' Request
         284..9999              reserved
         10000..32767           vendor-unique request types
       
       
       
       
                            oooOOOooo















                                   65
