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)

General Remarks

Acquiring the Software and Documentation

The CGNS Mid-Level Library may be downloaded from SourceForge external link. This manual, as well as the other CGNS documentation, is available in both HTML and PDF format from the CGNS documentation web site.

Organization of This Manual

The sections that follow describe the Mid-Level Library functions in detail. The first three sections cover some basic file operations (i.e., opening and closing a CGNS file, and some configuration options), accessing a specific node in a CGNS database, and error handling. The remaining sections describe the functions used to read, write, and modify nodes and data in a CGNS database. These sections basically follow the organization used in the "Detailed CGNS Node Descriptions" section of the SIDS File Mapping manual.

At the start of each sub-section is a Node line, listing the the applicable CGNS node label, with links to that node's description in the SIDS and SIDS File Mapping manuals.

Next is a table illustrating the syntax for the Mid-Level Library functions. The C functions are shown in the top half of the table, followed by the corresponding Fortran routines in the bottom half of the table. Input variables are shown in an upright blue font, and output variables are shown in a slanted red font. As of Version 3.1, some of the arguments to the Mid-Level Library have changed from int to cgsize_t in order to support 64-bit data. These changes are shown in an upright green font for input variables, and a slanted bright red font for output variables. For each function, the right-hand column lists the modes (read, write, and/or modify) applicable to that function.

The input and output variables are then listed and defined.

Language

The CGNS Mid-Level Library is written in C, but each function has a Fortran counterpart. All function names start with "cg_". The Fortran functions have the same name as their C counterpart with the addition of the suffix "_f".

Character Strings

All data structure names and labels in CGNS are limited to 32 characters. When reading a file, it is advised to pre-allocate the character string variables to 32 characters in Fortran, and 33 in C (to include the string terminator). Other character strings, such as the CGNS file name or descriptor text, are unlimited in length. The space for unlimited length character strings will be created by the Mid-Level Library; it is then the responsibility of the application to release this space by a call to cg_free.

Error Status

All C functions return an integer value representing the error status. All Fortran functions have an additional parameter, ier, which contains the value of the error status. An error status different from zero implies that an error occured. The error message can be printed using the error handling functions of the CGNS library. The error codes are coded in the C and Fortran include files cgnslib.h and cgnslib_f.h.

Typedefs

Beginning with version 3.1, two new typedef variables have been introduced to support 64-bit mode. The cglong_t typedef is always a 64-bit integer, and cgsize_t will be either a 32-bit or 64-bit integer depending on how the library was built. Many of the C functions in the MLL have been changed to to use cgsize_t instead of int in the arguments. These functions include any that may exceed the 2Gb limit of an int, e.g. zone dimensions, element data, boundary conditions, and connectivity. In Fortran, all integer data is taken to be integer*4 for 32-bit and integer*8 for 64-bit builds.

Several types of variables are defined using typedefs in the cgnslib.h file. These are intended to facilitate the implementation of CGNS in C. These variable types are defined as an enumeration of key words admissible for any variable of these types. The file cgnslib.h must be included in any C application programs which use these data types.

In Fortran, the same key words are defined as integer parameters in the include file cgnslib_f.h. Such variables should be declared as integer in Fortran applications. The file cgnslib_f.h must be included in any Fortran application using these key words.

Note that the first two enumerated values in these lists, xxxNull and xxxUserDefined, are only available in the C interface, and are provided in the advent that your C compiler does strict type checking. In Fortran, these values are replaced by the numerically equivalent CG_Null and CG_UserDefined. These values are also defined in the C interface, thus either form may be used. The function prototypes for the MLL use CG_Null and CG_UserDefined, rather than the more specific values.

The list of enumerated values (key words) for each of these variable types (typedefs) are:

    ZoneType_t   ZoneTypeNull, ZoneTypeUserDefined, Structured, Unstructured
 
ElementType_t ElementTypeNull, ElementTypeUserDefined, NODE, BAR_2, BAR_3, TRI_3, TRI_6, QUAD_4, QUAD_8, QUAD_9, TETRA_4, TETRA_10, PYRA_5, PYRA_14, PENTA_6, PENTA_15, PENTA_18, HEXA_8, HEXA_20, HEXA_27, MIXED, PYRA_13, NGON_n, NFACE_n
 
DataType_t DataTypeNull, DataTypeUserDefined, Integer, RealSingle, RealDouble, Character, LongInteger
 
DataClass_t DataClassNull, DataClassUserDefined, Dimensional, NormalizedByDimensional, NormalizedByUnknownDimensional, NondimensionalParameter, DimensionlessConstant
 
MassUnits_t MassUnitsNull, MassUnitsNullUserDefined, Kilogram, Gram, Slug, PoundMass
 
LengthUnits_t LengthUnitsNull, LengthUnitsUserDefined, Meter, Centimeter, Millimeter, Foot, Inch
 
TimeUnits_t TimeUnitsNull, TimeUnitsUserDefined, Second
 
