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)


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.

This example uses the function QA_GetData

This is how the function prototype looks in the documentation:

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

The parameters viHandle and viDataOffset are inputs to the function (in the form of integers) and thus are passed by value. Similarly, the parameters viDataIDLength and viNameLength are also passed by value as they are inputs to the function in the form of integers. The parameters rsDataID and rsName are output parameters (in the form of strings), and consequently are passed by reference.

In addition, QA_GetData returns a status value indicating either the successful execution of the function, or whether an error has occurred (in the form of an error code).

This function can be written in native C as:

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

Visual BASIC for Windows would declare this function as:

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