| 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_close(int fn); | r w m |
| ier = cg_is_cgns(const char *filename); | 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_close_f(fn, ier) | r w m |
| call cg_is_cgns_f(filename, 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. For backwards compatibility, the equivalent mode names MODE_READ, MODE_WRITE, and MODE_MODIFY are still supported, but it is recommended that the new names be used. | ||
| fn | CGNS file index number. | ||
| version | CGNS version number. | ||
| 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 their ADF (or HDF) ID numbers are kept in memory for future reference. When a CGNS file is open in writing mode, large arrays passed to the library are immediately written into the CGNS file, directly under the root node. When the file is closed, these arrays are moved to their appropriate location in the CGNS tree.
| Functions | Modes |
|---|---|
| ier = cg_configure(int option, void *value); | r w m |
| option | The option to configure, currently one of CG_CONFIG_ERROR, CG_CONFIG_COMPRESS, CG_CONFIG_SET_PATH, or CG_CONFIG_ADD_PATH as defined in cgnslib.h. | ||
| value | The value to set, type cast as void *. | ||
| ier | Error status. |
The function cg_configure allows certain 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 | When a CGNS file is closed after being opened in modify mode, the normal operation of the CGNS library is to rewrite the file if there is unused space. This happens when nodes have been rewritten or deleted. Setting value to 0 will prevent the library from rewriting the file, and setting it to 1 will force the rewrite. The default value is −1. | ||
| 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. | ||
| 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. |
There is no Fortran counterpart to function cg_configure.