1 arta  1.1 =================== DRMS data types and structures ==================
  2           
  3           For full definitions see jsoc/src/base/libdrms/drms_types.h
  4           
  5           Main DRMS types visible to a module:
  6           
  7            DRMS_Type_t      : Basic scalar and string type enumerator.
  8            DRMS_Type_Value_t: Basic scalar and string values.
  9           
 10            DRMS_Record_t    : A single data record.
 11            DRMS_Keyword_t   : A record keyword (meta-data, headers)
 12            DRMS_Link_t      : A record link (links to other records)
 13            DRMS_Segment_t   : A record data segment holding bulk data of the record
 14            DRMS_Array_t     : A generic array of scalar values or strings. Used to
 15                               access the contents of a segment.
 16            DRMS_RecordSet_t : A set of data records.
 17           
 18           
 19           DMRS types used internally:
 20           
 21            DRMS_Env_t       : The main DRMS environment. Contains information about the
 22 arta  1.1                     DRMS session as well as caches of records, storage units
 23                               and series template records. In the DRMS server it 
 24                               contains mutexes (locks), signal masks and other data 
 25                               structures synchronize the server threads and allowing 
 26                               them to communicate.                    
 27            DRMS_Session_t   : A DRMS session handle. Holds information about the 
 28                               connection to a DRMS server.
 29            DRMS_ThreadInfo_t: Information passed to a thread in the DRMS server when 
 30                               it is spawned to service a new client.
 31            DRMS_SumRequest_t: Structure used to pass requests regarding storage units to
 32                               the designated SUMS communications thread in the server.
 33           
 34           
 35           ============ Record and RecordSet functions ===============
 36           
 37           For full definitions see jsoc/src/base/libdrms/drms_record.{c,h}.
 38           
 39           /* drms_open_records: Retrieve a recordset specified by the DRMS
 40              dataset name string given in the argument "datasetname". The
 41              records are inserted into the record cache and marked read-only. */
 42           DRMS_RecordSet_t *drms_open_records(DRMS_Env_t *env, char *recordsetname, 
 43 arta  1.1 int *status);
 44           
 45           /* drms_clone_records: Clone a set of records, i.e. create a new set
 46              of records and copy the value of keywords, links and segments from
 47              the pre-existing records given in "rs".  If
 48              mode=DRMS_SHARE_SEGMENTS the new segments will share segment files
 49              with the old records, i.e. it will have the same storage unit
 50              number, and only keyword and link data will be replicated.  If
 51              mode=DRMS_COPY_SEGMENTS the segment files for the old records will
 52              be copied to a new storage unit slots and assigned to the new
 53              records. */
 54           DRMS_RecordSet_t *drms_clone_records(DRMS_RecordSet_t *recset, int mode, 
 55           				     int *status);
 56           
 57           /* drms_create_records: Create a new set of n records. Fill keywords,
 58              links and segments with their default values from the series
 59              definition. Each record will be assigned a new storage unit slot to
 60              store its segment files in. */
 61           DRMS_RecordSet_t *drms_create_records(DRMS_Env_t *env, int n, char *seriesname,
 62           				      int *status);
 63           
 64 arta  1.1 /* drms_close_records: Close a set of records. 
 65              1. a) If action=DRMS_COMMIT_RECORD the record meta-data (keywords
 66                 and links) will be inserted into the database and the data
 67                 segments will be left in the storage unit directory for later
 68                 archiving by SUMS. NOTICE: The records will only be comitted 
 69                 permanently to the database if the session finishes without
 70                 error.
 71                 b) If action=DRMS_DISCARD_RECORD the data segment files are
 72                 deleted from disk.
 73              2. The record structures are freed from the record cache. */
 74           int drms_close_records(DRMS_RecordSet_t *rs, int action);
 75           
 76           /* drms_closeall_records: Execute drms_close_record for all records in
 77              the record cache that are not marked read-only, i.e. which were
 78              created by the present program. */
 79           int drms_closeall_records(DRMS_Env_t *env, int action);
 80           
 81           /* drms_record_print: Print the contents of a record data structure to
 82              stdout. */
 83           void  drms_record_print(DRMS_Record_t *rec);
 84           
 85 arta  1.1 /* Calculate size of a record and its segment arrays in bytes. */
 86           long long drms_record_size(DRMS_Record_t *rec);
 87           
 88           
 89           /* Single record versions: */
 90           DRMS_Record_t *drms_clone_record(DRMS_Record_t *record, int mode, int *status);
 91           DRMS_Record_t *drms_create_record(DRMS_Env_t *env, char *seriesname, 
 92           				  int *status);
 93           int drms_close_record(DRMS_Record_t *rec, int action);
 94           
 95           
 96           
 97           ======================== Keyword functions ========================
 98           
 99           For full definitions see jsoc/src/base/libdrms/drms_keyword.{c,h}.
