Go to the previous, next section, or Table of Contents.
A variable in an EPS file is referred to by its variable code. When an EPS file is created, each variable must be assigned a unique integer identifier, either a positive number for a predefined variable code, or a negative number for a user-defined variable code. It is not acceptable to use a positive variable code which is not defined in epic.keyfile. (See Appendix C EPIC.KEY File.) Predefined variable codes and other information (short name, long name, generic name, format and unit) of corresponding variables are provided in the epic.key file. The short name is four characters or less, and is suitable for use as a title for a column on a data listing. The long name is intended to be used in a label, such as an axis label on a graph. The generic name is used to access data from within the nccalc netCDF calculator, which is linked with the PPLUS graphics package; it can also be used to obtain its variable code by using the EPS function call ep_find_code (or epfindcode for Fortran).
A classic EPIC file fully depends on the epic.key file for the variable information, therefore only predefined variable code can be used in a classic EPIC file. When opening an existing classic EPIC file, the variable code is read from the header lines, then other information will be retrieved from the epic.key file. When writing a classic EPIC file, only the variable code will be stored in the data file. Therefore, all classic EPIC data files should be accompanied by a valid epic.key file. Note that the modification to the epic.key file have the impact on the existing classic EPIC files.
When opening an existing netCDF file, the variable code is read from variable attribute epic_code or if attribute epic_code is not found then a negative number is assigned to variable code. Other variable information are also read from the variable attribute in the data file. Only when epic_code is found but other variable information are not found in the data file, then these information will be read from the epic.key. The type of variable is always assumed to be EPREAL. When writting a netCDF file, user can choose to use variable information previded in epic.key, in this case the variable name is its short name appended by "_" then the variable code; or use user-defined information, then the variable name is the short name. Note that the modification to the epic.key file do not have any impact on the existing netCDF file files.
Once an EPS file is loaded to the internal database, the variable shape is described by a lower corner index lci[4] and an upper corner index uci[4]. The internal dimension order of variable is (x,y,z,t) regardless how they are defined by user. Therefore, lci(i) and uci(i) are for x-axis when i = 1; for y-axis when i = 2; for z-axis when i = 3; and for t-axis when i = 4. If one or more axes are found missing when read in or when defining a variable in a netCDF file, the missing axes will be inserted in the corresponding places automatically by EPS routines. Operations supported on variables are:
The function ep_find_code (or epfindcode for Fortran) get the variable code from its generic name in epic.key file. Str is a valid generic variable name. Note: this routine will return the variable code of the first variable whose generic name matches the input string. If variable code is not found, ier equals 1 and varcde equals -1 will be returned.
ep_find_code: C Interface
void ep_find_code(char* str, int* varcde, int* ier)
str I string containing generic variable name
varcde O variable code
ier O error code (0=no error)
epfindcode: Fortran Interface
subroutine epfindcode(character*(*) str, integer varcde, integer ier)
str I string containing generic variable name
varcde O variable code
ier O error code (0=no error)
The function ep_inq_code (or epinqcode for Fortran) returns information about a variable described in epic.key file, giving its variable code. The information include variable short name, long name, generic name, format and units. If the variable code is not found, the space will be returned to each output argument.
ep_inq_code: C Interface
void ep_inq_code(int varcde, char* sname, char* lname,
char* gname, char* frmt, char* units)
varcde I variable code
sname O short variable name
lname O long variable name
gname O generic variable name
frmt O variable format
units O variable units
epinqcode: Fortran Interface
subroutine epinqcode(integer varcde, character*(*) sname,
character*(*) lname, character*(*) gname,
character*(*) frmt, character*(*) units)
varcde I variable code
sname O short variable name
lname O long variable name
gname O generic variable name
frmt O variable format
units O variable units
The function ep_set_var (or epsetvar for Fortran) creates the variable in database if it does not exist, sets the data type and variable information. If varcde > 0 and it is defined in epic.key file, the input sname, lname, gname, frmt, units and dtype will be ignored, the variable information will be taken from the epic.key file, and data type will be EPREAL. If varcde < 0, the input arguments will be used. The valid classic EPIC data type is EPREAL. The valid data types for other data files are EPBYTE, EPSHORT, EPINT and EPREAL.
Possible causes of error to this routine call include:
ep_set_var: C Interface
void ep_set_var(Dbase* epf, int varcde, char* sname, char* lname,
char* gname, char* frmt, char* units, int dtype)
epf I EPIC system data structure
varcde I variable code
sname I short name of variable
lname I long name of variable
gname I generic name of variable
frmt I Fortran format for variable
units I units for variable
dtype I data type of variable
epsetvar: Fortran Interface
subroutine epsetvar(integer epf, integer varcde, character*(*) sname,
character*(*) lname, character*(*) gname,
character*(*) frmt, character*(*) units,
integer dtype)
epf I pointer file identifier
varcde I variable code
sname I short name of variable
lname I long name of variable
gname I generic name of variable
frmt I Fortran format for variable
units I units for variable
dtype I data type of variable
The function ep_reset_var (or epresetvar for Fortran) re-defines the variable in database after it has be defined. It overwrites the previous variable information by specified values. User should be aware that when writing classis EPIC data file, only variable code will be written to the file, the variable information you reset here must be entered in the epic.key file.
Possible causes of error to this routine call include:
ep_reset_var: C Interface
void ep_reset_var(Dbase* epf, int varcde, char* sname, char* lname,
char* gname, char* frmt, char* units, int dtype)
epf I EPIC system data structure
varcde I variable code
sname I short name of variable
lname I long name of variable
gname I generic name of variable
frmt I Fortran format for variable
units I units for variable
dtype I data type of variable
epresetvar: Fortran Interface
subroutine epresetvar(integer epf, integer varcde, character*(*) sname,
character*(*) lname, character*(*) gname,
character*(*) frmt, character*(*) units,
integer dtype)
epf I pointer file identifier
varcde I variable code
sname I short name of variable
lname I long name of variable
gname I generic name of variable
frmt I Fortran format for variable
units I units for variable
dtype I data type of variable
Logical function ep_find_var (or epfindvar for Fortran) returns false if the variable is not found in the current data file. If true, varcde contains the variable code. Input str may contain either a valid generic variable name (e.g. ``temp'' or ``sigma_t''), a specific variable code (e.g. ``-150'', ``eps150'' or ``epsm2''). The use of the form ``-150'' is provided for compatibility with the older EPIC library. The form ``epsm2'' (variable code -2) is used to access variables that do not have an EPIC variable code.
ep_find_var: C Interface
int ep_find_var(Dbase* epf, char* str, int* varcde)
epf I EPIC system data structure
str I string containing generic variable name
varcde O variable code
epfindvar: Fortran Interface
logical function epfindvar(integer epf, character*(*) str,
integer varcde)
epf I pointer file identifier
str I string containing generic variable name
varcde O variable code
The routine ep_inq_var (or epinqvar for Fortran) returns information about the variable in the current data file.
Possible causes of error to this routine call include:
ep_inq_var: C Interface
void ep_inq_var(Dbase* epf, int varcde, char** sname, char** lname,
char** frmt, char** units, int* dtype)
epf I EPIC system data structure
varcde I variable code
sname O short name of the variable
lname O long name of the variable
frmt O format to use to print out values of the variable
units O units of the variable
dtype O data type (e.g. EPREAL)
epinqvar: Fortran Interface
subroutine epinqvar(integer epf, integer varcde, character*(*) sname,
character*(*) lname, character*(*) frmt,
character*(*) units, integer dtype)
epf I pointer file identifier
varcde I variable code
sname O short name of the variable
lname O long name of the variable
frmt O format to use to print out values of the variable
units O units of the variable
dtype O data type (e.g. EPREAL)
The function ep_inq_varname (or epinqvname for Fortran) returns variable name in the current data file.
Possible causes of error to this routine call include:
ep_inq_varname: C Interface
char *ep_inq_varname(Dbase* epf, int varcde)
epf I EPIC system data structure
varcde I variable code
epinqvname: Fortran Interface
subroutine epinqvname(integer epf, integer varcde, character*(*) vname)
epf I pointer file identifier
varcde I variable code
vname O variable name
The function ep_inq_gname (or epinqgname for Fortran) returns variable generic name in the current data file.
Possible causes of error to this routine call include:
ep_inq_varname: C Interface
char *ep_inq_gname(Dbase* epf, int varcde)
epf I EPIC system data structure
varcde I variable code
epinqvname: Fortran Interface
subroutine epinqgname(integer epf, integer varcde, character*(*) vname)
epf I pointer file identifier
varcde I variable code
vname O variable name
The function ep_var_name_to_id (or epvarnmetoid for Fortran) returns the variable code in the current data file from the given short variable name. If the given short name is not found in the current data file, an error will occur.
Possible causes of error to this routine call include:
ep_var_name_to_id: C Interface
void ep_var_name_to_id(Dbase* epf, char* name, int* varcde)
epf I EPIC system data structure
name I short variable name
varcde O variable code
epvarnmetoid: Fortran Interface
subroutine epvarnmetoid(integer epf, character*(*) name, integer varcde)
epf I pointer file identifier
name I short variable name
varcde O variable code
The function ep_get_var_shape (or epgetvarshap for Fortran) returns the shape of the variable. The returned shape is the maximum range of each index that can be requested. lci[4] and uci[4] are the lower and upper corner index. These values are then used in request for the axis data epgetaxis and variable data epgetvar. (See discussion of variable shape at beginning of this chapter for details about definition of lower and upper corner index.)
Possible causes of error to this routine call include:
ep_get_var_shape: C Interface
void ep_get_var_shape(Dbase* epf, int varcde, int* lci, int* uci)
epf I EPIC system data structure
varcde I variable code
lci[4] O lower corner index
uci[4] O upper corner index
epgetvarshap: Fortran Interface
subroutine epgetvarshap(integer epf, integer varcde, integer lci(4),
integer uci(4))
epf I pointer file identifier
varcde I variable code
lci O lower corner index
uci O upper corner index
The function ep_get_var_list (or epgetvarlist for Fortran) returns a list of variable codes for the variables that are in the current data file.
ep_get_var_list: C Interface
void ep_get_var_list(Dbase* epf, int* vars, int dim, int* nvar)
epf I EPIC system data structure
vars[] O list of variable codes in file
dim I dimensioned size of vars (the second input argument)
nvar O number of variables in file
epgetvarlist: Fortran Interface
subroutine epgetvarlist(integer epf, integer vars(*), integer dim,
integer nvar)
epf I pointer file identifier
vars O list of variable codes in file
dim I dimensioned size of vars (the second input argument)
nvar O number of variables in file
The function ep_get_var (or epgetvar for Fortran) returns a hyperslab of a variable. If input lci and uci are obtained from the ep_get_var_shape routine, than the full size of variable will be returned. Increase lci and/or decrease uci after the ep_get_var_shape call, only a subset of the variable data will be returned into array. The data type dtype of array must agree with the dtype returned from ep_inq_var. The EPS library routine will not check for an invalid data type.
Note: For Fortran, the returned data values array will be converted to "real" for all these dtype: EPREAL, EPDOUBLE, EPSHORT and EPINT. Therefore, you must define array to be "real" for these data types.
Possible causes of error to this routine call include:
ep_get_: C Interface
void ep_get_var(Dbase* epf, int varcde, int* lci, int* uci,
void* array, int* dims)
epf I EPIC system data structure
varcde I variable code
lci[4] I lower corner index
uci[4] I upper corner index
array[] O column order data array
dims[4] I dimensions of data array
epgetvar: Fortran Interface
subroutine epgetvar(integer epf, integer varcde, integer lci(4),
integer uci(4), dtype array(*), integer dims(4))
epf I pointer file identifier
varcde I variable code
lci I lower corner index
uci I upper corner index
array O column order data array
dims I dimensions of data array
The function ep_put_var (or epputvar for Fortran) writes out a hyperslab of a variable. All the variable axes must exist before ep_put_var is called, that is, the routines ep_set_axis and ep_put_axis for setting the spatial coordinates, and ep_set_t_axis and ep_put_t_axis for setting time coordinates must be called before ep_put_var. See Chapter 7, Axis Routines for details about these function calls. When you write out a variable which is not defined in epic.key file, i.e. the variable code is a negative number, the function ep_set_var must be call first to define the variable.
Note: when write out one-point-depth CTD data to classic EPIC file, user must set global attribute EPDATATYPE to be CTD by calling ep_put_att_value (or epputattvalc for Fortran) before this function call.
Possible causes of error to this routine call include:
ep_put_var: C Interface
void ep_put_var(Dbase* epf, int varcde, int* origin, int* lci,
int* uci, void* array, int* dims)
epf I EPIC system data structure
varcde I variable code
origin[4] I location of array origin, e.g. the lci from getvar
lci[4] I lower corner index
uci[4] I upper corner index
array[] I column order data array
dims[4] I dimensions of data array
epputvar: Fortran Interface
subroutine epputvar(integer epf, integer varcde, integer origin(4),
integer lci(4), integer uci(4), dtype array(*),
integer dims(4))
epf I pointer file identifier
varcde I variable code
origin I location of array origin, e.g. the lci from getvar
lci I lower corner index
uci I upper corner index
array I column order data array
dims I dimensions of data array
The function ep_copy_var (or epcopyvar for Fortran) copies a variable information, its grid information and meta data (but not actual variable data) to output file. This function call is equivalent to the following sequence of calls: epinqvar, epinqvaratt, epinqaxis, epinqtaxis, epinqaxatt from input EPS file and epsetvar, epputvarattval, epputaxis, epputtaxis, epputaxattval to the output EPS file. (Refer to Chapter 7, Axis Routines To duplicate the variable data value, user needs to make the following two calls after ep_copy_var: ep_get_var from input EPS file and ep_put_var to the output EPS file.
Note: Never use this function to copy a variable whose name has already been defined in output file. This function cannot be used to overwrite the existing variable.
Possible causes of error to this routine call include:
ep_copy_var: C Interface
void ep_copy_var(Dbase* epin, int varcde, Dbase* epout)
epin I input EPIC system data structure
varcde I variable code
epout I output EPIC system data structure
epcopyvar: Fortran Interface
subroutine epcopyvar(integer epin, integer varcde, integer epout)
epin I input pointer file identifier
varcde I variable code
epout I output pointer file identifier
The function ep_append_var (or epappendvar for Fortran) appends hyperslab of a variable, which contains an unlimited dimension, to an existing NetCDF file. The input NetCDF file must opened for editing (i.e. use EPEDIT option when calling ep_open or epopen for Fortran). The input length is the length of x-, y-, z- and t-axis of input array. The data type of the input array must agree with that in the netCDF file. The EPS routine will not check for an invalid data type.
Possible causes of error to this routine call include:
ep_append_var: C Interface
void ep_append_var(Dbase* epf, int varcde, int* length, void* array)
epf I EPIC system data structure
varcde I variable code
length[4] I (x,y,z,t) dimension length of the array
array[] I array that appends the variable in NetCDF file
epappendvar: Fortran Interface
subroutine epappendvar(integer epf, integer varcde, integer length(4),
dtype array(*))
epf I pointer file identifier
varcde I variable code
length I (x,y,z,t) dimension length of the array
array I array that appends the variable in NetCDF file
The function ep_overwrite_var (or epoverwritevar for Fortran) overwrites hyperslab of a variable, which contains an unlimited dimension, to an existing NetCDF file. The input NetCDF file must opened for editing (i.e. use EPEDIT option when calling ep_open or epopen for Fortran). Start is the starting overwriting index of (x,y,z,t), e.g. (1,1,1,1) means starting from the first point. Length is the length of x-, y-, z- and t-axis of input array. The data type of the input array must agree with that in the netCDF file. The EPS routine will not check for an invalid data type.
Possible causes of error to this routine call include:
ep_overwrite_var: C Interface
void ep_overwrite_var(Dbase* epf, int varcde, int start, int length,
void* array)
epf I EPIC system data structure
varcde I variable code
start[4] I start point of (x,y,z,t) dimension of the variable
which will be overwitten in NetCDF file
length[4] I (x,y,z,t) dimension length of the array
array[] I array that overwrites the variable in NetCDF file
epoverwritevar: Fortran Interface
subroutine epoverwritevar(integer epf, integer varcde, integer start(4),
integer length(4), dtype aray(*))
epf I pointer file identifier
varcde I variable code
start I start point of (x,y,z,t) dimension of the variable
which will be overwitten in NetCDF file
length I (x,y,z,t) dimension length of the array
array I array that overwrites the variable in NetCDF file