Skip to main content

H4.2 - Reference Guides - C++

Lauren Wheeler
  • Updated
Previous Article matchIT Hub Index Next Article 

Introduction

matchIT Hub provides interfaces for use with a number of programming languages. This reference document details the interface for the C++ programming language, available for use with all supported platforms. There are separate documents for the other interfaces. Note that all interfaces provide the same functionality.

Files

The matchIT Hub C++ API is provided by the following files:

Name Description
matchITHub.lib Windows import library file
matchITHub.dll Windows dynamic link library
libmatchITHub.so Linux shared object file
matchITHub.hpp C++ header file

Classes

The C++ API for matchIT Hub is declared within this header file: matchITHub.hpp.

Engine

The Engine class comprises a number of methods.

To create an instance of the Engine class:

using namespace matchIT::Hub;
...
Engine engine;

or:

matchIT::Hub::Engine engine;

Engine2

The Engine2 class provides all the methods from the Engine class, plus additional methods.

Use the Engine2 class when requiring a method that isn't provided by the Engine class.

Engine3

From version 2.0.3

The Engine3 class provides all the methods from the Engine class, plus additional methods.

Use the Engine3 class when requiring a method that isn't provided by the Engine or Engine2 classes.

Engine Methods

Note that each method that takes one or more character string arguments is overloaded to allow passing either an ANSI-encoded character string, a wide character string (UTF-16 on Windows, UTF-32 on Linux/Unix), or a UTF-8-encoded character string.

All methods return an int that represents success (0) or error (1+). No method throws an exception.

Initialization

Initialize( activationCode, encoding )

Arguments:

  • activationCode - Customer-specific license code. This is usually supplied as a text file, but can be stored within a database table or even embedded within the user's application. Note that the argument does not specify the license code's filename; the contents of the license file must instead be read into a string that's passed in via this argument.
  • encoding - The character encoding that all engine methods use when converting ANSI character strings to UTF-8, for example "LATIN1", "ISO-8859-1", or "MacCyrillic". (Not applicable for Windows, in which the machine's active code page is used; pass a NULL (0) or a blank string ("") instead.)

Description:

Initialize the engine. This method must be called before any other method can be used.

Settings

ApplySettings( xml )

Arguments:

  • xml - XML-formatted string containing the configuration settings.

Description:

Configures the matchIT Hub engine using the supplied settings, provided the engine is currently idle - i.e. no data has been passed in via AddData().

This method can be used with a single configuration string, or can even be called multiple times with different configurations strings to share settings between different processes for example, or to break a single settings file into smaller, more manageable files. Each time a new configuration is applied, existing settings are overridden by the new settings; anything that's not specified in the new configuration is not changed.

Refer to the Configuration Guide for details of the configuration settings and how to create and customize them.

GetSettings( xml, size )

Arguments:

  • xml - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Retrieves the engine's current settings as an XML-formatted string. The pointer specifies a user-owned buffer that the result will be copied into; if this is of insufficient size then the buffer is not modified.

Note that if multiple configuration strings were applied using ApplySettings(), then this method will output a single string that represents an aggregation of all applied settings.

Data

AddData( table, data, timeout )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).
  • data - A delimited string (the first character is the delimiter, which must not be alphanumeric).
  • timeout - Timeout, in milliseconds.

Description:

Adds data to the engine's input buffer. If the buffer is full and a nonzero timeout is specified, then the method will wait until space becomes available, or until the timeout period has elapsed (in which case an error is returned). If a timeout of 0 is used, then the method will wait indefinitely until space becomes available.

When the processing mode is set to Matching, then the table can be 0, 1, or 2. When 0 is specified, then the engine performs matching on a single table of data. When 1 or 2 is specified, then the engine will instead find matches that overlap the two tables.

When the processing mode is set to Lookup, then the table can be 1 or 2. This effectively causes the engine to identify records that overlap the two tables.

When the processing mode is set to Normalization, then the table must be 0. Note that in this instance, the data is discarded immediately after it's processed, and isn't retained in memory.

matchIT Hub stores data internally using the UTF-8 character encoding. Use the UTF-8 overload of AddData() to load data encoded using UTF-8 wherever possible, for maximum efficiency.

