                     AMPLE322 DLL Reference Manual
              Windows functions for morphological parsing
                based on AMPLE functions version 3.3.16
                              March 2001

by Stephen McConnel (additions for versions 3.2.5-3.3.16 by Andy Black)

                 Copyright (C) 2001 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 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 AMPLE DLL
has therefore been developed with the goal of making it possible to
embed

AMPLE style morphological parsing into Windows programs written in a
variety of programming languages.

The AMPLE322 DLL is built with the AMPLE function library.  Its main
advantages over the AMPLE function library are that it allows bug fix
updates to be used without relinking the program, and it allows the
library to be used from programming languages that do not directly
interface with C code.

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 Windows 98.

Beginning with version 3.3.16, there is also an XAMPLE DLL.  This has
all the capabilities and functions of the AMPLE322 DLL with the
addition of allowing the use of a PC-PATR word grammar.  The XAMPLE DLL
has one additional function: `AmpleLoadGrammarFile'.

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

AMPLE322 DLL functions
**********************

All but one AMPLE322 DLL function (`AmpleCreateSetup') return a
character string.  This string contains either a value dependent on the
function or an error message.

(Please note that `AmpleLoadGrammarFile' is only available for the
XAMPLE DLL.)

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

Syntax
------

     DllExport const char * AmpleAddSelectiveAnalysisMorphs(
                             AmpleSetup *  pSetup_io,
                             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('`ampleSetup,' `"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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleAddSelectiveAnalysisMorphs;
     AmpleSetup *    pAmple = NULL;
     const 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("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleAddSelectiveAnalysisMorphs =
                     (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                     "AmpleAddSelectiveAnalysisMorphs");
         if (pfAmpleAddSelectiveAnalysisMorphs == NULL)
             {
             MessageBox(0,
         "Cannot find AmpleAddSelectiveAnalysisMorphs in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup == NULL) ||
                 (pfAmpleDeleteSetup == NULL) ||
                 (pfAmpleAddSelectiveAnalysisMorphs == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleAddSelectiveAnalysisMorphs)(pAmple,
                                                      szNewEntry);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                         = 0;
         pfAmpleCreateSetup                = NULL;
         pfAmpleDeleteSetup                = NULL;
         pfAmpleAddSelectiveAnalysisMorphs = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleApplyInputChangesToWord
============================

Syntax
------

     DllExport const char * AmpleApplyInputChangesToWord(
                            AmpleSetup * pSetup_io,
                            const char * pszWord_in)

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

`AmpleApplyInputChangesToWord' applies any input text changes to the
word in `pszWord_in'.

It should only be invoked after `AmpleLoadControlFiles' has been
successfully invoked.  It will typically be called before invoking
`AmpleParseText'.

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

a string containing either the word after input text changes have
applied or an error message

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleApplyInputChangesToWord;
     AMPLEFUNC2      pfAmpleParseText;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleParseText = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleParseText");
         if (pfAmpleParseText == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseText in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleApplyInputChangesToWord = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleApplyInputChangesToWord");
         if (pfAmpleApplyInputChangesToWord == NULL)
             {
             MessageBox(0, "Cannot find AmpleApplyInputChangesToWord in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup             == NULL) ||
                 (pfAmpleDeleteSetup             == NULL) ||
                 (pfAmpleApplyInputChangesToWord == NULL) ||
                 (pfAmpleParseText               == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleParseText)(pAmple,
             (*pfAmpleApplyInputChangesToWord)(pAmple,
             "Chayta rikar loomaman wicharkur hamakuykuran yachachinanpaq."));
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                      = 0;
         pfAmpleCreateSetup             = NULL;
         pfAmpleDeleteSetup             = NULL;
         pfAmpleApplyInputChangesToWord = NULL;
         pfAmpleParseText               = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleCheckMorphReferences
=========================

Syntax
------

     DllExport const char * AmpleCheckMorphReferences(
                             AmpleSetup *  pSetup_io)

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

`AmpleCheckMorphReferences' checks that all referenced morphnames in
dictionary entries and control information are defined in the
dictionaries.  It reports any unreferenced morphnames to the log file.
`AmpleCheckMorphReferences' should be invoked after
`AmpleInitializeMorphChecking', `AmpleLoadControlFiles', and all calls
to `AmpleLoadDictionary'.  If no log file has been defined, it does
nothing.  If `AmpleSetParameter('`ampleSetup,' `"CheckMorphReferences",'
`"TRUE")' has not been performed, it will perform it.

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

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC3      pfAmpleSetParameter;
     AMPLEFUNC5      pfAmpleLoadControlFiles;
     AMPLEFUNC2      pfAmpleLoadDictionary;
     AMPLEFUNC1      pfAmpleInitializeMorphChecking;
     AMPLEFUNC1      pfAmpleCheckMorphReferences;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleSetParameter = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadControlFiles = (AMPLEFUNC5)GetProcAddress(hAmpleLib,
                                                 "AmpleLoadControlFiles");
         if (pfAmpleLoadControlFiles == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadControlFiles in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadDictionary = (AMPLEFUNC2)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadDictionary");
         if (pfAmpleLoadDictionary == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadDictionary in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleInitializeMorphChecking = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                    "AmpleInitializeMorphChecking");
         if (pfAmpleInitializeMorphChecking == NULL)
             {
             MessageBox(0, "Cannot find AmpleInitializeMorphChecking in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleCheckMorphReferences = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleCheckMorphReferences");
         if (pfAmpleCheckMorphReferences == NULL)
             {
             MessageBox(0, "Cannot find AmpleCheckMorphReferences in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup             == NULL) ||
                 (pfAmpleDeleteSetup             == NULL) ||
                 (pfAmpleSetParameter            == NULL) ||
                 (pfAmpleLoadControlFiles        == NULL) ||
                 (pfAmpleLoadDictionary          == NULL) ||
                 (pfAmpleInitializeMorphChecking == NULL) ||
                 (pfAmpleCheckMorphReferences    == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleSetParameter)(pAmple,
                                        "LogFile",
                                        "D:/HG/HGMT05.LOG");
     ...
     pszResult = (*pfAmpleInitializeMorphChecking)(pAmple);
     ...
     pszResult = (*pfAmpleLoadControlFiles)(pAmple,
                                            "D:/HG/HGAD01.CTL",
                                            "D:/HG/HGANCD.TAB",
                                            NULL,
                                            "D:/HG/HGINTX.CTL");
     ...
     pszResult = (*pfAmpleLoadDictionary)(pAmple,
                                          "D:/HG/HGMORPH.DIC");
     ...
     pszResult = (*pfAmpleCheckMorphReferences)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                      = 0;
         pfAmpleCreateSetup             = NULL;
         pfAmpleDeleteSetup             = NULL;
         pfAmpleSetParameter            = NULL;
         pfAmpleLoadControlFiles        = NULL;
         pfAmpleLoadDictionary          = NULL;
         pfAmpleInitializeMorphChecking = NULL;
         pfAmpleCheckMorphReferences    = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleCreateSetup
================

     DllExport AmpleSetup * AmpleCreateSetup()

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

`AmpleCreateSetup' creates a new `AmpleSetup' data structure,
initializing it to be empty.  This is required before any of the other
functions is called.  It can be called multiple times to allow multiple
independent AMPLE setups to be loaded into memory simultaneously.

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

a pointer to the newly created and allocated `AmpleSetup' data
structure.  This pointer serves as a "magic cookie" to all of the other
functions.

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     typedef const char * (* AMPLEFUNC3)(AmpleSetup *,
                                         const char *,
                                         const char *);
     typedef const char * (* AMPLEFUNC5)(AmpleSetup *,
                                         const char *,
                                         const char *,
                                         const char *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC3      pfAmpleSetParameter;
     AMPLEFUNC5      pfAmpleLoadControlFiles;
     AMPLEFUNC2      pfAmpleLoadDictionary;
     2AMPLEFUNC3      pfAmpleParseFile;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleSetParameter = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadControlFiles = (AMPLEFUNC5)GetProcAddress(hAmpleLib,
                                                 "AmpleLoadControlFiles");
         if (pfAmpleLoadControlFiles == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadControlFiles in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadDictionary = (AMPLEFUNC2)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadDictionary");
         if (pfAmpleLoadDictionary == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadDictionary in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleParseFile = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                       "AmpleParseFile");
         if (pfAmpleParseFile == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseFile in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup      == NULL) ||
                 (pfAmpleDeleteSetup      == NULL) ||
                 (pfAmpleSetParameter     == NULL) ||
                 (pfAmpleLoadControlFiles == NULL) ||
                 (pfAmpleLoadDictionary   == NULL) ||
                 (pfAmpleParseFile        == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     pszResult = (*pfAmpleSetParameter)(pAmple,
                                        "LogFile",
                                        "D:/HG/HGMT05.LOG");
     ...
     pszResult = (*pfAmpleLoadControlFiles)(pAmple,
                                            "D:/HG/HGAD01.CTL",
                                            "D:/HG/HGANCD.TAB",
                                            NULL,
                                            "D:/HG/HGINTX.CTL");
     ...
     pszResult = (*pfAmpleLoadDictionary)(pAmple,
                                          "D:/HG/HGMORPH.DIC");
     ...
     pszResult = (*pfAmpleParseFile)(pAmple,
                                     "D:/HG/HGMT05.TXT",
                                     "D:/HG/HGMT05.SGM");
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib               = 0;
         pfAmpleCreateSetup      = NULL;
         pfAmpleDeleteSetup      = NULL;
         pfAmpleSetParameter     = NULL;
         pfAmpleLoadControlFiles = NULL;
         pfAmpleLoadDictionary   = NULL;
         pfAmpleParseFile        = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleDeleteSetup
================

     DllExport const char * AmpleDeleteSetup(
                             AmpleSetup * pSetup_io)

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

`AmpleDeleteSetup' erases the given `AmpleSetup' data structure, and
frees any associated memory.

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

a string indicating success or failure

Example
-------

See Example.

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

`ampledll.c'

AmpleGetAllAllomorphs
=====================

     DllExport const char * AmpleGetAllAllomorphs(
                            AmpleSetup * pSetup_io,
                            const char * pszRestOfWord_in,
                            const char * pszState_in)

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

`AmpleGetAllAllomorphs' gets all the allomorphs which match the string
in `pszRestOfWord_in'.  It does this for a given affix state.  The
caller is responsible to keep track of the state.  The states are given
in the following table.
`BOW'
     The current state is the beginning of the word.

`PFX'
     The current state is a prefix.

`ROOT'
     The current state is a root.

`SFX'
     The current state is a suffix.

`EOW'
     The current state is the end of the word.

One should invoke `AmpleApplyInputChangesToWord' when the state is
`BOW'.

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

a string containing the parse result

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     typedef const char * (* AMPLEFUNC3)(AmpleSetup *,
                                         const char *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleApplyInputChangesToWord;
     AMPLEFUNC2      pfAmpleParseText;
     AMPLEFUNC3      pfAmpleGetAllAllomorphs;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     char *          pszState;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleParseText = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleParseText");
         if (pfAmpleParseText == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseText in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleApplyInputChangesToWord = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleApplyInputChangesToWord");
         if (pfAmpleApplyInputChangesToWord == NULL)
             {
             MessageBox(0, "Cannot find AmpleApplyInputChangesToWord in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleGetAllAllomorphs = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleGetAllAllomorphs");
         if (pfAmpleGetAllAllomorphs == NULL)
             {
             MessageBox(0, "Cannot find AmpleGetAllAllomorphs in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup             == NULL) ||
                 (pfAmpleDeleteSetup             == NULL) ||
                 (pfAmpleApplyInputChangesToWord == NULL) ||
                 (pfAmpleGetAllAllomorphs        == NULL) ||
                 (pfAmpleParseText               == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     if (streq(pszState, "BOW"))
        pszResult = (*pfAmpleApplyInputChangesToWord)(pAmple, pszWord);
     pszResult = (*pfAmpleGetAllAllomorphs)(pAmple, pszResult, pszState);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                      = 0;
         pfAmpleCreateSetup             = NULL;
         pfAmpleDeleteSetup             = NULL;
         pfAmpleApplyInputChangesToWord = NULL;
         pfAmpleGetAllAllomorphs        = NULL;
         pfAmpleParseText               = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleGetParameter(
                             AmpleSetup *  pSetup_io,
                             const char * pszName_in)

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

`AmpleGetParameter' retrieves the value of an AMPLE322 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.

`CheckMorphReferences'
     corresponds to the AMPLE program's `-r' command line option.

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

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

`ErrorMessages'
     (not yet implemented)

`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.

`OutputDecomposition'
     corresponds to the AMPLE program's `-w d' and `-x d' command line
     options.

`OutputOriginalWord'
     corresponds to the AMPLE program's `-w w' and `-x w' command line
     options.

`OutputProperties'
     corresponds to the AMPLE program's `-w p' and `-x p' command line
     options.

`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.)

`ShowPercentages'
     corresponds to the AMPLE program's `-p' command line option.

`StoreErrorString'
     (not yet implemented)

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

`VerifyLoading'
     corresponds to the AMPLE program's `-v' 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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleGetParameter;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleGetParameter = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                     "AmpleGetParameter");
         if (pfAmpleGetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleGetParameter in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup  == NULL) ||
                 (pfAmpleDeleteSetup  == NULL) ||
                 (pfAmpleGetParameter == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleGetParameter)(pAmple,
                                        "MaxTrieDepth");
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib           = 0;
         pfAmpleCreateSetup  = 0;
         pfAmpleDeleteSetup  = 0;
         pfAmpleGetParameter = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleGetTraceString
===================

Syntax
------

     DllExport const char * AmpleGetTraceString(
                             AmpleSetup *  pSetup_io)

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

`AmpleGetTraceString' retrieves the string containing the trace results
from the most recent parse, or an error message if trace results are
going to a file.

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

a string containing the trace results, or a string indicating failure

Example
-------

See Example.

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

`ampledll.c'

AmpleInitializeMorphChecking
============================

Syntax
------

     DllExport const char * AmpleInitializeMorphChecking(
                             AmpleSetup *  pSetup_io)

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

`AmpleInitializeMorphChecking' initializes the process of checking that
all referenced morphnames in dictionary entries and control information
are defined in the dictionaries.  `AmpleInitializeMorphChecking' should
be invoked before `AmpleLoadControlFiles' and all calls to
`AmpleLoadDictionary'.  Then `AmpleCheckMorphReferences' should be
invoked.  If no log file has been defined, it does nothing.  If
`AmpleSetParameter('`ampleSetup,' `"CheckMorphReferences",' `"TRUE")'
has not been performed, it will perform it.

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

a string indicating success or failure

Example
-------

See Example.

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

`ampledll.c'

AmpleInitializeTraceString
==========================

Syntax
------

     DllExport const char * AmpleInitializeTraceString(
                             AmpleSetup *  pSetup_io)

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

`AmpleInitializeTraceString' sets tracing to use a string rather than a
file for storing the information.  This is an irreversible operation.

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

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC1      pfAmpleInitializeTraceString;
     AMPLEFUNC1      pfAmpleGetTraceString;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         pfAmpleInitializeTraceString = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                 "AmpleInitializeTraceString");
         if (pfAmpleInitializeTraceString == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleInitializeTraceString in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleGetTraceString = (AMPLEFUNC0)GetProcAddress(hAmpleLib,
                                                 "AmpleGetTraceString");
         if (pfAmpleGetTraceString == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleGetTraceString in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup           == NULL) ||
                 (pfAmpleDeleteSetup           == NULL) ||
                 (pfAmpleInitializeTraceString == NULL) ||
                 (pfAmpleGetTraceString        == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleInitializeTraceString)(pAmple);
     ...
     pszResult = (*pfAmpleGetTraceString)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                    = 0;
         pfAmpleCreateSetup           = NULL;
         pfAmpleDeleteSetup           = NULL;
         pfAmpleInitializeTraceString = NULL;
         pfAmpleGetTraceString        = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleLoadControlFiles(
                             AmpleSetup *  pSetup_io,
                             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
-------

See Example.

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleLoadDictionary(
                             AmpleSetup *  pSetup_io,
                             const char * pszFilePath_in)

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

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

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

a string indicating success or failure

Example
-------

See Example.

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

`ampledll.c'

AmpleLoadGrammarFile
====================

Syntax
------

     DllExport const char * AmpleLoadGrammarFile(
                            AmpleSetup * pSetup_io,
                            const char * pszGrammarFile_in)

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

`AmpleLoadGrammarFile' loads the indicated XAMPLE PATR grammar file
into memory.

NOTE: THIS FUNCTION IS ONLY AVAILABLE FOR THE XAMPLE DLL.

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

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     typedef const char * (* AMPLEFUNC3)(AmpleSetup *,
                                         const char *,
                                         const char *);
     typedef const char * (* AMPLEFUNC5)(AmpleSetup *,
                                         const char *,
                                         const char *,
                                         const char *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC3      pfAmpleSetParameter;
     AMPLEFUNC5      pfAmpleLoadControlFiles;
     AMPLEFUNC2      pfAmpleLoadDictionary;
     AMPLEFUNC2      pfAmpleLoadGrammarFile;
     2AMPLEFUNC3      pfAmpleParseFile;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("XAMPLE.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading XAMPLE.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleSetParameter = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadControlFiles = (AMPLEFUNC5)GetProcAddress(hAmpleLib,
                                                 "AmpleLoadControlFiles");
         if (pfAmpleLoadControlFiles == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadControlFiles in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadDictionary = (AMPLEFUNC2)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadDictionary");
         if (pfAmpleLoadDictionary == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadDictionary in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadGrammarFile = (AMPLEFUNC2)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadGrammarFile");
         if (pfAmpleLoadGrammarFile == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadGrammarFile in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleParseFile = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                       "AmpleParseFile");
         if (pfAmpleParseFile == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseFile in XAMPLE.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup      == NULL) ||
                 (pfAmpleDeleteSetup      == NULL) ||
                 (pfAmpleSetParameter     == NULL) ||
                 (pfAmpleLoadControlFiles == NULL) ||
                 (pfAmpleLoadDictionary   == NULL) ||
                 (pfAmpleLoadGrammarFile  == NULL) ||
                 (pfAmpleParseFile        == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     pszResult = (*pfAmpleSetParameter)(pAmple,
                                        "LogFile",
                                        "D:/HG/HGMT05.LOG");
     ...
     pszResult = (*pfAmpleLoadControlFiles)(pAmple,
                                            "D:/HG/HGAD01.CTL",
                                            "D:/HG/HGANCD.TAB",
                                            NULL,
                                            "D:/HG/HGINTX.CTL");
     ...
     pszResult = (*pfAmpleLoadGrammarFile)(pAmple,
                                          "D:/HG/HGPATR.GRM");
     ...
     pszResult = (*pfAmpleLoadDictionary)(pAmple,
                                          "D:/HG/HGMORPH.DIC");
     ...
     pszResult = (*pfAmpleParseFile)(pAmple,
                                     "D:/HG/HGMT05.TXT",
                                     "D:/HG/HGMT05.SGM");
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib               = 0;
         pfAmpleCreateSetup      = NULL;
         pfAmpleDeleteSetup      = NULL;
         pfAmpleSetParameter     = NULL;
         pfAmpleLoadControlFiles = NULL;
         pfAmpleLoadDictionary   = NULL;
         pfAmpleLoadGrammarFile  = NULL;
         pfAmpleParseFile        = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleParseFile(
                             AmpleSetup *  pSetup_io,
                             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
-------

See Example.

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleParseText(
                             AmpleSetup *  pSetup_io,
                             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 >
For the XAMPLE DLL, the parse output includes the parses from PC-PATR.
The change to the above is in the `<analysis>' element:

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

We currently have a problem in that the `<analysis>' member element is
actually defined differently.  It is a PC-PATR `<analysis>' element.
See the `set tree' section of the PC-PATR documentation.

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

a string containing either the parse output or an error message

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleParseText;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleParseText = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                       "AmpleParseText");
         if (pfAmpleParseText == NULL)
             {
             MessageBox(0, "Cannot find AmpleParseText in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup == NULL) ||
                 (pfAmpleDeleteSetup == NULL) ||
                 (pfAmpleParseText   == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleParseText)(pAmple,
             "Chayta rikar loomaman wicharkur hamakuykuran yachachinanpaq.");
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleCreateSetup = NULL;
         pfAmpleDeleteSetup = NULL;
         pfAmpleParseText   = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleRemoveSelectiveAnalysisMorphs(
                             AmpleSetup *  pSetup_io)

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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC1      pfAmpleRemoveSelectiveAnalysisMorphs;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleRemoveSelectiveAnalysisMorphs =
                     (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                   "AmpleRemoveSelectiveAnalysisMorphs");
         if (pfAmpleRemoveSelectiveAnalysisMorphs == NULL)
             {
             MessageBox(0,
         "Cannot find AmpleRemoveSelectiveAnalysisMorphs in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup                   == NULL) ||
                 (pfAmpleDeleteSetup                   == NULL) ||
                 (pfAmpleRemoveSelectiveAnalysisMorphs == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleRemoveSelectiveAnalysisMorphs)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib                            = 0;
         pfAmpleCreateSetup                   = NULL;
         pfAmpleDeleteSetup                   = NULL;
         pfAmpleRemoveSelectiveAnalysisMorphs = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleReportVersion
==================

Syntax
------

     DllExport const char * AmpleReportVersion(
                             AmpleSetup *  pSetup_io)

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

`AmpleReportVersion' prints the version information (of amplelib) to
the log file.  If no log file has been defined, it does nothing.

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

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC3      pfAmpleSetParameter;
     AMPLEFUNC1      pfAmpleReportVersion;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleSetParameter = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleReportVersion = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                   "AmpleReportVersion");
         if (pfAmpleReportVersion == NULL)
             {
             MessageBox(0, "Cannot find AmpleReportVersion in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup   == NULL) ||
                 (pfAmpleDeleteSetup   == NULL) ||
                 (pfAmpleSetParameter  == NULL) ||
                 (pfAmpleReportVersion == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleSetParameter)(pAmple,
                                        "LogFile",
                                        "D:/HG/HGMT05.LOG");
     ...
     pszResult = (*pfAmpleReportVersion)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib            = 0;
         pfAmpleCreateSetup   = NULL;
         pfAmpleDeleteSetup   = NULL;
         pfAmpleSetParameter  = NULL;
         pfAmpleReportVersion = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleReset
==========

Syntax
------

     DllExport const char * AmpleReset(
                             AmpleSetup *  pSetup_io)

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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC1      pfAmpleReset;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleReset = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                   "AmpleReset");
         if (pfAmpleReset == NULL)
             {
             MessageBox(0, "Cannot find AmpleReset in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup == NULL) ||
                 (pfAmpleDeleteSetup == NULL) ||
                 (pfAmpleReset       == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleReset)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleCreateSetup = NULL;
         pfAmpleDeleteSetup = NULL;
         pfAmpleReset       = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

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

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

`AmpleSetParameter' sets the value of an AMPLE322 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.

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

`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"'.

`ErrorMessages'
     (not yet implemented)

`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"'.

`OutputDecomposition'
     corresponds to the AMPLE program's `-w d' (if set to true) and `-x
     d' (if set to false) command line options.  Possible values are
     `"TRUE"' (or `"T"') and `"FALSE"' (or `"F"').  The default value
     is `"FALSE"'.

`OutputOriginalWord'
     corresponds to the AMPLE program's `-w w' (if set to true) and `-x
     w' (if set to false) command line options.  Possible values are
     `"TRUE"' (or `"T"') and `"FALSE"' (or `"F"').  The default value
     is `"FALSE"'.

`OutputProperties'
     corresponds to the AMPLE program's `-w p' (if set to true) and `-x
     p' (if set to false) command line options.  Possible values are
     `"TRUE"' (or `"T"') and `"FALSE"' (or `"F"').  The default value
     is `"FALSE"'.

`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).

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

`StoreErrorString'
     (not yet implemented)

`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.

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

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
-------

See Example.

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleUpdateEntry(
                             AmpleSetup *  pSetup_io,
                             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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleUpdateEntry;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     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("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleUpdateEntry = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                     "AmpleUpdateEntry");
         if (pfAmpleUpdateEntry == NULL)
             {
             MessageBox(0, "Cannot find AmpleUpdateEntry in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup == NULL) ||
                 (pfAmpleDeleteSetup == NULL) ||
                 (pfAmpleUpdateEntry == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleUpdateEntry)(pAmple,
                                       szNewEntry);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib          = 0;
         pfAmpleCreateSetup = NULL;
         pfAmpleDeleteSetup = NULL;
         pfAmpleUpdateEntry = NULL;
         ...
         }
     ...

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

`ampledll.c'

AmpleVerifyLoading
==================

Syntax
------

     DllExport const char * AmpleVerifyLoading(
                             AmpleSetup *  pSetup_io)

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

`AmpleVerifyLoading' prints some verifying output to the log file (this
corresponds to the AMPLE program's `-v' command line option).  If no
log file has been defined, it does nothing.  `AmpleVerifyLoading'
should be invoked after `AmpleLoadControlFiles' and all calls to
`AmpleLoadDictionary'.  If `AmpleSetParameter('`ampleSetup,'
`"VerifyLoading",' `"TRUE")' has not been performed, it will perform it.

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

a string indicating success or failure

Example
-------

     #include <windows.h>
     typedef struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC3      pfAmpleSetParameter;
     AMPLEFUNC5      pfAmpleLoadControlFiles;
     AMPLEFUNC2      pfAmpleLoadDictionary;
     AMPLEFUNC1      pfAmpleVerifyLoading;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleSetParameter = (AMPLEFUNC3)GetProcAddress(hAmpleLib,
                                                     "AmpleSetParameter");
         if (pfAmpleSetParameter == NULL)
             {
             MessageBox(0, "Cannot find AmpleSetParameter in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadControlFiles = (AMPLEFUNC5)GetProcAddress(hAmpleLib,
                                                 "AmpleLoadControlFiles");
         if (pfAmpleLoadControlFiles == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadControlFiles in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleLoadDictionary = (AMPLEFUNC2)GetProcAddress(
                                         hAmpleLib,
                                         "AmpleLoadDictionary");
         if (pfAmpleLoadDictionary == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleLoadDictionary in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleVerifyLoading = (AMPLEFUNC1)GetProcAddress(hAmpleLib,
                                                   "AmpleVerifyLoading");
         if (pfAmpleVerifyLoading == NULL)
             {
             MessageBox(0, "Cannot find AmpleVerifyLoading in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup      == NULL) ||
                 (pfAmpleDeleteSetup      == NULL) ||
                 (pfAmpleSetParameter     == NULL) ||
                 (pfAmpleLoadControlFiles == NULL) ||
                 (pfAmpleLoadDictionary   == NULL) ||
                 (pfAmpleVerifyLoading    == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleSetParameter)(pAmple,
                                        "LogFile",
                                        "D:/HG/HGMT05.LOG");
     ...
     pszResult = (*pfAmpleLoadControlFiles)(pAmple,
                                            "D:/HG/HGAD01.CTL",
                                            "D:/HG/HGANCD.TAB",
                                            NULL,
                                            "D:/HG/HGINTX.CTL");
     ...
     pszResult = (*pfAmpleLoadDictionary)(pAmple,
                                          "D:/HG/HGMORPH.DIC");
     ...
     pszResult = (*pfAmpleVerifyLoading)(pAmple);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib               = 0;
         pfAmpleCreateSetup      = NULL;
         pfAmpleDeleteSetup      = NULL;
         pfAmpleSetParameter     = NULL;
         pfAmpleLoadControlFiles = NULL;
         pfAmpleLoadDictionary   = NULL;
         pfAmpleVerifyLoading    = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

Syntax
------

     DllExport const char * AmpleWriteDictionary(
                             AmpleSetup *  pSetup_io,
                             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 struct ample_setup AmpleSetup;
     typedef AmpleSetup * (* AMPLEFUNC0)(void);
     typedef const char * (* AMPLEFUNC1)(AmpleSetup *);
     typedef const char * (* AMPLEFUNC2)(AmpleSetup *,
                                         const char *);
     ...
     HANDLE          hAmpleLib;
     AMPLEFUNC0      pfAmpleCreateSetup;
     AMPLEFUNC1      pfAmpleDeleteSetup;
     AMPLEFUNC2      pfAmpleWriteDictionary;
     const char *    pszResult;
     AmpleSetup *    pAmple;
     ...
     char            szOutputDictionary[] = "updated.dic";
     hAmpleLib = LoadLibrary("AMPLE322.DLL");
     if ((unsigned long)hAmpleLib < 32)
         {
         MessageBox(0, "Error loading AMPLE322.DLL", "App Name",
                    MB_OK | MB_ICONEXCLAMATION);
         hAmpleLib = 0;
         }
     ...
     if (hAmpleLib != 0)
         {
         pfAmpleCreateSetup = (AMPLEFUNC0)GetProcAddress(hAmpleLib_g,
                                     "AmpleCreateSetup");
         if (pfAmpleCreateSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleCreateSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleDeleteSetup = (AMPLEFUNC1)GetProcAddress(hAmpleLib_g,
                                     "AmpleDeleteSetup");
         if (pfAmpleDeleteSetup == NULL)
             {
             MessageBox(0,
                        "Cannot find AmpleDeleteSetup in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         pfAmpleWriteDictionary = (AMPLEFUNC2)GetProcAddress(hAmpleLib,
                                                     "AmpleWriteDictionary");
         if (pfAmpleWriteDictionary == NULL)
             {
             MessageBox(0, "Cannot find AmpleWriteDictionary in AMPLE322.DLL",
                        "App Name", MB_OK | MB_ICONEXCLAMATION);
             }
         if (    (pfAmpleCreateSetup     == NULL) ||
                 (pfAmpleDeleteSetup     == NULL) ||
                 (pfAmpleWriteDictionary == NULL) )
             return -1;              /* signal an error */
         }
     ...
     pAmple = (*pfAmpleCreateSetup)();
     if (pAmple == NULL)
         return -1;                  /* signal an error */
     ...
     pszResult = (*pfAmpleWriteDictionary)(pAmple,
                                           szOutputDictionary);
     ...
     (*pfAmpleDeleteSetup)(pAmple);
     pAmple = NULL;
     ...
     if (hAmpleLib != 0)
         {
         FreeLibrary(hAmpleLib);
         hAmpleLib              = 0;
         pfAmpleCreateSetup     = NULL;
         pfAmpleDeleteSetup     = NULL;
         pfAmpleWriteDictionary = NULL;
         ...
         }
     ...

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

`ampledll.c'

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

The following error message strings may be returned by the AMPLE322 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>AMPLE322 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=noTraceString>No trace string exists</error>'
     This indicates that `AmpleGetTraceString' has been called before
     calling `AmpleInitializeTraceString'.

`<error code=fatalCrash>AMPLE DLL has crashed badly!</error>'
     An internal error occurred which could not be diagnosed further.
     There may be more information in the log file, but don't count on
     it!

`<error code=invalidSetupArgument>Invalid AmpleSetup parameter</error>'
     The `AmpleSetup' pointer passed to the function did not come from a
     call to `AmpleCreateSetup', or has been invalidated by a call to
     `ampleDeleteSetup'.

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