Commit 3e99514d authored by Uwe Schulzweida's avatar Uwe Schulzweida
Browse files

Docu update

parent 3b7ef021
......@@ -110,15 +110,15 @@ void cdiDefCompress(int level);
/* STREAM control routines */
/* streamOpenRead: Open a file for reading */
int streamOpenRead(const char *filename);
/* streamOpenRead: Open a dataset for reading */
int streamOpenRead(const char *path);
/* streamOpenWrite: Open a file for writing */
int streamOpenWrite(const char *filename, int filetype);
/* streamOpenWrite: Create a new dataset */
int streamOpenWrite(const char *path, int filetype);
int streamOpenAppend(const char *filename);
int streamOpenAppend(const char *path);
/* streamClose: Close an Open file */
/* streamClose: Close an open dataset */
void streamClose(int streamID);
/* streamDefVlist: Define the Vlist for a stream */
......@@ -236,12 +236,12 @@ int vlistInqVarGrid(int vlistID, int varID);
int vlistInqVarZaxis(int vlistID, int varID);
int vlistInqVarTime(int vlistID, int varID);
/* vlistDefVarCode: Define the Code number of a variable */
/* vlistDefVarCode: Define the code number of a Variable */
void vlistDefVarCode(int vlistID, int varID, int code);
int vlistInqVarCode(int vlistID, int varID);
/* vlistDefVarDatatype: Define the data type of a variable */
/* vlistDefVarDatatype: Define the data type of a Variable */
void vlistDefVarDatatype(int vlistID, int varID, int datatype);
int vlistInqVarDatatype(int vlistID, int varID);
......@@ -253,12 +253,12 @@ int vlistInqVarModel(int vlistID, int varID);
void vlistDefVarTable(int vlistID, int varID, int tableID);
int vlistInqVarTable(int vlistID, int varID);
/* vlistDefVarName: Define the name of a variable */
/* vlistDefVarName: Define the name of a Variable */
void vlistDefVarName(int vlistID, int varID, const char *name);
void vlistInqVarName(int vlistID, int varID, char *name);
/* vlistDefVarLongname: Define the long name of a variable */
/* vlistDefVarLongname: Define the long name of a Variable */
void vlistDefVarLongname(int vlistID, int varID, const char *longname);
void vlistDefVarStdname(int vlistID, int varID, const char *stdname);
......@@ -266,12 +266,12 @@ void vlistDefVarStdname(int vlistID, int varID, const char *stdname);
void vlistInqVarLongname(int vlistID, int varID, char *longname);
void vlistInqVarStdname(int vlistID, int varID, char *stdname);
/* vlistDefVarUnits: Define the units of a variable */
/* vlistDefVarUnits: Define the units of a Variable */
void vlistDefVarUnits(int vlistID, int varID, const char *units);
void vlistInqVarUnits(int vlistID, int varID, char *units);
/* vlistDefVarMissval: Define the missing value of a variable */
/* vlistDefVarMissval: Define the missing value of a Variable */
void vlistDefVarMissval(int vlistID, int varID, double missval);
double vlistInqVarMissval(int vlistID, int varID);
......@@ -300,23 +300,26 @@ int vlistFindLevel(int vlistID, int fvarID, int flevelID);
void gridName(int gridtype, char *gridname);
char *gridNamePtr(int gridtype);
void gridCompress(int gridID);
void gridDefMask(int gridID, int *mask);
int gridInqMask(int gridID, int *mask);
void gridPrint(int gridID);
int gridSize(void);
/* gridNew: Create a new Grid */
int gridNew(int gridtype, int size);
/* gridDuplicate: Duplicate a Grid */
int gridDuplicate(int gridID);
/* gridInqType: Get the type of a Grid */
int gridInqType(int gridID);
/* gridInqSize: Get the size of a Grid */
int gridInqSize(int gridID);
/* gridDuplicate: Duplicate a Grid */
int gridDuplicate(int gridID);
void gridCompress(int gridID);
void gridPrint(int gridID);
int gridSize(void);
/* gridDefXsize: Define the size of a X-axis */
void gridDefXsize(int gridID, int xsize);
......@@ -338,10 +341,6 @@ int gridInqXvals(int gridID, double *xvals);
/* gridDefYvals: Define the values of a Y-axis */
void gridDefYvals(int gridID, double *yvals);
int gridInqMask(int gridID, int *mask);
void gridDefMask(int gridID, int *mask);
/* gridInqYvals: Get all values of a Y-axis */
int gridInqYvals(int gridID, double *yvals);
......
......@@ -537,8 +537,27 @@ static void defineYvals(int gridID)
The function {\tt gridNew} creates a new Grid.
@Result
{\tt gridNew} return an identifier to the new Grid.
{\tt gridNew} returns an identifier to the new Grid.
@Example
Here is an example using {\tt gridNew} to create a new {\tt LONLAT} Grid:
@Source
#include <cdi.h>
...
int gridID;
int nlon = 12;
int nlat = 6;
double lons[nlon] = {0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330};
double lats[nlat] = {-75, -45, -15, 15, 45, 75};
...
gridID = gridNew(GRID_LONLAT, nlon*nlat);
gridDefXsize(gridID, nlon);
gridDefYsize(gridID, nlat);
gridDefXvals(gridID, lons);
gridDefYvals(gridID, lats);
...
@EndSource
@EndFunction
*/
int gridNew(int gridtype, int size)
......@@ -620,7 +639,7 @@ int gridNew(int gridtype, int size)
char *gridNamePtr(int gridtype)
{
char *name;
int size = sizeof(Grids)/sizeof(char *);
int size = (int) (sizeof(Grids)/sizeof(char *));
if ( gridtype >= 0 && gridtype < size )
name = Grids[gridtype];
......@@ -797,10 +816,10 @@ void gridDefYunits(int gridID, char *yunits)
@Item name Name of the X-axis
@Description
The function {\tt gridInqXname} gets the name of a X-axis.
The function {\tt gridInqXname} returns the name of a X-axis.
@Result
{\tt gridInqXname} return the name of the X-axis to the parameter name.
{\tt gridInqXname} returns the name of the X-axis to the parameter name.
@EndFunction
*/
......@@ -824,10 +843,10 @@ void gridInqXname(int gridID, char *xname)
@Item longname Longname of the X-axis
@Description
The function {\tt gridInqXlongname} gets the longname of a X-axis.
The function {\tt gridInqXlongname} returns the longname of a X-axis.
@Result
{\tt gridInqXlongname} return the longname of the X-axis to the parameter longname.
{\tt gridInqXlongname} returns the longname of the X-axis to the parameter longname.
@EndFunction
*/
......@@ -851,10 +870,10 @@ void gridInqXlongname(int gridID, char *xlongname)
@Item units Units of the X-axis
@Description
The function {\tt gridInqXunits} gets the units of a X-axis.
The function {\tt gridInqXunits} returns the units of a X-axis.
@Result
{\tt gridInqXunits} return the units of the X-axis to the parameter units.
{\tt gridInqXunits} returns the units of the X-axis to the parameter units.
@EndFunction
*/
......@@ -888,10 +907,10 @@ void gridInqXstdname(int gridID, char *xstdname)
@Item name Name of the Y-axis
@Description
The function {\tt gridInqYname} gets the name of a Y-axis.
The function {\tt gridInqYname} returns the name of a Y-axis.
@Result
{\tt gridInqYname} return the name of the Y-axis to the parameter name.
{\tt gridInqYname} returns the name of the Y-axis to the parameter name.
@EndFunction
*/
......@@ -915,10 +934,10 @@ void gridInqYname(int gridID, char *yname)
@Item longname Longname of the Y-axis
@Description
The function {\tt gridInqYlongname} gets the longname of a Y-axis.
The function {\tt gridInqYlongname} returns the longname of a Y-axis.
@Result
{\tt gridInqYlongname} return the longname of the Y-axis to the parameter longname.
{\tt gridInqYlongname} returns the longname of the Y-axis to the parameter longname.
@EndFunction
*/
......@@ -942,10 +961,10 @@ void gridInqYlongname(int gridID, char *ylongname)
@Item units Units of the Y-axis
@Description
The function {\tt gridInqYunits} gets the units of a Y-axis.
The function {\tt gridInqYunits} returns the units of a Y-axis.
@Result
{\tt gridInqYunits} return the units of the Y-axis to the parameter units.
{\tt gridInqYunits} returns the units of the Y-axis to the parameter units.
@EndFunction
*/
......@@ -977,10 +996,10 @@ void gridInqYstdname(int gridID, char *ystdname)
@Item gridID Grid identifier
@Description
The function {\tt gridInqType} get the type of a Grid.
The function {\tt gridInqType} returns the type of a Grid.
@Result
{\tt gridInqType} return the type of the grid,
{\tt gridInqType} returns the type of the grid,
one of the set of predefined CDI grid types.
The valid CDI grid types are {\tt GRID_GENERIC}, {\tt GRID_GAUSSIAN},
{\tt GRID_LONLAT}, {\tt GRID_SPECTRAL}, {\tt GRID_CURVILINEAR} and {\tt GRID_CELL}.
......@@ -1009,10 +1028,10 @@ int gridInqType(int gridID)
@Item gridID Grid identifier
@Description
The function {\tt gridInqSize} get the size of a Grid.
The function {\tt gridInqSize} returns the size of a Grid.
@Result
{\tt gridInqSize} return the number of grid points of a Grid.
{\tt gridInqSize} returns the number of grid points of a Grid.
@EndFunction
*/
......@@ -1085,6 +1104,7 @@ int gridInqTrunc(int gridID)
return (gridptr->trunc);
}
void gridDefTrunc(int gridID, int trunc)
{
static char func[] = "gridDefTrunc";
......@@ -1097,6 +1117,21 @@ void gridDefTrunc(int gridID, int trunc)
gridptr->trunc = trunc;
}
/*
@Function gridDefXsize
@Title Define the number of values of a X-axis
@Prototype void gridDefXsize(int gridID, int xsize)
@Parameter
@Item gridID Grid identifier
@Item xsize Number of values of a X-axis
@Description
The function {\tt gridDefXsize} defines the number of values of a X-axis.
@EndFunction
*/
void gridDefXsize(int gridID, int xsize)
{
static char func[] = "gridDefXsize";
......@@ -1168,12 +1203,18 @@ int gridInqPrec(int gridID)
/*
@Function
@Title
@Function gridInqXsize
@Title Get the number of values of a X-axis
@Prototype
@Prototype void gridInqXsize(int gridID)
@Parameter
@Item Grid identifier
@Item gridID Grid identifier
@Description
The function {\tt gridInqXsize} returns the number of values of a X-axis.
@Result
{\tt gridInqXsize} returns the number of values of a X-axis.
@EndFunction
*/
......@@ -1191,12 +1232,16 @@ int gridInqXsize(int gridID)
/*
@Function
@Title
@Function gridDefYsize
@Title Define the number of values of a Y-axis
@Prototype
@Prototype void gridDefYsize(int gridID, int ysize)
@Parameter
@Item Grid identifier
@Item gridID Grid identifier
@Item ysize Number of values of a Y-axis
@Description
The function {\tt gridDefYsize} defines the number of values of a Y-axis.
@EndFunction
*/
......@@ -1225,12 +1270,18 @@ void gridDefYsize(int gridID, int ysize)
/*
@Function
@Title
@Function gridInqYsize
@Title Get the number of values of a Y-axis
@Prototype
@Prototype void gridInqYsize(int gridID)
@Parameter
@Item Grid identifier
@Item gridID Grid identifier
@Description
The function {\tt gridInqYsize} returns the number of values of a Y-axis.
@Result
{\tt gridInqYsize} returns the number of values of a Y-axis.
@EndFunction
*/
......@@ -1369,10 +1420,10 @@ void gridDefMask(int gridID, int *mask)
@Item xvals X-values of the grid
@Description
The function {\tt gridInqXvals} gets all values of the X-axis.
The function {\tt gridInqXvals} returns all values of the X-axis.
@Result
Upon successful completion {\tt gridInqXvals} return the number of values and
Upon successful completion {\tt gridInqXvals} returns the number of values and
the values are stored in {\tt xvals}.
Otherwise, 0 is returned and {\tt xvals} is empty.
......@@ -1463,10 +1514,10 @@ void gridDefXvals(int gridID, double *xvals)
@Item yvals Y-values of the grid
@Description
The function {\tt gridInqYvals} gets all values of the Y-axis.
The function {\tt gridInqYvals} returns all values of the Y-axis.
@Result
Upon successful completion {\tt gridInqYvals} return the number of values and
Upon successful completion {\tt gridInqYvals} returns the number of values and
the values are stored in {\tt yvals}.
Otherwise, 0 is returned and {\tt yvals} is empty.
......@@ -2227,6 +2278,23 @@ int gridGenerate(GRID grid)
}
/*
@Function gridDuplicate
@Title Duplicate a grid
@Prototype int gridDuplicate(int gridID)
@Parameter
@Item gridID Identifier, from a previous call to {\tt gridNew},
{\tt gridDuplicate} or {\tt vlistInqVarGrid}.
@Description
The function {\tt gridDuplicate} duplicates a grid.
@Result
{\tt gridDuplicate} returns an identifier to the duplicated grid.
@EndFunction
*/
int gridDuplicate(int gridID)
{
static char func[] = "gridDuplicate";
......@@ -2531,10 +2599,10 @@ void gridDefXbounds(int gridID, double *xbounds)
@Item xbounds X-bounds of the grid
@Description
The function {\tt gridInqXbounds} gets the bounds of the X-axis.
The function {\tt gridInqXbounds} returns the bounds of the X-axis.
@Result
Upon successful completion {\tt gridInqXbounds} return the number of bounds and
Upon successful completion {\tt gridInqXbounds} returns the number of bounds and
the bounds are stored in {\tt xbounds}.
Otherwise, 0 is returned and {\tt xbounds} is empty.
......@@ -2639,10 +2707,10 @@ void gridDefYbounds(int gridID, double *ybounds)
@Item ybounds Y-bounds of the grid
@Description
The function {\tt gridInqYbounds} gets the bounds of the Y-axis.
The function {\tt gridInqYbounds} returns the bounds of the Y-axis.
@Result
Upon successful completion {\tt gridInqYbounds} return the number of bounds and
Upon successful completion {\tt gridInqYbounds} returns the number of bounds and
the bounds are stored in {\tt ybounds}.
Otherwise, 0 is returned and {\tt ybounds} is empty.
......
......@@ -189,10 +189,10 @@ static int getFiletype(const char *filename, int *byteorder)
@Item streamID Stream identifier
@Description
The function {\tt streamInqFiletype} gets the filetype of a stream.
The function {\tt streamInqFiletype} returns the filetype of a stream.
@Result
{\tt streamInqFiletype} return the type of the file format,
{\tt streamInqFiletype} returns the type of the file format,
one of the set of predefined CDI file format types.
The valid CDI file format types are {\tt FILETYPE_GRB}, {\tt FILETYPE_NC},
{\tt FILETYPE_NC2}, {\tt FILETYPE_SRV}, and {\tt FILETYPE_EXT}.
......@@ -284,7 +284,7 @@ int streamInqByteorder(int streamID)
char *streamFilesuffix(int filetype)
{
static char *fileSuffix[] = {"", ".grb", ".g2", ".nc", ".nc2", ".srv", ".ext", ".h5", ".ieg"};
int size = sizeof(fileSuffix)/sizeof(char *);
int size = (int) (sizeof(fileSuffix)/sizeof(char *));
if ( filetype > 0 && filetype < size )
return (fileSuffix[filetype]);
......@@ -738,17 +738,17 @@ int streamOpenA(const char *filename, const char *filemode, int filetype)
/*
@Function streamOpenRead
@Title Open a file for reading
@Title Open a dataset for reading
@Prototype int streamOpenRead(const char *filename)
@Prototype int streamOpenRead(const char *path)
@Parameter
@Item filename The file name of the dataset to be read
@Item path The name of the dataset to be read
@Description
The function {\tt streamOpenRead} opens an existing file for reading.
The function {\tt streamOpenRead} opens an existing dataset for reading.
@Result
Upon successful completion {\tt streamOpenRead} return an identifier to the
Upon successful completion {\tt streamOpenRead} returns an identifier to the
open stream. Otherwise, a negative number with the error status is returned.
@Errors
......@@ -810,20 +810,19 @@ int streamOpenAppend(const char *filename)
/*
@Function streamOpenWrite
@Title Open a file for writing
@Title Create a new dataset
@Prototype int streamOpenWrite(const char *filename, int filetype)
@Prototype int streamOpenWrite(const char *path, int filetype)
@Parameter
@Item filename The file name of the dataset to be read
@Item path The name of the new dataset
@Item filetype The type of the file format, one of the set of predefined CDI file format types.
The valid CDI file format types are {\tt FILETYPE_GRB}, {\tt FILETYPE_NC},
{\tt FILETYPE_NC2}, {\tt FILETYPE_SRV}, and {\tt FILETYPE_EXT}.
@Description
The function {\tt streamOpenWrite} create a new file for writing.
The function {\tt streamOpenWrite} creates a new datset.
@Result
Upon successful completion {\tt streamOpenWrite} return an identifier to the
Upon successful completion {\tt streamOpenWrite} returns an identifier to the
open stream. Otherwise, a negative number with the error status is returned.
@Errors
......@@ -857,7 +856,7 @@ int streamOpenWrite(const char *filename, int filetype)
/*
@Function streamClose
@Title Close an Open file
@Title Close an open dataset
@Prototype void streamClose(int streamID)
@Parameter
......@@ -865,7 +864,7 @@ int streamOpenWrite(const char *filename, int filetype)
or {\tt streamOpenWrite}
@Description
The function {\tt streamClose} closes an open file.
The function {\tt streamClose} closes an open dataset.
@EndFunction
*/
......@@ -996,7 +995,7 @@ void streamClose(int streamID)
The function {\tt streamDefTimestep} defines the timestep of a stream.
@Result
{\tt streamDefTimestep} return the number of records of the timestep.
{\tt streamDefTimestep} returns the number of records of the timestep.
@EndFunction
*/
......@@ -1055,10 +1054,10 @@ int streamDefTimestep(int streamID, int tsID)
@Item tsID Timestep identifier
@Description
The function {\tt streamInqTimestep} gets the timestep of a stream.
The function {\tt streamInqTimestep} returns the timestep of a stream.
@Result
{\tt streamInqTimestep} return the number of records of the timestep.
{\tt streamInqTimestep} returns the number of records of the timestep.
@EndFunction
*/
......@@ -1550,7 +1549,7 @@ void streamWriteContents(int streamID, char *cname)
varID = streams[streamID].tsteps[tsID].records[recID].varID;
levelID = streams[streamID].tsteps[tsID].records[recID].levelID;
recpos = streams[streamID].tsteps[tsID].records[recID].position;
recsize = streams[streamID].tsteps[tsID].records[recID].size;
recsize = (long)streams[streamID].tsteps[tsID].records[recID].size;
fprintf(cnp, "%4d:%4d:%4d:%4d:%4ld:%ld\n",
tsID, recID, varID, levelID, recsize, (long) recpos);
}
......@@ -1674,10 +1673,10 @@ void streamDefVlist(int streamID, int vlistID)
@Item streamID Stream identifier
@Description
The function {\tt streamInqVlist} gets the variable list of a stream.
The function {\tt streamInqVlist} returns the variable list of a stream.
@Result
{\tt streamInqVlist} return an identifier to the variable list.
{\tt streamInqVlist} returns an identifier to the variable list.
@EndFunction
*/
......
......@@ -105,7 +105,7 @@ static int splitBasetime(char *timeunits, TAXIS *taxis)
int timeunit = -1;
ptu = timeunits;
len = strlen(timeunits);
len = (int) strlen(timeunits);
(*taxis).type = timetype;
......@@ -303,7 +303,7 @@ int cdfCopyRecord(int ostreamID, int istreamID)
{
static char func[] = "cdfCopyRecord";
double *data;
size_t datasize;
int datasize;
int itsID, otsID, irecID, orecID;
int ivarID, gridID;
int nmiss;
......@@ -339,6 +339,7 @@ int cdfCopyRecord(int ostreamID, int istreamID)
return (ierr);
}
/* not used
int cdfInqRecord(int streamID, int *varID, int *levelID)
{
......
......@@ -190,7 +190,7 @@ static void taxisCheckID(const char *func, int taxisID)
The function {\tt taxisNew} creates a new Time axis.
@Result
{\tt taxisNew} return an identifier to the new T-axis.
{\tt taxisNew} returns an identifier to the new T-axis.
@EndFunction
*/
......@@ -422,10 +422,10 @@ void taxisCopyTimestep(int taxisIDdes, int taxisIDsrc)
@Item taxisID T-axis identifier
@Description
The function {\tt taxisInqVdate} gets the verification date of a Time axis.
The function {\tt taxisInqVdate} returns the verification date of a Time axis.
@Result
{\tt taxisInqVdate} return the verification date.
{\tt taxisInqVdate} returns the verification date.
@EndFunction
*/
......@@ -448,10 +448,10 @@ int taxisInqVdate(int taxisID)
@Item taxisID T-axis identifier
@Description
The function {\tt taxisInqVtime} gets the verification time of a Time axis.
The function {\tt taxisInqVtime} returns the verification time of a Time axis.
@Result
{\tt taxisInqVtime} return the verification time.
{\tt taxisInqVtime} returns the verification time.
@EndFunction
*/
......@@ -474,10 +474,10 @@ int taxisInqVtime(int taxisID)
@Item taxisID T-axis identifier
@Description
The function {\tt taxisInqRdate} gets the reference date of a Time axis.
The function {\tt taxisInqRdate} returns the reference date of a Time axis.
@Result
{\tt taxisInqVdate} return the reference date.
{\tt taxisInqVdate} returns the reference date.
@EndFunction
*/
......@@ -506,10 +506,10 @@ int taxisInqRdate(int taxisID)
@Item taxisID T-axis identifier
@Description
The function {\tt taxisInqRtime} gets the reference time of a Time axis.
The function {\tt taxisInqRtime} returns the reference time of a Time axis.
@Result
{\tt taxisInqVtime} return the reference time.
{\tt taxisInqVtime} returns the reference time.
@EndFunction
*/
......@@ -538,10 +538,10 @@ int taxisInqRtime(int taxisID)
@Item taxisID T-axis identifier
@Description
The function {\tt taxisInqCalendar} gets the calendar of a Time axis.
The function {\tt taxisInqCalendar} returns the calendar of a Time axis.
@Result
{\tt taxisInqCalendar} return the type of the calendar,
{\tt taxisInqCalendar} returns the type of the calendar,
one of the set of predefined CDI calendar types.
The valid CDI calendar types are {\tt CALENDAR_STANDARD}, {\tt CALENDAR_360DAYS},
{\tt CALENDAR_365DAYS} and {\tt CALENDAR_366DAYS}.
......
......@@ -353,7 +353,7 @@ void vlistUnlock(int vlistID)
@Item vlistID1 Source variable list
@Description
The {\tt vlistCopy} function copies all entries from vlistID1 to vlistID2.
The function {\tt vlistCopy} copies all entries from vlistID1 to vlistID2.
@EndFunction
*/
......@@ -423,10 +423,10 @@ void vlistCopy(int vlistID2, int vlistID1)
@Item vlistID Variable list identifier
@Description
The {\tt vlistDuplicate} function duplicate the variable list from vlistID1.
The function {\tt vlistDuplicate} duplicates the variable list from vlistID1.