TemperatureUnits_t TemperatureUnitsNull, TemperatureUnitsUserDefined, Kelvin, Celsius, Rankine, Fahrenheit
 
AngleUnits_t AngleUnitsNull, AngleUnitsUserDefined, Degree, Radian
 
ElectricCurrentUnits_t ElectricCurrentUnitsNull, ElectricCurrentUnitsUserDefined, Ampere, Abampere, Statampere, Edison, auCurrent
 
SubstanceAmountUnits_t SubstanceAmountUnitsNull, SubstanceAmountUnitsUserDefined, Mole, Entities, StandardCubicFoot, StandardCubicMeter
 
LuminousIntensityUnits_t LuminousIntensityUnitsNull, LuminousIntensityUnitsUserDefined, Candela, Candle, Carcel, Hefner, Violle
 
GoverningEquationsType_t GoverningEquationsTypeNull, GoverningEquationsTypeUserDefined, FullPotential, Euler, NSLaminar, NSTurbulent, NSLaminarIncompressible, NSTurbulentIncompressible
 
ModelType_t ModelTypeNull, ModelTypeUserDefined, Ideal, VanderWaals, Constant, PowerLaw, SutherlandLaw, ConstantPrandtl, EddyViscosity, ReynoldsStress, ReynoldsStressAlgebraic, Algebraic_BaldwinLomax, Algebraic_CebeciSmith, HalfEquation_JohnsonKing, OneEquation_BaldwinBarth, OneEquation_SpalartAllmaras, TwoEquation_JonesLaunder, TwoEquation_MenterSST, TwoEquation_Wilcox, CaloricallyPerfect, ThermallyPerfect, ConstantDensity, RedlichKwong, Frozen, ThermalEquilib, ThermalNonequilib, ChemicalEquilibCurveFit, ChemicalEquilibMinimization, ChemicalNonequilib, EMElectricField, EMMagneticField, EMConductivity, Voltage, Interpolated, Equilibrium_LinRessler, Chemistry_LinRessler
 
GridLocation_t GridLocationNull, GridLocationUserDefined, Vertex, CellCenter, FaceCenter, IFaceCenter, JFaceCenter, KFaceCenter, EdgeCenter
 
GridConnectivityType_t GridConnectivityTypeNull, GridConnectivityTypeUserDefined, Overset, Abutting, Abutting1to1
 
PointSetType_t PointSetTypeNull, PointSetTypeUserDefined, PointList, PointRange, PointListDonor, PointRangeDonor, ElementList, ElementRange, CellListDonor
 
BCType_t BCTypeNull, BCTypeUserDefined, BCAxisymmetricWedge, BCDegenerateLine, BCExtrapolate, BCDegeneratePoint, BCDirichlet, BCFarfield, BCNeumann, BCGeneral, BCInflow, BCOutflow, BCInflowSubsonic, BCOutflowSubsonic, BCInflowSupersonic, BCOutflowSupersonic, BCSymmetryPlane, BCTunnelInflow, BCSymmetryPolar, BCTunnelOutflow, BCWallViscous, BCWall, BCWallViscousHeatFlux, BCWallInviscid, BCWallViscousIsothermal, FamilySpecified
 
BCDataType_t BCDataTypeNull, BCDataTypeUserDefined, Dirichlet, Neumann
 
RigidGridMotionType_t RigidGridMotionTypeNull, RigidGridMotionTypeUserDefined, ConstantRate, VariableRate
 
ArbitraryGridMotionType_t ArbitraryGridMotionTypeNull, ArbitraryGridMotionTypeUserDefined, NonDeformingGrid, DeformingGrid
 
SimulationType_t SimulationTypeNull, SimulationTypeUserDefined, TimeAccurate, NonTimeAccurate
 
WallFunctionType_t WallFunctionTypeNull, WallFunctionTypeUserDefined, Generic
 
AreaType_t AreaTypeNull, AreaTypeUserDefined, BleedArea, CaptureArea
 
AverageInterfaceType_t AverageInterfaceTypeNull, AverageInterfaceTypeUserDefined, AverageAll, AverageCircumferential, AverageRadial, AverageI, AverageJ, AverageK

Character Names For Typedefs

The CGNS library defines character arrays which map the typedefs above to character strings. These are global arrays dimensioned to the size of each list of typedefs. To retrieve a character string representation of a typedef, use the typedef value as an index to the appropiate character array. For example, to retrieve the string "Meter" for the LengthUnits_t Meter typedef, use LengthUnitsName[Meter]. Functions are available to retrieve these names without the need for direct global data access. These functions also do bounds checking on the input, and if out of range, will return the string "<invalid>". An additional benefit is that these will work from within a Windows DLL, and are thus the recommended access technique. The routines have the same name as the global data arrays, but with a "cg_" prepended. For the example above, use "cg_LengthUnitsName(Meter)".