GetData( table, uniqueRef, data, size )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).
  • uniqueRef - String that identifies the record.
  • data - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Retrieves the record with the given unique ref from the specified table. Unique refs must identify individual records and thus cannot be optional.

UpdateData( table, newData, timeout )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).
  • newData - A delimited string (the first character is the delimiter, which must not be alphanumeric).
  • timeout - Timeout, in milliseconds.

Description:

The new data is parsed so that the unique ref can be extracted. The existing representation of the record with this unique ref is deleted and the new representation added. Unique refs must identify individual records and thus cannot be optional.

DeleteData( table, uniqueRef, timeout )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).
  • uniqueRef - String that identifies the record to be deleted.
  • timeout - Timeout, in milliseconds.

Description:

Deletes the record with the given unique ref from the specified table. Unique refs must identify individual records and thus cannot be optional.

NoMoreData( table )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).

Description:

Informs the engine that no more data will be added for the indicated table (refer to AddData() for details of the table identifier).

ClearData( table )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).

Description:

Removes and discards all data relating to the indicated table. This includes: buffered input data, cached records, clusters, matching pairs, matching groups. (refer to AddData() for details of the table identifier).

Processing is not interrupted, and any buffered results are left intact.

Results

GetResultCount( count )

Arguments:

  • count - Output, integer pointer.

Description:

Outputs the number of buffered results in the output buffer.

Note that when the processing mode is set to Lookup, the result count is the number of buffered results that are associated with the calling thread, not the total number of buffered results. Refer to the Getting Started | Processing Modes | Lookup for further details on the Lookup mode.

GetNextResult( result, size, timeout )

Arguments:

  • result - Output, character string pointer.
  • size - Maximum number of bytes that can be output.
  • timeout - Timeout, in milliseconds.

Description:

Gets the next buffered result and removes it from the output buffer. The pointer specifies a user-owned buffer that the result will be copied into; if this is of insufficient size then the buffer is not modified.

If no results are available, then the method returns an error. GetResultCount() can be used beforehand to ensure that there are results available.

A timeout can be used to ensure that blocking doesn't occur. For example, if the input buffer is full and AddData() is called with a timeout of 0 then the engine will be blocked; subsequently calling GetNextResult() from another thread, also with a timeout of 0, will cause the method to block until AddData() completes. If both methods are used simultaneously by concurrent threads, then a timeout of 0 should not be used.

Note that when the processing mode is set to Lookup, this method will remove the next buffered result that's associated with the calling thread. Refer to the Getting Started | Processing Modes | Lookup for further details on the Lookup mode.

ClearResults()

No arguments.

Description:

The output buffer is cleared; any buffered results are lost.

Note that when the processing mode is set to Lookup, this method will remove all buffered results, not just those for the calling thread. Refer to the Getting Started | Processing Modes | Lookup for further details on the Lookup mode.

Processing

GetState( state )

Arguments:

  • state - Pointer to a EngineState instance that receives the output.

Description:

Outputs the engine's current state:

  • Uninitialized - the engine has been created but not yet initialized;
  • Initialized - the engine has been initialized but no settings applied;
  • Ready - settings have been applied but no data has been added;
  • Running - data has been added, and the engine is actively processing data or waiting for more data to process;
  • Paused - the engine's processing threads have been temporarily paused;
  • Finished - all data input to the engine has been fully processed and all results have been output;
  • Aborted - the engine's processing threads have been stopped, and no more data can be added.

GetUnprocessedCount( count )

Arguments:

  • count - Pointer to an int that receives the output.

Description:

Outputs the number of records that have not yet been processed. This includes all records that are currently being processed by the processing threads, plus all records in the input buffer.

Note that when the processing mode is set to Lookup, this method returns the unprocessed count that's associated with the calling thread, rather than the total number of unprocessed records. Refer to the Getting Started | Processing Modes | Lookup for further details on the Lookup mode.

GetStats( xml, size )

Arguments:

  • xml - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Produces an XML-formatted string that lists useful statistical details for the current processing mode. This method can be called when processing has completed - to get final statistics - or even during processing to get extended information that supplements GetUnprocessedCount().

The pointer specifies a user-owned buffer that the XML string will be copied into; if this is of insufficient size then the buffer is not modified.

Pause()

No arguments.

Description:

