Records

int status = drms_open_records(DRMS_Session_t *drms_handle, char *dataset_desc, int *num_records, DRMS_Record_t ***records, int mode)

Open existing data records. The parameter dataset_desc contains a dataset descriptor string using the syntax described in Section 1.4. The number of records matching the descriptor is returned in (*num_records), and an array containing pointers to the records retrieved is returned in (*records). If mode=READONLY the record will be opened as read-only. Opening with mode=CLONE_COPY is shorthand for opening and cloning (with mode=COPY_DATA) records in a single call and corresponds to the following code snippet:

int num_recs, *flags;
DRMS_Record_t **old_recs, **new_recs;
...
drms_open_records(drms_handle, dataset_desc, &num_recs, &old_recs, READONLY);
new_recs = (DRMS_Record_t **) malloc(num_records*sizeof(DRMS_Record_t *));
mode = malloc(num_records*sizeof(int));
for (i=0; i<num_recs; i++)
  flags[i] = COPY_DATA;
drms_clone_records(drms_handle, num_records, old_recs, new_recs, flags);
for (i=0; i<num_recs; i++)
  flags[i] = DISCARD;
drms_close_records(drms_handle, num_recs, old_recs, flags);

Opening with mode=CLONE_SHARE is shorthand for opening and cloning with mode=SHARE_DATA. See the desciption of drms_clone_records below.

int status = drms_clone_records(DRMS_Session_t *drms_handle, int num_records, DRMS_Record_t *input[num_records], DRMS_Record_t *output[num_records], int mode[num_records])

Clones a set of existing data records. For each input record input[i], $i=0,\ldots,\mbox{\tt num\_records}-1$, create a copy of it, assign the copy a new unique record number.

The parameter mode can take the values COPY_DATA, SHARE_DATA and determines whether the data segment files are copied or the old data segment shared between the old and the new record. If mode=COPY_DATA then the data segments are copied to a new slot in a storage unit and the caller will have permission to open them for writing. If mode=SHARE_DATA the new record will point to the data unit slot containing the data segments of the old record, and will not have permission to open them for writing. [exactly how permissions on datasegments will work is TBD]

If the value returned in status is 0 the call suceeded. If status is -1 an unknown error occured. TBD: [Add positive status codes for known error conditions]

int status = drms_create_records(DRMS_Session_t *drms_handle, char *series, int num_records, DRMS_Record_t *records[num_records])

Create num_records new records from the series whose name is given by the string argument series and return handles to the records in the array records. Each record will be given a unique record number and its keywords and links will be initialized to their default values. If the series definition contains one or more data segments, DRMS will assign a storage unit to each record. This may involve allocate new data units from SUMS if not enough slots available in new storage units already opened for writing for the series. If the value returned in status is 0 the call suceeded. If status is -1 an unknown error occured. TBD: [Add positive status codes for known error conditions]

int status = drms_close_records(DRMS_Session_t *drms_handle, int num_records, DRMS_Record_t *records[num_records], int action[num_records])

This call tells DRMS to close num_records data records identified by the handles in the array argument records. The optional array action has an entry for every record telling DRMS what to do with the record. Entries in action can take the values COMMIT and DISCARD.

A value of action[i]=COMMIT will tell DRMS to insert the keyword and link values for record $i$ in the record database, and to mark any of the data segment files written to a storage unit for subsequent archiving by the SUMS.

A value of action[i]=DISCARD will tell DRMS to discard the record, i.e. not insert it into the database. DRMS will also delete data segment files associated with the record, unless the record was created by drms_clone_records with mode=SHARE_DATA.

For ``old'' records opened with drms_open_records in read-only mode, action always defaults to DISCARD. For ``new'' records created by calling

• drms_open_records with mode=CLONE_COPY or mode=CLONE_SHARE,
• drms_clone_records with mode=COPY_DATA or mode=SHARE_DATA
• drms_create_records

the value of action always defaults to COMMIT. If action is NULL, the defaults just mentioned apply. drms_clone_records frees all memory associated with the records.

If the value returned in status is 0 the call suceeded. If status is -1 an unknown error occured. TBD: [Add positive status codes for known error conditions]

char * drms_get_record_path(DRMS_Record_t *record)

Returns a malloced string containing a path to the directory where data segment files associated with record reside. It is the responsibility of the caller to free the returned string.

void drms_free_record(DRMS_Session_t
*drms_handle, DRMS_Record_t *record)

Frees the memory associated with record.

void drms_free_record(DRMS_Session_t *drms_handle, int num_records,
DRMS_Record_t *records[num_records])

Frees the memory associated with record[i], i=1,...,num_records-1.

Table 1: List of status codes returned by drms_setkey and drms_getkey family of functions.

status	C macro	Meaning
0	SUCCESS	Success, no loss of accuracy
1	JSOC_INEXACT	Success, possible loss of accuracy
-1	JSOC_RANGE	Failure, value out of range
-2	JSOC_BADSTRING	Failure, trying to convert invalid string to numeric type
-3	JSOC_MISSING	Failure, keyname refers to non-existing keyword

Table 2: Matrix of status return values from the drms_setkey and drms_getkey family of functions depending on the types of source and destination operands in the call. In addition all calls can return -3. See Table 1 for the meaning of the various values.

	destination type	char	short	int	long long	float	double	string
source type
char		0	0	0	0	0	0	0
short		-1, 0	0	0	0	0	0	0
int		-1, 0	-1, 0	0	0	0, 1	0	0
long long		-1, 0	-1, 0	-1, 0	0	0, 1	0, 1	0
float		-1, 0, 1	-1, 0, 1	-1, 0, 1	-1, 0, 1	0	0	1
double		-1, 0, 1	-1, 0, 1	-1, 0, 1	-1, 0, 1	-1, 0, 1	0	1
string		-2, -1, 0	-2, -1, 0	-2, -1, 0	-2, -1, 0	-2, -1, 1	-2, -1, 1	0