These functions usually are found in the preamble or the epilog of your application code using the CGNS/MLL.
cg_open - Open a CGNS file
cg_version - Get CGNS file version
cg_precision - Get CGNS file precision
cg_close - Close a CGNS file
cg_is_cgns - Check for a valid CGNS file
cg_save_as - Save the open CGNS file
cg_set_file_type - Set default file type
cg_get_file_type - Get file type for open CGNS file
cg_configure - Configure CGNS internals
cg_error_handler - Set CGNS error handler
cg_set_compress - Set CGNS compression mode
cg_get_compress - Get CGNS compression mode
cg_set_path - Set the CGNS link search path
cg_add_path - Add to the CGNS link search path
cg_get_cgio - get the CGIO index number
cg_root_id - get the root node ID
| Functions | Modes |
|---|---|
ier = cg_open(char *filename, int mode, int *fn);
|
r w m
|
ier = cg_version(int fn, float *version);
|
r w m
|
ier = cg_precision(int fn, int *precision);
|
r w m
|
ier = cg_close(int fn);
|
r w m
|
ier = cg_is_cgns(const char *filename, int *file_type);
|
r w m
|
ier = cg_save_as(int fn, const char *filename, int file_type, int follow_links);
|
r w m
|
ier = cg_set_file_type(int file_type);
|
r w m
|
ier = cg_get_file_type(int fn, int *file_type);
|
r w m
|
call cg_open_f(filename, mode, fn, ier)
|
r w m
|
call cg_version_f(fn, version, ier)
|
r w m
|
call cg_precision_f(fn, precision, ier)
|
r w m
|
call cg_close_f(fn, ier)
|
r w m
|
call cg_is_cgns_f(filename, file_type, ier)
|
r w m
|
call cg_save_as_f(fn, filename, file_type, follow_links, ier);
|
r w m
|
call cg_set_file_type_f(file_type, ier);
|
r w m
|
call cg_get_file_type_f(fn, file_type, ier);
|
r w m
|
| filename |
| Name of the CGNS file, including path name if necessary. There is no limit on the length of this character variable. |
mode | Mode used for opening the file.
The modes currently supported are CG_MODE_READ,
CG_MODE_WRITE, and CG_MODE_MODIFY.
| ||
fn | CGNS file index number. | ||
version | CGNS version number. | ||
precision | 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. | ||
file_type | Type of CGNS file. This will typically be either CG_FILE_ADF
or CG_FILE_HDF5 depending on the underlying file format.
However, note that when built in 32-bit, there is also an option
to create a Version 2.5 CGNS file by setting the file type to
CG_FILE_ADF2.
| ||
follow_links | This flag determines whether links are left intact when saving a CGNS file. If non-zero, then the links will be removed and the data associated with the linked files copied to the new file. | ||
ier | Error status. |
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 fn.
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.
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.
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.
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.
For existing files, the function 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.
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.
| Functions | Modes |
|---|---|
ier = cg_configure(int option, void *value);
|
r w m
|
ier = cg_error_handler(void (*)(int, char *));
|
r w m
|
ier = cg_set_compress(int compress);
|
r w m
|
ier = cg_get_compress(int *compress);
|
r w m
|
ier = cg_set_path(const char *path);
|
r w m
|
ier = cg_add_path(const char *path);
|
r w m
|
call cg_configure_f(option, value, ier);
|
r w m
|
call cg_exit_on_errors_f(flag)
|
r w m
|
call cg_set_compress_f(compress, ier)
|
r w m
|
call cg_get_compress_f(compress, ier)
|
r w m
|
call cg_set_path_f(path, ier)
|
r w m
|
call cg_add_path_f(path, ier)
|
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_DISKLESS,
CG_CONFIG_HDF5_DISKLESS_INCR,
CG_CONFIG_HDF5_DISKLESS_WRITE,
CG_CONFIG_HDF5_COMPRESS, or CG_CONFIG_HDF5_MPI_COMM as
defined in cgnslib.h.
|
value | The value to set, type cast as void *. In Fortran the type is TYPE(C_PTR).
| ||
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 particular CGNS library internal
options to be configured.
The currently supported options and expected values are:
| CG_CONFIG_ERROR |
| 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.
|
CG_CONFIG_COMPRESS | 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).
| ||
CG_CONFIG_SET_PATH | 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. In Fortran,
the path must terminate with a NULL character, CHAR(0) or C_NULL_CHAR.
| ||
CG_CONFIG_ADD_PATH | 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. In Fortran,
the path must terminate with a NULL character, CHAR(0) or C_NULL_CHAR.
| ||
CG_CONFIG_FILE_TYPE | 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.
| ||
CG_CONFIG_RIND_INDEX | This option affects index bounds on structured arrays with rind planes.
The SIDS specifies that
core array locations begin at index 1. Lower rind planes, if present,
would have an index less than 1 (see
structured grid indexing
conventions). Versions of
the Mid-Level Library < 3.4 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 API's behavior 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
backward compatibility. Most users should not select this option and use
the default. Values used for this option do not need to be explicitly
cast as void*. This option does not change the cgns file
in any way; it only modifies the API to the library.
| ||
CG_CONFIG_HDF5_COMPRESS | 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. This option currently does nothing as compression is not yet implemented.
| ||
CG_CONFIG_HDF5_MPI_COMM | 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.
| ||
CG_CONFIG_HDF5_DISKLESS | Performs I/O directly to memory and can be used to create temporary CGNS files that never exist on permanent storage.
The memory is written to disk depending on the state of CG_CONFIG_HDF5_DISKLESS_WRITE. CGNS will use the
core file driver in HDF5 via H5Pset_fapl_core, and the parameters associated with
CG_CONFIG_HDF5_DISKLESS are associated with that API. When value is 1, any previously defined driver mode is ignored.
Setting value to 0 disables the diskless mode, enabling the previous mode. This configuration is
not a valid option when accessing the memory by more than one process.
| ||
CG_CONFIG_HDF5_DISKLESS_INCR | Value specifies the increment by which allocated memory is to be increased each time more memory is required, in bytes.
The default is 10MiB. Ideally, value should be set large enough to minimize repeated increases. The type of value is size_t in C and C_SIZE_T in Fortran. Due to a bug with gfortran, it is advisable to use C_LOC or C_FUNLOC in-line of the call instead of using a variable.
| ||
CG_CONFIG_HDF5_DISKLESS_WRITE | Value indicates whether to write (value=1) the memory contents to disk when the file is closed. Otherwise, value=0 does not persist the memory to disk.
|
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 for function
cg_error_handler. The Fortran function cg_exit_on_error_f
routine can 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 a 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.
| Functions | Modes |
|---|---|
ier = cg_get_cgio(int fn, int *cgio_num);
|
r w m
|
ier = cg_root_id(int fn, double *rootid);
|
r w m
|
call cg_get_cgio_f(fn, cgio_num, ier)
|
r w m
|
call cg_root_id_f(fn, rootid, ier)
|
r w m
|
| fn |
| CGNS file index number. |
cgio_num | CGIO identifier 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.