Skip navigation links
(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Mid-Level Library) (Standard Interface Data Structures) (SIDS File Mapping Manual) (CGIO Manual) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(Introduction) (The ADF Software Library) (Glossary of Terms) (History of ADF Version Releases) (File System Architectures) (File Version Control Numbering) (Design Considerations) (Conventions and Implementations) (Error Messages) (Default Values and Limits) (Database-Level Routines) (Data Structure and Management Routines) (Data Query Routines) (Data I/O Routines) (Miscellaneous Routines) (Sample Fortran Program) (Sample C Program)

ADF Design Considerations

This section provides a summary of the design considerations that were used in the construction of the ADF software library.

ADF File Header Information

Every ADF file has a header section that contains information about the file itself. The following information from this header is available to the user:

[Under data format, "endian" refers to the ordering of bytes in a multi-byte number. Big endian is a computer architecture in which, within a given multi-byte numeric representation, the most significant byte has the lowest address (the word is stored "big-end-first"). Little endian is a computer architecture in which, within a given 16- or 32-bit word, bytes at lower addresses have lower significance (the word is stored "little-end-first").]

ADF File Optimizations

To optimize the performance of ADF, the following techniques have been incorporated into the ADF software to enhance performance of the file:

Allow data space to grow by linking data chunks. It is possible to increase the last dimension; doing so will extend the data. However, internal dimensional changes will corrupt the existing data.

The pointer table for child nodes will also contain the child node names.

ADF File Portability

To address code portability and future needs, the following design decisions were made:

ADF File Error Checking

Error checking has been implemented for the ADF file and is summarized here. Each item in the ADF file will have item-specific boundary tags surrounding it to provide file-based corruption checking. For variable-sized items, the associated boundary tags will include file-based size information. Information will be written to the disk in a sequence that will not allow corrupt files. For example, when adding a new child node, the complete child information will be written before the parent's child-table is updated. An ADF-core subroutine for downloading data to disk will be provided.

ADF Source Code Considerations

The ADF library of source code will incorporate the use of UNIX "what" strings for the ADF version number and also RCS versioning information in the source code and in the object code. The source code is written in portable ANSI C, using POSIX-defined system calls.

ADF Node Header Information

The following information is contained in an ADF node header:

Fortran Character Array Portability Concerns

Fortran character arrays are different from any other array type because they inherently include declared length information. Abstractly, they are a compound type: an array and an integer. The ANSI standards do not specify the implementation mechanism for handling this data type and so it is left to the vendor. As one might expect, vendors have devised different policies. This is particularly evident in how argument lists are created and used. The matter is further complicated when writing functions in other languages that are to be called from Fortran.

To keep the interfaces simple and to keep the Fortran and C data I/O calls similar (as opposed to having separate data I/O functions for character data), ADF suggests abiding by the following rules (these are required for Cray T90-mode users):

Note to Cray T90-mode users: The above rules must be followed. In addition, the given node must be available and have its data type correctly defined. Error handling is not possible otherwise, and ADF will abort or fail regardless of how the error state flag is set.

Integer 64 Data Type Portability Concerns

For portability reasons, it is suggested that the use of the I8 data type be restricted to a 64-bit environment.

Compound Data Types Portability Concerns

For the transportability reasons discussed below, use of compound data types is not recommended.

When using compound data types (e.g., with structures in C), it is important to be aware of data alignment issues. If one is not careful, the actual size of the structure in memory may be larger than the sum of the individual members. The total size depends on the order and word boundary alignment requirements of the specific data types. This is platform and compiler dependent and not handled by ADF. In order to provide the greatest portability (at least up to 64-bit environments), it is recommended that

So a 4-byte data type (e.g., I4[1]) needs "padding" (e.g., I4[2]) if it is to be followed by an 8-byte data type. And assuming a word size of 4 bytes, all C1-data-type elements need dimension values of multiples of 4 bytes (e.g., C1[4], C1[8], etc.). To be even more careful, size everything in multiples of 8 bytes, for example, "C1[8], I4[2], C1[16], R4[6], R8[5], I8[1]".

For a given architecture and compiler, and taking into consideration the restrictions given above, compound data types should work. It is more portable and highly recommended that users write out the individual components of a structure into separate nodes. It would probably be best to copy the individual components of a list of structures into an appropriate array type and write the temporary array out using the write-all or write-strided routines.