End-user routines for easy conversions between dates, seconds-since-1996, and day-of-1996.
date = get_date_from_day_1996(day1996)
This routine returns a structure which corresponds to the zeroth second of the day day1996. Be aware that day1996 = 1 is defined as 1/1/96.
Usage:
4/23/1998
day1996 = 633 /* sept 24, 1997 (day1996 = 1 on 1/1/96) */
date = get_date_from_day_1996(day1996)
print, date
Input:
| Last Modified: 4/23/1998 | Return to Contents |
date = get_date_from_seconds_since_1996(secondsSince1996)
get_date_from_seconds_since_1996 returns a date ({AceTime} struct format) which corresponds to the number of seconds since Jan 1, 1996, 00:00:00.
Usage:
secondsSince1996 = 54605304L
date = get_date_from_seconds_since_1996(secondsSince1996)
print, date
Input:
| Last Modified: 4/22/1998 | Return to Contents |
day1996 = get_day_1996_from_date(date)
get_day_1996_from_date returns the day-of-1996 corresponding to the date given in an {AceTime} struct.
Usage:
timeStruct = {AceTime}
timeStruct.year = 1998
timeStruct.month = 0
timeStruct.day = 27
day1996 = get_day_1996_from_date(timeStruct)
print, "day1996 = ", day1996
Input:
| Last Modified: 4/27/1998 | Return to Contents |
day1996 = get_day_1996_from_seconds_since_1996(secondsSince1996)
get_day_1996_from_seconds_since_1996 returns the day of 1996 (a count of days since Jan 1, 1996 where day1996 = 1 on Jan 1, 1996) in which the second secondsSince1996 occurs.
Usage:
secondsSince1996 = 54605304L
day1996 = get_day_1996_from_seconds_since_1996(secondsSince1996)
print, "day1996 = ", day1996
Input:
| Last Modified: 4/22/1998 | Return to Contents |
secondSince1996 = get_seconds_since_1996_from_date(date)
get_seconds_since_1996_from_date returns the seconds since 1996 corresponding to the date given in an {AceTime} struct format.
Usage:
date = get_date_from_day_1996(705)
secondsSince1996 = get_seconds_since_1996_from_date(date)
print, 'secondsSince1996 at the start of day1996 = 705 is ', secondsSince1996
Input:
| Last Modified: 4/23/1998 | Return to Contents |
secondsSince1996 = get_seconds_since_1996_from_day_1996(day1996)
get_seconds_since_1996_from_day_1996 returns the seconds-since-1996 corresponding to the zeroth second of the day day1996. Be aware that day1996 = 1 is defined as 1/1/96.
Usage:
day1996 = 700
secondsSince1996 = get_seconds_since_1996_from_day_1996(day1996)
print, 'The number of seconds since 1996 at the start of day1996 = ', $
day1996, ' is ', secondsSince1996
Input:
| Last Modified: 4/23/1998 | Return to Contents |
End-user routines to get general information about the archive and archive files.
date = get_first_date_of_archived_data(structName)
get_first_date_of_archived_data is used to determine what the first day of a particular type of data is in the archive for a particular instrument (CRIS or SIS).
Usage:
structToUse = {L1CrisCommandEcho}
structName = get_struct_name_from_struct(structToUse)
date = get_first_date_of_archived_data(structName)
print, 'Date of initial day of archived data is ', date
Input:
| Last Modified: 4/23/1998 | Return to Contents |
date = get_last_date_of_archived_data(structName)
get_last_date_of_archived_data is used to determine what the last day of a particular type of data is in the archive for a particular instrument (CRIS or SIS).
Usage:
structToUse = {L1CrisCommandEcho}
structName = get_struct_name_from_struct(structToUse)
date = get_last_date_of_archived_data(structName)
print, 'Date of final day of archived data for ', structName, ' is ', date
Input:
| Last Modified: 4/23/1998 | Return to Contents |
stamps = get_time_stamps_of_days_structs(day1996, structToUse)
Get a list of the time stamps of a particular data type for a given day. The time stamps returned are those starting at the data valid at second zero of the day and ending just before the data which is valid at second zero of the next day. Any intervals of missing data for the day return values of -1 for their time stamps. Beware that both start and stop time stamps are returned. For periodic data types, this means all of the stop time stamps will be set to -1 (because they have no stop time stamps.)
Usage:
day1996 = 703
structToUse = {L1CrisCommandEcho}
stamps = get_time_stamps_of_days_structs(day1996, structToUse)
i = 0
while (stamps[i] NE 0) do begin
print, i, stamps[i], stamps[i+1]
i = i + 2
endwhile
Input:
| Last Modified: 4/23/1998 | Return to Contents |
End-user routines specific to the processing of event data.
result = get_request_times_for_days_evt_cycles(day1996, instrumentID)
Get a list of times which can be used to iteratively retrieve a day's worth of event data with no possibility of getting overlapping data when using this routine to retrieve data over many days. These times *are not* data time stamps because actually getting the time stamps would be just as time consuming as a full read of the data.
Usage:
instrumentID = 's'
for day1996 = 695, 730, do begin
timeList = get_request_times_for_days_evt_cycles(day1996, instrumentID)
i = 0
while (timeList[i] NE 0) do begin
structs = get_events_s(timeList[i])
; process your events here
print, n_elements(structs) - 1
i = i + 1
endwhile
endfor
Input:
| Last Modified: 4/27/1998 | Return to Contents |
Low level routines for time stamp determination.
stamps = get_time_stamps_of_structs(structs)
get_time_stamps_of_structs returns the start time stamps of a set of data structs.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
stopTimes = get_stop_times_of_structs(structs)
get_stop_times_of_structs extracts the stop time stamps from a set of data structs. If there is no stop time stamp field in the struct, the start time + period - 1 is returned as the stop time.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
Low level utilities for some systems concerns. (C only.)
Low level archive data retrieval utilities.
timeStamps = get_archive_files_time_stamps(day1996, structToUse)
get_archive_files_time_stamps creates a list of the time stamps of a particular type of data in one daily archive file. WARNING: This routine *does not* return what is referred to elsewhere as a day's set of data. This routine should be used to check what time stamps are on data in an archive file for debugging purposes only. Do not process data using this routine.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
result = generate_data_file_path(date, structName)
generate_data_file_path constructs the path to a particular archive data file.
Usage:
day1996 = 633
structToUse = {L1CrisHskp}
date = get_date_from_day_1996(day1996); /* sept 24, 1997 */
structName = get_struct_name_from_struct(structToUse)
path = generate_data_file_path(date, structName);
print, "path to data file is ", path
Input:
| Last Modified: 4/22/1998 | Return to Contents |
suffix = get_data_file_suffix_from_struct_name(structName)
The data files in the CRIS/SIS archive have suffixes associated with them, such as "hp" (high priority rates), "evt" (event cycles), etc. get_data_file_suffix_from_struct_name looks at the name of the structure we are dealing with and determines the suffix string associated with it.
This routine is useful in generating data file paths to the desired archive files.
Input:
| Last Modified: 4/22/1998 | Return to Contents |
period = get_data_type_period_from_struct_name(structName)
Most of the data types in the CRIS/SIS archive are periodic in the time interval they cover. get_data_type_period_from_struct_name takes the name of a data type and returns this period.
Input:
| Last Modified: 4/22/1998 | Return to Contents |
id = get_instrument_id_from_struct_name(structName)
Get an ID for the instrument associated with the data type given by structName.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
count = get_files_struct_count(dataFilePath, structToUse, hasHeader)
get_files_struct_count is used to determine the number of data structs of size structSize in the file pointed at by dataFilePath. It does this merely by looking at the size of the file, subtracting out the number of bytes in the standard CRIS/SIS data archive header if the flag hasHeader is set (it usually will be), and then dividing by structSize. If the divide does not return an integral number, get_files_struct_count will exit with an error message.
Usage:
structToUse = {L1CrisCommandEcho}
hasHeader = 1
structName = get_struct_name_from_struct(structToUse)
day1996 = 700
date = get_date_from_day_1996(day1996)
path = generate_data_file_path(date, structName)
count = get_files_struct_count(path, structToUse, hasHeader)
print, 'struct count in ', path, ' is ', count
Input:
| Last Modified: 4/23/1998 | Return to Contents |
size = get_struct_size(struct)
get_struct_size merely returns the size (in bytes) of the data struct.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
name = get_struct_name_from_struct(dataStructure)
Given an instance of a CRIS/SIS level1 data struct, get_struct_name_from_struct will return the name of the structure (in all lower case letters.)
Usage:
structToUse = {L1CrisEventCycle}
structName = get_struct_name_from_struct(structToUse)
print, 'structName = ', structName
Input:
| Last Modified: 4/23/1998 | Return to Contents |
newSuffix = validate_data_type_suffix(suffix)
Check that a data type archive file suffix is valid. If it is not valid, but is recognizable, the suffix is fixed to the valid version. If it is not recognizable, the process exits.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
newID = validate_instrument_id(id)
Check that an instrument ID is valid. If it is not valid, but is recognizable, the ID is fixed to the valid version. If it is not recognizable, the process exits.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
Low level archive data retrieval engines and low level wrappers.
structs = get_structs(secondsSince1996Start, secondsSince1996Stop, structToUse)
get_structs retrieves any data structures of type structToUse from the archives which were valid between the start time, secondsSince1996Start, and the stop time, secondsSince1996Stop (But see the note below for an important clarification of exactly what this means.) An array of structs of type structToUse is returned. This array is always terminated by a zeroed struct of type structToUse.
The start and stop times used in get_structs can be across an arbitrary time interval. This may cause problems if users abuse it. In other words, get_structs allocates an arbitrary amount of memory for the struct array it will be creating. Users should be warned about this (though they should be accessing get_structs via a more user friendly wrapper like getGroupHiRates_s or the like, the same warning applies there.)
Note: A structure which is valid at the time secondsSince1996Start will always be returned by this call, but the structure valid at secondsSince1996Stop will not be returned unless it is the same structure which is valid at secondsSince1996Start. Any and all structures valid at times between secondsSince1996Start and secondsSince1996Stop will be returned (which seems too obvious to state.) The reason that the last structure (the one valid at secondsSince1996Stop) is not returned by this call is to prevent seemingly contiguous calls to get_structs from returning overlapping data. For this reason, any series of calls to get_structs for contiguous data must use the prior secondsSince1996Stop as the secondsSince1996Start for the new call. Otherwise there will be a 1 second gap in each call's time intervals.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
structs = get_struct(secondsSince1996, structToUse)
get_struct retrieves any data structure of type structName from the archives which was valid at time secondsSince1996. Beware that despite the singular nature of the name, an array of structs is always returned. This array is always terminated by a zeroed struct of type structName. The reason for this is that, due to some anomoly with the clock perhaps, more than 1 data struct may be stamped as valid during a particular interval, so there is a small chance of getting more than a single "valid" data struct back. There is a much better chance of the array only containing the terminal zeroed struct. In such a case, either no data exists during the interval or it has not yet been archived. - get_struct is really just a special case of get_structs, where both secondsSince1996Start and secondsSince1996Stop are set to the same value, secondsSince1996.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
structs = get_days_structs(day1996, structName)
A get a day's worth of structs, starting with the data struct which is valid at second zero of the day (which is usually archived in the file of the previous day), and ending just prior to the data struct which is valid at second zero of the next day (which is usually the last struct in this day's archive file.)
get_days_structs reads the non-zero structs from the file, terminates the array of structs with a zeroed struct, and returns the struct array.
Input:
| Last Modified: 4/23/1998 | Return to Contents |
Low level file I/O routines.
result = file_exists(path);
file_exists is used primarily by the put data routines to check if an archive data file exists already or needs to be created and initialized. Returns 1 (true) if the file does exist, and 0 (false) if not. If the file is actually a directory, 0 is returned.
Usage:
filePath = "/home/idunn1/rgr/dataStorage/data1.out"
if (file_exists(filePath)) then print, filePath, " exists." $
else print, filePath, " does not exist."
Input:
| Last Modified: 4/23/1998 | Return to Contents |
result = directory_exists(path);
directory_exists is used primarily by the put data routines to check if an archive directory already exists (before createDirectory is called). Returns 1 (true) if the directory does exist, and 0 (false) if not.
Usage:
directoryPath = "/home/idunn1/rgr/dataStorage";
if (directory_exists(directoryPath)) then print, directoryPath, " exists." $
else print, directoryPath, " does not exist."
Input:
| Last Modified: 4/23/1998 | Return to Contents |
Low level data archival routines. Available for C only.
Return to level1 Data Retrieval Libraries Documentation