Go to the previous, next section, or Table of Contents.
This chapter discusses the interfaces for EPS routines that deal with an EPS file as a whole.
As described in Chapter 2, EPS File Compunents , an EPS file is defined as a collection of data files and a pointer file which contains the full path to these data files. An unopened EPS file is referred to by the pointer file name; once an EPS file is opened, it is referred to by an EPS file identifier returned by function ep_open (or epopen for Fortran) when you open the EPS file. The EPS file identifier is also referred to as "system data structure" (Dbase* epf ) for C interface and as "pointer file identifier" (integer epf) for Fortran interface in the manual. Each data file listed in the pointer file is loaded to the database at the time you position to it by using the EPS function call ep_set_next(or epsetnext for Fortran), and unloaded when you load the next data file or when you close the pointer file. The EPS routines only operate on the current loaded data file; once a data file is unloaded (closed), you cannot load it unless you close the entire EPS file and reopen it again. However, you can open several EPS files (i.e. pointer files) at the same time.
The operations supported on an EPS file are:
The function ep_open or epopen for Fortran) opens an EPS file, initializes internal tables, allocates the memory necessary for the tables and data, forms an internal database for the EPS file, and returns a unique EPS file identifier which can subsequently be used to refer to the internal database. This routine must be called before any routine that uses the EPS file identifier. All data files listed in the pointer file will be opened in the same mode.
The input argument EPS file, file, can be either a pointer file which contains a list of data file names or a single data file when reading. If a BLANK string is specified when creating, no pointer file will be generated. Refer to the following table when you specify the EPS file argument.
| Open Mode | Input EPS File argument | Comments |
|---|---|---|
| READ | a pointer file name | contains a list of data files |
| READ | a single data file name | netCDF or Classic EPIC file |
| READ | an ASCII table | contains data info |
| EDIT | a pointer or single data file name | netCDF file only |
| CREATE | A Pointer file Name | will contain a list of output data files |
| CREATE | A Blank or Null String | no pointer file will be generated |
When READ, the pointer file can contain a list of netCDF or Classic EPIC data files, or ASCII data file information table. (Refer to EPS Implementation of ASCII Data File Format for details about ASCII data format.) When EDIT, the pointer file must contain only netCDF data files. When CREATE, the pointer file will contain a list of output data files which have the same data type (netCDF or Classic EPIC).
The input argument option, opts, contains information about open mode and file type. There are only 4 possible inputs for the file processing options which are listed in the following table.
| Open Mode | Data File Type | Input option, opts |
|---|---|---|
| READ | netCDF | EPREAD |
| READ | Classic EPIC | EPREAD |
| READ | ASCII data file | EPREAD |
| CREATE | netCDF | EPCREATE+EPCDF |
| CREATE | Classic EPIC | EPCREATE+EPEPIC |
| EDIT | netCDF | EPEDIT |
Possible causes of error and warning to this routine call include:
void ep_open(Dbase** epf, char* file, int opts)
epf O EPIC system data structure
file I EPS file
opts I EPS file processing options
ep_open: FORTRAN Interface
subroutine epopen(integer epf, character*(*) file, integer opts)
epf O pointer file identifier
file I EPS file
opts I EPS file processing options
The function ep_close (or epclose for Fortran) closes an EPS file, i.e. an EPS pointer file and associated data files. It frees the memory that has been allocated by the ep_open and succeeding EPS routines. When the EPS file was opened for create, ep_close also writes out variable information and attributes information of last opened data file before closes the EPS file. Without using ep_close, an opened EPS file will not be closed properly when a program terminates.
ep_close: C Interface
void ep_close(Dbase* epf)
epf I EPIC system data structure
ep_close: FORTRAN Interface
subroutine epclose(integer epf)
epf I pointer file identifier
The function ep_set_next (or epsetnext for Fortran) will position to the next data file in the pointer file based on the sort specifier and close the previously opened data file. If EPS file is opened with EPREAD or EPEDIT, a pointer of data file name (no path name included) will be returned by the function (or returned in argument filename for Fortran).
When opening an existing EPS file, the default order for positioning to the next data file is the order listed in the pointer file. When reading the classic EPIC data files, user can call epsetsort to specify the sorting criteria. If doing so, epsetsort must be called before epsetnext. The first time epsetnext is called, the current data file is set to the first data file.
When writing an EPS file, the file name, filename, is an input argument which indicates the output file name; this filename can be specified with or without the path name.
Possible causes of error and warning to this routine call include:
ep_set_next: C Interface
char* ep_set_next(Dbase* epf, char* filename)
epf I EPIC system data structure
filename I new data file name when opened with EPCREATE
Enter (char *)NULL when opened with EPREAD or EPEDIT.
epsetnext: Fortran Interface
subroutine epsetnext(integer epf, character*(*) filename)
epf I pointer file identifier
filename I/O data file name. It is an input argument when creating a file.
It is an output argument when reading or editing a file.
The integer function ep_inq_numfile (or epinqnumfile for Fortran) returns total number of data files in the database.
ep_inq_numfile: C Interface
int ep_inq_numfile(Dbase* epf)
epf I EPIC system data structure
epinqnumfile: FORTRAN Interface
integer function epinqnumfile(integer epf)
epf I pointer file identifier
The Logical function ep_last_datafile (or eplastdatafile for Fortran) returns true if the last data file in the database is reached; returns false otherwise.
ep_last_datafile: C Interface int ep_last_datafile(Dbase* epf) epf I EPIC system data structure
eplastdatafile: FORTRAN Interface
logical function eplastdatafile(integer epf)
epf I pointer file identifier
The function ep_inq_dir (or epinqdir for Fortran) returns the directory path name of the current data file. It must be called after the function call epsetnext.
ep_inq_dir: C Interface
void ep_inq_dir(Dbase* epf, (char**) path)
epf I EPIC system data structure
path O current data file path name
epinqdir: FORTRAN Interface
subroutine epinqdir(integer epf, character*(*) path )
epf I pointer file identifier
path O current data file path name
The function ep_inq_type (or epinqtype for Fortran) returns the type of the current opened data file (e.g. EPIC, CDF) and the data type (e.g. CTD for CTD data or profile data, TIME for time series data). The EPS routines recognize the file type at the time when the data file is loaded, that is, when ep_set_next is called. Therefore, this function must be called after ep_set_next (or epsetnext for Fortran) is called. For a classic EPIC file, the data type information is provided by a flag in the data file (header 2, col 78); for a netCDF file the data type information is obtained by reading the global attribute ``DATA_TYPE''.
ep_inq_type: C Interface
void ep_inq_type(Dbase* epf, char** ftype, char** dformat)
epf I EPIC system data structure
ftype O data file type
dformat O data format
epinqtype: FORTRAN Interface
subroutine epinqtype(integer epf, character*(*) ftype,
character*(*) dformat)
epf I pointer file identifier
ftype O data file type
dformat O data format
The function ep_set_sort (or epsetsort for Fortran) sets the criteria for the sorting of data records for reading. This function is only implemented for classic EPIC data files and netCDF files in which all variables are sharing the same set of axes. If epsetsort is used, it should be called prior to the first invocation of epsetnext. The input argument sort specifier, sort, indicates the data file sorting order: sort(i) > 0, ort by increasing values of axis i; sort(i) < 0, sort by decreasing values of axis i; and sort(i) = 0, do not sort. For example, sort={1,2,0,0} indicates to sort by increasing x-axis then by increasing y-axis and not to sort by z-axis and time-axis.
ep_set_sort: C Interface
void ep_set_sort(Dbase* epf, int* sort)
epf I EPIC system data structure
sort[4] I sort specifier.
epsetsort: FORTRAN Interface
subroutine epsetsort(integer epf, integer sort(4))
epf I pointer file identifier
sort I sort specifier.
The function ep_err_opts (or eperropts for Fortran sets the error handling options which will be carried on through out the program unless this function is called again. When an error or warning has occurred, the error code and error message will be stored in the internal database. By default, error message will not be printed out and the program will not stop. The available options are listed in the following table.
| Option | Comments |
|---|---|
| EPDEFAULT | default; no error message and no stop on any error |
| EPCONT | continue on warning and fatal error |
| EPCONTW | continue on warning and stop on fatal error |
| EPSTOP | stop on warning and fatal error |
| EPPRINTERR | print out the error message; can be combined with above options except EPDEFAULT |
The EPPRINTEER canbe combined with other options except EPDEFAULT. For example, set opts to be EPSTOP+EPPRINTERR will print out the error message and exit when an error or warning occurs. If this function has never been called, the default error-handling option will be used. In this case, in order to catch EPS error at right place, user needs to call EPS routine epinqerr and epmesg, or call epmesgdo to print the error and take the corresponding action after each EPS routine call in the program. (See discussion in the following sections.)
ep_err_opts: C Interface
void ep_err_opts(int opts)
opts I Error handling options
eperropts: FORTRAN Interface
subroutine eperropts(integer opts)
opts I Error handling options
Integer function ep_inq_error (or epinqerr for Fortran) returns the value of the error code of the latest EPS routine: 0 = no error, positive integer = fatal error, and negative error = warning error. Epinqerr does not clear the error.
ep_inq_error: C Interface
int ep_inq_error(Dbase* epf)
epf I EPIC system data structure
epinqerr: FORTRAN Interface
integer function epinqerr(integer epf)
epf I pointer file identifier
The function ep_message (or epmesg for Fortran) returns a string that describes the error. The string is valid only if epinqerr returns a non-zero result.
ep_message: C Interface
void ep_message(Dbase* epf, char** string)
epf I EPIC system data structure
string O description of the error
epmesg: FORTRAN Interface
subroutine epmesg(integer epf, character*(*) string, integer len)
epf I pointer file identifier
string O description of the error
len O length of the string
ep_mesg_do: C Interface
void ep_mesg_do(Dbase* epf, int action)
epf I EPIC system data structure
action I do the specified action
epmesgdo: FORTRAN Interface
subroutine epmesgdo(integer epf, integer lun, integer action)
epf I pointer file identifier
lun I Fortran logical unit number
action I do the specified action
Go to the previous, next section, or Table of Contents.