MfixReader User Guide

2. Usage

An application that uses the MfixReader library will proceed in stages. At each stage, the library will provide information that can help the application (and the user, if the application is interactive) decide what to do next. For example, the libary can provide a list of variables after the dataset is opened but before any data is read.

An application may also wish to work with several sets of data. The library supports this by internally creating multiple "instances" of its information about a dataset. Each call to the library to return metadata, coordinates, or variables must include the "handle" (a simple integer) that identifies the instance. Each instance retains knowledge of the files, byte offsets and other metadata for each open dataset. The operations on one instance are completely independent of operations on other instances.

As an example, let's imagine an interactive application that wishes to compare a user-selected variable from two MFIX datasets. The application could use the MfixReader library functions in this order:

create reader instance 1
set parameters for instance 1
open instance 1
get metadata for instance 1
create reader instance 2
set parameters for instance 2
open instance 2
get metadata for instance 2
prompt user to select variable from those in both datasets
for each time
- get variable from instance 1
- get variable from instance 2
- compare
close instance 1
destroy instance 1
close instance 2
destroy instance 2

The above example could use the library in many other ways to accomplish the same result.

Many of the routines in this library will return pointers to arrays. The application does not need to provide these arrays, and should never modify the arrays in any way. The library will free the memory used by the arrays at the appropriate time (i.e., at the close or destroy operation).