CM/V1.0/drms_api.txt

=================== DRMS data types and structures ==================

For full definitions see jsoc/src/base/libdrms/drms_types.h

Main DRMS types visible to a module:

 DRMS_Type_t      : Basic scalar and string type enumerator.
 DRMS_Type_Value_t: Basic scalar and string values.

 DRMS_Record_t    : A single data record.
 DRMS_Keyword_t   : A record keyword (meta-data, headers)
 DRMS_Link_t      : A record link (links to other records)
 DRMS_Segment_t   : A record data segment holding bulk data of the record
 DRMS_Array_t     : A generic array of scalar values or strings. Used to
                    access the contents of a segment.
 DRMS_RecordSet_t : A set of data records.


DMRS types used internally:

 DRMS_Env_t       : The main DRMS environment. Contains information about the
                    DRMS session as well as caches of records, storage units
                    and series template records. In the DRMS server it 
                    contains mutexes (locks), signal masks and other data 
                    structures synchronize the server threads and allowing 
                    them to communicate.                    
 DRMS_Session_t   : A DRMS session handle. Holds information about the 
                    connection to a DRMS server.
 DRMS_ThreadInfo_t: Information passed to a thread in the DRMS server when 
                    it is spawned to service a new client.
 DRMS_SumRequest_t: Structure used to pass requests regarding storage units to
                    the designated SUMS communications thread in the server.


============ Record and RecordSet functions ===============

For full definitions see jsoc/src/base/libdrms/drms_record.{c,h}.

/* drms_open_records: 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, char *recordsetname, 
int *status);

/* drms_clone_records: Clone a set of records, i.e. create a new set
   of records and copy the value of keywords, links and segments from
   the pre-existing records given in "rs".  If
   mode=DRMS_SHARE_SEGMENTS the new segments will share segment files
   with the old records, i.e. it will have the same storage unit
   number, and only keyword and link data will be replicated.  If
   mode=DRMS_COPY_SEGMENTS the segment files for the old records will
   be copied to a new storage unit slots and assigned to the new
   records. */
DRMS_RecordSet_t *drms_clone_records(DRMS_RecordSet_t *recset, int mode, 
                                     int *status);

/* drms_create_records: Create a new set of n records. Fill keywords,
   links and segments with their default values from the series
   definition. Each record will be assigned a new storage unit slot to
   store its segment files in. */
DRMS_RecordSet_t *drms_create_records(DRMS_Env_t *env, int n, char *seriesname,
                                      int *status);

/* drms_close_records: Close a set of records. 
   1. a) If action=DRMS_COMMIT_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. NOTICE: The records will only be comitted 
      permanently to the database if the session finishes without
      error.
      b) If action=DRMS_DISCARD_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);

/* drms_closeall_records: Execute drms_close_record for all records in
   the record cache that are not marked read-only, i.e. which were
   created by the present program. */
int drms_closeall_records(DRMS_Env_t *env, int action);

/* drms_record_print: Print the contents of a record data structure to
   stdout. */
void  drms_record_print(DRMS_Record_t *rec);

/* Calculate size of a record and its segment arrays in bytes. */
long long drms_record_size(DRMS_Record_t *rec);


/* Single record versions: */
DRMS_Record_t *drms_clone_record(DRMS_Record_t *record, int mode, int *status);
DRMS_Record_t *drms_create_record(DRMS_Env_t *env, char *seriesname, 
                                  int *status);
int drms_close_record(DRMS_Record_t *rec, int action);


======================== Keyword functions ========================

For full definitions see jsoc/src/base/libdrms/drms_keyword.{c,h}.

/* Versions with type conversion. */
char drms_getkey_char(DRMS_Record_t *rec, const char *key,int *status);
short drms_getkey_short(DRMS_Record_t *rec, const char *key, int *status);
int drms_getkey_int(DRMS_Record_t *rec, const char *key, int *status);
long long drms_getkey_longlong(DRMS_Record_t *rec, const char *key, int *status);
float drms_getkey_float(DRMS_Record_t *rec, const char *key, int *status);
double drms_getkey_double(DRMS_Record_t *rec, const char *key, int *status);
char *drms_getkey_string(DRMS_Record_t *rec, const char *key, int *status);

/* Generic version. */
DRMS_Type_Value_t drms_getkey(DRMS_Record_t *rec, const char *key, 
                                DRMS_Type_t *type, int *status);

/* Versions with type conversion. */
int drms_setkey_char(DRMS_Record_t *rec, const char *key, char value);
int drms_setkey_short(DRMS_Record_t *rec, const char *key, short value);
int drms_setkey_int(DRMS_Record_t *rec, const char *key, int value);
int drms_setkey_longlong(DRMS_Record_t *rec, const char *key, long long value);
int drms_setkey_float(DRMS_Record_t *rec, const char *key, float value);
int drms_setkey_double(DRMS_Record_t *rec, const char *key, double value);
int drms_setkey_string(DRMS_Record_t *rec, const char *key, char *value);

/* Generic version. */
int drms_setkey(DRMS_Record_t *rec, const char *key, DRMS_Type_t type, 
                DRMS_Type_Value_t *value);

