                     PATR100 DLL Reference Manual
              COM Interface for unification based parsing
                 based on PATR functions version 1.2.2
                              April 2000

                          by Stephen McConnel

                 Copyright (C) 2000 SIL International

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

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

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

PC-PATR is an implementation for personal computers of the PATR-II
computational linguistic formalism.  The PATR-II formalism can be
viewed as a computer language for encoding linguistic information.  It
does not presuppose any particular theory of syntax.  It was originally
developed by Stuart M. Shieber at Stanford University in the early
1980's.  A PATR-II grammar consists of a set of rules and a lexicon.
Each rule consists of a context-free *phrase structure rule* and a set
of *feature constraints*, that is, *unifications* on the *feature
structures* associated with the constituents of the phrase structure
rules.  The lexicon provides the items that can replace the terminal
symbols of the phrase structure rules, that is, the words of the
language together with their relevant features.

The PATR100 DLL is built with the processing functions used by PC-PATR
and related programs.  It has been developed with the goal of making it
easier to use PATR-II style parsing as a component in Windows programs
written in different programming languages such as C++ or Visual Basic.

PC-PATR (and thus this COM DLL) is still under development.  The author
would appreciate feedback directed to the following address:

     Stephen McConnel                 (972)708-7361 (office)
     Language Software Development    (972)708-7561 (fax)
     SIL International
     7500 W. Camp Wisdom Road
     Dallas, TX 75236                 steve@acadcomp.sil.org
     U.S.A.                        or Stephen_McConnel@sil.org

The PatrParser Interface
************************

In order to facilitate using the PC-PATR functions from programming
languages such as Visual Basic, a COM interface named `IPatrParser' has
been written to encapsulate the essential PC-PATR functionality.  This
interface has the properties and methods described below.

The AmplePropertyIsFeature property
===================================

Interface description
---------------------

     [propget] HRESULT AmplePropertyIsFeature([out, retval] BOOL * pVal);
     [propput] HRESULT AmplePropertyIsFeature([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_AmplePropertyIsFeature(BOOL * pVal);
     HRESULT put_AmplePropertyIsFeature(BOOL newVal);

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

This Boolean property controls whether or not the values in the AMPLE
analysis `\p' (property) field are to be interpreted as feature
template names, the same as the values in the AMPLE analysis `\fd'
(feature descriptor) field.  If it is `true', then the values in the
AMPLE analysis `\p' field are interpreted as feature template names.
If it is `false', then the AMPLE analysis `\p' field is ignored except
for adding it verbatim to the lexicon feature structure as an atomic
feature value with the label `"properties"'.

The `AmplePropertyIsFeature' property corresponds to the `set
property-is-feature' command in the PCPATR program.

Default Value
-------------

`false'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox AmplePropertyIsFeature
           Caption         =   "Interpret AMPLE Properties as Features"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         AmplePropertyIsFeature.Value = m_patr.AmplePropertyIsFeature
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.AmplePropertyIsFeature = AmplePropertyIsFeature.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The CheckCycles property
========================

Interface description
---------------------

     [propget] HRESULT CheckCycles([out, retval] BOOL * pVal);
     [propput] HRESULT CheckCycles([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_CheckCycles(BOOL * pVal);
     HRESULT put_CheckCycles(BOOL newVal);

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

This Boolean property controls whether or not feature structures are
checked for cycles following unification.  If it is `true', then
feature structures are checked.  If it is `false', then no check is
performed.

It is a bad idea to set this property to `false' unless the grammer is
known to *never* create cycles during parsing, even for failed parses.

The `CheckCycles' property corresponds to the `set check-cycles'
command in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox CheckCycles
           Caption         =   "Check Features for Cycles"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         CheckCycles.Value = m_patr.CheckCycles
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.CheckCycles = CheckCycles.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The Clear method
================

Interface description
---------------------

     HRESULT Clear();

C++ prototypes
--------------

     HRESULT Clear();

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

This method frees all of the allocated memory, erasing any lexicon or
grammar file that has been loaded.

The `Clear' method corresponds to the `clear' command in the PCPATR
program.

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

`S_OK'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu ClearCmd
              Caption         =   "Clear"
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub ClearCmd_Click()
         On Error GoTo Failed
         m_patr.Clear
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Clear Failed"
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The CloseLog method
===================

Interface description
---------------------

     HRESULT CloseLog();

C++ prototypes
--------------

     HRESULT CloseLog();

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

This method closes the open log file.

The `CloseLog' method corresponds to the `close' command in the PCPATR
program.

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

`S_OK', or E_UNEXPECTED if a log file was not open

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu CloseLogCmd
              Caption         =   "&Close Log"
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub CloseLogCmd_Click()
         On Error GoTo Failed
         m_patr.CloseLog
         LogFile.Text = ""
         Exit Sub
     Failed:
         MsgBox "Closing Log File Failed"
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The CodePage property
=====================

Interface description
---------------------

     [propget] HRESULT CodePage([out, retval] long * pVal);
     [propput] HRESULT CodePage([in] long newVal);

C++ prototypes
--------------

     HRESULT get_CodePage(long * pVal);
     HRESULT put_CodePage(long newVal);

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

This integer property selects the code page used for converting between
the 16-bit Unicode characters used in BSTRs (and XML) and the 8-bit
multibyte characters used by the PCPATR functions and the grammar and
lexicon files.

The `CodePage' property has no corresponding command in the PCPATR
program.  It is useful primarily for converting from the 8-bit
characters used by the PCPATR functions and files into the 16-bit
Unicode characters used by the BSTRs used by COM interface methods.  It
is also useful for designating the encoding in XML files produced by
the PCPATR output functions.

Default Value
-------------

