NAME

dsfile.h - DATASET_METHOD for flat binary files.

SYNOPSIS

These routines define methods for accessing files. With this module, a DATASET can consist of a large binary file. Patterns are loaded on a need-only basis, so memory is preserved.

#include <dsfile.h>

DSM_FILE *dsm_file(char *fname);

int dsm_file_initiate(DSM_FILE *dsmf);

void dsm_destroy_file(DSM_FILE *dsmf);

double *dsm_file_x(void *instance, unsigned index);

double *dsm_file_y(void *instance, unsigned index);

DESCRIPTION

Type Declarations

The following types are defined in the header file dsfile.h.

DSM_FILE

typedef struct DSM_FILE {
  /*
   * User modifiable fields.
   */
  unsigned x_width, y_width; 
  unsigned x_read_width, y_read_width;
  int offset;
  unsigned step, skip;
  int (*convert_x)(void *source, double *dest, void *obj);
  int (*convert_y)(void *source, double *dest, void *obj);
  void *obj;
  SL_TYPE type;
  /*
   * Private fields.
   */
  void *xbuf, *ybuf;
  double *xdata, *ydata;
  unsigned size, numpat, patsz, initp;
  FILE *fp;
  char *mmapptr;
} DSM_FILE;

The DSM_FILE type specififies how to interpret a binary file as a DATA_SET. You need to set at least the first five fields. The first two give the size of the x and y vectors. The next two are the number of bytes that need to be read for the x and y vectors. The offset is the number of bytes to skip between the x and the y vectors, which may be a negative number. The step specifies the distance in bytes between successive records in the file, and skip specifies the number of bytes to initially skip in the file.

The two conversion routines should be used to map the binary data in the doubles. The value of the obj field is passed as the last argument. If you need to implement some sort of delayed embedding, then you must do it in these routines.

If you specify a type (as found in nodelib/misc.h) and if the size of your source type times x_width is equal to x_read_width, then dataset_x() anddataset_y() will automagically do the conversion for you.

Function Definitions

The following function prototypes are given in the header file dsfile.h.

DSM_FILE *dsm_file(char *fname);

This function allocates memory for a DSM_FILE structure, sets the fields to reasonable initial values, and checks that the requested file is valid and, if so, opens it for reading.

int dsm_file_initiate(DSM_FILE *dsmf);

After creating a DSM_FILE, one must set the fields to appropriate values. Once they are set, this function is used to set up buffer space and to perform other miscellaneous tasks that are necessary before any of the other routines can be used.

void dsm_destroy_file(DSM_FILE *dsmf);

Free up any memory that was allocated for the DSM_FILE, and closes the FILE pointer.

double *dsm_file_x(void *instance, unsigned index);

Internal function to retrieve x data from a file. Don't use this function. This is only to be used by the DATASET method handlers.

double *dsm_file_y(void *instance, unsigned index);

Internal function to retrieve y data from a file. Don't use this function. This is only to be used by the DATASET method handlers.

AUTHOR

Gary William Flake (gary.flake@usa.net).

SEE ALSO

dsmethod(3), and dataset(3).