These functions usually are found the the preamble or the epilog of your application code using the CGNS/MLL.
cg_is_cgns(const char *filename, int *file_type)¶Check for a valid CGNS file.
For existing files, the function /e cg_is_cgns may be used to determine if a file is a CGNS file or not, and the type of file (CG_FILE_ADF or CG_FILE_HDF5). If the file is a CGNS file, cg_is_cgns returns CG_OK, otherwise CG_ERROR is returned and file_type is set to CG_FILE_NONE.
filename – [in] Name of the CGNS file, including path name if necessary. There is no limit on the length of this character variable.
file_type – [in] Type of CGNS file. This will typically be either CG_FILE_ADF or CG_FILE_HDF5 depending on the underlying file format.
Error status.
cg_open(const char *filename, int mode, int *fn)¶Open a CGNS file.
The function cg_open must always be the first one called. It opens a CGNS file for reading and/or writing and returns an index number file_number. The index number serves to identify the CGNS file in subsequent function calls. Several CGNS files can be opened simultaneously. The current limit on the number of files opened at once depends on the platform. On an SGI workstation, this limit is set at 100 (parameter FOPEN_MAX in stdio.h). The file can be opened in one of the following modes:
CG_MODE_READ |
Read only mode. |
CG_MODE_WRITE |
Write only mode. |
CG_MODE_MODIFY |
Reading and/or writing is allowed. |
When the file is opened, if no CGNSLibraryVersion_t node is found, a default value of 1.05 is assumed for the CGNS version number. Note that this corresponds to an old version of the CGNS standard, that doesn’t include many data structures supported by the current standard.
In order to reduce memory usage and improve execution speed, large arrays such as grid coordinates or flow solutions are not actually stored in memory. Instead, only basic information about the node is kept, while reads and writes of the data is directly to and from the application’s memory. An attempt is also made to do the same with unstructured mesh element data.
filename – [in] Name of the CGNS file, including path name if necessary. There is no limit on the length of this character variable.
mode – [in] Mode used for opening the file. The modes currently supported are CG_MODE_READ, CG_MODE_WRITE, and CG_MODE_MODIFY.
fn – [out] CGNS file index number.
Error status.
cg_version(int fn, float *version)¶Get CGNS file version.
The function cg_version returns the CGNS version number.
fn – [in] CGNS file index number.
version – [out] CGNS version number.
Error status.
cg_precision(int fn, int *precision)¶Get CGNS file precision.
Precision used to write the CGNS file. The precision value will be one of 32 (32-bit), 64 (64-bit), or 0 if not known.
fn – [in] CGNS file index number.
precision – [out] Precision used to write the CGNS file. The return value will be one of 32 (32-bit), 64 (64-bit), or 0 if not known.
Error status.
cg_close(int fn)¶Close a CGNS file.
The function cg_close must always be the last one called. It closes the CGNS file designated by the index number fn and frees the memory where the CGNS data was kept. When a file is opened for writing, cg_close writes all the CGNS data in memory onto disk prior to closing the file. Consequently, if is omitted, the CGNS file is not written properly.
fn – [in] CGNS file index number.
Error status.
cg_save_as(int fn, const char *filename, int file_type, int follow_links)¶Save the open CGNS file.
The CGNS file identified by fn may be saved to a different filename and type using cg_save_as(). In order to save as an HDF5 file, the library must have been built with HDF5 support. ADF support is always built. The function cg_set_file_type() sets the default file type for newly created CGNS files. The function cg_get_file_type() returns the file type for the CGNS file identified by fn. If the CGNS library is built as 32-bit, the additional file type, CG_FILE_ADF2, is available. This allows creation of a 2.5 compatible CGNS file.
fn – [in] CGNS file index number.
filename – [in] Name of the CGNS file, including path name if necessary. There is no limit on the length of this character variable.
file_type – [in] Type of CGNS file. This will typically be either CG_FILE_ADF or CG_FILE_HDF5 depending on the underlying file format.
follow_links – [in] This flag determines whether links are left intact when saving a CGNS file. If non-zero, then the links
Error status.
cg_set_file_type(int file_type)¶Set default file type.
When a CGNS file is newly created using CG_MODE_WRITE, the default type of database manager used is determined at compile time. If the CGNS library was built with HDF5 version 1.8 or later support, the file type will be CG_FILE_HDF5, otherwise CG_FILE_ADF is used. This may be changed either by setting an environment variable, CGNS_FILETYPE, to one of adf, hdf5, or adf2, or by calling the routine cg_set_file_type() prior to the cg_open() call. Calling cg_set_file_type() with the argument CG_FILE_NONE will reset the library to use the default file type. Note: If the environment variable CGNS_FILETYPE is set, it takes precedence.
file_type – [in] Type of CGNS file. This will typically be either CG_FILE_ADF or CG_FILE_HDF5 depending on the underlying file format.
Error status.
cg_get_file_type(int fn, int *file_type)¶Get file type for open CGNS file.
The function cg_get_file_type gets the file type (adf, hdf5, or adf2) for an open CGNS file.
fn – [in] CGNS file index number.
file_type – [out] Type of CGNS file. This will typically be either CG_FILE_ADF or CG_FILE_HDF5 depending on the underlying file format.
Error status.
C Functions |
Modes |
|---|---|
ier = |
r w m |
ier = |
r w m |
ier = |
r w m |
ier = |
r w m |
ier = |
r w m |
ier = |
r w m |
Fortran interfaces |
Modes |
|---|---|
call |
r w m |
call |
r w m |
call |
r w m |
call |
r w m |
call |
r w m |
- option
The option to configure, currently one of
CG_CONFIG_ERROR,CG_CONFIG_COMPRESS,CG_CONFIG_SET_PATH,CG_CONFIG_ADD_PATH,CG_CONFIG_FILE_TYPE,CG_CONFIG_RIND_INDEX,CG_CONFIG_HDF5_COMPRESS, orCG_CONFIG_HDF5_MPI_COMMas defined incgnslib.h.- value
The value to set, type cast as
void *.- compress
CGNS compress (rewrite) setting.
- path
Pathname to search for linked to files when opening a file with external links.
- flag
Fortran flag to set automatic exit in the case of error.
- ier
Error status.
The function cg_configure allows certain CGNS library internal options to be configured. The currently supported options and expected values are:
This allows an error call-back function to be defined by the user. The value should be a pointer to a function to receive the error. The function is defined as void err_callback(int is_error, char *errmsg), and will be called for errors and warnings. The first argument, is_error, will be 0 for warning messages, 1 for error messages, and −1 if the program is going to terminate (i.e., a call to cg_error_exit()). The second argument is the error or warning message. If this is defined, warning and error messages will go to the function, rather than the terminal. A value of NULL will remove the call-back function.
This is the rewrite-upon-close setting.
Note
Prior versions of the library would automatically rewrite the CGNS file when it was closed after being opened in modify mode if there was unused space. This is no longer done, due to possible conflicts when using parallel I/O. The previous behavior may be recovered by setting value to a positive integer. In this case the file will be rewritten if the number of node deletions or modifications are equal to or exceed this number. Setting value to a negative number will force the rewrite when the file is closed. The default value is 0 (no rewrite).
Sets the search path for locating linked-to files. The argument value should be a character string containing one or more directories, formatted the same as for the PATH environment variable. This will replace any current settings. Setting value to NULL will remove all paths.
Adds a directory, or list of directories, to the linked-to file search path. This is the same as CG_CONFIG_SET_PATH, but adds to the path instead of replacing it.
Sets the default file type for newly created CGNS files. The argument, value should be set to one of CG_FILE_NONE, CG_FILE_ADF, CG_FILE_HDF5, or CG_FILE_ADF2. See the discussion above for cg_set_file_type.
This option affects index bounds on structured arrays with rind planes. By default (CG_CONFIG_RIND_CORE), the core array locations always begin at index 1. Lower rind planes, if present, would have an index less than 1. For backward compatibility, CG_CONFIG_RIND_ZERO is provided and the index 1 will then locate the start of the array and not necessarily the start the core array.
Note
Use of this option does not change the cgns file in any way; it only modifies the API to the library.
The API changed for versions of the Mid-Level Library greater than 3.4. Before, it did not produce this behavior.
Index 1 always represented the start of an array: in an array with no rind planes, the core location would have index 1; in an array with 1 rind plane, the core location would have index 2. In version 3.4 of the Mid-Level Library, the behavior of the API was fixed to match that specified in the SIDS: core array locations always begin at index 1. This option allows for configuring the library to pre-3.4 indexing behavior (set value to CG_CONFIG_RIND_ZERO) or the new default behavior (set value to CG_CONFIG_RIND_CORE). Note that using CG_CONFIG_RIND_ZERO is considered obsolete, but is provided for backwards compatability.
Most users should not set this option and use the default.
Values used for this option do not need to be explicitly cast as void*.
Sets the compression level for data written from HDF5. The default is no compression. Setting value to -1, will use the default compression level of 6. The acceptable values are 0 to 9, corresponding to gzip compression levels.
Sets the MPI communicator for parallel I/O. The default is MPI_COMM_WORLD. The new communicator is given by typecasting it to a void *. This is generally used internally - see cgp_mpi_comm instead.
The routines cg_error_handler, cg_set_compress, cg_set_path, cg_add_path, and cg_set_file_type are convenience functions built on top of cg_configure.
There is no Fortran counterpart to function cg_configure or cg_error_handler. The Fortran function cg_exit_on_error_f routine be be used in place of cg_error_handler. If flag is non-zero, then when an error is encountered, the library will print the error message and exit with an code of 1. Setting flag to zero (the default) prevents this and the error is returned to the user code.
Note
The HDF5 implementation does not support search paths for linked files. The links need to be either absolute or relative pathnames. As a result, it is recommended that the search path options not be used as they may be removed in future versions.
C Functions |
Modes |
|---|---|
ier = |
r w m |
ier = |
r w m |
Fortran interfaces |
Modes |
|---|---|
call |
r w m |
call |
r w m |
- fn
CGNS file index number.
- cgio_num
CGIO indentifier for the CGNS file.
- rootid
Root node identifier for the CGNS file.
- ier
Error status.
These allow for the use of the low-level CGIO functions in conjunction with the Mid Level Library. The function cg_get_cgio
returns the CGIO database identifier for the specified CGNS file, which is used in the CGIO routines. The root node identifier for the CGNS file is returned by cg_root_id.