To Next Page

To Previous Page

3.2 The TR122 API

The TR122 application programming interface (API) is provided as a Windows dynamic

link library (DLL) which is installed in the Windows system directory (\WinNT\System32 or

equivalent). Also stored at this location is the binary image file for the gate array in the

instrument. When the API DLL (TR122API.DLL) is loaded by the application, or by the

operating system on behalf of the application, initialization code is executed which finds a

module, loads the gate array, and sets system defaults.

The API exports functions which provide an easy path to use features of the instrument.

Exported functions, data structures, and definitions which will be needed by an application

calling the API are defined in the TR122API.H header file. All exported functions are defined

with a name prefix of TR122_ and will always return an unsigned 32-bit number which will be

set to 1 if the function performs as expected and 0 if a difficulty is encountered. Any substantive

data returned by a function is returned by reference in the arguments.

Several steps are taken to improve compatibility with a wide variety of programming

environments. An export definition file (TR122API.DEF) is part of the source code so that

exported names are explicitly defined for the benefit of environments which may not be aware

of Microsoft name mangling standards. All arguments of exported functions are atomic types

and pointers to atomic types as opposed to complex data structures which may be complicated to

define in some environments. The source code is written in the C programming language with

some Microsoft conventions geared towards the Windows programming model for the Intel

architecture. The following are some useful relationships between data types for arguments in

several software environments.

API Argument Type Description VB Type LabView Type

BYTE Unsigned 8-bit number ByVal Byte uInt8

DWORD Unsigned 32-bit number ByVal Long uInt32

long Signed 32-bit number ByVal Long int32

char* Pointer To 0 Terminated Text String ByVal String CStr

There are several points to consider regarding range of arguments. Any type may also be

presented in an argument as a pointer to data of that type, while the char (strictly a signed 8-bit

number) always appears as a pointer in the API and refers to the location of a null terminated text

string. Generally it is an error for null pointers to be passed in arguments. Some environments

required more work than others to avoid passing null pointers to strings. The BYTE data type is

sometimes used as a number, but is often used as a proxy for a boolean type where 0 is false and

anything else is true. The API avoids the use of 16-bit words of any kind because some

environments do not support them or do not support an unsigned version. The use of the long

integer type implies that the API is expecting a signed number. The DWORD data type implies

that the API is expecting an unsigned number. However, in the later case the range will in most

cases be less than 31 bits so that environments such as Visual Basic (VB) which do not have an

unsigned 32-bit number can use a signed 32-bit number in its place.

DDC TR122 User Manual

Questions and Answers: