Data types

There are a few specific data types which appear in the API and need some explanation. These types define the parameters that the functions take and values they return. They can be split into three categories:

• the values that are returned by the functions.
• the parameters that go into the functions.
• the parameters you get out of the functions.

Equivalent C data types are shown, but additional type modifiers are applied for certain environments, such as Windows.

Function return values

Batch API data type	Description	Equivalent C data type
INTRET	integer	int
LONGRET	long integer	long
VOIDRET	no return value	void

Parameters (Input)

Batch API data type	Description	Equivalent C data type
STRVAL	string	char *
INTVAL	integer	int
LONGVAL	long integer	long
VOIDARG	no arguments	void

Parameters (Output)

Batch API data type	Description	Equivalent C data type
STRREF	string	char *
INTREF	integer	int *
LONGREF	long integer	long *

Calling functions from languages other than C

While C is the language most commonly used when working with these API functions, it is perfectly possible to work in other programming environments. However, there are a few points which you should note. These are:

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

Passing by value or by reference

In normal C programming, function parameters can 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.

• Strings are always passed by reference, whether they are input or output parameters.
• Numbers are passed by value when they are inputs to the function. They are passed by reference when they are outputs from the function.

NULL termination

Batch API is written in the C programming language. In C, all strings are expected to be terminated with a NULL. The NULL character is the absolute character 0 (zero), not ASCII '0'.

For the Batch API functions, all parameters of type STRVAL 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 the strings, as in this example:

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

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 could be achieved as follows:

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

Padding

When an API function returns a result, it writes a NULL-terminated result string into a buffer. You are responsible for creating this buffer. You must ensure that it is big 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)

Example of data types

The example below uses the function QABatchWV_DataSetInfo. This is how the function prototype looks in the documentation:

INTRET QABatchWV_DataSetInfo
    (INTVAL viHandle,
    STRVAL vsIsoCode,
    INTREF riDaysLeft,
    INTREF riDataDaysLeft
    INTREF riLicenceDaysLeft
    STRREF rsVersion,
    INTVAL viVerLength,
    STRREF rsCopyright,
    INTVAL viCopyrightLength);

The parameters viHandle and viVerLength are inputs to the function (in the form of integers) and thus are passed by value. The parameter rsVersion is an output parameter (in the form of a string), and consequently it is passed by reference. Similarly, the parameter riDaysLeft is also passed by reference as it is output by the function in the form of an integer.

In addition, QABatchWV_DataSetInfo returns a status value which indicates either the successful execution of the function, or else failure - via an error code.

This function can be written in native C as:

int QABatchWV_DataSetInfo
    (int viHandle,
    char *vsIsoCode,
    int *riDaysLeft,
    int *riDataDaysLeft,
    int *riLicenceDaysLeft,
    char *rsVersion,
    int viVerLength,
    char *rsCopyright,
    int viCopyrightLength);

On 32-bit system, Visual BASIC for Windows would declare this function as:

Declare Function QABatchWV_DataSetInfo Lib "QABWVED.DLL"
    (ByRef viHandle As Long,
    ByRef vsIsoCode As String,
    ByRef riDaysLeft As Long,
    ByRef riDataDaysLeft As Long,
    ByRef riLicenceDaysLeft As Long,
    ByRef rsVersion As String,
    ByRef viVerLength As Long,
    ByRef rsCopyright As String,
    ByRef viCopyrightLength As Long)
    As Long

On 64-bit system, Visual BASIC for Windows would declare this function as:

Declare Function QABatchWV_DataSetInfo Lib "QABWVGD.DLL"
    (ByRef viHandle As Long,
    ByRef vsIsoCode As String,
    ByRef riDaysLeft As Long,
    ByRef riDataDaysLeft As Long,
    ByRef riLicenceDaysLeft As Long,
    ByRef rsVersion As String,
    ByRef viVerLength As Long,
    ByRef rsCopyright As String,
    ByRef viCopyrightLength As Long)
    As Long