Data I-O: Libgretl Reference Manual

Data I-O

Data I-O — basic input and output of data

Functions

int	gretl_read_native_data ()
int	gretl_write_native_data ()
int	gretl_read_foreign_data ()
GretlFileType	gretl_detect_filetype ()

Includes

#include <gretl/libgretl.h>

Description

Functionality for reading data from native-format gretl datafiles, and writing data to such files. Plus importation of data from various sorts of non-native data files.

Here is a simple but complete example of use of gretl_read_native_data() to pull data into a program's workspace and print basic info on the data that were read.

#include <gretl/libgretl.h>

int main (int argc, char **argv)
{
    char *fname;
    DATASET *dset;
    PRN *prn;
    int err;

    if (argc >= 2) {
        fname = argv[1];
    } else {
        exit(EXIT_FAILURE);
    }

    libgretl_init();
    prn = gretl_print_new(GRETL_PRINT_STDOUT, NULL);
    dset = datainfo_new();
   
    err = gretl_read_native_data(fname, dset);
    if (err) {
        pprintf(prn, "Got error %d reading data from %s\n", err, fname);
        errmsg(err, prn);
    } else {
        pprintf(prn, "Read data from %s OK\n", fname);
        print_smpl(dset, 0, OPT_NONE, prn);
        list_series(dset, OPT_NONE, prn);
    }

    destroy_dataset(dset);
    gretl_print_destroy(prn);
    libgretl_cleanup();

    return 0;
}

Functions

gretl_read_native_data ()

int
gretl_read_native_data (const char *fname,
                        DATASET *dset);

Read data from file into gretl's work space, allocating memory as required.

The argument dset represents a pointer-to-DATASET. It should either be given as the address of a DATASET struct that exists at the caller level, or it can be a pointer obtained via the libgretl function datainfo_new().

Parameters

fname	path to a native gretl (.gdt) data file.
dset	dataset struct.

Returns

0 on successful completion, non-zero code on error.

gretl_write_native_data ()

int
gretl_write_native_data (const char *fname,
                         const int *list,
                         const DATASET *dset);

Write out in native gretl (.gdt) format a data file containing the values of the given set of variables.

Parameters

fname	name of file to write.
list	list of ID numbers of series to write (or NULL to write all).
dset	dataset struct.

Returns

0 on successful completion, non-zero on error.

gretl_read_foreign_data ()

int
gretl_read_foreign_data (const char *fname,
                         GretlFileType file_type,
                         DATASET *dset,
                         PRN *prn);

Read data from a "foreign" format data file into gretl's work space, allocating memory as required. For comments on the arguments pZ and dset , see gretl_read_native_data().

file_type must be one of GRETL_CSV, GRETL_OCTAVE, GRETL_GNUMERIC, GRETL_XLS, GRETL_XLSX, GRETL_ODS, GRETL_WF1, GRETL_DTA, GRETL_SAV, GRETL_SAS or GRETL_JMULTI. If you are unsure of the type of the file you may call gretl_detect_filetype() first. Note that the GRETL_CSV type is quite "permissive", including plain text data files with the data values separated in various ways, not just comma-separated values in the strict sense. (The separation must, however, be consistent within the given file.)

If prn is non-NULL, diagnostic information will be printed. This can be useful to gauge how successful the import was.

Parameters

fname	path to a data file of a type that gretl can handle.
file_type	code representing the format of the data file.
dset	dataset struct.
prn	printer for diagnostic info, or NULL.

Returns

0 on successful completion, non-zero code on error.

gretl_detect_filetype ()

GretlFileType
gretl_detect_filetype (const char *fname);

Attempts to determine if the named file is of a type from which gretl can read data.

Parameters

fname

name of the file to be examined.

Returns

code representing the type of the data file, or GRETL_UNRECOGNIZED if the file doesn't seem to be something gretl can work with.