base/drms/libs/api/drms_record.h

Go to the documentation of this file.

#ifndef _DRMS_RECORD_H
#define _DRMS_RECORD_H

#include "drms_types.h"
#include "db.h"
#include "list.h"

#define kLocalSegName "local_data" /* Name of segment created when reading 
                    * fits files from local disk (outside 
                    * of any database). */
#define kLocalPrimekey "primekey"
#define kLocalPrimekeyType DRMS_TYPE_LONGLONG

/************* Constants for mode and action flags etc. *************/
typedef enum {DRMS_COPY_SEGMENTS, DRMS_SHARE_SEGMENTS} DRMS_CloneAction_t;
typedef enum {DRMS_FREE_RECORD, DRMS_INSERT_RECORD} DRMS_CloseAction_t;
/* Macros so code using the old names will still work. */
/* removed because there is no code using them
#define DRMS_DISCARD_RECORD (DRMS_FREE_RECORD)
#define DRMS_COMMIT_RECORD (DRMS_INSERT_RECORD)
*/

typedef enum {DRMS_QUERY_COUNT, DRMS_QUERY_FL, DRMS_QUERY_ALL, DRMS_QUERY_N, DRMS_QUERY_PARTIAL} DRMS_QueryType_t;


enum DRMS_RecChunking_enum
{
   kRecChunking_None = 0,
   kRecChunking_NoMoreRecs,  /* A call to drms_recordset_fetchnext() was made after a previous call returned the last record in the record set.  */
   kRecChunking_LastInChunk, /* The last call to drms_recordset_fetchnext() advanced the rec pointer to the last record in chunk. */
   kRecChunking_LastInRS     /* The last call to drms_recordset_fetchnext() advanced the rec pointer to the last record in the record set. */
};

typedef enum DRMS_RecChunking_enum DRMS_RecChunking_t;

/************** User level record functions ************/

/**** For record sets. ****/
/* Retrieve a recordset specified by the DRMS dataset name string
   given in the argument "datasetname". The records are inserted into
   the record cache and marked read-only. */

DRMS_RecordSet_t *drms_open_records(DRMS_Env_t *env, const char *recordsetname, 
                    int *status);
DRMS_RecordSet_t *drms_open_nrecords(DRMS_Env_t *env, 
                                     const char *recordsetname, 
                                     int n,
                                     int *status);
DRMS_RecordSet_t *drms_open_recordswithkeys(DRMS_Env_t *env, const char *specification, const char *keylist, int *status);

DRMS_RecordSet_t *drms_clone_records(DRMS_RecordSet_t *recset,  
                     DRMS_RecLifetime_t lifetime, 
                     DRMS_CloneAction_t mode, int *status);
DRMS_RecordSet_t *drms_clone_records_nosums(DRMS_RecordSet_t *recset,  
                                            DRMS_RecLifetime_t lifetime, 
                                            DRMS_CloneAction_t mode, int *status);

DRMS_RecordSet_t *drms_create_records(DRMS_Env_t *env, int n, 
                      const char *seriesname, DRMS_RecLifetime_t lifetime,
                      int *status);

DRMS_RecordSet_t *drms_create_recprotos(DRMS_RecordSet_t *recset, int *status);
void drms_destroy_recprotos(DRMS_RecordSet_t **protos);
DRMS_Record_t *drms_create_recproto(DRMS_Record_t *recSource, int *status);
void drms_destroy_recproto(DRMS_Record_t **proto);

/* Close a set of records. 
   1. a) If action=DRMS_INSERT_RECORD the record meta-data (keywords
      and links) will be inserted into the database and the data
      segments will be left in the storage unit directory for later
      archiving by SUMS.
      b) If action=DRMS_FREE_RECORD the data segment files are
      deleted from disk.
   2. The record structures are freed from the record cache. */

int drms_close_records(DRMS_RecordSet_t *rs, int action);

int drms_stage_records(DRMS_RecordSet_t *rs, int retrieve, int dontwait);
int drms_sortandstage_records(DRMS_RecordSet_t *rs, int retrieve, int dontwait, HContainer_t **suinfo);
int drms_record_getinfo(DRMS_RecordSet_t *rs);

/**** For a single record. ****/
DRMS_Record_t *drms_clone_record(DRMS_Record_t *record, 
                 DRMS_RecLifetime_t lifetime, 
                 DRMS_CloneAction_t mode, int *status);
DRMS_Record_t *drms_create_record(DRMS_Env_t *env, char *seriesname, 
                  DRMS_RecLifetime_t lifetime, int *status);
int drms_close_record(DRMS_Record_t *rec, int action);
void  drms_print_record(DRMS_Record_t *rec);
void  drms_fprint_record(FILE *recfile, DRMS_Record_t *rec);
long long drms_record_size(DRMS_Record_t *rec);
int drms_record_numkeywords(DRMS_Record_t *rec);
int drms_record_numlinks(DRMS_Record_t *rec);
int drms_record_numsegments(DRMS_Record_t *rec);
int drms_record_num_nonlink_segments(DRMS_Record_t *rec);
/* Storage Unit Directory associated with a record. */
int drms_record_directory(DRMS_Record_t *rec, char *dirname, int retrieve);
int drms_record_directory_nosums(DRMS_Record_t *rec, char *dirout, int size);

