     [file front.txi not included]

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 (AMPLE Function Library Reference Manual). 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 Reference Manual).

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 Reference Manual).

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.