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)

(General Remarks) (File Operations) (Navigating a CGNS File) (Error Handling) (Structural Nodes) (Descriptors) (Physical Data) (Location and Position) (Auxiliary Data) (Grid Specification) (Solution Data) (Grid Connectivity) (Boundary Conditions) (Equation Specification) (Families) (Time-Dependent Data) (Links)

Navigating a CGNS File

Accessing a Node


Functions Modes
ier = cg_goto(int fn, int B, ..., "end"); r w m
ier = cg_gorel(int fn, ..., "end"); r w m
ier = cg_gopath(int fn, const char *path); r w m
ier = cg_golist(int fn, int B, int depth, char **label, int *index); r w m
ier = cg_where(int *fn, int *B, int *depth, char **label, int *index); r w m
call cg_goto_f(fn, B, ier, ..., 'end') r w m
call cg_gorel_f(fn, ier, ..., 'end') r w m
call cg_gopath_f(fn, path, ier) r w m

Input/Output

    fn   CGNS file index number.

B Base index number, where 1 ≤ B ≤ nbases.

... Variable argument list used to specify the path to a node. It is composed of an unlimited list of pair-arguments identifying each node in the path. Nodes may be identified by their label or name. Thus, a pair-argument may be of the form 
   "CGNS_NodeLabel", NodeIndex
where CGNS_NodeLabel is the node label and NodeIndex is the node index, or 
   "CGNS_NodeName", 0
where CGNS_NodeName is the node name. The 0 in the second form is required, to indicate that a node name is being specified rather than a node label. In addition, a pair-argument may be specified as 
   "..", 0
indicating the parent of the current node. The different pair-argument forms may be intermixed in the same function call.

There is one exception to this rule. When accessing a BCData_t node, the index must be set to either Dirichlet or Neumann since only these two types are allowed. (Note that Dirichlet and Neumann are defined in the include files cgnslib.h and cgnslib_f.h). Since "Dirichlet" and "Neuman" are also the names for these nodes, you may also use the "Dirichlet", 0 or "Neuman", 0 to access the node. See the example below.

end The character string "end" (or 'end' for the Fortran function) must be the last argument. It is used to indicate the end of the argument list. You may also use the empty string, "" ('' for Fortran), or the NULL string in C, to terminate the list.

path The pathname for the node to go to. If a position has been already set, this may be a relative path, otherwise it is an absolute path name, starting with "/Basename", where Basename is the base under which you wish to move.

depth Depth of the path list. The maximum depth is defined in cgnslib.h by CG_MAX_GOTO_DEPTH, and is currently equal to 20.

label Array of node labels for the path. This argument may be passed as NULL to cg_where(), otherwise it must be dimensioned by the calling program. The maximum size required is label[MAX_GO_TO_DEPTH][33]. You may call cg_where() with both label and index set to NULL in order to get the current depth, then dimension to that value.

index Array of node indices for the path. This argument may be passed as NULL to cg_where(), otherwise it must be dimensioned by the calling program. The maximum size required is index[MAX_GO_TO_DEPTH]. You may call cg_where() with both label and index set to NULL in order to get the current depth, then dimension to that value.

ier Error status. The possible values, with the corresponding C names (or Fortran parameters) defined in cgnslib.h (or cgnslib_f.h) are listed below.

    Value   Name/Parameter
0 CG_OK
1 CG_ERROR
2 CG_NODE_NOT_FOUND
3 CG_INCORRECT_PATH

For non-zero values, an error message may be printed using cg_error_print().

This function allows access to any parent-type nodes in a CGNS file. A parent-type node is one that can have children. Nodes that cannot have children, like Descriptor_t, are not supported by this function.

To illustrate the use of the above routines, assume you have a file with CGNS index number filenum, a base node named Base with index number basenum, 2 zones (named Zone1 and Zone2, with indices 1 and 2), and user-defined data (User, index 1) below each zone. To move to the user-defined data node under zone 1, you may use any of the following: 

   cg_goto(filenum, basenum, "Zone_t", 1, "UserDefinedData_t", 1, NULL);
   cg_goto(filenum, basenum "Zone1", 0, "UserDefinedData_t", 1, NULL);
   cg_goto(filenum, basenum, "Zone_t", 1, "User", 0, NULL);
   cg_goto(filenum, basenum, "Zone1", 0, "User", 0, NULL);
   cg_gopath(filenum, "/Base/Zone1/User");
Now, to change to the user-defined data node under zone 2, you may use the full path specification as above, or else a relative path, using one of the following: 
   cg_gorel(filenum, "..", 0, "..", 0, "Zone_t", 2, "UserDefinedData_t", 1, NULL);
   cg_gorel(filenum, "..", 0, "..", 0, "Zone2", 0, "UserDefinedData_t", 1, NULL);
   cg_gorel(filenum, "..", 0, "..", 0, "Zone_t", 2, "User", 0, NULL);
   cg_gorel(filenum, "..", 0, "..", 0, "Zone2", 0, "User", 0, NULL);
   cg_gopath(filenum, "../../Zone2/User");

Shown below are some additional examples of various uses of these routines, in both C and Fortran, where fn, B, Z, etc., are index numbers. 

   ier = cg_goto(fn, B, "Zone_t", Z, "FlowSolution_t", F, "..", 0, "MySolution", 0, "end");

   ier = cg_gorel(fn, "..", 0, "FlowSolution_t", F, NULL);

   ier = cg_gopath(fn, "/MyBase/MyZone/MySolution");

   ier = cg_gopath(fn, "../../MyZoneBC");

   call cg_goto_f(fn, B, ier, 'Zone_t', Z, 'GasModel_t', 1, 'DataArray_t', A, 'end')

   call cg_goto_f(fn, B, ier, 'Zone_t', Z, 'ZoneBC_t', 1, 'BC_t', BC, 'BCDataSet_t', S,
                  'BCData_t', Dirichlet, 'end')

   call cg_gorel_f(fn, ier, '..', 0, 'Neumann', 0, '')

   call cg_gopath_f(fn, '../../MyZoneBC', ier)

Deleting a Node


Functions Modes
ier = cg_delete_node(char *NodeName); - - m
call cg_delete_node_f(NodeName, ier) - - m

Input/Output

    NodeName   Name of the child to be deleted.
ier Error status.

The function cg_delete_node is used is conjunction with cg_goto. Once positioned at a parent node with cg_goto, a child of this node can be deleted with cg_delete_node. This function requires a single argument, NodeName, which is the name of the child to be deleted.

Since the highest level that can be pointed to with cg_goto is a base node for a CGNS database (CGNSBase_t), the highest-level nodes that can be deleted are the children of a CGNSBase_t node. In other words, nodes located directly under the ADF (or HDF) root node (CGNSBase_t and CGNSLibraryVersion_t) can not be deleted with cg_delete.

A few other nodes are not allowed to be deleted from the database because these are required nodes as defined by the SIDS, and deleting them would make the file non-CGNS compliant. These are:

When a child node is deleted, both the database and the file on disk are updated to remove the node. One must be careful not to delete a node from within a loop of that node type. For example, if the number of zones below a CGNSBase_t node is nzones, a zone should never be deleted from within a zone loop! By deleting a zone, the total number of zones (nzones) changes, as well as the zone indexing. Suppose for example that nzones is 5, and that the third zone is deleted. After calling cg_delete_node, nzones is changed to 4, and the zones originally indexed 4 and 5 are now indexed 3 and 4.