All processing threads within the engine are paused, so no more data will be processed until the engine is resumed. Data can still be added via AddData(), provided there's space in the input buffer. Results can be retrieved from the output buffer.

Resume()

No arguments.

Description:

Resumes processing if the engine was paused.

Abort()

No arguments.

Description:

Aborts processing. All processing threads are stopped. No more data can be added, and any existing buffered input data is not processed. Any results in the output buffer are left intact and can still be retrieved.

Reset()

No arguments.

Description:

Resets the engine so that new data can be added and processed using the current settings. All unprocessed and buffered input data is cleared. All buffered results are cleared.

Restart() - NOT IMPLEMENTED

No arguments.

Description:

Reserved for future use.

Errors

GetNextError( error, size )

Arguments:

  • error - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

All errors are stored internally within a stack. This method retrieves the next error and removes it from the stack. The pointer specifies a user-owned buffer that the error message will be copied into; if this is of insufficient size then the buffer is not modified.

When any engine method fails and returns an error code, additional information about the failure can be retrieved via this method.

Internal processing failures and warnings will also be logged to the stack. Any large clusters encountered during processing are also logged to the stack (refer to the Configuration Guide for details on large clusters).

GetErrorText( code, error, size )

Arguments:

  • code - An integer identifying an error code returned from an engine method.
  • error - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

This method can be used to retrieve a textual description of a specified result code returned from any engine method.

The pointer specifies a user-owned buffer that the error message will be copied into; if this is of insufficient size then the buffer is not modified.

Engine2 Methods

Note that each method that takes one or more character string arguments is overloaded to allow passing either an ANSI-encoded character string, a wide character string (UTF-16 on Windows, UTF-32 on Linux/Unix), or a UTF-8-encoded character string.

All methods return an int that represents success (0) or error (1+). No method throws an exception.

Settings

GetAdvancedSettings( xml, size )

Arguments:

  • xml - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Retrieves the engine's current advanced settings as an XML-formatted string. The pointer specifies a user-owned buffer that the result will be copied into; if this is of insufficient size then the buffer is not modified.

Note that if multiple configuration strings were applied using ApplySettings(), then this method will output a single string that represents an aggregation of all applied settings.

Data

AllowMoreData( table )

Arguments:

  • table - Integer that indicates the table (0, 1, or 2).

Description:

Informs the engine that more data will be added for the indicated table (refer to AddData() for details of the table identifier).

Information

GetVersion( version, size )

Arguments:

  • version - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Returns a string representing the version number of the matchIT Hub engine.

The version consists of four delimited numbers (product.major.minor.patch) plus an optional pre-release indicator, for example "1.0.3.2" or "1.1.0.0 (beta 2)".

GetExpiry( expiry, size )

Arguments:

  • expiry - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Returns an 8-character string of format YYYYMMDD that indicates the expiry date of the applied activation code, for example "20170531".

Engine3 Methods

Note that each method that takes one or more character string arguments is overloaded to allow passing either an ANSI-encoded character string, a wide character string (UTF-16 on Windows, UTF-32 on Linux/Unix), or a UTF-8-encoded character string.

All methods return an int that represents success (0) or error (1+). No method throws an exception.

Settings

GetMatchingMatrices( xml, size )

Arguments:

  • xml - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Retrieves the engine's current matching matrices settings as an XML-formatted string. The pointer specifies a user-owned buffer that the result will be copied into; if this is of insufficient size then the buffer is not modified.

Information

GetMetadata( xml, size )

Arguments:

  • xml - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Retrieves metadata about the settings applied. The pointer specifies a user-owned buffer that the result will be copied into; if this is of insufficient size then the buffer is not modified.

Normalization mode metadata schema:

<metadata>
<mappedComponents>
<component>...</component>
<component>...</component>
...
</mappedComponents>
<outputs>
<output>...</output>
<output>...</output>
...
</outputs>
</metadata>

Matching mode metadata schema:

<metadata>
<mappedComponents>
<component>...</component>
<component>...</component>
...
</mappedComponents>
<outputs>
<output>...</output>
<output>...</output>
...
</outputs>
<matchingMethods>
<recommended>
<method>...</method>
<method>...</method>
...
</recommended>
<additional>
<method>...</method>
<method>...</method>
...
</additional>
</matchingMethods>
</metadata>

Previous Article matchIT Hub Index Next Article 

Related articles