`CP_ACP' (the ANSI code page)

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox CodePage
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         Select Case m_patr.CodePage
             Case 0
                 CodePage.Text = "ANSI"
             Case 1
                 CodePage.Text = "OEM"
             Case 2
                 CodePage.Text = "MAC"
             Case 42
                 CodePage.Text = "SYMBOL"
             Case 65000
                 CodePage.Text = "UTF7"
             Case 65001
                 CodePage.Text = "UTF8"
             Case Else
                 CodePage.Text = m_patr.CodePage
         End Select
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         If CodePage.Text = "ANSI" Then
             m_patr.CodePage = 0
         ElseIf CodePage.Text = "OEM" Then
             m_patr.CodePage = 1
         ElseIf CodePage.Text = "MAC" Then
             m_patr.CodePage = 2
         ElseIf CodePage.Text = "SYMBOL" Then
             m_patr.CodePage = 42
         ElseIf CodePage.Text = "UTF7" Then
             m_patr.CodePage = 65000
         ElseIf CodePage.Text = "UTF8" Then
             m_patr.CodePage = 65001
         Else
             m_patr.CodePage = CodePage.Text
         End If
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The CommentChar property
========================

Interface description
---------------------

     [propget] HRESULT CommentChar([out, retval] long * pVal);
     [propput] HRESULT CommentChar([in] long newVal);

C++ prototypes
--------------

     HRESULT get_CommentChar(long * pVal);
     HRESULT put_CommentChar(long newVal);

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

This integer property selects the 8-bit character used to mark the
beginning of comments in the grammar and lexicon files.  If `newVal' is
0, then no comments are allowed in the grammar and lexicon files.

The `CommentChar' property corresponds to the `set comment' command in
the PCPATR program.

Default Value
-------------

the semicolon character (`;')

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `newVal' is out of range (less than 0 or greater
     than 255)

   * `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox CommentChar
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         CommentChar.Text = Chr(m_patr.CommentChar)
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.CommentChar = Asc(CommentChar.Text)
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The DebuggingLevel property
===========================

Interface description
---------------------

     [propget] HRESULT DebuggingLevel([out, retval] long * pVal);
     [propput] HRESULT DebuggingLevel([in] long newVal);

C++ prototypes
--------------

     HRESULT get_DebuggingLevel(long * pVal);
     HRESULT put_DebuggingLevel(long newVal);

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

This integer property selects the level of debugging output written to
the log file.

This property is of use primarily to the programmer maintaining PCPATR.
It corresponds to the virtually undocumented `-/' command line option.

Default Value
-------------

`0'

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `newVal' is out of range (less than 0)

   * `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox DebugLevel
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         DebugLevel.Text = m_patr.DebuggingLevel
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.DebuggingLevel = DebugLevel.Text
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The DisambiguateAnaFile method
==============================

Interface description
---------------------

     HRESULT DisambiguateAnaFile([in] BSTR bstrInput, [in] BSTR bstrOutput);

C++ prototypes
--------------

     HRESULT DisambiguateAnaFile(BSTR bstrInput, BSTR bstrOutput);

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

This method disambiguates word analyses in an AMPLE analysis file by
applying a syntactice parse to the sentences in the analysis file.  It
reads the file given by `bstrInput', and writes a new AMPLE analysis
file given by `bstrOutput'.

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

`S_OK', `E_INVALIDARG', `E_FAIL', or another appropriate COM error code

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog AnaDlg
           ...
        End
        Begin MSComDlg.CommonDialog AnbDlg
           ...
        End
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu DisambigFileCmd
              Caption         =   "&Disambiguate File..."
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         AnaDlg.Filter = "AMPLE ANA files|*.ana"
         AnaDlg.CancelError = True
         AnbDlg.Filter = "Disam ANA files|*.anb"
         AnbDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub DisambigFileCmd_Click()
         If Not IsReadyToParse Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         AnaDlg.ShowOpen
         AnbDlg.ShowOpen
         On Error GoTo Failed
         m_patr.SentenceFinalPunctuation
         m_patr.DisambiguateAnaFile AnaDlg.FileName, AnbDlg.FileName
         MsgBox "Done parsing " & AnaDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Parsing " & AnaDlg.FileName & " into " &
             AnbDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The DisplayFeatures property
============================

Interface description
---------------------

     [propget] HRESULT DisplayFeatures([out, retval] BOOL * pVal);
     [propput] HRESULT DisplayFeatures([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_DisplayFeatures(BOOL * pVal);
     HRESULT put_DisplayFeatures(BOOL newVal);

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

This Boolean property controls whether or not any feature structures are
displayed in the parse output.  If it is `true', then one or more
features structures are displayed, with the exact details controlled by
the `FlatFeatureDisplay', `TopFeatureOnly', and `TrimEmptyFeatures'
properties.  If `DisplayFeatures' is `false', then no features are
displayed in parse output.

The `DisplayFeatures' property corresponds to the `set features on' and
`set features off' commands in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.Frame Frame1
           ...
           Begin VB.OptionButton FeaturesOn
              Caption         =   "On"
              ...
           End
           Begin VB.OptionButton FeaturesOff
              Caption         =   "Off"
              ...
           End
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         If m_patr.DisplayFeatures Then
             FeaturesOn.Value = True
             ...
         Else
             FeaturesOff.Value = True
             ...
         End If
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.DisplayFeatures = FeaturesOn.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The Failures property
=====================

Interface description
---------------------

     [propget] HRESULT Failures([out, retval] BOOL * pVal);
     [propput] HRESULT Failures([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_Failures(BOOL * pVal);
     HRESULT put_Failures(BOOL newVal);

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

This Boolean property controls how the PCPATR parse functions deal with
sentences that fail to parse.  If it is `true', then an attempt is made
to produce partial results in a three stage process:
  1. If unification is on, turn it off, try again to parse the
     sentence, and turn unification back on.

  2. If the preceding step does not produce any results, and top-down
     filtering is on, turn off top-down filtering, try again to parse
     the sentence, and turn top-down filtering back on.

  3. If the preceding steps have not produced any results, call a
     special function to link the partial results stored in the parse
     chart together for display as a set of (possibly intersecting)
     parse "bushes".
     If any sort of partial result is obtained by these steps, then that
