DB read

DB read — reading from databases

Synopsis

#include <gretl/libgretl.h>
#include <gretl/dbread.h>

#define             DB_DESCRIP_LEN
enum                DBError;
typedef             dbnumber;
                    SERIESINFO;
                    dbwrapper;
#define             ODBC_OBSCOLS
                    ODBC_info;
                    netfloat;
float               retrieve_float                      (netfloat nf);
int                 get_native_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);
int                 get_remote_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);
int                 get_pcgive_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);
int                 get_rats_db_data                    (const char *fname,
                                                         SERIESINFO *sinfo,
                                                         double **Z);
dbwrapper *         read_rats_db                        (const char *fname,
                                                         FILE *fp);
dbwrapper *         read_pcgive_db                      (const char *fname,
                                                         FILE *fp);
dbwrapper *         dbwrapper_new                       (int n,
                                                         const char *fname,
                                                         int dbtype);
void                dbwrapper_destroy                   (dbwrapper *dw);
double *            compact_db_series                   (const double *src,
                                                         SERIESINFO *sinfo,
                                                         int target_pd,
                                                         CompactMethod method);
double *            expand_db_series                    (const double *src,
                                                         SERIESINFO *sinfo,
                                                         int target_pd,
                                                         int interpol);
int                 set_db_name                         (const char *fname,
                                                         int filetype,
                                                         PRN *prn);
const char *        get_db_name                         (void);
int                 set_odbc_dsn                        (const char *line,
                                                         PRN *prn);
int                 db_set_sample                       (const char *s,
                                                         DATASET *dset);
int                 db_get_series                       (char *line,
                                                         DATASET *datainfo,
                                                         gretlopt opt,
                                                         PRN *prn);
int                 db_delete_series_by_name            (char *line,
                                                         PRN *prn);
int                 db_delete_series_by_number          (const int *list,
                                                         const char *fname);
void                get_db_padding                      (SERIESINFO *sinfo,
                                                         DATASET *dset,
                                                         int *pad1,
                                                         int *pad2);
int                 db_range_check                      (SERIESINFO *sinfo,
                                                         DATASET *dset);
int                 check_db_import                     (SERIESINFO *sinfo,
                                                         DATASET *dset);
int                 compact_data_set                    (DATASET *dset,
                                                         int newpd,
                                                         CompactMethod default_method,
                                                         int monstart,
                                                         int repday);
int                 expand_data_set                     (DATASET *dset,
                                                         int newpd,
                                                         int interpol);

Description

Functions that read data from native gretl databases as well as RATS 4.0 and PcGive databases. As you will see, this area is mostly undocumented at present, but since it may ultimately be useful for third-party coders we will try to remedy this!

Details

DB_DESCRIP_LEN

#define DB_DESCRIP_LEN 72  /* size of array to hold "# description" */


enum DBError

typedef enum {
    DB_MISSING_DATA = E_MAX + 1,
    DB_NO_SUCH_SERIES,
    DB_PARSE_ERROR
} DBError;

DB_MISSING_DATA

DB_NO_SUCH_SERIES

DB_PARSE_ERROR


dbnumber

typedef float dbnumber;

The type used for representing primary data in gretl databases.


SERIESINFO

typedef struct {
    int t1, t2, v;
    char varname[VNAMELEN];
    char descrip[MAXLABEL];
    int nobs;
    char stobs[OBSLEN];
    char endobs[OBSLEN];
    int pd;
    int offset;
    int err;
    int undated;
} SERIESINFO;


dbwrapper

typedef struct {
    char *fname;
    int dbtype;
    int nv;
    int nalloc;
    SERIESINFO *sinfo;
} dbwrapper;


ODBC_OBSCOLS

#define ODBC_OBSCOLS 3


ODBC_info

typedef struct {
    char *dsn;
    char *username;
    char *password;
    char *query;
    char **fmts;
    char coltypes[ODBC_OBSCOLS];
    double **X;
    char **S;
    int nrows;
    int obscols;
    int nvars;
} ODBC_info;


netfloat

typedef struct {
    long frac;
    short exp;
} netfloat;


retrieve_float ()

float               retrieve_float                      (netfloat nf);


get_native_db_data ()

int                 get_native_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);

Z :

data array.

Returns :

0 on success, non-zero code on failure.

get_remote_db_data ()

int                 get_remote_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);

Z :

