[Top] [Prev]

2.4 Programming Issues

This section introduces information relevant to the process of developing programs that use the HDF library, such as the names of necessary header files, lists of common definitions and issues concerning FORTRAN-77 and C programming.

2.4.1 Header File Information

The header file "hdf.h" must be included in every HDF application program written in C, except for programs that call routines in the SD interface. The header file "mfhdf.h" must be included in all programs that call SD interface routines.

Fortran programmers who use compilers that allow file inclusion can include the files "hdf.inc" and "dffunc.inc". If a Fortran compiler that does not support file inclusion is used, HDF library definitions must be explicitly defined in the Fortran program as they are included in the header files of the HDF library.

2.4.2 HDF Definitions

The HDF library provides several sets of definitions which can be used easily in the user applications. These sets include the definitions of the data types, the data type flags, and the limits that set various maximum values. The definitions of the data types supported by HDF are located in the "hdf.h" header file, and the data type flags are located in the "hntdefs.h" header file. Both are also included in Table 2E on page 13, Table 2F on page 14, and Table 2G on page 14. HDF data types are used for portability in the declaration of variables, and data type flags are used as parameters in various HDF interface routines.

2.4.2.1 Standard HDF Data Types

The definitions of the fundamental data types are in Table 2E. Although DFNT_FLOAT (or 5), DFNT_UCHAR (or 3), and DFNT_CHAR (or 4) have not been added to this table, they are also supported by the HDF library for backward compatibility.

If the machine used is big-endian, using these data types will result in no byte-order conversion being performed. If the machine used is little-endian, the library will convert the byte-order of the variables to big-endian.

TABLE 2E - Standard HDF Data Types and Flags

HDF Data Type
Data Type Flag and Value
Description
char8

DFNT_CHAR8 (4)

8-bit character type

uchar8

DFNT_UCHAR8 (3)

8-bit unsigned character type

int8

DFNT_INT8 (20)

8-bit integer type

uint8

DFNT_UINT8 (21)

8-bit unsigned integer type

int16

DFNT_INT16 (22)

16-bit integer type

uint16

DFNT_UINT16 (23)

16-bit unsigned integer type

int32

DFNT_INT32 (24)

32-bit integer type

uint32

DFNT_UINT32 (25)

32-bit unsigned integer type

float32

DFNT_FLOAT32 (5)

32-bit floating-point type

float64

DFNT_FLOAT64 (6)

64-bit floating-point type

Fortran programmers should refer to Section 2.4.3 on page 15 for a discussion of the Fortran data types.

2.4.2.2 Native Format Data Types

When a native format data type is specified, the corresponding numbers are stored in the HDF file exactly as they appear in memory, without conversion. For example, on a Cray Y-MP, 8 bytes of memory, or one Cray word, is used to store most integers. Therefore, an 8-bit signed integer, represented by the DFNT_INT32 flag, on a Cray Y-MP uses 8 bytes of memory. Consequently, when the data type DFNT_NATIVE | DFNT_INT32 (DFNT_NATIVE bytewise-ORed with DFNT_INT32) is used on a Cray Y-MP to specify the data type of an HDF SDS or vdata, each integer stored in the HDF file is 8 bytes.

The method for constructing the data type flag for each native data type described in the previous paragraph is used for any of the native data types: the DFNT_NATIVE flag is bitwise-ORed with the flag of the corresponding standard data type.

If the user is on a big-endian machine, using native data types will result in no conversion. If the user is on a little-endian machine, the HDF library will perform little-to-big-endian conversion.

The definitions of the native format data types and the corresponding data type flags appear in Table 2F.

TABLE 2F - Native Format Data Type Definitions

HDF Data Type
HDF Data Type Flag and Value
Description
int8

DFNT_NINT8 (4116)

8-bit native integer type

uint8

DFNT_NUINT8 (4117)

8-bit native unsigned integer type

int16

DFNT_NINT16 (4118)

16-bit native integer type

uint16

DFNT_NUINT16 (4119)

16-bit native unsigned integer type

int32

DFNT_NINT32 (4120)

32-bit native integer type

uint32

DFNT_NUINT32 (4121)

32-bit native unsigned integer type

float32

DFNT_NFLOAT32 (4101)

32-bit native floating-point type

float64

DFNT_NFLOAT64 (4102)

64-bit native floating-point type

2.4.2.3 Little-Endian Data Types

HDF also provides a "little-endian" option to suppress any rearranging of byte ordering from little- to big-endian. This is primarily for users of Intel-based machines who do not want to incur the cost of reordering data when writing to an HDF file. Note that direct conversions are supported between little-endian and all other byte-order formats supported by HDF.

The method for constructing the data type flag for each little-endian data type is similar to the method for constructing native format data type flags: the DFNT_LITEND flag is bitwise-ORed with the flag of the corresponding standard data type.

If the user is on a little-endian machine, using these data types will result in no conversion. If the user is on a big-endian machine, the HDF library will perform big-to-little-endian conversion.

The definitions of the little-endian data types and the corresponding data type flags appear in Table 2G.

TABLE 2G - Little-Endian Format Data Type Definitions

HDF Data Type
HDF Data Type Flag and Value
Description
int8

DFNT_LINT8 (16404)

8-bit little-endian integer type

uint8

DFNT_LUINT8 (16405)

8-bit little-endian unsigned integer type

int16

DFNT_LINT16 (16406)

16-bit little-endian integer type

uint16

DFNT_LUINT16 (16407)

16-bit little-endian unsigned integer type

int32

DFNT_LINT32 (16408)

32-bit little-endian integer type

uint32

DFNT_LUINT32 (16409)

