                LinguaLinks AMPLE DLL Reference Manual
          functions for morphological parsing in LinguaLinks
                based on AMPLE functions version 3.2.1
                             October 1998

                          by Stephen McConnel

                 Copyright (C) 2000 SIL International

Published by:
Language Software Development
SIL International
7500 W. Camp Wisdom Road
Dallas, TX 75236
U.S.A.
Permission is granted to make and distribute verbatim copies of this
file provided the copyright notice and this permission notice are
preserved in all copies.

The author may be reached at the address above or via email as
`steve@acadcomp.sil.org'.

Introduction to the LinguaLinks AMPLE DLL
*****************************************

Since it was released in 1988, the AMPLE program has been used for
morphological analysis in many different languages.  It has always
functioned as a batch processing program, which is useful for
production work such as analyzing an entire book, but is less useful
during the early stages of developing a morphological description.  The
LinguaLinks AMPLE DLL has therefore been developed with the goal of
making it possible to embed AMPLE style morphological parsing into
LinguaLinks.

The LinguaLinks AMPLE DLL is built with the AMPLE function library.
See Introduction (amplelib.info).  For maximum usefulness, it is
a Win32 DLL, not a Win16 (Microsoft Windows 3.x) DLL.  It is compiled
for an 80386 or better CPU, and is compatible with Microsoft Windows
NT, Windows 95, and `WIN32S.DLL' for Windows 3.x.

This manual, and the DLL it documents, are still being revised.

LinguaLinks AMPLE DLL functions
*******************************

The LinguaLinks AMPLE DLL functions all return a character string.
This string contains either a value dependent on the function or an
error message.  The arguments to these functions, which vary in number
from zero to four, are also all character strings.

(This is, of course, subject to negotiation and change.)

AmpleAddSelectiveAnalysisMorphs
===============================

Syntax
------

     DllExport char * AmpleAddSelectiveAnalysisMorphs(
                             const char * pszMorphs_in)

Description
-----------

`AmpleAddSelectiveAnalysisMorphs' adds one or more morphnames to the
existing list of morphnames for selective analysis.  It may be called
once or more than once to build up the list of morphnames.

`AmpleAddSelectiveAnalysisMorphs' is an alternative to
`AmpleSetParameter('`"SelectiveAnalysisFile",' `filename)'.  It erases
any filename stored for the `SelectiveAnalysisFile' parameter, but does
not erase any morphnames already in the list for selective analysis.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleAddSelectiveAnalysisMorphs;
     char *		pszResult;
     ...
     char            szNewEntry[] = "\
     \\m mateo\n\
     \\t root\n\
     \\c N0\n\
     \\a mateo {Matthew_1}\n\
     \\a mateu {Matthew_2}\n\
     \\a matei {Matthew_3}\n\
     ";
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleAddSelectiveAnalysisMorphs =
                     (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                     "AmpleAddSelectiveAnalysisMorphs");
         if (pfAmpleAddSelectiveAnalysisMorphs == NULL)
             {
             MessageBox(0,
         "Cannot find AmpleAddSelectiveAnalysisMorphs in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleAddSelectiveAnalysisMorphs != NULL)
         {
         pszResult = (*pfAmpleAddSelectiveAnalysisMorphs)(szNewEntry);
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleAddSelectiveAnalysisMorphs = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleGetParameter
=================

Syntax
------

     DllExport char * AmpleGetParameter(
                             const char * pszName_in)

Description
-----------

`AmpleGetParameter' retrieves the value of a LinguaLinks AMPLE DLL
parameter (global variable).  The following parameter names are
recognized.

`AppendLogFile'
     determines whether a new log file is created, or an old log file is
     added to.

`BeginComment'
     corresponds to the AMPLE program's `-c' command line option.

`DebugAllomorphConds'
     corresponds to the AMPLE program's `-a' command line option.

`DebugLevel'
     corresponds to the AMPLE program's `-/' command line option.

`LogFile'
     corresponds to redirecting the standard output from the AMPLE
     program.  (This retrieves the file name.)

`MaxMorphnameLength'
     corresponds to the AMPLE program's `-n' command line option.

`MaxTrieDepth'
     corresponds to the AMPLE program's `-d' command line option.

`OutputStyle'
     determines the style of output produced by `AmpleParseFile'.  The
     possible values are `Ana' (for the normal standard output analysis
     file), `AResult' (for SGML output similar to that produced by
     `AmpleParseText'), and `Ptext' (for SGML output according to the
     `ptext.dtd' document type definition).  (`Ptext' is not yet
     implemented.)  The default style is `Ana'.

`RootGlosses'
     corresponds to the AMPLE program's `-g' command line option.