data array.

Returns :

0 on success, non-zero code on failure.

get_pcgive_db_data ()

int                 get_pcgive_db_data                  (const char *dbbase,
                                                         SERIESINFO *sinfo,
                                                         double **Z);

Z :

data array.

Returns :

0 on success, non-zero code on failure.

get_rats_db_data ()

int                 get_rats_db_data                    (const char *fname,
                                                         SERIESINFO *sinfo,
                                                         double **Z);

Read the actual data values for a series from a RATS database.

fname :

name of RATS 4.0 database to read from

sinfo :

holds info on the given series (input)

Z :

data matrix

Returns :

0 on successful completion, E_FOPEN if the data could not be read, and DB_MISSING_DATA if the data were found but there were some missing values.

read_rats_db ()

dbwrapper *         read_rats_db                        (const char *fname,
                                                         FILE *fp);

Read the series info from a RATS 4.0 database: read the base block at offset 0 in the data file, and recurse through the directory entries.

fname :

database filename.

fp :

pre-opened stream (caller to close it)

Returns :

pointer to a dbwrapper containing the series info, or NULL in case of failure.

read_pcgive_db ()

dbwrapper *         read_pcgive_db                      (const char *fname,
                                                         FILE *fp);

Read the series info from a PcGive database, .in7 file

fname :

name of database file.

fp :

pre-opened stream (caller to close it)

Returns :

pointer to a dbwrapper containing the series info, or NULL in case of failure.

dbwrapper_new ()

dbwrapper *         dbwrapper_new                       (int n,
                                                         const char *fname,
                                                         int dbtype);

n :

initial number of series.

fname :

database filename.

dbtype :

database type code.

Returns :

an allocated database series wrapper.

dbwrapper_destroy ()

void                dbwrapper_destroy                   (dbwrapper *dw);

Frees all resources associated with dw as well as the pointer itself.

dw :

database series wrapper.

compact_db_series ()

double *            compact_db_series                   (const double *src,
                                                         SERIESINFO *sinfo,
                                                         int target_pd,
                                                         CompactMethod method);


expand_db_series ()

double *            expand_db_series                    (const double *src,
                                                         SERIESINFO *sinfo,
                                                         int target_pd,
                                                         int interpol);


set_db_name ()

int                 set_db_name                         (const char *fname,
                                                         int filetype,
                                                         PRN *prn);


get_db_name ()

const char *        get_db_name                         (void);


set_odbc_dsn ()

int                 set_odbc_dsn                        (const char *line,
                                                         PRN *prn);


db_set_sample ()

int                 db_set_sample                       (const char *s,
                                                         DATASET *dset);


db_get_series ()

int                 db_get_series                       (char *line,
                                                         DATASET *datainfo,
                                                         gretlopt opt,
                                                         PRN *prn);


db_delete_series_by_name ()

int                 db_delete_series_by_name            (char *line,
                                                         PRN *prn);


db_delete_series_by_number ()

int                 db_delete_series_by_number          (const int *list,
                                                         const char *fname);


get_db_padding ()

void                get_db_padding                      (SERIESINFO *sinfo,
                                                         DATASET *dset,
                                                         int *pad1,
                                                         int *pad2);


db_range_check ()

int                 db_range_check                      (SERIESINFO *sinfo,
                                                         DATASET *dset);


check_db_import ()

int                 check_db_import                     (SERIESINFO *sinfo,
                                                         DATASET *dset);


compact_data_set ()

int                 compact_data_set                    (DATASET *dset,
                                                         int newpd,
                                                         CompactMethod default_method,
                                                         int monstart,
                                                         int repday);

Compact the data set from higher to lower frequency.

dset :

dataset struct.

newpd :

target data frequency.

default_method :

code for the default compaction method.

monstart :

FIXME add explanation.

repday :

"representative day" for conversion from daily to weekly data (with method COMPACT_WDAY only).

Returns :

0 on success, non-zero error code on failure.

expand_data_set ()

int                 expand_data_set                     (DATASET *dset,
                                                         int newpd,
                                                         int interpol);

Expand the data set from lower to higher frequency: an "expert" option. This is supported at present only for expansion from annual to quarterly or monthly, or from quarterly to monthly.

dset :

dataset struct.

newpd :

target data frequency.

interpol :

use interpolation (0/1).

Returns :

0 on success, non-zero error code on failure.