partial result will be returned by the parse method, along with a parse
failure indication.

The `Failures' property corresponds to the `set failures' command in
the PCPATR program.

Default Value
-------------

`false'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox PartialResults
           Caption         =   "Partial Results for Failures"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         PartialResults.Value = m_patr.Failures
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.Failures = PartialResults.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The FlatFeatureDisplay property
===============================

Interface description
---------------------

     [propget] HRESULT FlatFeatureDisplay([out, retval] BOOL * pVal);
     [propput] HRESULT FlatFeatureDisplay([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_FlatFeatureDisplay(BOOL * pVal);
     HRESULT put_FlatFeatureDisplay(BOOL newVal);

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

This Boolean property controls how feature structures are displayed (if
`DisplayFeatures' is `true').  If it is `true', then each parse node
feature is written as a flat bracketed string, with open and close
brackets marking the boundaries of complex features.  This format
requires the least amount of space on the screen or in a file.  If
`FlatFeaturesDisplay' is `false', then each parse node feature is
written as a bracketed string, with open and close brackets marking the
boundaries of complex features, and with newlines and spaces used to
line up the labels of internal features in a column for embedded
features.  This works best for short labels and fixed width fonts.

Note that while the `DisplayFeatures' property is `false', this
property has no effect on the parse output.

The `FlatFeatureDisplay' property corresponds to the `set features
flat' and `set features full' commands in the PCPATR program.

Default Value
-------------

`false'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox FlatFeatures
           Caption         =   "Flat Feature Format"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         FlatFeatures.Value = m_patr.FlatFeatureDisplay
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.FlatFeatureDisplay = FlatFeatures.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The Gloss property
==================

Interface description
---------------------

     [propget] HRESULT Gloss([out, retval] BOOL * pVal);
     [propput] HRESULT Gloss([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_Gloss(BOOL * pVal);
     HRESULT put_Gloss(BOOL newVal);

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

This Boolean property controls whether glosses are displayed in the
parse tree output in addition to the lexical forms for the leaf nodes
of the parse tree.  If the lexicon does not contain any glosses, this
property has no effect.  If `Gloss' is `true', then glosses are
displayed in parse trees (if the lexicon contains glosses).  If `Gloss'
is `false', then glosses are not displayed in parse trees even if they
exist in the lexicon.  Note that feature structures associated with
leaf nodes in the parse tree will contain any glosses found in the
lexicon regardless of the value of this property.

The `Gloss' property corresponds to the `set gloss' command in the
PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox EnableGlosses
           Caption         =   "Enable Display of Glosses"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         EnableGlosses.Value = m_patr.Gloss
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.Gloss = EnableGlosses.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The GrammarFile property
========================

Interface description
---------------------

     [propget] HRESULT GrammarFile([out, retval] BSTR * pVal);

C++ prototypes
--------------

     HRESULT get_GrammarFile(BSTR * pVal);

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

This string property contains the name of the grammar file most recently
loaded by a `LoadGrammarFile' method.  If `LoadGrammarFile' has never
been called, or if `Clear' has been called since `LoadGrammarFile',
then this property is set to `NULL'.

The `GrammarFile' property corresponds to part of the `status' command
in the PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox GrammarFile
           Enabled         =   0   'False
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         GrammarFile.Text = m_patr.GrammarFile
         ...
     End Sub

C++ Example
-----------

     // TODO: write an example

The LexCategoryMarker property
==============================

