\documentstyle{unixman} 

\filenamewidth 3.5 in
\def\met#1{{\it #1}}
\def\meta#1{{$<${\it #1}$>$}}
\gdef\[{\char'133}
\gdef\]{\char'135}

\begin{document} 

\version{1.0}{May 1995}
\header{BBHUtil}{1L}[RNPL compatible HDF routines]

\section{NAME}

gft\_close, gft\_close\_all, gft\_set\_d\_type, gft\_write, gft\_write\_brief, \\ 
gft\_write\_full, gft\_read\_brief, gft\_read\_full, gft\_read\_shape, \\
gft\_read\_id\_str\_p, gft\_read\_id\_int\_p, gft\_read\_id\_float\_p, gft\_read\_2idata, \\
gft\_read\_1idata, gft\_read\_idata, gft\_write\_id\_str\_p, gft\_write\_id\_int\_p, \\
gft\_write\_id\_float\_p, gft\_write\_2idata, gft\_write\_1idata, gft\_write\_idata \\

RNPL HDF routines

\section{SYNOPSIS} 

{\tt
\#include <bbhutil.h>\\

BBH\_I gft\_close(const BBH\_C *nm);\\
BBH\_I gft\_close\_all(BBH\_V);\\

BBH\_I gft\_set\_d\_type(BBH\_I type)\\

BBH\_I gft\_write(const BBH\_C *func\_name, BBH\_D time, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *data);\\
BBH\_I gft\_write\_brief(const BBH\_C *func\_name, BBH\_D time, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *data);\\
BBH\_I gft\_write\_bbox(const BBH\_C *func\_name, BBH\_D time, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *coords, BBH\_D *data);\\
BBH\_I gft\_write\_full(const BBH\_C *func\_name, BBH\_D time,\\
                    BBH\_I *shape, BBH\_C **cnames, BBH\_I rank, \\
                    BBH\_D *coords, BBH\_D *data ); \\

BBH\_I gft\_read\_brief(const BBH\_C *file\_name, BBH\_I level, BBH\_D *data);\\
BBH\_I gft\_read\_full(const BBH\_C *file\_name, BBH\_I level, \\
                    BBH\_I *shape, BBH\_C **cnames,\\
                    BBH\_I rank, BBH\_D *time, BBH\_D *coords, \\
                    BBH\_D *data);\\
BBH\_I gft\_read\_shape(const BBH\_C *file\_name, BBH\_I *shape);\\

BBH\_I gft\_read\_id\_str\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_C **param, BBH\_I nparam);\\
BBH\_I gft\_read\_id\_int\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_I *param, BBH\_I nparam);\\
BBH\_I gft\_read\_id\_float\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_I *param, BBH\_I nparam);\\
BBH\_I gft\_read\_2idata(const BBH\_C *file\_name, const BBH\_C *func\_name,\\
                    BBH\_I *shape, BBH\_I rank, \\
                    BBH\_D *datanm1, BBH\_D *datan); \\
BBH\_I gft\_read\_1idata(const BBH\_C *file\_name, const BBH\_C *func\_name, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *datan); \\
BBH\_I gft\_read\_idata(const BBH\_C *file\_name, const BBH\_C *func\_name, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *data); \\

BBH\_I gft\_write\_id\_str\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_C **param, BBH\_I nparam);\\
BBH\_I gft\_write\_id\_int\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_I *param, BBH\_I nparam);\\
BBH\_I gft\_write\_id\_float\_p(const BBH\_C *file\_name, const BBH\_C *param\_name,\\
                        BBH\_D *param, BBH\_I nparam);\\
BBH\_I gft\_write\_2idata(const BBH\_C *file\_name, const BBH\_C *func\_name, \\
                    BBH\_I *shape, BBH\_I rank, \\
                    BBH\_D *datanm1, BBH\_D *datan); \\
BBH\_I gft\_write\_1idata(const BBH\_C *file\_name, const BBH\_C *func\_name, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *datan);\\
BBH\_I gft\_write\_idata(const BBH\_C *file\_name, const BBH\_C *func\_name, \\
                    BBH\_I *shape, BBH\_I rank, BBH\_D *data);\\
}

