
The is the "ReadMe" for NameMch.DLL only. For general information about the
application and registration, see ReadMe.txt.

The information here applies to a Pascal call to NameMch.DLL via CallNamM.
For the DELPHI application call, see ReadMe.txt and other information
provided by Richard Curzon.  This upload is a collaboration between
Paul Onstand and Richard Curzon.
-----------------------------------------------
For additional information, contact:

	Paul W. Onstad
	PRIORI Systems
	10168 Parrish Ave NE
	Elk River, MN 55330

	CompuServe: 70641,3236 / Internet:70641.3236@compuserve.com

This software can be registered through CompuServe's software registration
service, SWREG.  #10470 price $35.00 US. per installation.  Please
contact for rates for more than one installation.

Quick-Start
===========
Put all files in a clean directory. Run CallNamM.exe.


NameMch.DLL
===========

NameMch is a name matching DLL that can be used in applications such
as on-line inquiry systems where only a text name (perhaps of uncertain
spelling or structure) is provided to locate a particular data record.
Reservation systems and telephone number lookups are a couple of
examples. Called by a database, NameMch can also be used to clean up
name fields in almost any DB application that is able to call a DLL.

When a match of a name to a known name is uncertain, NameMch will
pass back up to 20 candidate names and assign the first (the closest
match) a certainty score from 0 to 10. Generally, scores below 7 or
8 should be posed to a human operator who can select the one best name
from the list of candidate names. The sample program CallNamM.exe is a
very simple implementation of this decision-making process.

NameMch was designed to be used to match names of individuals. However
the maximum length string for a single name is 255 characters and thus
could have other applications.


Running CallNamM.exe Demo of NameMch.dll
========================================

For simplicity, file names are coded in the demo program so that the
EXE and sample files must be located in a single directory. Any clean
directory can be used. Two text files will be read, one containing
trial names and the other, proof or candidate names. A third file
will then be output, containing the matched names.

   Put the following files in a clean directory

   NameMch.dll	    (later the DLL can be moved to the system directory)
   CallNamM.exe
   Proof.txt
   Trial.txt

   Run CallNamM.exe (enter numbers from 1 to 5 to select names)

   MtchTest.txt     (will be created--open it with any text editor)

---------------
Also included is CallNamM.pas, the Pascal source for CallNamM.exe
=========================================================================
Definitions:

	Proof names		a list of names known to be correct

	Trial names		names taken one at a time and compared
				against proof names

	Certainty		a score evaluating the "sureness" of
				match between a proof and trial name

There are two options to load proof names. In the simpliest case, they
can be read from a text file (option InitLoad) by passing the file name
as a parameter. A second option (InitItem) is called repeatedly for
each proof name. It is used in cases when the proof names may be coming
from a pre-existing source such as a database.

=========================================================================
I-A.	Option InitLoad		Reads proof-names from a text file

	Call InitLoad
		MemHdl		a returned integer
		MaxDisp		max names to display in cases of
				uncertainty
		FlName		file name of a text file containing proof
				names
		ErrRtn		zero if successful
----------------------- * OR * ------------------------------------------
I-B.	Option InitItem		Called repeatedly. Passed one proof name
				at a time

	Call InitItem
		MemHdl		returned and passed integer
		MaxDisp		max names to display in cases of
				uncertainty
		ProofName	the current proof name
		ErrRtn		zero if successful
=========================================================================
II.	Call PerformMatch	Called once for each match of a trial
				name against a proof name

		MemHdl		passed integer
		TrialName	the current name being matched to proofs
		Certainty	the results of the match rated from
				0 to 10 -- 10 being the most certain
		NumResults	the number of proof names being passed
				back -- from 1 to MaxDisp
		ProofArry	an array holding NumResults proof names.
				The first array item is the most certain
		ErrRtn		zero if successful
=========================================================================
III.	Call DestroyMatch	Destroys structures and releases memory
				used by the DLL

		MemHdl		passed integer
		ErrRtn		zero if successful
=========================================================================

Variable Usage
                    	Description	Pascal		C
			--------------  --------------- -------
	MemHdl		integer		var THandle	LPInt
	MaxDisp		integer		integer		Int
	FlName		string		PChar		LPStr
	ErrRtn		integer		var integer	LPInt
	ProofName	string		PChar		LPStr
	TrialName	string		PChar		LPStr
	Certainty	integer		var integer	LPInt
	NumResults	integer		var integer	LPInt
	ProofArry	string array	array [1..20]	LPStr [20]
					of PChar

	MemHdl should be intialized to zero before first use
	ProofArry is an array of 20 strings
	all strings null terminated
	all integers 2-byte signed