`SelectiveAnalysisFile'
     corresponds to the AMPLE program's `-s' command line option.
     (This retrieves the file name.)

`TraceAnalysis'
     corresponds to the AMPLE program's `-t' command line option.

Note that the parameter names are not case sensitive, even though they
are shown here in a mixture of uppercase and lowercase.

Return Value
------------

a string indicating the parameter value, or an error message

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleGetParameter;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleGetParameter = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                     "AmpleGetParameter");
         if (pfAmpleGetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleGetParameter in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleGetParameter != NULL)
         {
         pszResult = (*pfAmpleGetParameter)("MaxTrieDepth");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib           = 0;
         pfAmpleGetParameter = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleLoadControlFiles
=====================

Syntax
------

     DllExport char * AmpleLoadControlFiles(
                             const char * pszAnalysisDataFile_in,
                             const char * pszDictCodeTable_in,
                             const char * pszDictOrthoChangeTable_in,
                             const char * pszTextInputControlFile_in)

Description
-----------

`AmpleLoadControlFiles' loads the indicated control files into memory.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC4)(const char *,
                                            const char *,
                                            const char *,
                                            const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC4	pfAmpleLoadControlFiles;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleLoadControlFiles = (AMPLEFUNC4)GetProcAddress(hAmpleLib,
                                                 "AmpleLoadControlFiles");
         if (pfAmpleLoadControlFiles == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadControlFiles in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleLoadControlFiles != NULL)
         {
         pszResult = (*pfAmpleLoadControlFiles)("D:/HG/HGAD01.CTL",
                                                "D:/HG/HGANCD.TAB",
                                                NULL,
                                                "D:/HG/HGINTX.CTL");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib               = 0;
         pfAmpleLoadControlFiles = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleLoadDictionary
===================

Syntax
------

     DllExport char * AmpleLoadDictionary(
                             const char * pszFilePath_in)

Description
-----------

`AmpleLoadDictionary' loads the indicated (unified) AMPLE dictionary
file into memory.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleLoadDictionary;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleLoadDictionary = (AMPLEFUNC1)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadDictionary");
         if (pfAmpleLoadDictionary == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadDictionary in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleLoadDictionary != NULL)
         {
         pszResult = (*pfAmpleLoadDictionary)("D:/HG/HGMORPH.DIC");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib             = 0;
         pfAmpleLoadDictionary = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleParseFile
==============

Syntax
------

     DllExport char * AmpleParseFile(
                             const char * pszInFilePath_in,
                             const char * pszOutFilePath_in)

Description
-----------

`AmpleParseFile' parses an input text file, producing an output
analysis file.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC2)(const char *,
                                            const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC2	pfAmpleParseFile;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleParseFile = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleParseFile");
         if (pfAmpleParseFile == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseFile in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleParseFile != NULL)
         {
         pszResult = (*pfAmpleParseFile)("D:/HG/HGMT05.TXT",
                                         "D:/HG/HGMT05.SGM");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib        = 0;
         pfAmpleParseFile = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleParseText
==============

Syntax
------

     DllExport char * AmpleParseText(
                             const char * pszInputText_in)

Description
-----------

`AmpleParseText' parses the words in the input string.  If the string
contains only one word, then that word is parsed, obviating the need
for a separate `AmpleParseWord' function.

The parse output follows the simple SGML style format given by the
following "document type definition".  (The parse output is not quite
SGML because it does not begin with a DOCTYPE declaration and it does
not quote attribute values even when needed.)

     <!ELEMENT AResult - - ((error | parse)*) >

     <!ELEMENT error - - (#PCDATA) >
     <!ATTLIST error code (analysisFailure | rootFailure) #REQUIRED >

     <!ELEMENT parse - - (analysis*) >
     <!ATTLIST parse id CDATA #REQUIRED >

     <!ELEMENT analysis - - (morph*) >
     <!ATTLIST analysis cat CDATA #REQUIRED >

     <!ELEMENT morph - O EMPTY >
     <!ATTLIST morph id   CDATA #REQUIRED
                     allo CDATA #REQUIRED >

Return Value
------------

a string containing either the parse output or an error message

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleParseText;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleParseText = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                       "AmpleParseText");
         if (pfAmpleParseText == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseText in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleParseText != NULL)
         {
         pszResult = (*pfAmpleParseText)(
             "Chayta rikar loomaman wicharkur hamakuykuran yachachinanpaq.");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib        = 0;
         pfAmpleParseText = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleRemoveSelectiveAnalysisMorphs
==================================

Syntax
------

     DllExport char * AmpleRemoveSelectiveAnalysisMorphs()

Description
-----------

`AmpleRemoveSelectiveAnalysisMorphs' erases any existing list of
morphnames for selective analysis.  It also erases any filename stored
for the `SelectiveAnalysisFile' parameter.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC0)(void);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC0	pfAmpleRemoveSelectiveAnalysisMorphs;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleRemoveSelectiveAnalysisMorphs =
                     (AMPLEFUNC0)GetProcAddress(hAmpleLib,
                                   "AmpleRemoveSelectiveAnalysisMorphs");
         if (pfAmpleRemoveSelectiveAnalysisMorphs == NULL)
             {
             MessageBox(0,
         "Cannot find AmpleRemoveSelectiveAnalysisMorphs in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleRemoveSelectiveAnalysisMorphs != NULL)
         {
         pszResult = (*pfAmpleRemoveSelectiveAnalysisMorphs)();
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib    = 0;
         pfAmpleRemoveSelectiveAnalysisMorphs = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleReset
==========

Syntax
------

     DllExport char * AmpleReset()

Description
-----------

`AmpleReset' removes all control and dictionary information from
memory, and restores all internal settings to their default values.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC0)(void);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC0	pfAmpleReset;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleReset = (AMPLEFUNC0)GetProcAddress(hAmpleLib,
                                                   "AmpleReset");
         if (pfAmpleReset == NULL)
             {
             MessageBox(0, "Cannot find AmpleReset in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleReset != NULL)
         {
         pszResult = (*pfAmpleReset)();
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib    = 0;
         pfAmpleReset = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleSetParameter
=================

Syntax
------

     DllExport char * AmpleSetParameter(
                             const char * pszName_in,
                             const char * pszValue_in)

Description
-----------

`AmpleSetParameter' sets the value of a LinguaLinks AMPLE DLL parameter
(global variable).  The following parameter names are recognized.  If
`pszValue_in' is `NULL', the parameter is set to its default value.

`AppendLogFile'
     determines whether a new log file is created, or an old log file is
     added to.  Possible values are `"TRUE"' (or `"T"') and `"FALSE"'
     (or `"F"').  The default value is `"FALSE"'.

`BeginComment'
     corresponds to the AMPLE program's `-c' command line option.  The
     first nonspace character in the value string is used for the new
     comment character.  The default value is `"|"'.  If the value
     string does not contain any nonspace characters, then nothing can
     mark comments in the input files.

`DebugAllomorphConds'
     corresponds to the AMPLE program's `-a' command line option.
     Possible values are `"TRUE"' (or `"T"') and `"FALSE"' (or `"F"').
     The default value is `"FALSE"'.

`DebugLevel'
     corresponds to the AMPLE program's `-/' command line option.
     Possible values are positive integers (encoded as ASCII digit
     strings).  The default value is `"0"'.

`LogFile'
     corresponds to redirecting the standard output from the AMPLE
     program.  The value string is the name of the output log file.
     The default is not to have a log file.

`MaxMorphnameLength'
     corresponds to the AMPLE program's `-n' command line option.
     Possible values are positive integers greater than zero (encoded as
     ASCII digit strings).  The default value is `"15"'.

`MaxTrieDepth'
     corresponds to the AMPLE program's `-d' command line option.
     Possible values are positive integers greater than zero (encoded as
     ASCII digit strings).  The default value is `"2"'.

`OutputStyle'
     determines the style of output produced by `AmpleParseFile'.  The
     possible values are `"Ana"' (for the normal standard output
     analysis file), `"AResult"' (for SGML output similar to that
     produced by `AmpleParseText'), and `"Ptext"' for SGML output
     according to the `ptext.dtd' document type definition).  The
     default value is `"Ana"'.

`RootGlosses'
     corresponds to the AMPLE program's `-g' command line option.
     Possible values are `"TRUE"' (or `"T"') and `"FALSE"' (or `"F"').
     The default value is `"FALSE"'.

`SelectiveAnalysisFile'
     corresponds to the AMPLE program's `-s' command line option.  The
     value string is the name of a file containing the morphnames (or
     allomorphs) that are used for subsequent analyses.  The default is
     not to use selective analysis, but to use every allomorph of every
     morpheme loaded from the dictionary file(s).

`TraceAnalysis'
     corresponds to the AMPLE program's `-t' command line option.
     Possible values are `"OFF"', `"ON"' (for normal AMPLE tracing),
     and `"SGML"' (for `<AmpleTrace>' tracing).  The default value is
     `"OFF"'.  Note that the trace output is written to the log file,
     and may be mixed with other log output.

Note that the parameter names are not case sensitive, even though they
are shown here in a mixture of uppercase and lowercase.

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC2)(const char *,
                                            const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC2	pfAmpleSetParameter;
     char *		pszResult;
     ...
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleSetParameter = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleSetParameter != NULL)
         {
         pszResult = (*pfAmpleSetParameter)("MaxTrieDepth", "3");
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib           = 0;
         pfAmpleSetParameter = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleUpdateEntry
================

Syntax
------

     DllExport char * AmpleUpdateEntry(
                             const char * pszNewEntry_in)

Description
-----------

`AmpleUpdateEntry' updates an entry in the dictionary.  The input
string looks like an entry from the standard format dictionary file.
The default values for the standard format markers are the lowercase
characters for the internal codes described in the AMPLE reference
manual.  See Dictionary Files (ample.info).

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleUpdateEntry;
     char *		pszResult;
     ...
     char            szNewEntry[] = "\
     \\m mateo\n\
     \\t root\n\
     \\c N0\n\
     \\a mateo {Matthew_1}\n\
     \\a mateu {Matthew_2}\n\
     \\a matei {Matthew_3}\n\
     ";
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleUpdateEntry = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                     "AmpleUpdateEntry");
         if (pfAmpleUpdateEntry == NULL)
             {
             MessageBox(0, "Cannot find AmpleUpdateEntry in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleUpdateEntry != NULL)
         {
         pszResult = (*pfAmpleUpdateEntry)(szNewEntry);
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleUpdateEntry = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

AmpleWriteDictionary
====================

Syntax
------

     DllExport char * AmpleWriteDictionary(
                             const char * pszOutputDictionary_in)

Description
-----------

`AmpleWriteDictionary' writes the dictionary to a standard format file.
The standard format markers are based on the lowercase letters of the
internal codes described in the AMPLE reference manual.  See
Dictionary Files (ample.info).

Return Value
------------

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef char * (CALLBACK * AMPLEFUNC1)(const char *);
     ...
     HANDLE		hAmpleLib;
     AMPLEFUNC1	pfAmpleWriteDictionary;
     char *		pszResult;
     ...
     char            szOutputDictionary[] = "updated.dic";
     hAmpleLib = LoadLibrary("LLAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading LLAMPLE.DLL", "App Name",
     	       MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleWriteDictionary = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                     "AmpleWriteDictionary");
         if (pfAmpleWriteDictionary == NULL)
             {
             MessageBox(0, "Cannot find AmpleWriteDictionary in LLAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         }
     ...
     if (pfAmpleWriteDictionary != NULL)
         {
         pszResult = (*pfAmpleWriteDictionary)(szOutputDictionary);
         ...
         }
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleWriteDictionary = NULL;
         ...
         }
     ...

Source File
-----------

`llample.c'

Error Message Strings
*********************

The following error message strings may be returned by the LinguaLinks
AMPLE DLL functions.  Most of these messages should be self explanatory.

`<error code=badAnalysisDataFile>Error reading the analysis data file</error>'

`<error code=badDictCodeTableFile>Error reading the dictionary code table file</error>'

`<error code=badDictEntry>Error updating the dictionary</error>'

`<error code=badDictOrthoChangesFile>Error reading the dictionary orthography changes table file</error>'

`<error code=badDictionaryFile>Error reading the dictionary file</error>'

`<error code=badTextInputControlFile>Error reading the text input control file</error>'

`<error code=fatalCrash>AMPLE DLL has crashed badly!</error>'
     This indicates an extremely serious problem that would cause the
     AMPLE program to exit prematurely.  Running out of memory would be
     a possible cause of this message.

`<error code=invalidInputFilename>Cannot open file for input</error>'

`<error code=invalidOutputFilename>Cannot open file for output</error>'

`<error code=invalidParameterName>Parameter name not recognized</error>'
     This indicates an invalid argument to `AmpleGetParameter' or
     `AmpleSetParameter'.

`<error code=invalidParameterValue>Bad parameter value string</error>'
     This indicates an invalid argument to `AmpleSetParameter'.

`<error code=missingArgument>Required argument is empty</error>'

`<error code=none>Success</error>'
     This is not really an _error_ message, but rather an indication
     that the function worked flawlessly.