CGIO User's Guide - Data I/O Routines

(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Mid-Level Library) (Standard Interface Data Structures) (SIDS File Mapping Manual) (CGIO User's Guide) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(The CGIO Software Library) (Database-Level Routines) (Data Structure Management Routines) (Link Management Routines) (Node Management Routines) (Data I/O Routines) (Error Messages and Routines) (Miscellaneous Routines) (Example Programs)

Data I/O Routines

Functions	Modes
`ier = cgio_read_data_type(int cgio_num, double id, const cgsize_t s_start, const cgsize_t s_end, const cgsize_t s_stride, const char m_data_type, int m_num_dims, const cgsize_t m_dims, const cgsize_t m_start, const cgsize_t m_end, const cgsize_t m_stride, void *data);`	`r w m`
`ier = cgio_read_all_data_type(int cgio_num, double id, const char m_data_type, void data);`	`r w m`
`ier = cgio_read_block_data_type(int cgio_num, double id, cgsize_t b_start, cgsize_t b_end, const char m_data_type, void data);`	`r w m`
`ier = cgio_write_data(int cgio_num, double id, const cgsize_t s_start, const cgsize_t s_end, const cgsize_t s_stride, int m_num_dims, const cgsize_t m_dims, const cgsize_t m_start, const cgsize_t m_end, const cgsize_t m_stride, void data);`	`- w m`
`ier = cgio_write_data_type(int cgio_num, double id, const cgsize_t s_start, const cgsize_t s_end, const cgsize_t s_stride, const char m_data_type, int m_num_dims, const cgsize_t m_dims, const cgsize_t m_start, const cgsize_t m_end, const cgsize_t m_stride, void *data);`	`- w m`
`ier = cgio_write_all_data(int cgio_num, double id, void *data);`	`- w m`
`ier = cgio_write_all_data_type(int cgio_num, double id, const char m_data_type, void data);`	`- w m`
`ier = cgio_write_block_data(int cgio_num, double id, cgsize_t b_start, cgsize_t b_end, void *data);`	`- w m`
`call cgio_read_data_type_f(cgio_num, id, s_start, s_end, s_stride, m_data_type, m_num_dims, m_dims, m_start, m_end, m_stride, data, ier)`	`r w m`
`call cgio_read_all_data_type_f(cgio_num, id, m_data_type, data, ier)`	`r w m`
`call cgio_read_block_data_type_f(cgio_num, id, b_start, b_end, m_data_type, data, ier)`	`r w m`
`call cgio_write_data_f(cgio_num, id, s_start, s_end, s_stride, m_num_dims, m_dims, m_start, m_end, m_stride, data, ier)`	`- w m`
`call cgio_write_data_type_f(cgio_num, id, s_start, s_end, s_stride, m_data_type, m_num_dims, m_num_dims, m_dims, m_start, m_end, m_stride, data, ier)`	`- w m`
`call cgio_write_all_data_f(cgio_num, id, data, ier)`	`- w m`
`call cgio_write_all_data_type_f(cgio_num, id, m_data_type, data, ier)`	`- w m`
`call cgio_write_block_data_f(cgio_num, id, b_start, b_end, data, ier)`	`- w m`

Input/Output

	`cgio_num`		Database identifier.
	`id`		Node identifier.
	`s_start`		Starting indices for data in the database. Fortran indexing is used (starting at 1).
	`s_end`		Ending indices for data in the database. Fortran indexing is used (starting at 1).
	`s_stride`		Step increment for data in the database.
	`m_num_dims`		Number of dimensions for data in memory.
	`m_dims`		Dimension values for data in memory.
	`m_start`		Starting indices for data in memory. Fortran indexing is used (starting at 1).
	`m_end`		Ending indices for data in memory. Fortran indexing is used (starting at 1).
	`m_stride`		Step increment for data in memory.
	`m_data_type`		Type of data being used for data in memory. One of "I4", "I8", "U4", "U8", "R4", "R8", "C1", or "B1".
	`data`		Array of data to be read or written.
	`b_start`		Starting offset (index) for the data in the database. Fortran indexing is used (starting at 1).
	`b_end`		Ending offset (index) for the data in the database. Fortran indexing is used (starting at 1).
	`ier`		Error status.

Function Descriptions

cgio_read_data_type: This routine provides general purpose read capabilities from the node identified by id in the database given by cgio_num. It allows for a general specification of the starting location within the data as well as fixed step lengths (strides) through the data from the initial position. This capability works for both the data on disk and the data being stored in memory. One set of vectors (s_start, s_end and s_stride) are used to describe the mapping of the data within the node, and a second set of vectors (m_start, m_end and m_stride) are used to describe the mapping of the desired data within memory.

The memory dimensions are given by m_num_dims and m_dims. There is no requirement that the node dimensions and memory dimensions match, only that the total number of values to be read are the same for the node and memory specifications.

The data are stored in both memory and on disk in "Fortran ordering." That is, the first index varies the fastest, and indexing starts at 1. Negative indexing is not allowed.

Be careful when writing data using cgio_write_all_data and then using cgio_read_data_type to randomly access the data. cgio_write_all_data_type takes a starting address in memory and writes N words to disk, making no assumption as to the order of the data. cgio_read_data_type assumes that the data have Fortran-like ordering to navigate through the data in memory and on disk. It assumes that the first dimension varies the fastest. It would be easy for a C program to use the default array ordering (last dimension varying fastest) and write the data out using cgio_write_all_data_type. Then another program might use cgio_read_data_type to access a subsection of the data, and the routine would not return what was expected.

There can be a significant performance penalty for using cgio_read_data_type when compared with cgio_read_all_data_type. If performance is a major consideration, it is best to organize data to take advantage of the speed of cgio_read_all_data_type.

The function returns 0 on success, else an error code.

cgio_read_all_data_type: Reads all the data from the node identified by id in the database given by cgio_num. On success, the function returns 0 and the data in data, else an error code is returned. Note: Data is returned in Fortran indexing order.

cgio_read_block_data_type: Reads a contiguous block of data from the node identified by id in the database given by cgio_num. On success, the function returns 0 and the data in data, else an error code is returned. The starting index is given by b_start and the end by b_end. Note: Fortran indexing order for multi-dimensional data is used when computing the starting and ending locations.

cgio_write_data, cgio_write_data_type: This function is similar to cgio_read_data_type, but writes the data from memory to the node.

cgio_write_all_data, cgio_write_all_data_type: This function is similar to cgio_read_all_data_type, but writes the data from memory to the node.

cgio_write_block_data: This function is similar to cgio_read_block_data_type, but writes the data from memory to the node.