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)

The ADF Software Library

The ADF library is a hierarchical database system that is built around the concept of a "node". Each node contains information about itself and its ancestors and possibly data (e.g., arrays, vectors, character strings, etc.). Each of these nodes, in turn, can be connected to an arbitrary number of children, each of which is itself a node. In this system, an ADF node contains user-accessible information related to identification, name, type, and amount of data associated with it, and pointers to child nodes. Basic nodal information includes:

There are no restrictions on the number of child nodes that a node can have associated with it in the ADF database. This structure allows the construction of a hierarchical database as shown in the figure below. As illustrated in the figure, it is possible to reference nodes in a second file (ADF_File_Two) from the original file (ADF_File_One). This is the concept of "linking."

Example database showing node connections and links

Example Database Hierarchy of Nodes

A node knows about itself and its children, but it does not know anything about its parent. This means that it is possible to traverse "down" the tree by making queries about what lies below the current node, but it is not possible to traverse "up" the tree by making queries about nodes above a given node. If it is desired to move back up the tree, the user must keep track of that information.

All ADF files start with the root node, named "ADF MotherNode". This node is created automatically when a new file is opened. There is only one root node in an ADF file.

ADF Node Attributes

There is a single building block called a node (see the example database figure) used to construct the hierarchical structure. Each node may have zero to many subnodes that are associated with it, as well as its own data. The following are a list of attributes accessible by the user for a node in the ADF hierarchical database system.

    Child Table   A table of file pointers and names for each of the node's children.
Data The data associated with a node.
Data Type A 32-byte character field, blank filled, case sensitive. Specifies the type of data (e.g., real, integer, complex) associated with this node. The supported data types are listed below.
Dimensions An integer vector containing the number of elements within each dimension. For example, if the array A was declared (Fortran) as A(10,20), the Dimension vector would contain two entries (10,20).
ID A unique identifier to access a given node within a file. This field contains sufficient information for ADF to locate the node within a file. For any given node, the ID is generated only after the file it resides in has been opened by a program and the user requests information about the node. The ID is valid only within the program that opened the file and while that file is open. If the file is closed and reopened, the ID for any given node will be different. Within different programs, the node ID for the same node will be different. The ID is never actually written into a file.
Label A 32-byte character field. The rules for Labels are identical to those for Names. Unlike names, Labels do not have to be unique. The Label field was introduced to allow "data typing" similar to the "typedef" concept in C. Using the Label field in this way allows programs to know some additional information about the use of the node itself or its child nodes and to call specific subroutines to read the data or react in specific ways upon detection of the type.
Name A 32-byte character field. The names of child nodes directly attached to a parent node must be unique. For example, in the example database figure, all nodes directly attached to N3 must have unique names. When a request to create a new node is made, ADF checks the requested name against the other names of the child nodes of the specified parent. If the requested name is not unique, ADF returns an error.

Legal characteristics of a name are a A-Z, a-z, 0-9, and special characters (ASCII values from 32 to 126, except for the forward slash "/" (ASCII number 47)). Names will be blank filled to 32 bytes; they are case sensitive. Leading blanks are discarded and trailing blanks are ignored, whereas internal blanks are significant.

Note: Names passed to ADF from C must have the null "\0" character appended to them. Names returned from ADF through the C interface will have the null character appended to them. Therefore, C programs should allocate 33 bytes for any Name in order to accommodate the null character.

Fortran programs can allocate 32 characters for Names. The Fortran interface takes care of adding or removing the null character as required.
Names of Subnodes A list of names of the subnodes (children) of a node. (This is the information contained in the child table.)
Number of Dimensions The dimensionality of the data. ADF views all data as an array and can handle from zero (i.e., no data) to 12 dimensions. A "0" is used if the data type is empty. Thus, a scalar is viewed as a vector with one dimension and length 1.
Number of Subnodes The number of child nodes directly attached to any given node. Each node can have zero or more child nodes directly associated with it.
Pointer An address, from the point of view of a programming language. Pointers are like jumps, leading from one part of the data structure to another.

The following table lists the data types supported by CGNS.

    Data Type   Notation
No Data MT (i.e., eMpTy)
Integer 32 I4
Integer 64 I8
Unsigned Integer 32 U4
Unsigned Integer 64 U8
Real 32 R4
Real 64 R8
Complex 64 X4
Complex 128 X8
Character (unsigned byte) C1
Byte (unsigned byte) B1
Link LK

Data Type Definitions

    Structure   It is possible to define a "structure" in ADF similar to the way that "struct" is defined in the C programming language. ADF will treat each instance of the structure as a single instance of data. A structure is described by using a string. For example: "I4,I4,R8,R4".

  • Structures can be only as complex as can be described in 32 characters.
  • This construct is not very portable; therefore, its use is highly discouraged.
Character A character type is intended for ASCII-type character information. There may be different system architectures that use different representations for translating data. Byte data type should be used for pure byte or bit data usage.
Precision The R4 and R8 are single and double precision, respectively, on a 32-bit system architecture. On the Cray, single precision is R8 and double precision may be R8 or R16, depending on the compile settings. ADF tracks the number of bits to guarantee precision.
Link A link is denoted by "LK" in the table of supported data types and defines the linkage between nodes and subnodes. A link provides a mechanism for referring to a node that physically resides in a different part of the hierarchy or a different file. A link within ADF parallels a soft link in the UNIX operating system in that it does not guarantee that the referenced node exists. ADF will "resolve" the link only when information is requested about the linked node.

Acquiring the Software and Documentation

The ADF software is distributed as part of the CGNS Library. This manual, as well as the other CGNS documentation, is available in both HTML and PDF format from the CGNS documentation web site.