100           
101           /* Versions with type conversion. */
102           char drms_getkey_char(DRMS_Record_t *rec, const char *key,int *status);
103           short drms_getkey_short(DRMS_Record_t *rec, const char *key, int *status);
104           int drms_getkey_int(DRMS_Record_t *rec, const char *key, int *status);
105           long long drms_getkey_longlong(DRMS_Record_t *rec, const char *key, int *status);
106 arta  1.1 float drms_getkey_float(DRMS_Record_t *rec, const char *key, int *status);
107           double drms_getkey_double(DRMS_Record_t *rec, const char *key, int *status);
108           char *drms_getkey_string(DRMS_Record_t *rec, const char *key, int *status);
109           
110           /* Generic version. */
111           DRMS_Type_Value_t drms_getkey(DRMS_Record_t *rec, const char *key, 
112           				DRMS_Type_t *type, int *status);
113           
114           /* Versions with type conversion. */
115           int drms_setkey_char(DRMS_Record_t *rec, const char *key, char value);
116           int drms_setkey_short(DRMS_Record_t *rec, const char *key, short value);
117           int drms_setkey_int(DRMS_Record_t *rec, const char *key, int value);
118           int drms_setkey_longlong(DRMS_Record_t *rec, const char *key, long long value);
119           int drms_setkey_float(DRMS_Record_t *rec, const char *key, float value);
120           int drms_setkey_double(DRMS_Record_t *rec, const char *key, double value);
121           int drms_setkey_string(DRMS_Record_t *rec, const char *key, char *value);
122           
123           /* Generic version. */
124           int drms_setkey(DRMS_Record_t *rec, const char *key, DRMS_Type_t type, 
125           		DRMS_Type_Value_t *value);
126           
127 arta  1.1 === Utility keyword functions: ===
128           /* drms_keyword_print: Print all fields of the DRMS_Keyword_t struct 
129              to stdout. */
130           void drms_keyword_print(DRMS_Keyword_t *key);
131           /* drms_keyword_printval: print formatted keyword value to stdout. */
132           void drms_keyword_printval(DRMS_Keyword_t *key);
133           DRMS_Keyword_t *drms_keyword_lookup(DRMS_Record_t *rec, const char *key);
134           
135           
136           ======================== Link functions ========================
137           
138           For full definitions see jsoc/src/base/libdrms/drms_link.{c,h}.
139           
140           /* Set a static link to point to the record with absolute 
141              record number "recnum" in the target series of link "linkname"
142              associated with record "rec". */
143           int drms_setlink_static(DRMS_Record_t *rec, const char *linkname, int recnum);
144           
145           /* Set a dynamic link to point to the record(s) with primary index values
146              mathing those given in the "types" and "values" arrays. When a dynamic
147              link is resolved the record with the highest record number of the ones
148 arta  1.1    matching the primary index is selected. */
149           int drms_setlink_dynamic(DRMS_Record_t *rec, const char *linkname, 
150           			 DRMS_Type_t *types, DRMS_Type_Value_t *values);
151           
152           /* Follow a link to its destination record, retrieve it and return a 
153              pointer to it. */
154           DRMS_Record_t *drms_link_follow(DRMS_Record_t *rec, const char *linkname, 
155           				int *status);
156           
157           === Utility Link functions: ===
158           /* Print the contents of a link structure to stdout. */
159           void drms_link_print(DRMS_Link_t *link);
160           
161           
162           ======================== Segment functions ========================
163           
164           For full definitions see jsoc/src/base/libdrms/drms_segment.{c,h}.
165           
166           Storage protocols currently supported: 
167              DRMS_BINARY: Raw binary format
168              DRMS_BINZIP: GZIP compressed raw binary format.
169 arta  1.1 
170           /* drms_segment_readraw: Read the data coresponding to the segment
171              argument from file.  the data values will be read into an array of
172              the same type that the segment values are stored on disk and no
173              scaling will be done. */
174           DRMS_Array_t *drms_segment_readraw(DRMS_Segment_t *seg, int *status);
175           
176           /* drms_segment_writeraw: Write the array argument to the (partial)
177              file occupied by the segment argument. The array dimension and type
178              must match the segment type and dimension. */
179           int drms_segment_writeraw(DRMS_Segment_t *seg, DRMS_Array_t *arr);
180           
181           === Utility Segment functions: ===
182           /* Print the fields of a keyword struct to stdout. */
183           void drms_segment_print(DRMS_Segment_t *seg)
184           /* Calculate segment size in bytes. */
185           long long drms_segment_size(DRMS_Segment_t *seg)
186           /* Look up a segment structure by name and return a pointer to it. */
187           DRMS_Segment_t *drms_segment_lookup(DRMS_Record_t *rec, const char *segname)
188