Summary

###########################################################################

	File:     gettext.icn

	Subject:  Procedures for gettext (simple text-base routines)

	Author:   Richard L. Goerwitz

	Date:     May 2, 2001

###########################################################################

   This file is in the public domain.

###########################################################################

  History:
       Version 1.19: December 28, 1993 (plt)
            Tested with DOS, DOS-386, OS/2, ProIcon, UNIX
            Modified link and OS statements.
            Open index file in untranslated mode for
              MS-DOS and OS/2 -- ignored by UNIX and Amiga
            Handle multiple, indexed citations.
            Change delimiter from <TAB> to char(255).
            Simplified binary search. 
        Version 1.20: August 5, 1995 (plt)
            Replace link statement with preprocessor include.
            Retrieve text for multiple keys on the same line.
            Correct debug printout of indexed and sequential
              search values.

###########################################################################

  Version:  1.19   December 28, 1993 - Phillip Lee Thomas
  Version:  1.20   August 5, 1995    - plt

###########################################################################

  Gettext() and associated routines allow the user to maintain a file
  of KEY/value combinations such that a call to gettext(KEY, FNAME)
  will produce value.  Gettext() fails if no such KEY exists.
  Returns an empty string if the key exists, but has no associated
  value in the file, FNAME.

  The file format is simple.  Keys belong on separate lines, marked
  as such by an initial colon+colon (::).  Values begin on the line
  following their respective keys, and extend up to the next
  colon+colon-initial line or EOF.  E.g.

    ::sample.1
 or:
    ::sample.1  ::sample.2

    Notice how the key above, sample.1, has :: prepended to mark it
    out as a key.  The text you are now reading represents that key's
    value.  To retrieve this text, you would call gettext() with the
    name of the key passed as its first argument, and the name of the
    file in which this text is stored as its second argument (as in
    gettext("sample.1","tmp.idx")).
    ::next.key
    etc...

  For faster access, an indexing utility is included, idxtext.  Idxtext
  creates a separate index for a given text-base file.  If an index file
  exists in the same directory as FNAME, gettext() will make use of it.
  The index becomes worthwhile (at least on my system) after the text-
  base file becomes longer than 5 kilobytes.

  Donts:
      1) Don't nest gettext text-base files.
      2) In searches, surround phrases with spaces or tabs in
        key names with quotation marks:   "an example"
      3) Don't modify indexed files in any way other than to append
         additional keys/values (unless you want to re-index).

  This program is intended for situations where keys tend to have
  very large values, and use of an Icon table structure would be
  unwieldy.

  BUGS:  Gettext() relies on the Icon runtime system and the OS to
  make sure the last text/index file it opens gets closed.

###########################################################################

  Links:  adjuncts

###########################################################################

         Invoke set_OS() before first call to gettext() or
           sequential_search()

  Tested with UNIX, OS/2, DOS, DOS-386, ProIcon

###########################################################################

This file is part of the (main) package.

get_offsets(KEY, inidx)

: binary search of index

gettext(KEY, FNAME)

: search database by indexed term

sequential_search(KEY, intext)

: brute-force database search