MatchUp Object:Read-Write:Initialization

From Melissa Data Wiki
Jump to navigation Jump to search

← MatchUp Object Reference

MatchUp Object Read-Write Interface Navigation
Overview
Order of Operations
Functions
Initialization
Mapping
Match Key
Processing
Retrieval



The following functions prepare the Read/Write interface for use and link it to its supporting data files.

SetPathToMatchUpFiles

String value. This function accepts a string value containing the path to the folder containing the MatchUp Read-Write data files. It must be called before calling the InitializeDataFiles function.

To provide maximum compatibility with Windows, three files are installed in your ‘Common App Data’ directory:

Windows Vista and newer
C:\ProgramData\MelissaDATA\MatchUp
Windows XP
C:\Documents and Settings\All Users\Application Data\Melissa DATA\MatchUp

The location of this directory can be changed by users so please note this, as it can often be the source of issues when running the samples/demos.

Syntax mdMU->SetPathToMatchUpFiles(char)
C mdMUReadWriteSetPathToMatchUpFiles(mdMU, char)
.Net mdMU.SetPathToMatchUpFiles = string


SetLicenseString

This function passes the License Key required for MatchUp Object to function. A value of "1" is returned if the License Key is valid, a vlue of "0" is returned for an invalid or empty string.

This function is only required if the environment variable method is not used.

Each customer is issued a License Key when purchasing MatchUp Object or renewing a subscription. This string must be passed to this function to unlock the functionality of MatchUp Object.

The License Key is normally set using an environment variable, either MD_LICENSE or MD_LICENSE_DEMO. Calling this function is an alternative method for setting the License Key, but applications developed for a production environment should only use the environment variable.

When using an environment variable, it is not necessary to call this function.

For more information on setting the environment variable, see Entering Your MatchUp Object License Key.

Syntax int = mdMU->SetLicenseString(char)
C int = mdMUReadWriteSetLicenseString(mdMU, char)
.Net integer = mdMU.SetLicenseString string


SetMatchcodeName

This function selects the matchcode to use for the current Read-Write deduping operation. The SetMatchcodeName function accepts a string value that must match the name of an existing matchcode in the current matchcode file.

Syntax mdMU->SetMatchcodeName(char)
C mdMUReadWriteSetMatchcodeName(mdMU, char)
.Net mdMU.SetMatchcodeName = string


SetMatchcodeObject

This functions selects the matchcode to use for the current Read-Write deduping operation. It largely duplicates the purpose of the SetMatchcodeName function, but instead of accepting a character value containing the name of a matchcode in the current matchcode file, this function accepts a Matchcode object created using the Matchcode Editing interface.

Because this function requires the use of a separate interface to create the Matchcode object variable, it is usually simpler to use the SetMatchcodeName function.

It is possible to use this function to build a new matchcode on the fly using the Matchcode Editing interface. Unless a specific application demands such flexibility, it is usually much simpler to add a new matchcode to the matchcode file and call it using the SetMatchcodeName function.

Syntax mdMU->SetMatchcodeObject(mdMUMatchcode)
C mdMUReadWriteSetMatchcodeObject(mdMU, mdMUMatchcode)
.Net mdMU.SetMatchcodeObject = mdMUMatchcode


SetKeyFile

This function selects the name and file path for the key file that will be used for the current Read-Write deduping operation.

Every instance of the Read-Write interface creates a new key file for each session. Any existing key file with the same name is overwritten. If more than one instance of the Read-Write interface is running on either the same computer or the same network, make certain that they do not point to the same key file. If one instance overwrites the key file being used by another instance, it can cause the second instance to fail.

Syntax mdMU->SetKeyFile(char)
C mdMUReadWriteSetKeyFile(mdMU, char)
.Net mdMU.SetKeyFile = string


SetGroupSorting

This function sets the Read-Write interface to return processed records in dupe group order. By default, the Read-Write interface returns records sorted by their match key. This should return records in the same dupe group together or close to each other.

Passing a boolean "True" value to this function will cause the Read-Write interface to return the processed records sorted into dupe groups.

The additional processing can increase the time needed to dedupe a large list and it is often possible to use the information returned by the Read-Write interface to sort records into this order programmatically.

Syntax mdMU->SetGroupSorting()
C mdMUReadWriteSetGroupSorting(mdMU)
.Net mdMU.SetGroupSorting


SetReserved

Optional. This function accepts two parameters: A string parameter containing the property to be set; and a string parameter representing the value for the property being set.

It must be called before calling the InitializeDataFiles function.

The unique identifier set by SetUserInfo and attached to built match keys is 1024 bytes by default. This lets you pass an advanced custom identifier or even source data to the key file. This can have data handling advantages but will slow down the process because the key file and temporary sort files will grow much larger than needed for most jobs. This function property has been added, allowing you to override the default UserInfo to a more efficient size.

Syntax mdMU->SetReserved(char, char)
C mdMUReadWriteSetReserved(mdMU, char, char)
.Net mdMU.SetReserved(string)


SetMaximumCharacterSize

Optional. This function will accommodate UTF-8 input data. Since a single UTF-8 character can be up to 4 bytes long, the storage of the matchcode keys may need to be altered to accommodate this maximum size. However, if you are working in a part of the world where you are sure that a byte sequence will always be shorter, you can use this function to override the storage overhead.

It must be called before calling the InitializeDataFiles function.

Valid input values are 1, 2, 3 or 4. Invalid values will be ignored and the default size (e.g. if this function is not called) is 1.

Syntax mdMU->SetMaximumCharacterSize(int)
C mdMUReadWriteSetMaximumCharacterSize(mdMU, int)
.Net mdMU.SetMaximumCharacterSize(integer)


SetEncoding

Optional. This function define encoded format of the input file and the resultant format of the build keys. Input data is converted into the UTF-8 format and processed as such. When GetKey is called, the data is converted back from UTF-8 to the specified input format.

The return value is 1 if the desired encoding can be set or 0 if the encoding is not recognized or can not be set.

It must be called before calling the InitializeDataFiles function.

The default encoding type is "ISO-8859-1", if this function is not used.

Syntax mdMU->SetEncoding(char)
C mdMUReadWriteSetEncoding(mdMU, char)
.Net mdMU.SetEncoding(string)


InitializeDataFiles

This function opens the needed data files and prepares the MatchUp Object for use. Before calling this function, the application must have successfully called the SetLicenseString and SetPathToMatchUpFiles functions.

Check the return value of the GetInitializeErrorString function to retrieve the result of the initialization call. Any result other than “No Error” means the initialization failed for some reason.

This returns a value of the enumerated type ProgramStatus.

Value Enumeration Description
0 ErrorNone No error - Initialization was successful.
1 ErrorConfigFile Could not find mdMatchUp.dat.
2 ErrorLicenseExpired The License Key has expired.
3 ErrorDatabaseExpired The database has expired.
4 ErrorMatchcodeNotSpecified No matchcode was specified.
5 ErrorMatchcodeNotFound Specified Matchcode does not exist.
6 ErrorInvalidMatchcode The specified matchcode is not valid.
7 ErrorKeyFile The specified key file was not found.

If any other value other than "ErrorNone" is returned, check the GetInitializeErrorString function to see the reason for the error.

Syntax ProgramStatus = mdMU->InitializeDataFiles()
C int = mdMUReadWriteInitializeDataFiles(mdMU)
.Net ProgramStatus = mdMU.InitializeDataFiles


GetInitializeErrorString

This function returns a string to describe the error caused when the InitializeDataFiles function cannot be successfully called.

The possible strings returned by this function are:

  • "No error"
  • "Could not find mdMatchUp.dat."
  • "The License Key has expired."
  • "The database has expired."
  • "No matchcode was specified."
  • "Specified Matchcode does not exist."
  • "The specified matchcode is not valid."
  • "The specified key file was not found."
Syntax char = mdMU->GetInitializeErrorString()
C char = mdMUReadWriteGetInitializeErrorString(mdMU)
.Net string = mdMU.GetInitializeErrorString


GetBuildNumber

This function returns the current development release build number of MatchUp Object.

Syntax char = mdMU->GetBuildNumber()
C char = mdMUReadWriteGetBuildNumber(mdMU)
.Net string = mdMU.GetBuildNumber


GetDatabaseDate

This function returns a string value that represents the revision date of the MatchUp Object data files.

Syntax char = mdMU->GetDatabaseDate()
C char = mdMUReadWriteGetDatabaseDate(mdMU)
.Net string = mdMU.GetDatabaseDate


GetDatabaseExpirationDate

This function returns a string value containing the expiration date of the current database file (mdMatchUp.dat).

Syntax char = mdMU->GetDatabaseExpirationDate()
C char = mdMUReadWriteGetDatabaseExpirationDate(mdMU)
.Net string = mdMU.GetDatabaseExpirationDate


GetLicenseExpirationDate

This function returns a string value containing the expiration date of the current License Key. After this date, MatchUp Object will no longer function.

Syntax char = mdMU->GetLicenseExpirationDate()
C char = mdMUReadWriteGetLicenseExpirationDat(mdMU)
.Net string = mdMU.GetLicenseExpirationDate