Interface description
---------------------

     [propget] HRESULT LexCategoryMarker([out, retval] BSTR * pVal);
     [propput] HRESULT LexCategoryMarker([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_LexCategoryMarker(BSTR * pVal);
     HRESULT put_LexCategoryMarker(BSTR newVal);

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

This string property contains the standard format marker used to
indicate the syntactic category field of lexicon entries.  The
"category" is what connect the lexicon entry to the grammar rules.  It
is copied to the word's lexical feature structure as the embedded `cat'
feature.

The `LexCategoryMarker' property corresponds to the `set marker
category' command in the PCPATR program.

Default Value
-------------

`\c' (C string would be `"\\c"')

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox CategoryMarker
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         CategoryMarker.Text = m_patr.LexCategoryMarker
         ...
     End Sub
     ...
     Private Function SetLexMarkers() As Boolean
         SetLexMarkers = False
         On Error GoTo Failed
         ...
         If (CategoryMarker.Text = "") Or (CategoryMarker.Text = "\") Then
             MsgBox "The Category marker must be set before loading the lexicon"
             Exit Function
         End If
         ...
         m_patr.LexCategoryMarker = CategoryMarker.Text
         ...
         SetLexMarkers = True
         Exit Function
     Failed:
         Exit Function
     End Function

C++ Example
-----------

     // TODO: write an example

The LexFeaturesMarker property
==============================

Interface description
---------------------

     [propget] HRESULT LexFeaturesMarker([out, retval] BSTR * pVal);
     [propput] HRESULT LexFeaturesMarker([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_LexFeaturesMarker(BSTR * pVal);
     HRESULT put_LexFeaturesMarker(BSTR newVal);

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

This string property contains the standard format marker used to
indicate the features field of lexicon entries.  The content of this
field is usually a set of names of feature templates (or lexical rules)
defined in the grammar file.

The `LexFeaturesMarker' property corresponds to the `set marker
features' command in the PCPATR program.

Default Value
-------------

`\f' (C string would be `"\\f"')

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox FeatureMarker
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         FeatureMarker.Text = m_patr.LexFeaturesMarker
         ...
     End Sub
     ...
     Private Function SetLexMarkers() As Boolean
         SetLexMarkers = False
         On Error GoTo Failed
         ...
         If (FeatureMarker.Text = "") Or (FeatureMarker.Text = "\") Then
             MsgBox "The Feature marker must be set before loading the lexicon"
             Exit Function
         End If
         ...
         m_patr.LexFeaturesMarker = FeatureMarker.Text
         ...
         SetLexMarkers = True
         Exit Function
     Failed:
         Exit Function
     End Function

C++ Example
-----------

     // TODO: write an example

The LexGlossMarker property
===========================

Interface description
---------------------

     [propget] HRESULT LexGlossMarker([out, retval] BSTR * pVal);
     [propput] HRESULT LexGlossMarker([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_LexGlossMarker(BSTR * pVal);
     HRESULT put_LexGlossMarker(BSTR newVal);

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

This string property contains the standard format marker used to
indicate the gloss field of lexicon entries.  The content of this field
is copied to the word's lexical feature structure as the embedded
`gloss' feature.

The `LexGlossMarker' property corresponds to the `set marker gloss'
command in the PCPATR program.

Default Value
-------------

`\g' (C string would be `"\\g"')

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox GlossMarker
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         GlossMarker.Text = m_patr.LexGlossMarker
         ...
     End Sub
     ...
     Private Function SetLexMarkers() As Boolean
         SetLexMarkers = False
         On Error GoTo Failed
         ...
         If (GlossMarker.Text = "") Or (GlossMarker.Text = "\") Then
             MsgBox "The Gloss marker must be set before loading the lexicon"
             Exit Function
         End If
         ...
         m_patr.LexGlossMarker = GlossMarker.Text
         ...
         SetLexMarkers = True
         Exit Function
     Failed:
         Exit Function
     End Function

C++ Example
-----------

     // TODO: write an example

The LexiconFile property
========================

Interface description
---------------------

     [propget] HRESULT LexiconFile([in] long iFile, [out, retval] BSTR * pVal);

C++ prototypes
--------------

     HRESULT get_LexiconFile(long iFile, BSTR * pVal);

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

This string property contains the name of one of the lexicon files most
recently loaded by a `LoadLexiconFile' method.  If `LoadLexiconFile'
has never been called, or if `Clear' has been called since
`LoadLexiconFile', then this property is set to `NULL'.  This property
is also set to `NULL' if `iFile' is outside the range (`0',
`LexiconFileCount - 1').

The `LexiconFile' property corresponds to part of the `status' command
in the PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     ' TODO: write an example retrieving multiple lexicon filenames.
     Begin VB.Form Form1
        ...
        Begin VB.TextBox LexiconFile
           Enabled         =   0   'False
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         LexiconFile.Text = m_patr.LexiconFile(0)
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The LexiconFileCount property
=============================

Interface description
---------------------

     [propget] HRESULT LexiconFileCount([out, retval] long * pVal);

C++ prototypes
--------------

     HRESULT get_LexiconFileCount(long * pVal);

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

This integer property contains the number of lexicon files that are
currently loaded.  It is always greater than or equal to zero.

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.Label LexFileCnt
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         LexFileCnt.Caption = m_patr.LexiconFileCount & "Lexicon Files"
         ...
     End Sub

C++ Example
-----------

     // TODO: write an example

The LexRecordMarker property
============================

Interface description
---------------------

     [propget] HRESULT LexRecordMarker([out, retval] BSTR * pVal);
     [propput] HRESULT LexRecordMarker([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_LexRecordMarker(BSTR * pVal);
     HRESULT put_LexRecordMarker(BSTR newVal);

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

This string property contains the standard format marker used to
indicate the beginning of each entry in the lexicon file.  It may be
the same as one of the other lexicon marker properties.

The `LexRecordMarker' property corresponds to the `set marker record'
command in the PCPATR program.

Default Value
-------------

`\w' (C string would be `"\\w"')

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox RecordMarker
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         RecordMarker.Text = m_patr.LexRecordMarker
         ...
     End Sub
     ...
     Private Function SetLexMarkers() As Boolean
         SetLexMarkers = False
         On Error GoTo Failed
         ...
         If (RecordMarker.Text = "") Or (RecordMarker.Text = "\") Then
             MsgBox "The Record marker must be set before loading the lexicon"
             Exit Function
         End If
         ...
         m_patr.LexRecordMarker = RecordMarker.Text
         ...
         SetLexMarkers = True
         Exit Function
     Failed:
         Exit Function
     End Function

C++ Example
-----------

     // TODO: write an example

The LexWordMarker property
==========================

Interface description
---------------------

     [propget] HRESULT LexWordMarker([out, retval] BSTR * pVal);
     [propput] HRESULT LexWordMarker([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_LexWordMarker(BSTR * pVal);
     HRESULT put_LexWordMarker(BSTR newVal);

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

This string property contains the standard format marker used to
indicate the word field of lexicon entries.  The content of this field
is copied to the word's lexical feature structure as the embedded `lex'
feature.

The `LexWordMarker' property corresponds to the `set marker word'
command in the PCPATR program.

Default Value
-------------

`\w' (C string would be `"\\w"')

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox WordMarker
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         WordMarker.Text = m_patr.LexWordMarker
         ...
     End Sub
     ...
     Private Function SetLexMarkers() As Boolean
         SetLexMarkers = False
         On Error GoTo Failed
         ...
         If (WordMarker.Text = "") Or (WordMarker.Text = "\") Then
             MsgBox "The Word marker must be set before loading the lexicon"
             Exit Function
         End If
         ...
         m_patr.LexWordMarker = WordMarker.Text
         ...
         SetLexMarkers = True
         Exit Function
     Failed:
         Exit Function
     End Function

C++ Example
-----------

     // TODO: write an example

The LoadAnaFile method
======================

Interface description
---------------------

     HRESULT LoadAnaFile([in] BSTR bstrAnaFile, [in] BOOL fAdd);

C++ prototypes
--------------

     HRESULT LoadAnaFile(BSTR bstrAnaFile, BOOL fAdd);

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

This method loads an AMPLE analysis file as a lexicon file.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `bstrAnaFile' is `NULL', or if that file has
     already been loaded as a lexicon file

   * `E_FAIL' if an error occurs during the load process

   * `E_OUTOFMEMORY' if allocating memory fails for any reason.  In this
     case, the in-memory lexicon may or may not contain any entries.

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog AnaDlg
           ...
        End
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu LoadLexiconCmd
              Caption         =   "Load &Ana file..."
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         AnaDlg.Filter = "AMPLE Analysis Files|*.ana"
         AnaDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub LoadLexiconCmd_Click()
         If Not SetLexMarkers Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         AnaDlg.ShowOpen
         On Error GoTo Failed
         m_patr.LoadAnaFile AnaDlg.FileName, False
         LexiconFile.Text = AnaDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Loading " & AnaDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The LoadGrammarFile method
==========================

Interface description
---------------------

     HRESULT LoadGrammarFile([in] BSTR bstrGrammarFile);

C++ prototypes
--------------

     HRESULT LoadGrammarFile(BSTR bstrGrammarFile);

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

This method loads a PCPATR grammar file into memory, first erasing any
grammar that had been previously loaded.

The `LoadGrammarFile' method corresponds to the `load grammar' command
in the PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `bstrGrammarFile' is `NULL'

   * `E_FAIL' if an error occurs during the load process

   * `E_OUTOFMEMORY' if allocating memory fails converting
     `bstrGrammarFile' to an 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog GrmDlg
           ...
        End
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           Begin VB.Menu LoadGrammarCmd
              Caption         =   "Load &Grammar..."
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         GrmDlg.Filter = "PC-PATR Grammar Files|*.grm"
         GrmDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub LoadGrammarCmd_Click()
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         GrmDlg.ShowOpen
         On Error GoTo Failed
         m_patr.LoadGrammarFile GrmDlg.FileName
         GrammarFile.Text = GrmDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Loading " & GrmDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The LoadLexiconFile method
==========================

Interface description
---------------------

     HRESULT LoadLexiconFile([in] BSTR bstrLexiconFile, [in] BOOL fAdd);

C++ prototypes
--------------

     HRESULT LoadLexiconFile(BSTR bstrLexiconFile, BOOL fAdd);

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

This method loads a PCPATR lexicon file into memory, first erasing any
lexicon that had been previously loaded unless `fAdd' is `True'.  If
`fAdd' is `True', then `bstrLexiconFile' must not have already been
loaded.

The `LoadLexiconFile' method corresponds to the `load lexicon' command
in the PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `bstrLexiconFile' is `NULL', or if that file has
     already been loaded as a lexicon file

   * `E_FAIL' if an error occurs during the load process

   * `E_OUTOFMEMORY' if allocating memory fails converting
     `bstrLexiconFile' to an 8-bit character string, or storing the
     filename.  In the latter case, the entire lexicon is unloaded from
     memory.

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog LexDlg
           ...
        End
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu LoadLexiconCmd
              Caption         =   "Load &Lexicon..."
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         LexDlg.Filter = "PC-PATR Lexicon Files|*.lex"
         LexDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub LoadLexiconCmd_Click()
         If Not SetLexMarkers Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         LexDlg.ShowOpen
         On Error GoTo Failed
         m_patr.LoadLexiconFile LexDlg.FileName, False
         LexiconFile.Text = LexDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Loading " & LexDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The LogFile property
====================

Interface description
---------------------

     [propget] HRESULT LogFile([out, retval] BSTR * pVal);

C++ prototypes
--------------

     HRESULT get_LogFile(BSTR * pVal);

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

This string property contains the name of the currently open log file,
if there is one.  If no log file is currently open, then this property
is set to `NULL'.

The `LogFile' property corresponds to part of the `status' command in
the PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox LogFile
           Enabled         =   0   'False
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         LogFile.Text = m_patr.LogFile
         ...
     End Sub

C++ Example
-----------

     // TODO: write an example

The MaxAmbiguity property
=========================

Interface description
---------------------

     [propget] HRESULT MaxAmbiguity([out, retval] long * pVal);
     [propput] HRESULT MaxAmbiguity([in] long newVal);

C++ prototypes
--------------

     HRESULT get_MaxAmbiguity(long * pVal);
     HRESULT put_MaxAmbiguity(long newVal);

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

This integer property specifies the maximum number of parses displayed
for an ambiguous parse.  This can be critical because the number of
parses for long sentences can run into the thousands, especially in the
early stages of developing a grammar.

The `MaxAmbiguity' property corresponds to the `set ambiguities'
command in the PCPATR program.

Default Value
-------------

`10'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox MaxAmbiguity
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         MaxAmbiguity.Text = m_patr.MaxAmbiguity
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.MaxAmbiguity = MaxAmbiguity.Text
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The OpenLog method
==================

Interface description
---------------------

     HRESULT OpenLog([in] BSTR bstrLogFile);

C++ prototypes
--------------

     HRESULT OpenLog(BSTR bstrLogFile);

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

This method opens a log file after first closing any previously opened
log file.  The log file receives various error messages and other
information produced by the load and parse methods which would otherwise
go unreported.  If a file of the same name already exists, it is
replaced by the new log file.

The `OpenLog' method corresponds to the `log' command in the PCPATR
program.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `bstrLogFile' is `NULL'

   * `E_FAIL' if the log file cannot be opened

   * `E_OUTOFMEMORY' if allocating memory fails converting
     `bstrLogFile' to an 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog LogDlg
           ...
        End
        ...
        Begin VB.TextBox LogFile
           Enabled         =   0   'False
           ...
        End
        ...
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu OpenLogCmd
              Caption         =   "&Open Log"
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         ...
         LogDlg.Filter = "PC-PATR Log Files|*.log"
         LogDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub OpenLogCmd_Click()
         On Error GoTo Cancelled
         LogDlg.ShowOpen
         On Error GoTo Failed
         m_patr.OpenLog LogDlg.FileName
         LogFile.Text = LogDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Opening Log File " & LogDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The ParseFile method
====================

Interface description
---------------------

     HRESULT ParseFile([in] BSTR bstrInput, [in] BSTR bstrOutput);

C++ prototypes
--------------

     HRESULT ParseFile(BSTR bstrInput, BSTR bstrOutput);

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

This method reads sentences from a file and writes the resulting parses
to another file.  Each line of the input file represents a separate
"sentence", and punctuation and sentence capitalization should not be
used.  Proper names should be capitalized the same way they are in the
lexicon.

Actually, punctuation can be used if three conditions are met:
  1. Punctuation "categories" are used in the grammar rules.

  2. Punctuation characters and their "categories" are listed in the
     lexicon.

  3. Punctuation characters are separated by spaces from words and from
     each other in the input sentences.
     Constructs which use a specific punctuation character such as an
apostrophe (English possessives and contractions) must be handled
differently, possibly by a preprocessor step that splits contractions
into multiple words as needed.

[NOTE: PCPATR can handle having a phrase as a single entry (category) in
the lexicon.  Can it also handle a contraction representing two or more
consecutive syntactic categories?  Should it?]

The `ParseFile' method corresponds to the `file parse' command in the
PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if either `bstrInput' or `bstrOutput' is `NULL'

   * `E_FAIL' if either the input file or the output file cannot be
     opened

   * `E_OUTOFMEMORY' if allocating memory fails converting either
     `bstrInput' or `bstrOutput' to an 8-bit character string

   * `E_UNEXPECTED' in very bizarre circumstances Note that the return
value does not depend on whether or not any of the sentences
successfully parses.

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin MSComDlg.CommonDialog SenDlg
           ...
        End
        Begin MSComDlg.CommonDialog ParDlg
           ...
        End
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu ParseFileCmd
              Caption         =   "&Parse File..."
           End
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         SenDlg.Filter = "Sentence files|*.sen"
         SenDlg.CancelError = True
         ParDlg.Filter = "Parse output files|*.par"
         ParDlg.CancelError = True
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub ParseFileCmd_Click()
         If Not IsReadyToParse Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         SenDlg.ShowOpen
         ParDlg.ShowOpen
         On Error GoTo Failed
         m_patr.ParseFile SenDlg.FileName, ParDlg.FileName
         MsgBox "Done parsing " & SenDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Parsing " & SenDlg.FileName & " into " &
             ParDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The ParseString method
======================

Interface description
---------------------

     HRESULT ParseString(
         [in] BSTR bstrSentence,
         [out, retval] BSTR * pbstrParse);

C++ prototypes
--------------

     HRESULT ParseString(BSTR bstrSentence, BSTR * pbstrParse);

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

This method parses the input sentence and produces a string containing
the parse results.  Punctuation and sentence capitalization should not
be used in the input sentence.  Proper names should be capitalized the
same way they are in the lexicon.

Actually, punctuation can be used if three conditions are met:
  1. Punctuation "categories" are used in the grammar rules.

  2. Punctuation characters and their "categories" are listed in the
     lexicon.

  3. Punctuation characters are separated by spaces from words and from
     each other in the input sentence.
     Constructs which use a specific punctuation character such as an
apostrophe (English possessives and contractions) must be handled
differently, possibly by a preprocessor step that splits contractions
into multiple words as needed.

[NOTE: PCPATR can handle having a phrase as a single entry (category) in
the lexicon.  Can it also handle a contraction representing two or more
consecutive syntactic categories?  Should it?]

The `ParseString' method corresponds to the `parse' command in the
PCPATR program.

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

`S_OK', or one of these COM error codes:
   * `E_INVALIDARG' if `bstrSentence' is `NULL',

   * `E_POINTER' if `pbstrParse' is `NULL',

   * `E_UNEXPECTED' if either the grammar or the lexicon has not yet
     been loaded (or possibly in some other, very bizarre,
     circumstances),

   * `E_OUTOFMEMORY' if allocating memory fails during the parse setup,
     or in converting the internal parse result to the output `BSTR',

   * `E_FAIL' if any of the words in the sentence cannot be found in the
     lexicon,

   * `S_FALSE' if the parse fails.  (Partial results may be available
     for display depending on the value of the `Failures'.)

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CommandButton ParseButton
           Caption         =   "Parse"
           ...
        End
        Begin VB.TextBox Sentence
           ...
        End
        Begin RichTextLib.RichTextBox SentenceParse
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         Sentence.Text = ""
         SentenceParse.Text = ""
         ...
     End Sub
     ...
     Private Sub ParseButton_Click()
         If Not IsReadyToParse Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         If Sentence.Text = "" Then
             MsgBox "Must enter sentence before parsing it!"
             Exit Sub
         End If
         On Error GoTo Failed
         SentenceParse.Text = m_patr.ParseString(Sentence.Text)
         Exit Sub
     Failed:
         MsgBox "Parsing sentence failed"
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The PromoteDefaultAtoms property
================================

Interface description
---------------------

     [propget] HRESULT PromoteDefaultAtoms([out, retval] BOOL * pVal);
     [propput] HRESULT PromoteDefaultAtoms([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_PromoteDefaultAtoms(BOOL * pVal);
     HRESULT put_PromoteDefaultAtoms(BOOL newVal);

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

This Boolean property controls whether default atomic feature values
loaded from the lexicon are "promoted" to ordinary atomic feature
values before parsing.  If this property is `true', then default atomic
values are changed to atomic values before parsing; otherwise, they
remain marked as default atomic values.  (This can affect feature
unification since a conflicting default value does not cause a failure:
the default value merely disappears.)

The `PromoteDefaultAtoms' property corresponds to the `set
promote-defaults' command in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     ' TODO: write an example

C++ Example
-----------

     // TODO: write an example

The ReloadLexicon method
========================

Interface description
---------------------

     HRESULT ReloadLexicon();

C++ prototypes
--------------

     HRESULT ReloadLexicon();

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

This method clears the lexicon from memory, and reloads the current set
of lexicon files.  If any of the files fails to load, it is removed from
the list of loaded files.  Only if none of the files loads successfully
is an error returned.  If no lexicon files are currently loaded, the
function returns immediately, reporting success.

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

`S_OK', or an appropriate COM error code

Visual Basic Example
--------------------

     // TODO: write an example

C++ Example
-----------

     #include "PatrParser.h"
     ...
     PatrParser * patr;
     ...
     HRESULT hr = patr->ReloadLexicon();
     if (FAILED(hr))
     {
         ...
     }

The SentenceFinalPunctuation property
=====================================

Interface description
---------------------

     [propget] HRESULT SentenceFinalPunctuation([out, retval] BSTR * pVal);
     [propput] HRESULT SentenceFinalPunctuation([in] BSTR newVal);

C++ prototypes
--------------

     HRESULT get_SentenceFinalPunctuation(BSTR * pVal);
     HRESULT put_SentenceFinalPunctuation(BSTR newVal);

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

This string property specifies the set of (possibly muligraph)
characters that can terminate a sentence in the `\n' fields of input
AMPLE analysis files.  It affects only the `DisambiguateAnaFile' method.

The `SentenceFinalPunctuation' property corresponds to the `set
final-punctuation' command in the PCPATR program.

Default Value
-------------

`. ? ! : ;' (standard English punctuation for marking clauses)

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL'

   * `E_OUTOFMEMORY' if allocating memory fails for either the output
     `BSTR' or the internal list of 8-bit character strings

   * `E_UNEXPECTED' in very bizarre circumstances

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox SentencePunc
           ...
        End
        ...
        Begin MSComDlg.CommonDialog AnaDlg
           ...
        End
        Begin MSComDlg.CommonDialog AnbDlg
           ...
        End
        Begin VB.Menu FileMenu
           Caption         =   "&File"
           ...
           Begin VB.Menu DisambigFileCmd
              Caption         =   "&Disambiguate File..."
           End
           ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         SentencePunc.Text = m_patr.SentenceFinalPunctuation
         ...
     End Sub
     ...
     Private Sub DisambigFileCmd_Click()
         If Not IsReadyToParse Then
             Exit Sub
         End If
         If Not DoSettings Then
             Exit Sub
         End If
         On Error GoTo Cancelled
         AnaDlg.ShowOpen
         AnbDlg.ShowOpen
         On Error GoTo Failed
         m_patr.SentenceFinalPunctuation = SentencePunc.Text
         m_patr.DisambiguateAnaFile AnaDlg.FileName, AnbDlg.FileName
         MsgBox "Done parsing " & AnaDlg.FileName
         Exit Sub
     Failed:
         MsgBox "Parsing " & AnaDlg.FileName & " into " &
             AnbDlg.FileName & " Failed"
         Exit Sub
     Cancelled:
         Exit Sub
     End Sub

C++ Example
-----------

     // TODO: write an example

The TimeLimit property
======================

Interface description
---------------------

     [propget] HRESULT TimeLimit([out, retval] long * pVal);
     [propput] HRESULT TimeLimit([in] long newVal);

C++ prototypes
--------------

     HRESULT get_TimeLimit(long * pVal);
     HRESULT put_TimeLimit(long newVal);

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

This integer property specifies the maximum number of seconds that a
parse is allowed to take.  A value of `0' means that no time limit is
imposed.

NOTE: this is still experimental.  The program *may* crash some time
after terminating a parse due to exceeding the time limit.  (Don't say I
didn't warn you!)

The `TimeLimit' property corresponds to the `set limit' command in the
PCPATR program.

Default Value
-------------

`0' (no limit)

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.TextBox TimeLimit
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         Dim limit As Integer
         limit = m_patr.TimeLimit
         If limit = 0 Then
             TimeLimit.Text = "(no limit)"
         Else
             TimeLimit.Text = limit
         End If
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         If TimeLimit.Text = "(no limit)" Then
             m_patr.TimeLimit = 0
         Else
             m_patr.TimeLimit = TimeLimit.Text
         End If
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The TopDownFilter property
==========================

Interface description
---------------------

     [propget] HRESULT TopDownFilter([out, retval] BOOL * pVal);
     [propput] HRESULT TopDownFilter([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_TopDownFilter(BOOL * pVal);
     HRESULT put_TopDownFilter(BOOL newVal);

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

This Boolean property controls whether top-down filtering is imposed on
the chart parser.  If this property is `true', then top-down filtering
is used; otherwise, top-down filtering is not used.

Top-down filtering speeds up parsing by ruling out obviously invalid
parses earlier in the process.  However, it may possibly rule out valid
parses as well in rare cases.  This is not a problem for most grammars.

The `TopDOwnFilter' property corresponds to the `set top-down-filter'
command in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox TopDownFilter
           Caption         =   "Enable Top Down Filtering"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         TopDownFilter.Value = m_patr.TopDownFilter
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.TopDownFilter = TopDownFilter.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The TopFeatureOnly property
===========================

Interface description
---------------------

     [propget] HRESULT TopFeatureOnly([out, retval] BOOL * pVal);
     [propput] HRESULT TopFeatureOnly([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_TopFeatureOnly(BOOL * pVal);
     HRESULT put_TopFeatureOnly(BOOL newVal);

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

This Boolean property controls whether features structures are displayed
for all nodes of a parse tree, or only for the top node.  If it is
`true', then only the feature structure for the top node in the parse
tree is displayed.  If it is `false', then the feature structures for
all nodes in the parse tree are displayed.

Note that while the `DisplayFeatures' property is `false', this
property has no effect on the parse output.

The `TopFeatureOnly' property corresponds to the `set features top' and
`set features all' commands in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox TopFeatureOnly
           Caption         =   "Top Feature Only"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         TopFeatureOnly.Value = m_patr.TopFeatureOnly
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.TopFeatureOnly = TopFeatureOnly.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The TreeDisplay property
========================

Interface description
---------------------

     [propget] HRESULT TreeDisplay([out, retval] long * pVal);
     [propput] HRESULT TreeDisplay([in] long newVal);

C++ prototypes
--------------

     HRESULT get_TreeDisplay(long * pVal);
     HRESULT put_TreeDisplay(long newVal);

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

This integer property controls the format of the parse trees displayed
in the parse output.  It can take one of these values:
`0'
     No parse tree is displayed.

`1'
     The parse tree is displayed as a parenthesized list, similar to
     how LISP would represent a tree.

`2'
     The parse tree is displayed as a tree using ASCII characters to
     draw the branches, and depending on using a fixed width font to
     look reasonable.

`3'
     The parse tree is displayed as an indented list with each node on a
     separate line, similar to an outline.

`4'
     The parse tree is displayed in XML format, with the feature
     structure for each node included with the node rather than being
     displayed separately.  This is the least readable form for humans,
     but the most tractable for computer programs to parse for
     displaying results graphically.  (This setting overrides any
     properties that control the display of feature structures.)

The `TreeDisplay' property corresponds to the `set tree' command in the
PCPATR program.

Default Value
-------------

`2' (full ASCII tree)

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

`S_OK', or one of these COM error codes:
   * `E_POINTER' if `pVal' is `NULL',

   * `E_INVALIDARG' if `NewVal' is out of range (less than `0' or
     greater than `4')

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.Frame Frame2
           ...
           Begin VB.OptionButton ParseTreeXML
              Caption         =   "XML"
              ...
           End
           Begin VB.OptionButton ParseTreeIndented
              Caption         =   "Indented"
              ...
           End
           Begin VB.OptionButton ParseTreeFlat
              Caption         =   "Flat"
              ...
           End
           Begin VB.OptionButton ParseTreeFull
              Caption         =   "Full"
              ...
           End
           Begin VB.OptionButton ParseDisplayOff
              Caption         =   "Off"
              ...
           End
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         Select Case m_patr.TreeDisplay
             Case 0
                 ParseDisplayOff.Value = True
             Case 1
                 ParseTreeFlat.Value = True
             Case 2
                 ParseTreeFull.Value = True
             Case 3
                 ParseTreeIndented.Value = True
             Case 4
                 ParseTreeXML.Value = True
             Case Else
                 ' actually an error, but ...
                 ParseTreeFull.Value = True
                 m_patr.TreeDisplay = 2
         End Select
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         If ParseDisplayOff.Value Then
             m_patr.TreeDisplay = 0
         ElseIf ParseTreeFlat.Value Then
             m_patr.TreeDisplay = 1
         ElseIf ParseTreeFull.Value Then
             m_patr.TreeDisplay = 2
         ElseIf ParseTreeIndented.Value Then
             m_patr.TreeDisplay = 3
         ElseIf ParseTreeXML.Value Then
             m_patr.TreeDisplay = 4
         Else
             ' should never happen
             m_patr.TreeDisplay = 2
         End If
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The TrimEmptyFeatures property
==============================

Interface description
---------------------

     [propget] HRESULT TrimEmptyFeatures([out, retval] BOOL * pVal);
     [propput] HRESULT TrimEmptyFeatures([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_TrimEmptyFeatures(BOOL * pVal);
     HRESULT put_TrimEmptyFeatures(BOOL newVal);

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

This Boolean property controls whether feature structures with null
values are displayed.  If it is `true', then feature structures that
are null are not displayed, and if they have a label as part of a
complex feature structure, their label is not displayed either.  If it
is `false', then null feature structures are displayed as `[]' in the
parse output.

Note that while the `DisplayFeatures' property is `false', this
property has no effect on the parse output.

The `TrimEmptyFeatures' property corresponds to the `set
trim-empty-features' command in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox TrimEmptyFeatures
           Caption         =   "Trim Empty Features"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         TrimEmptyFeatures.Value = m_patr.TrimEmptyFeatures
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.TrimEmptyFeatures = TrimEmptyFeatures.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The Unification property
========================

Interface description
---------------------

     [propget] HRESULT Unification([out, retval] BOOL * pVal);
     [propput] HRESULT Unification([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_Unification(BOOL * pVal);
     HRESULT put_Unification(BOOL newVal);

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

This Boolean property controls whether feature unification failures
affect the parse process.  If it is `true', then a unification failure
causes a parse failure.  If it is `false', then a unification failure
is noted, but does not otherwise affect the parse.

Note that this property does *not* control whether feature unification
is performed: it controls only whether the result of the unification
affects the parse process.

The `Unification' property corresponds to the `set unification' command
in the PCPATR program.

Default Value
-------------

`true'

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox EnableUnification
           Caption         =   "Enable Unification"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         EnableUnification.Value = m_patr.Unification
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.Unification = EnableUnification.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

The WriteAmpleParses property
=============================

Interface description
---------------------

     HRESULT WriteAmpleParses([out, retval] BOOL * pVal);
     HRESULT WriteAmpleParses([in] BOOL newVal);

C++ prototypes
--------------

     HRESULT get_WriteAmpleParses(BOOL * pVal);
     HRESULT put_WriteAmpleParses(BOOL newVal);

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

This Boolean property controls whether syntactic parse trees are written
to the disambiguated AMPLE analysis file created by a call to the
`DisambiguateAnaFile' method.

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

`S_OK', or `E_POINTER' if `pVal' is `NULL'

Visual Basic Example
--------------------

     Begin VB.Form Form1
        ...
        Begin VB.CheckBox WriteParses
           Caption         =   "Write Parses of AMPLE Sentences"
           ...
        End
        ...
     End
     ...
     Dim m_patr As PatrParser
     Private Sub Form_Load()
         On Error GoTo Failed
         If m_patr Is Nothing Then
             Set m_patr = New PatrParser
         End If
         Call resetdialogbox
         ...
         Exit Sub
     Failed:
         MsgBox "Unexpected error while initializing"
         Exit Sub
     End Sub
     ...
     Private Sub resetdialogbox()
         ...
         WriteParses.Value = m_patr.WriteAmpleParses
         ...
     End Sub
     ...
     Private Function DoSettings() As Boolean
         ...
         m_patr.WriteAmpleParses = WriteParses.Value
         ...
     End Function

C++ Example
-----------

     // TODO: write an example

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

THIS HAS YET TO BE WRITTEN.