32-bit little-endian unsigned integer type

float32

DFNT_LFLOAT32 (16389)

32-bit little-endian floating-point type

float64

DFNT_LFLOAT64 (16390)

64-bit little-endian floating-point type

2.4.2.4 Tag Definitions

These definitions identify the object tags defined and used by the HDF interface library. The concept of object tags is introduced in Section 2.2.2.1 on page 8, and a list of tags can be found in Appendix A of this manual. Note that tags can also identify properties of data objects.

2.4.2.5 Limit Definitions

These definitions declare the maximum size of specific data object parameters, such as the maximum length of a vdata field or the maximum number of objects in a vgroup. They are located in the header file "hlimits.h". A selection of the most-commonly-used limit definitions appears in Table 2H.

TABLE 2H - Limit Definitions

Definition Name
Definition Value
Description
FIELDNAMELENMAX

128
Maximum length of a vdata field in bits - 16 characters

VSNAMELENMAX

64
Maximum length of a vdata name in bytes - 64 characters

VGNAMELENMAX

64
Maximum length of a vgroup name in bytes - 64 characters

VSFIELDMAX

256
Maximum number of fields per vdata (64 for Macintosh)

VDEFAULTBLKSIZE

4096
Default block size in a vdata

VDEFAULTNBLKS

32
Default number of blocks in a vdata

MAXNVELT

64
Maximum number of objects in a vgroup

MAX_ORDER

65535
Maximum order of a vdata field

MAX_FIELD_SIZE

65535
Maximum length of a field

MAX_NC_DIMS

5000
Maximum number of dimensions per file

MAX_NC_ATTRS

3000
Maximum number of file or variable attributes

MAX_NC_VARS

5000
Maximum number of file attributes

MAX_NC_DIMS

32
Maximum number of variable attributes

MAX_NC_NAME

256
Maximum length of a name - NC interface

MAX_PATH_LEN

1024
Maximum length of an external file name

MAX_FILE

32
Maximum number of open files

MAX_GROUPS

8
Maximum number of groups

MAX_GR_NAME

256
Maximum length of a name - GR interface

MAX_VAR_DIMS

32
Maximum number of dimensions per variable

MAX_REF

65535
The largest number that will fit into a 16-bit word reference variable

MAX_BLOCK_SIZE

65536
Maximum size of blocks in linked blocks

2.4.3 FORTRAN-77 and C Language Issues

HDF provides both FORTRAN-77 and C versions of most of its interface routines. In order to make the FORTRAN-77 and C versions of each routine as similar as possible, some compromises have been made in the process of simplifying the interface for both programming languages.

FORTRAN-77-to-C Translation

Nearly all of the HDF library code is written in C. A FORTRAN-77 HDF interface routine translates all parameter data types to C data types, then calls the C routine that performs the functionality of the interface routine. For example, d8aimg is the FORTRAN-77 equivalent for DFR8addimage. Calls to either routine execute the same C code that adds an 8-bit raster image to an HDF file. See Figure 2e.

FIGURE 2e - Use of a Function Call Converter to Route FORTRAN-77 HDF Calls to the C Library

Case Sensitivity

FORTRAN-77 identifiers generally are not case sensitive, whereas C identifiers are. Although all of the FORTRAN-77 routines shown in this manual are written in lower case, FORTRAN-77 programs can generally call them using either upper- or lower-case letters without loss of meaning.

Name Length

Because some FORTRAN-77 compilers only interpret identifier names with seven or fewer characters, the first seven characters of the FORTRAN-77 HDF routine names are unique.

Header Files

The inclusion of header files is not generally permitted by FORTRAN-77 compilers. However, it is sometimes available as an option. On UNIX systems, for example, the macro processors m4 and cpp let the compiler include and preprocess header files. If this capability is not available, the user may have to copy the declarations, definitions, or values needed from the files "dffunc.inc" and "hdf.inc" into the user application. If the capability is available, the files can be included in the Fortran code. These two files reside in the include directory after the library is installed on the user's system.

Data Type Specifications

When mixing machines, compilers, and languages, it is difficult to maintain consistent data type definitions. For instance, on some machines an integer is a 32-bit quantity and on others, a 16-bit quantity. In addition, the differences between FORTRAN-77 and C lead to difficulties in describing the data types found in the argument lists of HDF routines. To maintain portability, the HDF library expects assigned names for all data types used in HDF routines. See Table 2I.

TABLE 2I - Correspondence Between Fortran and HDF C Data Types

Data Type
FORTRAN
C
8-bit signed integer

character*1 **

int8

8-bit unsigned integer

character*1

uint8

16-bit signed integer

integer*2

int16

16-bit unsigned integer

Not supported

uint16

32-bit signed integer

integer*4 **

int32

32-bit unsigned integer

Not supported

uint32

32-bit floating point number

real*4 **

float32

64-bit floating point number

real*8 **

float64

Native signed integer

integer

intn

Native unsigned integer

Not supported

uintn

** if the compiler supports this data type

When using a FORTRAN-77 data type that is not supported, the general practice is to use another data type of the same size. For example, an 8-bit signed integer can be used to store an 8-bit unsigned integer variable.

String and Array Specifications

The following conventions are followed in the specification of arrays in this manual:

FORTRAN-77 and ANSI C

As much as possible, we have ensured that the HDF interface routines conform to the implementations of Fortran and C that are in most common use today, namely FORTRAN-77 and ANSI C.

As Fortran-90 is a superset of FORTRAN-77, HDF programs should compile and run correctly when using a Fortran-90 compiler. However, an HDF library interface that makes full use of Fortran-90 enhancements is being considered.



[Top] [Prev]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.