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 User's Guide) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(The CGIO Software Library) (Database-Level Routines) (Data Structure Management Routines) (Link Management Routines) (Node Management Routines) (Data I/O Routines) (Error Messages and Routines) (Miscellaneous Routines) (Example Programs)

The CGIO Software Library

Node - The Building Block

A database is a hierarchical 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, may be connected to an arbitrary number of children, each of which is itself a node. In this system, a 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 database. This structure allows the construction of a hierarchical system as shown in the figure below. As illustrated in the figure, it is possible to reference nodes in a second file (File_Two) from the original file (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 database files start with a root node, which is created automatically when a new file is opened. There is only one root node in a database file, and may be referenced by the database Root ID or by name as "/".

Node Attributes

Each node in the database 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 hierarchical database system.

    Data   The data associated with a node.
 
Data Type A 2-byte character field, blank filled, case sensitive. Specifies the type of data (e.g., real, integer, character) 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 the database manager 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 may be different. Within different programs, the node ID for the same node may also 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, the database manager checks the requested name against the other names of the child nodes of the specified parent. If the requested name is not unique, an error is returned.

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 from C must have the null "\0" character appended to them. Names returned 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.
 
Number of Dimensions The dimensionality of the data. All data is viewed as an array with 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.

The following table lists the data types supported by CGNS.

    Notation   Data Type   C Type   Fortran Type
MT No Data
I4 32-bit Integer int integer*4
I8 64-bit Integer cglong_t integer*8
U4 32-bit Unsigned Integer unsigned int integer*4
U8 64-bit Unsigned Integer cgulong_t integer*8
R4 32-bit Real float real*4
R8 64-bit Real double real*8
C1 Character char character
B1 Byte (unsigned byte) unsigned char character*1
LK Link

The "MT" node contains no data, and is typically used as a container for subnodes (children).

A link is denoted by "LK", 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 database file. The link parallels a soft link in the UNIX operating system in that it does not guarantee that the referenced node exists. The database manager will "resolve" the link only when information is requested about the linked node or it's children.

Glossary of Terms

    Child   One of the subnodes of a Parent. A child node does not have knowledge of its parent node. The user must keep track of this relationship.
 
Database The representation of a hierarchy of nodes on disk files. By use of links, it may physically span multiple files.
 
File The database file, with a single root node and its underlying structure.
 
ID A unique identifier to access a given node within a database file. This field contains sufficient information for the database manager 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 may be different. Within different programs, the node-ID for the same node may also be different. The ID is never actually written into a file.
 
Link-Node A special type of node. Links are created using the cgio_create_link subroutine. The data type of this node is LK, and its data is a one-dimensional array containing the name of the file (if other than the current file) containing the node to be linked and the full path name in that file from the root node to the desired node.

Links provide a mechanism for referring to a node that physically resides in a different part of the hierarchy. The node pointed to by a link may or may not reside in the same file as the link itself. A link is very similar to a "soft" link in the UNIX operating system in that it does not guarantee that the referenced node exists. The database manager will "resolve" the link only when information is requested about the node. If the ID of a link-node is used in an CGIO call, the effect of the call is the same as if the ID of the linked-to node was actually used. Note that a link node does not have children itself. In the example database figure, the children seen for L3 are F4 and F5. If a child is "added" to L3, then in reality, the child is added to F3. There are specialized subroutines provided to create link nodes and extract the link details.
 
Node The single component used to construct a database.
 
Node name A node has a 32-character name. Every child node directly under a given parent must have a unique name. Legal characteristics in a name are A-Z, a-z, 0-9, and special characters (ASCII values from 32 to 126, omitting 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.
 
Parent A node that has subnodes directly associated with it.
 
Pathname Within a database, nodes can be referenced using the name of a node along with its parent ID, or by using a "pathname" whose syntax is roughly the same as a path name in the UNIX environment. A pathname that begins with a leading slash "/" is assumed to begin at the root node of the file. If no leading slash is given, the name is assumed to begin at the node specified by the parent ID. Although there is a 32-character limitation on the node Name, there is no restriction on the length of the pathname. For example, equivalent ways to refer to node N8 in the hierarchy in the example database figure are:
  • Node-ID for N6 and name = "N8"
  • Node-ID for N4 and name = "N6/N8"
  • Node-ID for N1 and name = "N4/N6/N8"
  • Node-ID for the Root_Node and name = "/N1/N4/N6/N8"

Conventions and Implementations

    C   All input strings are to be null terminated. All returned strings will have the trailing blanks removed and will be null terminated. Variables declared to hold Names, Labels, and Data-Types should be at least 33 characters long. cgns_io.h has a number of variables defined. An example declaration would be:
   char name[CGIO_MAX_NAME_LENGTH+1];
       
Fortran Strings will be determined using inherited length. Returned strings will be blank filled to the specified length. All returned names will be left justified and blank filled on the right. There will be no null character. An example declaration would be:
   PARAMETER CGIO_MAX_NAME_LENGTH=32
   CHARACTER*(CGIO_MAX_NAME_LENGTH) NAME
       
or include the Fortran header file cgns_io_f.h which defines these parameters.
 
ID A unique identifier to access a given node within a database. 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 may be different. Within different programs, the node ID for the same node may also be different. The ID is not ever actually written into a file.

The declaration for variables that will hold node IDs should be for an 8-byte real number.
 
Indexing All indexing is Fortran-like in that the starting index is 1 and the last is N for N items in an index or array dimension. The array structure is assumed to be the same as in Fortran with the first array dimension varying the fastest and the last dimension varying the slowest.

The index starting at one is used in cgio_read_data_type, cgio_write_data, cgio_children_names, and cgio_children_ids.

The user should be aware of the differences in array indexing between Fortran and C. The subroutines cgio_read_all_data_type and cgio_write_all_data merely take a pointer to the beginning of the data, compute how much data is to be read/written, and process as many bytes as have been requested. Thus, these routines effectively make a copy of memory onto disk or vice versa. Given this convention, it is possible for a C program to use standard C conventions for array indexing and use cgio_write_all_data to store the array on disk. Then a Fortran program might use cgio_read_all_data_type_f to read the data set. Unless the user is aware of the structure of the data, it is possible for the array to be transposed relative to what is expected.

The implications of the assumed array structure convention can be quite subtle. The subroutines cgio_write_data and cgio_read_data_type assume the Fortran array structure in order to index the data. Again, unless the user is aware of the implications of this, it is possible to write an array on disk and later try to change a portion of the data and not change the correct numbers.

As long as users are aware of how their data structure maps onto the database, there will not be any problems.
 
return codes The CGIO routines return an integer code indicating whether they were successfull or not. On success, 0 (CGIO_ERR_NONE) is returned. A non-zero return indicates an error. Return codes < 0 indicate an error at the CGIO level; codes > 0 indicate an error in the database manager. See Error Messages for a list of error codes and mesages.

Limits and Sizes

The following default values, sizes, and limits are defined in the header file cgns_io.h.

    Define   Value   Attribute  
CGIO_MAX_DATATYPE_LENGTH 2 Data type length
CGIO_MAX_DIMENSIONS 12 Maximum dimensions
CGIO_MAX_NAME_LENGTH 32 Maximum node name length
CGIO_MAX_LABEL_LENGTH 32 maximum node label length
CGIO_MAX_VERSION_LENGTH 32 Maximum version length
CGIO_MAX_DATE_LENGTH 32 Maximum date length
CGIO_MAX_ERROR_LENGTH 80 Maximum length of error string
CGIO_MAX_LINK_DEPTH 100 Maximum link depth
CGIO_MAX_FILE_LENGTH 1024 Maximum file name length
CGIO_MAX_LINK_LENGTH 4096 Maximum link data size