Data types

There are a few Experian-specific data types which appear in the documentation and need some explanation. These types define the parameters that the functions take and values they return.

These can be split into three categories: the values that are returned by the functions, the parameters that go into the functions, and the parameters you get out of the functions.

Function return values

Pro data type	Description	Equivalent 'C' data type	Actual Size
INTRET	integer	int	32 bits
LONGRET	long integer	long	32 bits on Windows / 64 bits on Unix
VOIDRET	no return value	void	-

Parameters (Input)

Pro data type	Description	Equivalent 'C' data type	Actual Size
STRVAL	string	char *	64 bit ptr
INTVAL	integer	int	32 bits
LONGVAL	long integer	long	32 bits on Windows / 64 bits on Unix
VOIDARG	no arguments	void	-

Parameters (Output)

Pro data type	Description	Equivalent 'C' data type	Actual Size
STRREF	string	char *	64 bit ptr
INTREF	integer	int *	64 bit ptr
LONGREF	long integer	long *	64 bit ptr
VOIDREFREF	pointer to void pointer	void **	64 bit ptr

Calling functions from languages other than C

Whilst C is the language most commonly used when working with these API functions, it is possible to integrate the API with other programming environments. There are, however, a few points which you should note. These are:

• NULL Termination
• Padding
• Passing by Value or by Reference

Null termination

Pro API is written in the C programming language. In C, all strings are expected to end with the NULL character (i.e. NULL terminated), which has the absolute value 0 (zero), not ASCII '0'.

For all functions in the API that accept parameters of the type STRVAL, these parameters must be NULL terminated. Furthermore, all return parameters of type STRREF will be NULL terminated.

In BASIC, for instance, string termination can be achieved by appending the NULL characters to all strings, as shown in the following example:

MyString$ = "Hello" + Chr$(0)

Padding

API functions that return a string (STRREF) into a buffer will automatically NULL terminate the result. However, you should create this buffer and ensure that it is large enough to hold any string which the function is likely to return.

Consider, for example, the programming language BASIC. In BASIC, strings are not normally stored in fixed length memory blocks. Rather, they occupy only the minimum amount of memory needed to store their value - which changes as the string changes.

Therefore, before you pass a string into a function you must first 'pad' it out. This means adding extra characters to the string in order to force the system into allocating enough memory to hold any possible return string.

In BASIC you might pad a string with two hundred '+' characters, like this:

retBuffer$ = STRING$(200, "+")

Alternatively, you could create a string with two hundred space characters like this:

retBuffer$ = SPACE$(200)

After an API function has returned a string, it might be necessary to strip off the NULL character if it cannot be handled by the calling language.

In BASIC this can be achieved as follows:

nullOffset=INSTR(retBuffer$, CHR$(0))
IF nullOffset>0 THEN retBuffer$=LEFT$(retBuffer$, nullOffset -1)

Passing by value or by reference

In general C programming, function parameters may be passed either by value or by reference.

You must pass a parameter in the way the function expects you to pass it. If you pass a parameter by value when the function is expecting it to be passed by reference then this might crash your program and will certainly produce incorrect results.

• In C programming, strings are always passed by reference, whether they are input or output parameters. However, this is not true of all languages, and strings may be passed by value in the language you are using.
• Numbers are passed by value when they are inputs to the function. They are passed by reference when they are outputs from the function.

Returned strings

When passing a buffer to an API function parameter that returns a string, the next parameter normally defines the size of the buffer passed. The following function prototype demonstrates this type of function:

INTRET QA_GetActiveData           ( INTVAL viHandle,
                                    STRREF rsDataID,
                                    INTVAL viDataIDLength );

Here, the parameter viDataIDLength is the length of the buffer passed with rsDataID.

If the buffer length parameter is zero, then the API function will not attempt to populate the buffer with the return string. The parameter that receieves the buffer can optionally be passed NULL in combination with a zero buffer length, if the integration language supports this.

If the buffer length parameter is greater than zero, then the integrator should ensure that the buffer size is large enough to receive the returned string. If this is not the case, then truncation will occur, and will be logged in the error log file.

INTRET QA_GetData            ( INTVAL viHandle,
                               INTVAL viDataOffset,
                               STRREF rsDataID,
                               INTVAL viDataIDLength,
                               STRREF rsName,
                               INTVAL viNameLength );

int QA_GetData         ( int viHandle,
                         int viDataOffset,
                         char *rsDataID,
                         int viDataIDLength,
                         char *rsName,
                         int viNameLength );

Declare Function QA_GetData Lib "qaupigd.dll"         ( ByVal viHandle As Integer,
                                                        ByVal viDataOffset As Integer,
                                                        ByRef *rsDataID As String,
                                                        ByVal viDataIDLength As Integer,
                                                        ByRef *rsName As String,
                                                        ByVal viNameLength As Integer ) As Integer