=== Utility keyword functions: ===
/* drms_keyword_print: Print all fields of the DRMS_Keyword_t struct 
   to stdout. */
void drms_keyword_print(DRMS_Keyword_t *key);
/* drms_keyword_printval: print formatted keyword value to stdout. */
void drms_keyword_printval(DRMS_Keyword_t *key);
DRMS_Keyword_t *drms_keyword_lookup(DRMS_Record_t *rec, const char *key);


======================== Link functions ========================

For full definitions see jsoc/src/base/libdrms/drms_link.{c,h}.

/* Set a static link to point to the record with absolute 
   record number "recnum" in the target series of link "linkname"
   associated with record "rec". */
int drms_setlink_static(DRMS_Record_t *rec, const char *linkname, int recnum);

/* Set a dynamic link to point to the record(s) with primary index values
   mathing those given in the "types" and "values" arrays. When a dynamic
   link is resolved the record with the highest record number of the ones
   matching the primary index is selected. */
int drms_setlink_dynamic(DRMS_Record_t *rec, const char *linkname, 
                         DRMS_Type_t *types, DRMS_Type_Value_t *values);

/* Follow a link to its destination record, retrieve it and return a 
   pointer to it. */
DRMS_Record_t *drms_link_follow(DRMS_Record_t *rec, const char *linkname, 
                                int *status);

=== Utility Link functions: ===
/* Print the contents of a link structure to stdout. */
void drms_link_print(DRMS_Link_t *link);


======================== Segment functions ========================

For full definitions see jsoc/src/base/libdrms/drms_segment.{c,h}.

Storage protocols currently supported: 
   DRMS_BINARY: Raw binary format
   DRMS_BINZIP: GZIP compressed raw binary format.

/* drms_segment_readraw: Read the data coresponding to the segment
   argument from file.  the data values will be read into an array of
   the same type that the segment values are stored on disk and no
   scaling will be done. */
DRMS_Array_t *drms_segment_readraw(DRMS_Segment_t *seg, int *status);

/* drms_segment_writeraw: Write the array argument to the (partial)
   file occupied by the segment argument. The array dimension and type
   must match the segment type and dimension. */
int drms_segment_writeraw(DRMS_Segment_t *seg, DRMS_Array_t *arr);

=== Utility Segment functions: ===
/* Print the fields of a keyword struct to stdout. */
void drms_segment_print(DRMS_Segment_t *seg)
/* Calculate segment size in bytes. */
long long drms_segment_size(DRMS_Segment_t *seg)
/* Look up a segment structure by name and return a pointer to it. */
DRMS_Segment_t *drms_segment_lookup(DRMS_Record_t *rec, const char *segname)

Revision:	1.1.1.1 (vendor branch)
Committed:	Tue Oct 2 00:12:21 2007 UTC (15 years, 11 months ago) by arta
Content type:	text/plain
Branch:	MAIN, Vtag
CVS Tags:	Ver_6-0, Ver_6-1, Ver_6-2, Ver_6-3, Ver_6-4, Ver_4-3, Ver_4-0, Ver_4-1, NetDRMS_Ver_8-8, NewTree01_cp03_JSOC, Ver_4-4, Ver_8-5, Ver_4-7, NewTree01_cp05_JSOC, Ver_5-14, Ver_5-13, Ver_5-12, Ver_5-11, Ver_5-10, Ver_LATEST, NetDRMS_Ver_LATEST, Ver_4-6, NewTree01_cp04_JSOC, NetDRMS_Ver_8-12, NetDRMS_Ver_8-10, NetDRMS_Ver_8-11, NetDRMS_Ver_9-1, NetDRMS_Ver_9-0, NetDRMS_Ver_9-3, NetDRMS_Ver_9-2, NetDRMS_Ver_9-5, NetDRMS_Ver_9-4, Ver_7-0, Ver_5-6, Ver_4-5, NewTree01_cp07_JSOC, NewTree01_cp08_JSOC, NewTree01_cp01_JSOC, Ver_4-2, NetDRMS_Ver_9-41, Ver_9-41, NewTree01_cp02_JSOC, NetDRMS_Ver_8-4, NetDRMS_Ver_8-5, Ver_5-8, NetDRMS_Ver_8-6, Ver_5-7, Ver_8-8, NetDRMS_Ver_8-7, NewTree01_cp06_JSOC, Ver_5-9, Ver_8-2, Ver_9-3, Ver_8-0, Ver_8-1, Ver_8-6, Ver_8-7, Ver_8-4, Ver_8-11, Ver_5-3, Ver_5-2, Ver_5-1, Ver_5-0, Ver_7-1, Ver_9-1, Ver_5-5, Ver_8-3, NewTree01_cp09_JSOC, Ver_9-5, Ver_9-4, Ver_8-10, Ver_9-2, Ver_8-12, Ver_9-0, HEAD
Changes since 1.1:	+0 -0 lines
Log Message:	First new, reorganized JSOC tree
#	User	Rev	Content
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			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			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			/* 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			/* 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			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			=== 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			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
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