CRIS/SIS Low Level Data Archival Routines

Last Modified Wednesday, 14-Jan-1998 23:05:58 PST.

Here are the low level routines used in the CRIS/SIS data archival libraries. This documentation is primarily intended for those who need to port and/or rewrite parts of the libraries. See notes on setting up the data archival libraries for instructions on setting up the source, makefiles, and directory structure involved in creating the libraries.

createInitializedFile

void createInitializedFile(int fd, char dataBuffer[], int bufferSize, int dataTypeID);

createInitializedFile initializes a day's data file for a particular data type. It writes the 32 byte header and zeros the rest of the file. The file is made large enough on initialization to contain all of the given type of data for the full day. createInitializedFile assumes that the data type has a periodicity of 256 seconds per data struct. Data types with different periododicities use the routine createInitializedFileWithIntervalN. Non-periodic data types use neither.

Input:

fd is the file descriptor of the just created, but uninitialized, file.
bufferSize is equal to the size of a single struct of the data type which is to be archived in this file.
dataBuffer is a char array of size bufferSize.
dataTypeID is the ID number assigned to the data type to be archived in this file. These IDs are defined in the header file FileTypes.h.

Output:

None. (A file is written to disk.)

createInitializedFileWithIntervalN

void createInitializedFileWithIntervalN(int fd, char dataBuffer[],
                        int bufferSize, int dataTypeID, int timeInterval);

See notes for routine createInitializedFile.

Input:

fd is the file descriptor of the just created, but uninitialized, file.
bufferSize is equal to the size of a single struct of the data type which is to be archived in this file.
dataBuffer is a char array of size bufferSize.
dataTypeID is the ID number assigned to the data type to be archived in this file. These IDs are defined in the header file FileTypes.h.
timeInterval is the period of time (in seconds) for which the data structs in question cover. (createInitializedFile assumes this value to be 256.)

Output:

None. (A file is written to disk.)

determineDataFilePathAndCreateDirsAsNeeded

void determineDataFilePathAndCreateDirsAsNeeded(uint32 secondsSince1996,
                                const char *dataFileSuffix, char *path,
                                int *pIntervalNumber, char instrumentID);

determineDataFilePathAndCreateDirsAsNeeded determines the path to the archive file of a particular data type from a particular day. If parts of this path do not exist yet, this routine attempts to create them before handing back the file's (or file-to-be's) path.

Input:

secondsSince1996 is the number of seconds since 1/1/96 00:00:00. All data structs are time tagged with such a number.
dataFileSuffix is the 2 or 3 character string which is appended to all data files containing a particular type of data. E.g., the "hp" at the end of the file sis_prelim.1997.10.31.hp is the marker used for all high priority rate data.
path is a pointer to a char array of sufficient size to hold the file path.
pIntervalNumber is a pointer to an int.
instrumentID is either 'c' or 's' to denote CRIS or SIS respectively.

Output:

The path of the data file is placed in the location pointed to by the char* path (which is passed to the routine as an argument).
The time slot in the data file associated with the value of the secondsSince1996 argument is returned in the location pointed to by the int* pIntervalNumber (which is passed to the routine as an argument).

sortTrackers

int sortTrackers(const void *pVoid1, const void *pVoid2);

sortTrackers is called by qsort in a few routines to reorder data structs in their files. This routine is used only for the reordering of non-periodic data types (i.e., those with start and stop time stamps) in their files when a struct needs to be written to an archive file somewhere before the end of the file in order to preserve a chronological ordering of the structs in the file.

Input:

pVoid1 is a void pointer to the first struct.
pVoid2 is a void pointer to the second struct.

Output:

An integer is returned signifying the chronological ordering (by start time stamps) of the two structs being tested.

writeDataStructToFile

int writeDataStructToFile(int fd, int intervalNumber, char dataBuffer[],
                                int bufferSize, char *pDataStruct, char *path);

writeDataStructToFile is used to write a data struct into the proper position in its archive file.

First this routine checks what has been written into the data file at the interval where the passed data struct is to be written. If the interval is all zeros (done at file initialization), the struct is written and a status of 0 is returned.

If the interval is found to contain data already, both the passed struct and the one already in the file are written out to an auxiliary file (same file name with ".overlap" suffix appended), the interval is filled with char -1s, and a status of 1 is returned.

If the interval is filled with char -1s, then the passed struct is written to the auxiliary file and a status of 2 is returned.

Finally, if the passed data struct is identical to the data already in the interval, nothing is written, and a status of 3 is returned.

Input:

fd is the file descriptor for the already opened-for-write data file.
intervalNumber is the number of the slot within the data file where the data will be (or attempted to be) written.
dataBuffer is a char array of size equal to the struct to be written.
bufferSize is the size of the struct to be written.
pDataStruct is a pointer to the struct to be written.
The path of the data file is passed in case an "overlap" file path needs to be constructed to write overlap data (see above.)

Output:

An integer status is returned. See description above for details.

writeHeader

void writeHeader(int fd, int dataTypeID);

writeHeader is used for writing the 32 byte header present at the beginning of every data file in the archive. Header description.

Input:

fd is the file descriptor for the already opened-for-write data file.
dataTypeID is an ID for the data type to be written to the file. These IDs are defined in the C header file FileTypes.h.

Output:

None. (A 32 byte header is written at the beginning of a data file.)

bruce