API:FAQ

How To Set Your License Key?

Set Your Environment Variable For Windows

Set Your Environment Variable For Linux

What development environment will the API work with?

The APIs are available for the following platforms: Windows®, Linux®, AIX and can be used with any programming language such as C#, Java, Python, C/C++.

What type of support do you offer?

Technical support is always free, as are the frequent updates, and many online resources found on our website.

Environment Variables

MDADDR_SERVERMODE

Currently, MDADDR_SERVERMODE only has one value, “sticky”. Sticky is an option that can be set to change the way Address Object behaves when many instances are created and destroyed. This variable, turned off by default, will enable Address Object to retain some of the data files used for initialization in memory after the last instance of Address Object is de-allocated, but before the application ends. This may be useful for applications that use multiple instances (For example: Web services that use individual threads for each client) and have times where the number of instances drop to 0 while the application is still running. Using this variable should increase the speed of initialization for those qualifying applications. To set the sticky variable, follow these steps:

• For Unix (Linux and Solaris), add these lines to .cshrc or .profile of the login account that is running Address Object:

csh, tcsh:
setenv MDADDR_SERVERMODE sticky

bash, sh, ksh:
MDADDR_SERVERMODE=sticky
export MDADDR_SERVERMODE

• For Windows, add the following entry to your system environment variables:

Variable Name: MDADDR_SERVERMODE
Value: sticky

Then restart the application using Address Object.

How do I use checksums to validate the integrity of my files?

