Skip to main content

Syniti Match API - C Reference Guide

Lauren Wheeler
  • Updated

Introduction

Syniti Match API 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 Syniti Match API 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.h C header file

Functions

The C API for Syniti Match API is declared within this header file: matchITHub.h. The API comprises a number of functions declared within the global namespace, all prefixed with "matchIT_Hub_".

Note that each function that takes one or more character string arguments has different versions 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. The different versions of these functions are suffixed with an A, W, or U to represent the different character string encodings.

All functions return an int that represents success (0) or error (1+). The two exceptions are matchIT_Hub_CreateEngine(), which returns a handle to a Syniti Match API engine (matchIT_Hub_Engine), and matchIT_Hub_DeleteEngine(), which has a void return type.

Creation/Destruction

matchIT_Hub_CreateEngine()

No arguments.

Description:

Creates and returns a new Syniti Match API engine instance. This is subsequently passed as the first argument to all other engine functions.

matchIT_Hub_DeleteEngine( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

Description:

Destroys the specified engine and frees all memory used by it.

Initialization

matchIT_Hub_Initialize( engine, activationCode, encoding )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 functions 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 function must be called before any other function can be used.

Settings

matchIT_Hub_ApplySettings( engine, xml )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • xml - XML-formatted string containing the configuration settings.

Description:

Configures the Syniti Match API engine using the supplied settings, provided the engine is currently idle - i.e. no data has been passed in via matchIT_Hub_AddData().

This function 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.

matchIT_Hub_GetSettings( engine, xml, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function will output a single string that represents an aggregation of all applied settings.

matchIT_Hub_GetAdvancedSettings( engine, xml, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function will output a single string that represents an aggregation of all applied settings.

matchIT_Hub_GetMatchingMatrices( engine, xml, size )

From version 2.0.3

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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.

Data

matchIT_Hub_AddData( engine, table, data, timeout )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function 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 function 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.

Syniti Match API stores data internally using the UTF-8 character encoding. Use matchIT_Hub_AddDataU to load data encoded using UTF-8 wherever possible, for maximum efficiency.

matchIT_Hub_GetData( engine, table, uniqueRef, data, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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.

matchIT_Hub_UpdateData( engine, table, newData, timeout )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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.

matchIT_Hub_DeleteData( engine, table, uniqueRef, timeout )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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.

matchIT_Hub_NoMoreData( engine, table )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 matchIT_Hub_AddData() for details of the table identifier).

matchIT_Hub_AllowMoreData( engine, table )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 matchIT_Hub_AddData() for details of the table identifier).

matchIT_Hub_ClearData( engine, table )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 matchIT_Hub_AddData() for details of the table identifier).

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

Results

matchIT_Hub_GetResultCount( engine, count )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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.

matchIT_Hub_GetNextResult( engine, result, size, timeout )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function returns an error. matchIT_Hub_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 matchIT_Hub_AddData() is called with a timeout of 0 then the engine will be blocked; subsequently calling matchIT_Hub_GetNextResult() from another thread, also with a timeout of 0, will cause the function to block until matchIT_Hub_AddData() completes. If both functions 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 function 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.

matchIT_Hub_ClearResults( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

Description:

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

Note that when the processing mode is set to Lookup, this function 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

matchIT_Hub_GetState( engine, state )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • state - Pointer to a matchIT_Hub_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.

matchIT_Hub_GetUnprocessedCount( engine, count )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function 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.

matchIT_Hub_GetStats( engine, xml, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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 function can be called when processing has completed - to get final statistics - or even during processing - to get extended information that supplements matchIT_Hub_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.

matchIT_Hub_Pause( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

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 matchIT_Hub_AddData(), provided there's space in the input buffer. Results can be retrieved from the output buffer.

matchIT_Hub_Resume( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

Description:

Resumes processing if the engine was paused.

matchIT_Hub_Abort( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

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.

matchIT_Hub_Reset( engine )

Arguments:

  • engine - Handle to the Syniti Match API engine.

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.

matchIT_Hub_Restart( engine ) - NOT IMPLEMENTED

Arguments:

  • engine - Handle to the Syniti Match API engine.

Description:

Reserved for future use.

Errors

matchIT_Hub_GetNextError( engine, error, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • error - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

All errors are stored internally within a stack. This function 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 Syniti Match API function fails and returns an error code, additional information about the failure can be retrieved via this function.

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

matchIT_Hub_GetErrorText( code, error, size )

Arguments:

  • code - An integer identifying an error code returned from a Syniti Match API function.
  • error - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

This function can be used to retrieve a textual description of a specified result code returned from any Syniti Match API function.

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.

Information

matchIT_Hub_GetVersion( engine, version, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • version - Output, character string pointer.
  • size - Maximum number of bytes that can be output.

Description:

Returns a string representing the version number of the Syniti Match API 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)".

matchIT_Hub_GetExpiry( engine, expiry, size )

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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".

matchIT_Hub_GetMetadata( engine, xml, size )

From version 2.0.3

Arguments:

  • engine - Handle to the Syniti Match API engine.
  • 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>

Related articles