/**** Can modify seriesinfo only if the record is a record prototype  ****/
int drms_recproto_setseriesinfo(DRMS_Record_t *rec,
                int *unitSize, 
                int *bArchive, 
                int *nDaysRetention,
                int *tapeGroup,
                const char *description);

DRMS_RecordSetType_t drms_record_getquerytype(const char *query);

long long drms_record_memsize(DRMS_Record_t *rec);

long long drms_keylist_memsize(DRMS_Record_t *rec, const char *keylist);

/* Return the JSOC software version that created the given record. */
char *drms_record_jsoc_version(DRMS_Env_t *env, DRMS_Record_t *rec);

/* Handling record sets */
char *drms_recordset_acquireseriesname(const char *query);

static inline int drms_recordset_getnrecs(DRMS_RecordSet_t *rs)
{
   return rs->n;
}

static inline int drms_recordset_getnumss(DRMS_RecordSet_t *rs)
{
   return rs->ss_n;
}

const char *drms_recordset_getqueryss(DRMS_RecordSet_t *rs, unsigned int setnum, int *status);

DRMS_RecordSetType_t *drms_recordset_gettypess(DRMS_RecordSet_t *rs, 
                           unsigned int setnum, 
                           int *status);

DRMS_Record_t *drms_recordset_getss(DRMS_RecordSet_t *set, unsigned int setnum, int *status);

int drms_recordset_getssnrecs(DRMS_RecordSet_t *set, unsigned int setnum, int *status);

int drms_merge_record(DRMS_RecordSet_t *rs, DRMS_Record_t *rec);

static inline DRMS_Record_t *drms_recordset_getrec(DRMS_RecordSet_t *rs, long long recnum)
{
   if (rs)
   {
      return rs->records[recnum];
   }

   return NULL;
}

/* Chunking record queries */
int drms_recordset_setchunksize(unsigned int size);
unsigned int drms_recordset_getchunksize();

DRMS_RecordSet_t *drms_open_recordset(DRMS_Env_t *env, 
                      const char *rsquery, 
                      int *status);
DRMS_Record_t *drms_recordset_fetchnext(DRMS_Env_t *env, 
                                        DRMS_RecordSet_t *rs, 
                                        int *drmsstatus, 
                                        DRMS_RecChunking_t *chunkstat,
                                        int *newchunk);
int drms_recordset_fetchnext_getcurrent(DRMS_RecordSet_t *rset);
void drms_recordset_fetchnext_setcurrent(DRMS_RecordSet_t *rset, int current);

void drms_free_cursor(DRMS_RecSetCursor_t **cursor);

int drms_count_records(DRMS_Env_t *env, const char *recordsetname, int *status);

DRMS_Array_t *drms_record_getvector(DRMS_Env_t *env, 
                                    const char *recordsetname, 
                                    const char *keylist, 
                                    DRMS_Type_t type, 
                                    int unique,
                                    int *status);

DRMS_Segment_t *drms_record_nextseg(DRMS_Record_t *rec, HIterator_t **last, int followlink);
DRMS_Segment_t *drms_record_nextseg2(DRMS_Record_t *rec, HIterator_t **last, int followlink, DRMS_Segment_t **orig);
DRMS_Keyword_t *drms_record_nextkey(DRMS_Record_t *rec, HIterator_t **last, int followlink);
DRMS_Link_t *drms_record_nextlink(DRMS_Record_t *rec, HIterator_t **last);

int drms_record_parserecsetspec(const char *recsetsStr, 
                                char **allvers, 
                                char ***sets, 
                                DRMS_RecordSetType_t **types, 
                                char ***snames,
                                char ***filts,
                                int *nsets,
                                DRMS_RecQueryInfo_t *info);

int drms_record_parserecsetspec_plussegs(const char *recsetsStr, char **allvers, char ***sets, DRMS_RecordSetType_t **types, char ***snames, char ***filts, char ***segs, int *nsets, DRMS_RecQueryInfo_t *info);

int drms_record_freerecsetspecarr(char **allvers, 
                                  char ***sets, 
                                  DRMS_RecordSetType_t **types, 
                                  char ***snames, 
                                  char ***filts, 
                                  int nsets);

int drms_record_freerecsetspecarr_plussegs(char **allvers, char ***sets, DRMS_RecordSetType_t **types, char ***snames, char ***filts, char ***segs, int nsets);

/* DSDS */
int drms_record_isdsds(DRMS_Record_t *rec);
int drms_record_islocal(DRMS_Record_t *rec);

/* Doxygen function documentation */

#endif

---