Auxiliary Data

Auxiliary Data

• Reference State
  • cg_state_write - Create ReferenceState_t node
  • cg_state_size - Get length of reference state description string.
  • cg_state_read - Read text description of reference state.
• Gravity
  • cg_gravity_write - Create Gravity_t node
  • cg_gravity_read - Read Gravity_t node
• Convergence History
  • cg_convergence_write - Create ConvergenceHistory_t node
  • cg_convergence_read - Read ConvergenceHistory_t node
• Integral Data
  • cg_integral_write - Create IntegralData_t node
  • cg_nintegrals - Get number of IntegralData_t nodes
  • cg_integral_read - Get name of an IntegralData_t node
• User-Defined Data
  • cg_user_data_write - Create UserDefinedData_t node
  • cg_nuser_data - Get number of UserDefinedData_t nodes
  • cg_user_data_read - Get name of an UserDefinedData_t node
• Freeing Memory
  • cg_free - Release library-allocated memory

Reference State

Node: ReferenceState_t (SIDS, File Mapping)

Functions	Modes
ier = cg_state_write(char *StateDescription);	- w m
ier = cg_state_read(char **StateDescription);	r - m
call cg_state_write_f(StateDescription, ier)	- w m
call cg_state_size_f(Size, ier)	r - m
call cg_state_read_f(StateDescription, ier)	r - m

Input/Output

	StateDescription		Text description of reference state.
	Size		Number of characters in the StateDescription string (Fortran interface only) - integer.
	ier		Error status.

The function cg_state_write creates the ReferenceState_t node and must be called even if StateDescription is undefined (i.e., a blank string). The descriptors, data arrays, data class, and dimensional units characterizing the ReferenceState_t data structure may be added to this data structure after its creation.

The function cg_state_read reads the StateDescription of the local ReferenceState_t node. If StateDescription is undefined in the CGNS database, this function returns a null string. If StateDescription exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(StateDescription).

Gravity

Node: Gravity_t (SIDS, File Mapping)

Functions	Modes
ier = cg_gravity_write(int fn, int B, float *GravityVector);	- w m
ier = cg_gravity_read(int fn, int B, float *GravityVector);	r - m
call cg_gravity_write_f(fn, B, GravityVector, ier)	- w m
call cg_gravity_read_f(fn, B, GravityVector, ier)	r - m

Input/Output

	fn		CGNS file index number.
	B		Base index number, where 1 ≤ B ≤ nbases.
	GravityVector		Components of the gravity vector. The number of components must equal PhysicalDimension. (In Fortran, this is an array of Real*4 values.)
	ier		Error status.

Convergence History

Node: ConvergenceHistory_t (SIDS, File Mapping)

Functions	Modes
ier = cg_convergence_write(int niterations,       char *NormDefinitions);	- w m
ier = cg_convergence_read(int *niterations,       char **NormDefinitions);	r - m
call cg_convergence_write_f(niterations, NormDefinitions, ier)	- w m
call cg_convergence_read_f(niterations, NormDefinitions, ier)	r - m

Input/Output

	niterations		Number of iterations for which convergence information is recorded.
	NormDefinitions		Description of the convergence information recorded in the data arrays.
	ier		Error status.

The function cg_convergence_write creates a ConvergenceHistory_t node. It must be the first one called when recording convergence history data. The NormDefinitions may be left undefined (i.e., a blank string). After creation of this node, the descriptors, data arrays, data class, and dimensional units characterizing the ConvergenceHistory_t data structure may be added.

The function cg_convergence_read reads a ConvergenceHistory_t node. If NormDefinitions is not defined in the CGNS database, this function returns a null string. If NormDefinitions exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(NormDefinitions).

Integral Data

Node: IntegralData_t (SIDS, File Mapping)

Functions	Modes
ier = cg_integral_write(char *Name);	- w m
ier = cg_nintegrals(int *nintegrals);	r - m
ier = cg_integral_read(int Index, char *Name);	r - m
call cg_integral_write_f(Name, ier)	- w m
call cg_nintegrals_f(nintegrals, ier)	r - m
call cg_integral_read_f(Index, Name, ier)	r - m

Input/Output

	Name		Name of the IntegralData_t data structure.
	nintegrals		Number of IntegralData_t nodes under current node.
	Index		Integral data index number, where 1 ≤ Index ≤ nintegrals.
	ier		Error status.

User-Defined Data

Node: UserDefinedData_t (SIDS, File Mapping)

Functions	Modes
ier = cg_user_data_write(char *Name);	- w m
ier = cg_nuser_data(int *nuserdata);	r - m
ier = cg_user_data_read(int Index, char *Name);	r - m
call cg_user_data_write_f(Name, ier)	- w m
call cg_nuser_data_f(nuserdata, ier)	r - m
call cg_user_data_read_f(Index, Name, ier)	r - m

Input/Output

	nuserdata		Number of UserDefinedData_t nodes under current node.
	Name		Name of the UserDefinedData_t node.
	Index		User-defined data index number, where 1 ≤ Index ≤ nuserdata.
	ier		Error status.

After accessing a particular UserDefinedData_t node using cg_goto, the Point Set functions may be used to read or write point set information for the node. The function cg_gridlocation_write may also be used to specify the location of the data with respect to the grid (e.g., Vertex or FaceCenter).

Multiple levels of UserDefinedData_t nodes may be written and retrieved by positioning via cg_goto. E.g.,

   ier = cg_goto(fn, B, "Zone_t", Z, "UserDefinedData_t", ud1, 
                 "UserDefinedData_t", ud2, "UserDefinedData_t", ud3, "end");

Freeing Memory

Functions	Modes
ier = cg_free(void *data);	r w m

Input/Output

	data		Data allocated by the Mid-Level Library.
	ier		Error status.

This function does not affect the structure of a CGNS file; it is provided as a convenience to free memory allocated by the Mid-Level Library. This isn't necessary in Fortran, and thus an equivalent Fortran function is not provided.

The functions that are used to allocate memory for return values are cg_descriptor_read, cg_convergence_read, cg_geo_read, cg_link_read, and cg_state_read. Each of these may allocate space to contain the data returned to the application. It is the responsibility of the application to free this data when it is no longer needed. Calling cg_free is identical to calling the standard C function free, however it is probably safer in that the memory is freed in the same module in which it is created, particularly when the Mid-Level Library is a shared library or DLL. The routine checks for NULL data and will return CG_ERROR in this case, otherwise it returns CG_OK.