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".
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.
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.
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.
The list of supported values (key words) for each of these variable
types (typedefs) are:
|ElementType_t||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, NGON_n|
|DataType_t||Integer, RealSingle, RealDouble, Character|
|DataClass_t||Dimensional, NormalizedByDimensional, NormalizedByUnknownDimensional, NondimensionalParameter, DimensionlessConstant|
|MassUnits_t||Null, UserDefined, Kilogram, Gram, Slug, PoundMass|
|LengthUnits_t||Null, UserDefined, Meter, Centimeter, Millimeter, Foot, Inch|
|TimeUnits_t||Null, UserDefined, Second|
|TemperatureUnits_t||Null, UserDefined, Kelvin, Celsius, Rankine, Fahrenheit|
|AngleUnits_t||Null, UserDefined, Degree, Radian|
|ElectricCurrentUnits_t||Null, UserDefined, Ampere, Abampere, Statampere, Edison, auCurrent|
|SubstanceAmountUnits_t||Null, UserDefined, Mole, Entities, StandardCubicFoot, StandardCubicMeter|
|LuminousIntensityUnits_t||Null, UserDefined, Candela, Candle, Carcel, Hefner, Violle|
|GoverningEquationsType_t||Null, UserDefined, FullPotential, Euler, NSLaminar, NSTurbulent, NSLaminarIncompressible, NSTurbulentIncompressible|
|ModelType_t||Null, UserDefined, 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||Vertex, CellCenter, FaceCenter, IFaceCenter, JFaceCenter, KFaceCenter, EdgeCenter|
|GridConnectivityType_t||Overset, Abutting, Abutting1to1|
|PointSetType_t||PointList, PointRange, PointListDonor, PointRangeDonor, ElementList, ElementRange, CellListDonor|
|BCType_t||Null, UserDefined, BCAxisymmetricWedge, BCDegenerateLine, BCExtrapolate, BCDegeneratePoint, BCDirichlet, BCFarfield, BCNeumann, BCGeneral, BCInflow, BCOutflow, BCInflowSubsonic, BCOutflowSubsonic, BCInflowSupersonic, BCOutflowSupersonic, BCSymmetryPlane, BCTunnelInflow, BCSymmetryPolar, BCTunnelOutflow, BCWallViscous, BCWall, BCWallViscousHeatFlux, BCWallInviscid, BCWallViscousIsothermal, FamilySpecified|
|RigidGridMotionType_t||Null, UserDefined, ConstantRate, VariableRate|
|ArbitraryGridMotionType_t||Null, UserDefined, NonDeformingGrid, DeformingGrid|
|AverageInterfaceType_t||AverageAll, AverageCircumferential, AverageRadial, AverageI, AverageJ, AverageK|
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)".
The CGNS Mid-Level Library may be downloaded from SourceForge . This manual, as well as the other CGNS documentation, is available in both HTML and PDF format from the CGNS documentation web site.
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 both the SIDS-to-ADF and SIDS-to-HDF file mapping manuals.
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-to-ADF 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. 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.