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)

Auxiliary Data

Reference State

Node: ReferenceState_t (SIDS, File Mapping)

Functions Modes
ier = cg_state_write(char *StateDescription); - w m
ier = cg_state_read(char **StateDescription); r - m
call cg_state_write_f(StateDescription, ier) - w m
call cg_state_size_f(Size, ier) r - m
call cg_state_read_f(StateDescription, ier) r - m

Input/Output

    StateDescription   Text description of reference state.
Size Number of characters in the StateDescription string (Fortran interface only) - integer.
ier Error status.

The function cg_state_write creates the ReferenceState_t node and must be called even if StateDescription is undefined (i.e., a blank string). The descriptors, data arrays, data class, and dimensional units characterizing the ReferenceState_t data structure may be added to this data structure after its creation.

The function cg_state_read reads the StateDescription of the local ReferenceState_t node. If StateDescription is undefined in the CGNS database, this function returns a null string. If StateDescription exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(StateDescription).

Gravity

Node: Gravity_t (SIDS, File Mapping)

Functions Modes
ier = cg_gravity_write(int fn, int B, float *GravityVector); - w m
ier = cg_gravity_read(int fn, int B, float *GravityVector); r - m
call cg_gravity_write_f(fn, B, GravityVector, ier) - w m
call cg_gravity_read_f(fn, B, GravityVector, ier) r - m

Input/Output

    fn   CGNS file index number.
B Base index number, where 1 ≤ Bnbases.
GravityVector Components of the gravity vector. The number of components must equal PhysicalDimension. (In Fortran, this is an array of Real*4 values.)
ier Error status.

Convergence History

Node: ConvergenceHistory_t (SIDS, File Mapping)

Functions Modes
ier = cg_convergence_write(int niterations,
      char *NormDefinitions);
- w m
ier = cg_convergence_read(int *niterations,
      char **NormDefinitions);
r - m
call cg_convergence_write_f(niterations, NormDefinitions, ier) - w m
call cg_convergence_read_f(niterations, NormDefinitions, ier) r - m

Input/Output

    niterations   Number of iterations for which convergence information is recorded.
NormDefinitions Description of the convergence information recorded in the data arrays.
ier Error status.

The function cg_convergence_write creates a ConvergenceHistory_t node. It must be the first one called when recording convergence history data. The NormDefinitions may be left undefined (i.e., a blank string). After creation of this node, the descriptors, data arrays, data class, and dimensional units characterizing the ConvergenceHistory_t data structure may be added.

The function cg_convergence_read reads a ConvergenceHistory_t node. If NormDefinitions is not defined in the CGNS database, this function returns a null string. If NormDefinitions exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(NormDefinitions).

Integral Data

Node: IntegralData_t (SIDS, File Mapping)

Functions Modes
ier = cg_integral_write(char *Name); - w m
ier = cg_nintegrals(int *nintegrals); r - m
ier = cg_integral_read(int Index, char *Name); r - m
call cg_integral_write_f(Name, ier) - w m
call cg_nintegrals_f(nintegrals, ier) r - m
call cg_integral_read_f(Index, Name, ier) r - m

Input/Output

    Name   Name of the IntegralData_t data structure.
nintegrals Number of IntegralData_t nodes under current node.
Index Integral data index number, where 1 ≤ Indexnintegrals.
ier Error status.

User-Defined Data

Node: UserDefinedData_t (SIDS, File Mapping)

Functions Modes
ier = cg_user_data_write(char *Name); - w m
ier = cg_nuser_data(int *nuserdata); r - m
ier = cg_user_data_read(int Index, char *Name); r - m
call cg_user_data_write_f(Name, ier) - w m
call cg_nuser_data_f(nuserdata, ier) r - m
call cg_user_data_read_f(Index, Name, ier) r - m

Input/Output

    nuserdata   Number of UserDefinedData_t nodes under current node.
Name Name of the UserDefinedData_t node.
Index User-defined data index number, where 1 ≤ Indexnuserdata.
ier Error status.

After accessing a particular UserDefinedData_t node using cg_goto, the Point Set functions may be used to read or write point set information for the node. The function cg_gridlocation_write may also be used to specify the location of the data with respect to the grid (e.g., Vertex or FaceCenter).

Multiple levels of UserDefinedData_t nodes may be written and retrieved by positioning via cg_goto. E.g.,

   ier = cg_goto(fn, B, "Zone_t", Z, "UserDefinedData_t", ud1, 
                 "UserDefinedData_t", ud2, "UserDefinedData_t", ud3, "end");

Freeing Memory


Functions Modes
ier = cg_free(void *data); r w m

Input/Output

    data   Data allocated by the Mid-Level Library.
ier Error status.

This function does not affect the structure of a CGNS file; it is provided as a convenience to free memory allocated by the Mid-Level Library. This isn't necessary in Fortran, and thus an equivalent Fortran function is not provided.

The functions that are used to allocate memory for return values are cg_descriptor_read, cg_convergence_read, cg_geo_read, cg_link_read, and cg_state_read. Each of these may allocate space to contain the data returned to the application. It is the responsibility of the application to free this data when it is no longer needed. Calling cg_free is identical to calling the standard C function free, however it is probably safer in that the memory is freed in the same module in which it is created, particularly when the Mid-Level Library is a shared library or DLL. The routine checks for NULL data and will return CG_ERROR in this case, otherwise it returns CG_OK.