Typedef Name Access Functions
const char *name = cg_MassUnitsName(MassUnits_t type);
const char *name = cg_LengthUnitsName(LengthUnits_t type);
const char *name = cg_TimeUnitsName(TimeUnits_t type);
const char *name = cg_TemperatureUnitsName(TemperatureUnits_t type);
const char *name = cg_ElectricCurrentUnitsName(ElectricCurrentUnits_t type);
const char *name = cg_SubstanceAmountUnitsName(SubstanceAmountUnits_t type);
const char *name = cg_LuminousIntensityUnitsName(LuminousIntensityUnits_t type);
const char *name = cg_DataClassName(DataClass_t type);
const char *name = cg_GridLocationName(GridLocation_t type);
const char *name = cg_BCDataTypeName(BCDataType_t type);
const char *name = cg_GridConnectivityTypeName(GridConnectivityType_t type);
const char *name = cg_PointSetTypeName(PointSetType_t type);
const char *name = cg_GoverningEquationsTypeName(GoverningEquationsType_t type);
const char *name = cg_ModelTypeName(ModelType_t type);
const char *name = cg_BCTypeName(BCType_t type);
const char *name = cg_DataTypeName(DataType_t type);
const char *name = cg_ElementTypeName(ElementType_t type);
const char *name = cg_ZoneTypeName(ZoneType_t type);
const char *name = cg_RigidGridMotionTypeName(RigidGridMotionType_t type);
const char *name = cg_ArbitraryGridMotionTypeName(ArbitraryGridMotionType_t type);
const char *name = cg_SimulationTypeName(SimulationType_t type);
const char *name = cg_WallFunctionTypeName(WallFunctionType_t type);
const char *name = cg_AreaTypeName(AreaType_t type);
const char *name = cg_AverageInterfaceTypeName(AverageInterfaceType_t type);

64-bit C Portability and Issues

If you use the cgsize_t data type in new code, it will work in both 32 and 64-bit compilation modes. In order to support CGNS versions prior to 3.1, you may also want to add something like this to your code:

#if CGNS_VERSION < 3100
#define cgsize_t int
#endif
Existing code that uses int will not work with a CGNS 3.1 library compiled in 64-bit mode. You may want to add something like this to your code:
#if CGNS_VERSION >= 3100 && CG_BUILD_64BIT
#error does not work in 64 bit mode
#endif
or modify your code to use cgsize_t.

64-bit Fortran Portability and Issues

All integer arguments in the Fortran interface - including enumerated values (enums) - are taken to be integer*4 in 32-bit mode and integer*8 in 64-bit mode. If you have used default or implicit integers in your Fortran code, it should port to 64-bit mode in most cases by simply turning on your compiler option that promotes implicit integers to integer*8. If you have explicitly defined your integers as integer*4, your code will not work in 64-bit mode. In that case, you will either need to change them to integer (recommended for portability) or integer*8.

A new integer parameter has been added to the cgnslib_f.h header, CG_BUILD_64BIT, which will be set to 1 in 64-bit mode and 0 otherwise. You may use this parameter to check at run time if the CGNS library has been compiled in 64-bit mode or not, as in:

if (CG_BUILD_64BIT .ne. 0) then
    print *,'will not work in 64-bit mode'
    stop
endif
If you are using a CGNS library prior to version 3.1, this parameter will not be defined and you will need to rely on your compiler initializing all undefined values to 0 (not always the case) for this test to work.

If your compiler supports automatic promotion of integers, and you use implicit integers, your code should port to 64-bit with the following exception.

If you use an Integer data type in any routine that takes a data type specification, and an implicit integer for the data, the code will fail when compiled in 64-bit mode with automatic integer promotion. An example of this would be:

integer dim
integer data(dim)
call cg_array_write_f('array',Integer,1,dim,data)
This is because the MLL interprets the Integer data type as integer*4 regardless of the compilation mode. The compiler, however, has automatically promoted data to be integer*8. What you will need to do to prevent this problem, is to either explicitly define data as in:
integer dim
integer*4 data(dim)
call cg_array_write_f('array',Integer,1,dim,data)
or
integer dim
integer*8 data(dim)
call cg_array_write_f('array',LongInteger,1,dim,data)
or test on CG_BUILD_64BIT as in:
integer dim
integer data(dim)
if (CG_BUILD_64BIT .eq. 0) then
  call cg_array_write_f('array',Integer,1,dim,data)
else
  call cg_array_write_f('array',LongInteger,1,dim,data)
endif
The last 2 options will only work with CGNS Version 3.1, since LongInteger and CG_BUILD_64BIT are not defined in previous versions.

You may also need to be careful when using integer constants as arguments in 64-bit mode. If your compiler automatically promotes integer constants to integer*8, then there is no problem. This is probably the case if your compiler supports implicit integer promotion. If not, then the constants will be integer*4, and your code will not work in 64-bit mode. In that case you will need to do something like:

integer*8 one,dim
integer*4 data(dim)
one = 1
call cg_array_write_f('array',Integer,one,dim,data)