Supplied Variables
	MemHdl		0		initialized to zero once, before
					first usage
	MaxDisp 	[1 to 20]	number of name strings to be passed
					back in cases of uncertainty
	FlName 		DOS file name	Name of text file containing
					proof names. The file name can be
					full or partial (partial if in
					the executing directory)
	ProofName	length<=255	required for each InitItem call
					(not necessary if calling
					InitLoad)
	TrialName	length<=255	required for each PerformMatch
					call
Returned Variables

	MemHdl				Do not alter value after 1st call
	ErrRtn				A three-digit error code passed
					back only if Call function is false
	Certainty	[1 to 10]	Sureness rating from PerformMatch
	NumResults	[1 to MaxDisp]	Number of proof strings being
					passed back. More than one in
					cases of uncertainty
	ProofArry	array of null	The array should be set up as a
			terminated 	variable in the calling program:
			strings		Pascal: array [1..20] of PChar
			[1 to 20]	C     : LPStr varname [20]
					The actual strings are allocated
					and disposed by the PerformMatch
					rountines

Limits

	MaxDisp <= 20
	all strings <= 255 characters
	maximum of 16000 proof names

Error Codes passed back in ErrRtn

	101		Memory error, failed GlobalAlloc or GlobalLock
	102		File of proof names specified by name to InitLoad
			could not be opened or read
	103		File of proof names contained no data
	104		MemHdl was not ititialized to zero before the
			first call to InitItem
        105		More than 16000 proof names
	106		PerformMatch was passed an empty string


PASCAL DEFINITIONS OF CALLS

TYPE
   ProofStrings     = array [1..20] of PChar;

FUNCTION INITLOAD     (VAR MEMHDL:THANDLE;MaxDisp:integer;
		      FlName:PChar;VAR ErrRtn:integer):LONGBOOL;
		      FAR;EXTERNAL
            'NAMEMCH' INDEX 1;
FUNCTION INITITEM     (VAR MEMHDL:THANDLE;MaxDisp:integer;
                      ProofName:PChar;VAR ErrRtn:integer):LONGBOOL;
                      FAR;EXTERNAL
            'NAMEMCH' INDEX 2;
FUNCTION PERFORMMATCH (VAR MEMHDL:THANDLE;Trial:PChar;
                      VAR Certainty:integer;VAR NumResults:integer;
                      VAR ProofArry:ProofStrings;
                      VAR ErrRtn:integer):LONGBOOL;FAR;EXTERNAL
            'NAMEMCH' INDEX 3;
FUNCTION DESTROYMATCH (VAR MEMHDL:THANDLE;
                      VAR ErrRtn:integer):LONGBOOL;FAR;EXTERNAL
            'NAMEMCH' INDEX 4;


SAMPLE PASCAL CODE (all strings are PChar with maximum length of 255)

  TYPE
     ProofStrings	= array [1..20] of PChar;

  VAR
     ProofArry                             : ProofStrings;
     MemHdl                                : THandle;
     ErrRtn,Certainty,NumResults           : integer;
     FlName,TrialName                      : PChar;

  (* Text file Option - InitLoad *)

  FlName:='Proof.txt';
  TrialName:='John Doe';
  MemHdl:=0;
  if not InitLoad(MemHdl,5,FlName,ErrRtn) then MyErrorHalt(ErrRtn);
  if not PerformMatch(MemHdl,TrialName,Certainty,NumResults,
                      ProofArry,ErrRtn)   then MyErrorHalt(ErrRtn);
  for N:=1 to NumResults do
     Writeln(TrialName,ProofArry[N],Certainty);
  if not DestroyMatch(MemHdl,ErrRtn)      then MyErrorHalt(ErrRtn);

  (* InitItem Option *)

  VAR
     ProofName         : PChar;
     chararray         : array [0..255] of char;
     TextFile          : text;

  ProofName:=chararray;
  MemHdl:=0;
  repeat
     Read(TextFile,chararray);
     if not ItitItem(MemHdl,5,ProofName,ErrRtn) then MyErrorHalt(ErrRtn);
  until EOF(TextFile);
  TrialName:='John Doe';
  if not PerformMatch(MemHdl,TrialName,Certainty,NumResults,
                      ProofArry,ErrRtn)   then MyErrorHalt(ErrRtn);
  for N:=1 to NumResults do
     Writeln(TrialName,ProofArry[N],Certainty);
  if not DestroyMatch(MemHdl,ErrRtn)      then MyErrorHalt(ErrRtn);

*end*







