[Top] [Prev]
2.5 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.5.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.5.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 2F on page 14, Table 2G on page 14, and Table 2H on page 15. 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.5.2.1 Standard HDF Data Types
The definitions of the fundamental data types are in Table 2F. 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 2F - Standard HDF Data Types and Flags
Fortran programmers should refer to Section 2.5.3 on page 16 for a discussion of the Fortran data types.
2.5.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.
The definitions of the native format data types and the corresponding data type flags appear in Table 2G.
TABLE 2G - Native Format Data Type Definitions
2.5.2.3 Little-Endian Data Types
HDF normally writes data in big-endian format, but provides a little-endian option forcing all data written to disk to be written in little-endian format. 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 2H.
TABLE 2H - Little-Endian Format Data Type Definitions
2.5.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.5.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 2I.
TABLE 2I - Limit Definitions
2.5.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 2J.
TABLE 2J - Correspondence Between Fortran and HDF C Data Types
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 - 05/19/99, NCSA HDF
Development Group.