\section{DESCRIPTION} 

BBHUtil provides a set of C and FORTRAN callable functions which read and write the HDF files which are read and written by \prog{rnpl} generated programs.  These include initial data files as well as evolution output files.

File names may be altered from the parameter in the following ways: spaces are killed, non-alphanumeric characters are replaced by \_, and .hdf is appended if it is not already there.

gft\_close closes the HDF file whose name is passed as a parameter.

gft\_close\_all closes all open HDF files.

gft\_set\_d\_type will set the grid function type which is written by the gft\_write* calls.  The default type is DFNT\_FLOAT64.  The only other valid type is DFNT\_INT32.

gft\_write, gft\_write\_brief will write the grid function given in data to the evolution HDF file whose name is formed from the func\_name.  Func\_name is the name of the grid function.  Time gives the time at which the grid function had the values given in data.  The rank and shape provide the size of the grid function.  The coordinates are named x,y,z and the coordinate values are integers running from 1 to shape.

gft\_write\_bbox performs the same function as gft\_write.  In addition, the coordinate values are taken from the bounding box coords.  Coords is a one dimensional array the whose first two values provide the min and max for the first coordinate, the next two values provide the min and max for the second coordinate, etc.  In general, the minimum for the nth coordinate is stored in position 2(n-1) and the maximum is in position 2(n-1) + 1.

gft\_write\_full works as the above except the coordinate names are given explicitly in cnames and the coordinate values are given explicitly in coords.  The first shape[0] values of coords are the values of the first coordinate, the next shape[1] values are for the second coordinate, etc.

gft\_read\_brief returns a grid function from the file given by file\_name.  Level runs from 1 to the number of time levels stored in the file.

gft\_read\_full takes the file name, desired time level, and rank and returns complete information including the grid function, time, shape, coordinate names, and coordinate values.  Storage for the returned values must be preallocated.

gft\_read\_shape returns the shape of the data sets in an \prog{rnpl} evolution HDF file.

gft\_read\_id\_str\_p, gft\_read\_id\_int\_p, and gft\_read\_id\_float\_p are for reading parameters from initial data HDF files.  The routines take the file name, parameter name, and number of parameters (array size) and return the parameter values.  Sufficient storage must be preallocated and passed in.

gft\_read\_2idata reads two time levels of initial data from an initial data HDF file.  File\_name is the name of the initial data file.  Func\_name is the name of the grid function.  Shape and rank contain the size of the data sets.  Datan is the data set with the later time, and datanm1 is the data set at the earlier time.  Storage must be preallocated.

gft\_read\_1idata works the same way except for grid functions with only one time level of initial data.

gft\_read\_idata will read one time level of data from an initial data file for a function with any number of time levels.  Func\_name must carry the time level information as well as the function name.  For instance if the grid function name is ``Phi'' then the first time level (earliest) would be requested with a func\_name of ``Phi[0]'' while the next would be ``Phi[1]'' and so on.

gft\_write\_id\_str\_p, gft\_write\_id\_int\_p, and gft\_write\_id\_float\_p work like their read counter parts, except they write data to an initial data file.

gft\_write\_2idata, gft\_write\_1idata, and gft\_write\_idata work like their read counter parts, except they write data to an initial data file.

All functions return 1 upon success and 0 on failure.  Error messages are sent to stderr.  The routines take care of opening or creating files as necessary.  The evolution data write routines (gft\_write[brief,bbox,full]) will check the environment variable GFT\_HDFAPPEND.  If this variable is set to 'on' then existing evolution files will be appended to instead of overwritten.

\section{FILES}

\begin{filelist}
\fileref{bbhutil.h} Header file for BBHUtil routines.
\fileref{libbbhutil.a} Library file.
\end{filelist}

\section{SEE ALSO}

\I rnpl(1)

The RNPL Reference Manual \\
The RNPL User's Guide

\end{document}