Types
Every IDL variable has a data type. The possible type codes and their mapping to C language types are listed in the following table. The undefined type code (IDL_TYP_UNDEF) will always have the value zero.
Although it is rare, the number of types could change. Therefore, you should always use the symbolic names when referring to any type except IDL_TYP_UNDEF. Even in the case of IDL_TYP_UNDEF, using the symbolic name will add clarity to your code. Note that all IDL structures are considered to be of a single type (IDL_TYP_STRUCT).
Clearly, distinctions must be made between various structures, but such distinctions are made at a different level. There are a few constants that can be used to make your code easier to read and less likely to break if/when the idl_export.h file changes. These are:
- IDL_MAX_TYPE—The value of the largest type.
- IDL_NUM_TYPES—The number of types. Since the types are numbered starting at zero, IDL_NUM_TYPES is one greater than IDL_MAX_TYPE.
|
Name |
Type |
C Type |
|---|---|---|
|
IDL_TYP_UNDEF |
Undefined |
None |
|
IDL_TYP_BYTE |
Unsigned byte |
UCHAR |
|
IDL_TYP_INT |
16–bit integer |
IDL_INT |
|
IDL_TYP_LONG |
32–bit integer |
IDL_LONG |
|
IDL_TYP_FLOAT |
Single precision floating |
Float |
|
IDL_TYP_DOUBLE |
Double precision floating |
Double |
|
IDL_TYP_COMPLEX |
Single precision complex |
IDL_COMPLEX |
|
IDL_TYP_STRING |
String |
IDL_STRING |
|
IDL_TYP_STRUCT |
Structure |
|
|
IDL_TYP_DCOMPLEX |
Double precision complex |
IDL_DCOMPLEX |
|
IDL_TYP_PTR |
32–bit integer |
IDL_ULONG |
|
IDL_TYP_OBJREF |
32–bit integer |
IDL_ULONG |
|
IDL_TYP_UINT |
Unsigned 16-bit integer |
|
|
IDL_TYP_ULONG |
Unsigned 32-bit integer |
IDL_ULONG |
|
IDL_TYP_LONG64 |
64-bit integer |
IDL_LONG64 |
|
IDL_TYP_ULONG64 |
Unsigned 64-bit integer |
IDL_ULONG64 |
Type Masks
There are some situations in which it is necessary to specify types in the form of a bit mask rather than the usual type codes, for example when a single argument to a function can represent more than a single type. For any given type, the bit mask value can be computed as: Mask = 2TypeCode
The IDL_TYP_MASK preprocessor macro is provided to calculate these masks. Given a type code, it returns the bit mask. For example, to specify a bit mask for all the integer types:
IDL_TYP_MASK(IDL_TYP_BYTE)|IDL_TYP_MASK(IDL_TYP_INT)|
IDL_TYP_MASK(IDL_TYP_LONG)
Specifying all the possible types would require a long statement similar to the one above. To avoid having to type so much for this common case, the IDL_TYP_B_ALL constant is provided.
Mapping of Basic Types
Within IDL, the IDL data types are mapped into data types supported by the C language. Most of the types map directly into C primitives, while IDL_TYP_COMPLEX, IDL_TYP_DCOMPLEX, and IDL_TYP_STRING are defined as C structures. The mappings are given in the following table. Structures are built out of the basic types by laying them out in memory in the specified order using the same alignment rules used by the C compiler for the target machine.
Unsigned Byte Data
UCHAR is defined to be unsigned char in idl_export.h.
Integer Data
IDL_INT represents the signed 16-bit data type and is defined in idl_export.h.
Unsigned Integer Data
IDL_UINT represents the unsigned 16-bit data type and is defined in
idl_export.h.
Long Integer Data
IDL long integers are defined to be 32-bits in size. The C long data type is not correct on all systems because C compilers for 64-bit architectures usually define long as 64- bits. Hence, the IDL_LONG typedef, declared in idl_export.h is used instead.
Unsigned Long Integer Data
IDL_ULONG represents the unsigned 32-bit data type and is defined in idl_export.h.
64-bit Integer Data
IDL_LONG64 represents the 64-bit data type and is defined in idl_export.h.
Unsigned 64-bit Integer Data
IDL_ULONG64 represents the unsigned 64-bit data type and is defined in idl_export.h.
Complex Data
The IDL_TYP_COMPLEX and IDL_TYP_DCOMPLEX data types are defined by the following C declarations:
typedef struct { float r, i; } IDL_COMPLEX;
typedef struct { double r, i; } IDL_DCOMPLEX;
This is the same mapping used by Fortran compilers to implement their complex data types, which allows sharing binary data with such programs.
String Data
The IDL_TYP_STRING data type is implemented by a string descriptor:
typedef struct {
IDL_STRING_SLEN_T slen; /* Length of string */
short stype; /* Type of string */
char *s; /* Pointer to string */
} IDL_STRING;
The fields of the IDL_STRING struct are defined as follows:
slen
The length of the string, not counting the null termination. For example, the string “Hello” has 5 characters.
stype
If stype is zero, the string pointed at by s (if any) was not allocated from dynamic memory, and should not be freed. If non-zero, s points at a string allocated from dynamic memory, and should be freed before being replaced. For information on dynamic memory, see Dynamic Memory.
s
If slen is non-zero, s is a pointer to a null-terminated string of slen characters. If slen is zero, s should not be used. The use of a string pointer to memory located outside the IDL_STRING structure itself allows IDL strings to have dynamically-variable lengths.
Note: Strings are the most complicated basic data type, and as such, are at the root of more coding errors than the other types. See IDL Internals: String Processing.
IDL_MEMINT and IDL_FILEINT Types
Some of the IDL-supported operating systems limit memory and file lengths to a signed 32-bit integer (approximately 2.3 GB). Some systems have 64-bit memory capabilities and others allow files longer than 231-1 bytes despite being 32-bit memory limited. To gracefully handle these differences without using conditional code, IDL internals use two special types, IDL_TYP_MEMINT (data type IDL_MEMINT) and IDL_TYP_FILEINT (data type IDL_FILEINT) to represent memory and file length limits.
IDL_MEMINT and IDL_FILEINT are not separate and distinct types; they are actually mappings to the IDL types discussed in Mapping of Basic Types. Specifically, they will be IDL_LONG for 32-bit quantities, and IDL_LONG64 for 64-bit quantities.
As an IDL internals programmer, do not write code that depends on the actual machine type represented by these abstract types. To ensure that your code runs properly on all systems, use IDL_MEMINT and IDL_FILEINT in place of more specific types. These types can be used anywhere that a normal IDL type can be used, such as in keyword processing. Their systematic use for these purposes will ensure that your code is correct on any IDL platform.
The IDL_MEMINTScalar() and IDL_FILEINTScalar() functions are described in Converting Arguments to C Scalars.