Checksums are codes generated from files that can be used to check the integrity of a file. If two files have the same checksum, they can be assumed to be the same file. At Melissa Data, we use a md5 checksum utility (http://www.fourmilab.ch/md5/). If our tech support asks for your checksum, you can download the command line utility at the URL above. Then, after unzipping it, navigate to md5.exe from the command line, and type md5 “filename” for the checksum. We will then compare your checksum to ours to see if any corruption has occurred.

What is in my DQ Suite DVD?

Here is a general overview of the structure and contents of the DQ Suite DVD:

• Root

setup.exe [For Windows install]

setup.sh [For Linux/Solaris install]

changes.txt [Text file containing latest changes and updates]

qstart.pdf [PDF file containing descriptions of the Objects, Install guides, Implementation guides, and other important information]

• Included Data Quality Objects Folders

The Included Data Quality Objects folders are separated into the different Objects included in your DQ Suite DVD: Address Object, Email Object, Name Object and Phone Object.

Each folder contains a PDF manual explaining the Objects’ methods, properties and initialization procedures.

• Data Files Folder

Each Included Data Quality Objects directory contains a Data Files folder which contains necessary files to run the Object.

For Address Object, the Data Files directory contains necessary data files as well as folders to the different Add-ons (DPV, LACSLink, SuiteLink, AddressPlus, RBDI and mdCanada).

• Operating System Folders

Each Included Data Quality Tool directory contains folders for different Operating Systems: Windows, Linux, AIX, and Solaris.

• Sample Codes, Technologies (For Windows) and Libraries Folders

Located within each Operating System Directory are folders for interfaces, samples, technologies and libraries.

The interfaces and samples folders contain sample codes for different types of languages. Interface samples include wrappers for their respective languages.

Readme files are included for step by step instructions on how to run sample codes.

The Windows directory contains folders for COM and DLL technologies. The COM and DLL files are needed in order for the windows sample codes to run.

All other Operating Systems contain Library folders for specific compilers such as GCC. These libraries are needed in order for the sample codes to run.

• Extras

This folder contains an Adobe Reader 9 installer for viewing PDF files, barcode fonts used for presorting, and other generic libraries used by Windows.

The extras folder also contains a dashboard that provides you a more detailed overview of the Data quality suite.

New scripts for automating the download and update procedure for Address, Name, Phone, Email, and Geocoder objects are now located in the extras directory.

How do I automate the DQ Suite setup?

For Windows

The Windows Setup program for Data Quality Tools accepts optional command line parameters. These can be useful to system administrators and to other programs calling the Setup program wishing to automate the entire process without clicking on the dialogs.

Run the Setup on a test machine like so:

D:\\setup.exe /SAVEINF="c:\\setup.inf" - This can be any file name you wish.

This instructs Setup to save installation settings to the specified file.

Now for any number of other machines, setup can run off the created INF file to run an identical setup on each individual machine.

D:\\setup /LOADINF="c:\\Scripts\\setup.inf" /SILENT /SUPPRESSMSGBOXES

This instructs Setup to load the settings from the specified file after having checked the command line. This file can be prepared using the '/SAVEINF=' command as explained above.

Acrobat Reader must already be installed on the client machine for a truly silent install.

Note: Please remember to use quotes if the filename contains any spaces.

For Unix

The unix installer can take flags to set all the options of a install in one line. To customize an install, run the installer once through interactive mode and customize it the way you like. Then, copy the command line options that the install will provide you to replicate the install on other machines.

What do I need to do when installing the DQ Suite DVD?

When you install the DQ Suite DVD, please pay attention to changes.txt on the root of the DVD. It will contain any changes that have been made to any of the objects which may require you to rewrite/recompile your application. Also, when using the wrappers in the Interfaces folder, please read the readmes for each wrapper you are using as they may contain changes to the build process you have to make.

What is a wrapper and how do I use it?

A wrapper is an additional layer of code that acts as an interface from the standard AddressObject dll to the target programming language. Currently, wrappers are available for dotNET, Java, PHP, PERL, Python, Ruby and OWB. In order to use the wrapper, both the underlining code and the wrapper itself must be installed. So, to first install the underlying code, run the install for AddressObject on the root of the DQ Suite DVD. Now, you must install the wrapper itself. Look in the Interfaces folder of the DVD and locate the language and platform of the wrapper you want. Then, follow the readme to install the wrapper. Once installed, again refer to the readme for instructions to setup and run.

What is multi-threaded programming, with respect to MelissaDATA’s data quality tools?

When working with MelissaDATA API components, you are multi-threading in these situations:

• You have several threads, each creating an instance of an object.
• You have several threads, all using a single (or a few) instances of an object.

Be aware that sometimes you are multi-threading without even realizing it. This is particularly true for web applications. For example, a web service will often handle multiple requests simultaneously. Each request will be handled on a separate thread, though the code you have written to handle a request is oblivious to this.

What should be my primary concerns?

Primarily, the thread that creates an instance to an object ‘owns’ that instance and any other threads should not use that instance. If you choose to violate this rule and ‘share’ instances across threads, your program must ensure that a thread is completely done using the instance before another thread attempts to use it. Often, this is done through the use of critical sections, mutexes or semaphores. Bear in mind that it is very difficult to debug multi-threaded applications, and the precautions needed to share instances further complicate the issue. The more practical solution is to ensure that each thread owns its own instance. However, when working with large numbers of threads, this can be problematic, as operating system limitations (open threads, file handles, memory, etc) can be a limiting factor.

Why is threading an issue?

At any given moment, an instance exists at a certain state. Two threads calling the same instance will usually cause the instance to change states in unexpected ways, leading to incorrect results and/or crashes. For example, say thread 1 calls the Address Object (AO) with an address. The AO at this point is in ‘State A’. Then, before thread 1 can obtain the AO’s results, thread 2 calls the AO with a different address, putting it into ‘State B’. When thread 1 retrieves its results, it will retrieve the ‘State B’ results rather than the correct ‘State A’ results.

Can MelissaDATA’s API components detect improper thread usage and handle the situation accordingly?

No, they cannot. It is not a fault of the programming, but rather is inherent to the way microprocessors and operating systems are designed and used.

If I’m using a single-core/single-CPU machine, I don’t have to worry about threading issues, right?

Wrong. The synchronization issue discussed in question 2 can happen even if the threading is not exactly simultaneous.

Not able to compile PHP interface in PHP Version 5.3.x, any solutions.

Current SWIG source file mdAddrPHPWrapper.cpp on the disk file is not compatible with Php Version 5.3.x. SWIG wrapper were compiled using PHP 5.2.x. In PPH 5.2.x, SWIG wrappers use zend_error_noreturn() function which is no longer avialable in PHP 5.3.x. To create compatible mdAddrPHPWrapper.dll with Php 5.3.x, you need to make changes in mdAddrPHPWrapper.cpp manually. Open mdAddrPHPWrapper.cpp in text pad and replace “zend_error_noreturn” with “zend_error “. After making changes in mdAddrPHPWrapper.cpp compile wrapper again using CreateDll.bat file.

xxxxObj.dll was loaded but the call to DllRegisterServer failed with the error code 0x80020009 or 0x80050007

The error is caused when the user does not have the administrative rights to register an object. Log into windows as an administrator or command a command prompt as an administrator and try to register again. This security feature was introduced in Windows 7 and Windows Server 2008.

'MelissaData.mdxxxxCSPINVOKE’ threw an exception

The error is caused when the .NET wrapper cannot find one or more necessary components. Make sure all necessary components are in the correct directories. Melissa Data .NET wrappers are generated using an open source project called SWIG. The chain of dependent libraries are as follows:

.NET project ---references--> mdxxxxNET.dll ---uses--> mdxxxxCS.dll ---uses--> mdxxxx.dll.

Example: For address check .NET wrapper, mdAddrNET.dll uses mdAddrCS.dll which uses mdAddr.dll.

Make sure all of these files are in the correct locations. The easiest way to ensure this is to place them all into the same directory, usually the same directory as your .NET project executable (bin/debug or bin/release).

64-bit System

Working with the .NET wrapper changes if a use is on a x64 system. On a 64bit machine, they can choose to execute in 32bit mode or 64bit mode, but whatever mode they choose, all components must have the same architecture.

Working in 32bit on a 64bit machine:

All provided dll’s on the DQ Suite are in 32bit. So, grab the existing mdxxxxNET.dll, mdxxxxCS.dll and dll_32bit/mdxxxx.dll. You also have to change to build target of your .NET application because on a x64 machine, the default ‘Any CPU’ option will default to 64bit. Go to Properties->Build->Target Platform and select x86.

Working in 64bit on a 64bit machine

To work in x64, you must recompile mdxxxxNET.dll and mdxxxxCS.dll into 64bit. Go into the source folder and run CreateDLLs.bat with a x64 Visual Studio command script. Please see the readme.txt and open CreateDLLs.bat in wordpad for more details. Then, grab dll_64bit/mdxxxx.dll. Go to Properties->Build->Target Platform and change to x64.

If you are working with IIS express in Visual Studio, go to Tools > Options > Projects and Solutions > Web Projects > Use the 64 bit version of IIS Express for websites and projects checkbox.

mdxxxxJavaWrapper.dll: Can't find dependent libraries

The error is caused when the Java wrapper cannot find one or more necessary components.Make sure all necessary components are in the correct directories. Melissa Data Java wrappers are generated using an open source project called SWIG. The chain of dependent libraries are as follows:

Java project ---references--> mdxxx.jar and mdxxxxJavaWrapper.dll ---uses--> mdxxxx.dll.

Example: For address check java wrapper, mdAddr.jar and mdAddrJavaWrapper.dll uses mdAddr.dll.

Make sure all of these files are in the correct locations. The easiest way to ensure this is to place them all into the same directory, usually the same directory as your java project executable.

64-bit System

Working with the java wrapper changes if a use is on a x64 system. On a 64bit machine, they can choose to execute in 32bit mode or 64bit mode, but whatever mode they choose, all components must have the same architecture.

Working in 32bit on a 64bit machine:

All provided dll’s on the DQ Suite are in 32bit. So, run the java wrapper as instructed in the readme. However, be sure you are using the 32bit version of java.

Working in 64bit on a 64bit machine

To work in x64, you must recompile mdxxxxJavaWrapper.dll into 64bit. To do so, go into the Source folder, and run CreateDLL.bat with a x64 Visual Studio command prompt. See the readme.txt and open CreateDLL.bat in wordpad for more details. Then, use the 64bit mdxxxxJavaWrapper.dll and dll_64bit/mdxxxx.dll. Also, be sure to path CreateDLL.bat, CreateJarFile.bat, and RunSample.bat to use the 64bit version of java.

"Cannot open shared object file"

Receiving "Cannot open shared object file: No such file or directory at" error message when trying to use a interface. Users typically get this error when the generated wrapper .so file cannot find the target .so library. To see this, do a ldd on the wrapper .so file and make sure all the dependency links are satisfied. If the target library dependency link is not satisfied, set your LD_LIBRARY_PATH environment variable to the directory containing the target library and try again. In AIX, the environment variable is called LIBPATH.

"skipping incompatible /th/melissadata/libmdxxxx.so when searching for -lmdxxxx"

The error is caused when the melissa data unix library is not compatible with your system. There are several configurations that must match for your system to be able to run our libraries on our unix platforms. Please make sure that your glibc version matches or is compatible with the provided library and that you are using the correct width (32 or 64 bit).

Debugging: Run a ldd command on mdxxxx.so and libmdxxxxJavaWrapper.so. All dependencies should have a corresponding library mapped. If you are having trouble still, please send the output of these two ldd commands along with a 'uname -a' to tech support.

Unable to establish SSL connection when downloading DQ Suite via wget Tool

If you encounter an SSL connection error when downloading the DQ Suite file using the wget tool, you can try adding the following options to your command to fix this issue:

1. We're moving away from TLS 1.1 to TLS 1.2 so you need to add the –secure-protocol option:

   --secure-protocol=TLSv1_2

2. If you get a 302 redirect to a different domain, try adding the --mirror option.

   --mirror https://update.melissadata.com