Time Series Functions
zstructTsNew
Description: Creates a new time series struct without a time window or data.
Declaration:
zStructTimeSeries* zstructTsNew(const char* pathname);
Parameters:
const char* pathname
The pathname for this struct. Must be a valid pathname. A copy of the pathname is used in struct.
Returns:
zStructTimeSeries*
An address to the time series struct created.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks: This is the standard struct used by the various DSS time series functions.
See: Chapter 4 (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
See Also:
zstructTsNewTimes()
zstructTsNewRegFloats()
zstructTsNewRegDoubles()
zstructTsNewIrregFloats()
zstructTsNewIrregDoubles()
zstructTsNewIrregDoubles
Description: Creates a new time series struct with data for storing a irregular-interval double data set. Note: For STORING data only.
Declaration:
zStructTimeSeries* zstructTsNewIrregDoubles(const char* pathname, double doubleValues, int numberValues, int *itimes, int timeGranularitySeconds, const char startDateBase, const char *units, const char *type);
Parameters:
const char* pathname
The pathname of the record to store. The pathname is case insensitive (i.e., "Apart" is the same as "APART"), and must have a correct E part (block or pseudo-interval)
double *doubleValues
A double array containing the data to store.
int numberValues
The number of data values in array doubleValues and itimes to store.
int *itimes
An integer array of minutes or seconds that correspond to the date/time for each value. If startDateBase is null or "", then these are minutes or seconds from 01 Jan 1900; otherwise this array is to contain minutes/seconds from startDateBase (start of the day for that date.) itimes must be the numberValues long and must have a one-to-one correspondence with doubleValues.
int timeGranularitySeconds
The number of seconds a unit in *itimes represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)
const char *startDateBase (optional)
If the time array starts from any other date than 01Jan1900, then that start date is given here. That date is added to each element in itimes to obtain the correct date. startDateBase is usually used when times in itimes might over run and integer words, such as when seconds are used as the granularity or times are very large. The date may appear similar to "23MAR1985". Multiple date formats are supported. If the default base date is used (01 Jan 1900), set to null or "".
const char *units
The units of the data, such as "CFS". The number of characters in units is not limited, but generally should not be greater than 25.
const char *type
The type of data. Valid values include "PER-AVER", "PER-CUM", "INST-VAL", and "INST-CUM". The number of characters in units is not limited, but generally should not be greater than 25.
Returns:
zStructTimeSeries*
An address to the time series struct created ready to be stored with ztsStore(). Additional data, such as quality values or notes can be added.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks:
This is an extension of zstructTsNew(). For STORING data only (To retrieve data, use zstructTsNew and provide time window in call to ztsRetrieve.)
The arrays are used directly (not copied), so they must stay intact until the store is complete.
You must not reuse this struct. Make a new one for every dataset.
See: Also (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
See Also:
zstructTsNew()
zstructTsNewTimes()
zstructTsNewRegFloats()
zstructTsNewRegDoubles()
zstructTsNewIrregFloats()
zstructTsNewIrregFloats
Description: Creates a new time series struct with data for storing a irregular-interval float data set. Note: For STORING data only.
Declaration:
zStructTimeSeries* zstructTsNewIrregFloats(const char* pathname, float floatValues, int numberValues, int *itimes, int timeGranularitySeconds, const char startDateBase, const char *units, const char *type);
Parameters:
const char* pathname
The pathname of the record to store. The pathname is case insensitive (i.e., "Apart" is the same as "APART"), and must have a correct E part (block or pseudo-interval)
float *floatValues
A float array containing the data to store.
int numberValues
The number of data values in array floatValues and itimes to store.
int *itimes
An integer array of minutes or seconds that correspond to the date/time for each value. If startDateBase is null or "", then these are minutes or seconds from 01 Jan 1900; otherwise this array is to contain minutes/seconds from startDateBase (start of the day for that date.) itimes must be the numberValues long and must have a one-to-one correspondence with floatValues.
int timeGranularitySeconds
The number of seconds a unit in *itimes represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)
const char *startDateBase (optional)
If the time array starts from any other date than 01Jan1900, then that start date is given here. That date is added to each element in itimes to obtain the correct date. startDateBase is usually used when times in itimes might over run and integer words, such as when seconds are used as the granularity or times are very large. The date may appear similar to "23MAR1985". Multiple date formats are supported. If the default base date is used (01 Jan 1900), set to null or "".
const char *units
The units of the data, such as "CFS". The number of characters in units is not limited, but generally should not be greater than 25.
const char *type
The type of data. Valid values include "PER-AVER", "PER-CUM", "INST-VAL", and "INST-CUM". The number of characters in units is not limited, but generally should not be greater than 25.
Returns:
zStructTimeSeries*
An address to the time series struct created ready to be stored with ztsStore(). Additional data, such as quality values or notes can be added.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks:
This is an extension of zstructTsNew(). For STORING data only (To retrieve data, use zstructTsNew and provide time window in call to ztsRetrieve.)
The arrays are used directly (not copied), so they must stay intact until the store is complete.
You must not reuse this struct. Make a new one for every dataset.
See: also (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
See Also:
zstructTsNew()
zstructTsNewTimes()
zstructTsNewIrregDoubles()
zstructTsNewRegFloats()
zstructTsNewRegDoubles()
zstructTsNewRegDoubles
Description: Creates a new time series struct with data for storing a regular-interval double data set. Note: For STORING data only.
Declaration:
zStructTimeSeries* zstructTsNewRegDoubles (const char* pathname, double *doubleValues, int numberValues, const char *startDate, const char *startTime, const char *units, const char *type);
Parameters:
const char* pathname
The pathname of the record to store. The pathname is case insensitive (i.e., "Apart" is the same as "APART"), and must have a correct E part (interval)
double *doubleValues
A double array containing the data to store.
int numberValues
The number of data values in array doubleValues to store.
const char *startDate
The date of the first data value, such as "23MAR1985". Multiple date formats are supported.
const char *startTime
The time of the first data value, such as "0700" or "07:00:00".
const char *units
The units of the data, such as "CFS". The number of characters in units is not limited, but generally should not be greater than 25.
const char *type
The type of data. Valid values include "PER-AVER", "PER-CUM", "INST-VAL", and "INST-CUM". The number of characters in units is not limited, but generally should not be greater than 25.
Returns:
zStructTimeSeries*
An address to the time series struct created ready to be stored with ztsStore(). Additional data, such as quality values or notes can be added.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks:
This is an extension of zstructTsNew(). For STORING data only (To retrieve data, use zstructTsNew and provide time window in call to ztsRetrieve.)
The arrays are used directly (not copied), so they must stay intact until the store is complete.
You must not reuse this struct. Make a new one for every dataset.
See: also (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
See Also:
zstructTsNew()
zstructTsNewTimes()
zstructTsNewRegFloats()
zstructTsNewIrregDoubles()
zstructTsNewIrregFloats()
zstructTsNewRegFloats
Description: Creates a new time series struct with data for storing a regular-interval float data set. Note: For STORING data only.
Declaration:
zStructTimeSeries* zstructTsNewRegDoubles (const char* pathname, float *floatValues, int numberValues, const char *startDate, const char *startTime, const char *units, const char *type);
Parameters:
const char* pathname
The pathname of the record to store. The pathname is case insensitive (i.e., "Apart" is the same as "APART"), and must have a correct E part (interval)
float *floatValues
A float array containing the data to store.
int numberValues
The number of data values in array floatValues to store.
const char *startDate
The date of the first data value, such as "23MAR1985". Multiple date formats are supported.
const char *startTime
The time of the first data value, such as "0700" or "07:00:00".
const char *units
The units of the data, such as "CFS". The number of characters in units is not limited, but generally should not be greater than 25.
const char *type
The type of data. Valid values include "PER-AVER", "PER-CUM", "INST-VAL", and "INST-CUM". The number of characters in units is not limited, but generally should not be greater than 25.
Returns:
zStructTimeSeries*
An address to the time series struct created ready to be stored with ztsStore(). Additional data, such as quality values or notes can be added.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks:
This is an extension of zstructTsNew(). For STORING data only (To retrieve data, use zstructTsNew and provide time window in call to ztsRetrieve.)
The arrays are used directly (not copied), so they must stay intact until the store is complete.
You must not reuse this struct. Make a new one for every dataset.
See: Chapter 4 (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
See Also:
zstructTsNew()
zstructTsNewTimes()
zstructTsNewRegDoubles()
zstructTsNewIrregDoubles()
zstructTsNewIrregFloats()
zstructTsClone
Description: Creates a new time series struct from an existing time series struct, excluding internal flags and times. This essentially allows reuse of a time series struct.
Declaration:
zStructTimeSeries* (zStructTimeSeries tss, const char pathname);
Parameters:
zStructTimeSeries *tss
An existing time series struct (with data) to clone from.
const char* pathname
A new pathname for this struct. Must be valid for the existing data set.
Returns:
zStructTimeSeries*
An address to the time series struct created ready to be stored with ztsStore(). Additional data, such as quality values or notes can be added.
Note: ALWAYS call function zstructFree(struct) when finished using.
Remarks:
This is an extension of zstructTsNew(). For STORING data only (To retrieve data, use zstructTsNew and provide time window in call to ztsRetrieve.)
The arrays are copied (and space is allocated for them, so it is important to call zstructFree when done.
See: Chapter 4 (ztsStore and ztsRetrieve) for definition of zStructTimeSeries
ztsRetrieve
Description: Primary function to retrieve time series data (all types)
Declaration:
int ztsRetrieve(long long *ifltab, zStructTimeSeries *tss, int retrieveFlag, int retrieveDoublesFlag, int boolRetrieveQualityNotes);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
zStructTimeSeries *tss
A struct that will contain all data and information read. This struct must be created by one of the following TS Struct new methods:
zStructTimeSeries* zstructTsNew(const char* pathname);
zStructTimeSeries* zstructTsNewTimes(const char* pathname, const char* startDate, const char* startTime, const char* endDate, const char* endTime);
int retrieveFlag
A flag indicating how to read and trim data.
For regular interval data:
retrieveFlag = 0: Adhere to time window provided and generate the time array.
retrieveFlag = -1: Trim data. Remove missing values at the beginning and end of data
set (not inside), and generate the time array.
retrieveFlag = -2: Adhere to time window provided but do not include time array.
retrieveFlag = -3: Trim data. Remove missing values at the beginning and end of data
set (not inside), no time array.
For irregular interval data:
retrieveFlag = 0: Adhere to time window provided.
retrieveFlag = 1: Retrieve one value previous to start of time window.
retrieveFlag = 2: Retrieve one value after end of time window.
retrieveFlag = 3: Retrieve one value before and one value after time window.
int retrieveDoublesFlag
A flag indicating if floats or doubles should be returned. This is independent of what is actually stored on disk. Values will be converted to the requested type.
0: Return data as stored. If missing, will return as doubles.
1: Return floats.
2: Return doubles.
int boolRetrieveQualityNotes
A flag indicating if you want quality and notes read also, if they exist. If you are not going to use them, it is much more efficient not to read them. (If they don't exist, they will not be returned, regardless.)
0: Do not read quality or note arrays
1: Read and return any quality or notes
Returns:
int status
STATUS_OKAY
error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
The time series struct and what is returned is defined in Chapter 4 (4.11.4).
Start and end dates and times are optional, if a correct D pathname part is supplied. If the start and end is not given, then the full data set will be returned, unless a date range is given in the pathname ("20July2002 - 13May2010")
Coordinates and other supplemental information is retrieved using the location functions
When the read is complete, the struct must be freed by a call to void zstructFree(zStructTimeSeries *zstruct). NEVER REUSE A zStructTimeSeries, always free and create a new on or use zstructTsClone
zStructTimeSeries parameters needed for this function:
Required:
const char* pathname
The pathname of the record to retrieve. The pathname must be exact, but is case insensitive (i.e., "Apart" is the same as "APART"), and have a correct E (interval) part. The full single record specified by the D (date part) will be read if the start date is not given. If the D part contains a date range ("20July2002 - 13May2010") and the start date is not given, then that time window will be used to read the data.
Optional:
const char* startDate
The starting date of the time window to read. A variety of date formats will be accepted, but the standard 9 character military style date will always work, such as "04JUL1776".
const char* startTime
The starting time for the date of the time window to read. This should be given as 24 hour clock style date, such as "1400", "08:30", or "17:23:15".
const char* endDate
The ending date of the time window to read.
const char* endTime
The ending time for the date of the time window to read.
ztsStore
Description: Primary function to store time series data (all types)
Declaration:
int ztsStore(long long *ifltab, zStructTimeSeries *tss, int storageFlag);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
zStructTimeSeries *tss
A struct that needs to contain all data and information related to this data set to store. This struct must be created by one of the following TS Struct new methods:
zStructTimeSeries* zstructTsNew(const char* pathname);
zStructTimeSeries* zstructTsNewRegFloats(const char* pathname, float *floatValues, int numberValues, const char *startDate, const char *startTime, const char *units, const char *type);
zStructTimeSeries* zstructTsNewRegDoubles(const char* pathname, double *doubleValues, int numberValues, const char *startDate, const char *startTime, const char *units, const char *type);
zStructTimeSeries* zstructTsNewIrregFloats(const char* pathname, float floatValues, int numberValues, int *itimes, int timeGranularitySeconds, const char startDateBase, const char *units, const char *type);
zStructTimeSeries* zstructTsNewIrregDoubles(const char* pathname, double doubleValues, int numberValues, int *itimes, int timeGranularitySeconds, const char startDateBase, const char *units, const char *type);
int storageFlag
A flag indicating how to handle existing data on disk.
For regular interval data:
storageFlag = 0 Always replace data.
storageFlag = 1 Only replace missing data.
storageFlag = 2 Write regardless, even if all missing data (write a missing record)
storageFlag = 3 If a record is all missing, do not write it and delete it from disk if it exists.
storageFlag = 4 Do not allow a missing input data to replace a valid data piece.
For irregular interval data, this is a flag to indicate whether to replace or merge new data or merge new data with old data. Replace for editing/changing data, merge for adding data.
storageFlag = 0 merge
storageFlag = 1 replace
Returns:
int status
STATUS_OKAY
error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
The time series struct and what can be stored is defined in Chapter 4 (4.11.4).
Coordinates and other supplemental information is stored using the location functions
When the store is complete, the struct must be freed by a call to void zstructFree(zStructTimeSeries *zstruct). NEVER REUSE A zStructTimeSeries, always free and create a new on or use zstructTsClone
ztsGetStandardInterval
Description: Get a standard DSS time interval in seconds from the E part, or the E part from the interval in seconds. Also will return a list of standard intervals.
Declaration:
int ztsGetStandardInterval(int dssVersion, int *intervalSeconds, char *Epart, size_t sizeofEpart, int *flagDirection);
Parameters:
int dssVersion
The DSS Version the results are for. Must either be 6 or 7. (Versions have different intervals)
int *intervalSeconds (input or output)
If flagDirection is 0 or 1, this is returned with the time interval, in seconds from the E part.
If flagDirection is 2, the E part is returned using this time interval.
If flagDirection is 3 or 4, this is returned with the a time interval from the list.
char *Epart (input or output)
The E part of the pathname, either determined from the interval, or used to determine the interval
size_t sizeofEpart (input)
The size of the E part, used when returning the E part from the interval.
int *flagDirection
A flag telling ztsGetStandardInterval what to do, set flagDirection to: 0 to go from char Epart to intervalSeconds AND change the E part to the standard for that interval.
1 to go from char Epart to intervalSeconds
2 to go from intervalSeconds to char Epart
3 to begin a list of valid E parts (intervals used to keep track)
4 In a list of valid E parts (returns -1 at end)
Returns:
0 for regular interval
1 for irregular interval
STATUS_NOT_OKAY for error or end of list
Remarks:
For a flagDirection set to 0 or 1, the function tries to recognize the E part to get the interval. When flagDirection is set to 0, the standard E part is returned in Epart. For example, if you pass an E part of "1MON", the E part will be returned with "1Month". To get a list of intervals, begin flagDirection with 3. ztsGetStandardInterval will return the interval in seconds and the E part for each valid interval, including irregular interval and pseudo-regular. At the end of the list, a STATUS_NOT_OKAY is returned.
See Chapter 4 for a list of standard intervals.
ztsGetInterval
Description: A convienence function for ztsGetStandardInterval. Returns the time interval for a regular time series pathname, or block size for an irregular times series pathname.
Declaration:
int ztsGetInterval(int dssVersion, const char *pathname);
Parameters:
int dssVersion
The DSS Version the results are for. Must either be 6 or 7.
const char *pathname
The pathname to get the interval from
Returns:
Time interval in seconds for DSS-7 and minutes for DSS-6, or the block size as a negative number for irregular interval. Zero (0) is returned if the pathname is not time series.
Missing Flag functions
Description: A set of small utility function to provide the missing flag and test for the missing flag.
Declarations:
float zmissingFlag(); // Returns float missing flag
float zmissingFlagFloat(); // Returns float missing flag
double zmissingFlagDouble(); // Returns double missing flag
int zisMissingFloat(float value); // Tests value for missing, returns 1 if missing, 0 if not.
int zisMissingDouble(double value); // Tests value for missing, returns 1 if missing, 0 if not.
void zsetMissingFloat(float *value); // Sets float value to missing.
void zsetMissingDouble(double *value); // Sets double value to missing
void zsetMissing(int *value, int lengthValue); // Sets value to missing, length 1 for float, 2 for double
void zsetMissingFloatArray(float *values, int numberValues); // Sets array to missing
void zsetMissingDoubleArray(double *values, int numberValues); // Sets array to missing
void zsetUndefined(int *data, int dataLength); // Sets non "values" to zero (undefined) - mainly notes and quality
Remarks:
Missing flag is defined as negative max float: A negative of the maximum float value for 32 bits; -FLT_MAX.
Note: This is the same for both floats and doubles (a missing double is the same, not the max double).
ztsGetDateRange
Description: Returns the Julian date of the first valid value in a time series dataset or record, and the last valid value. Will work with either a single record or a full dataset (multiple records).
See ztsGetDateTimeRange to get both dates and times.
Declaration:
int ztsGetDateRange(long long *ifltab, const char *pathname, int boolFullSet, int *firstValidJulian, int *lastValidJulian);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
const char* pathname
The pathname or seed pathname of the dataset.
int boolFullSet
A boolean flag set to 0 to return dates of the single record, or set to 1 to return the dates of the entire dataset (multiple records).
int *firstJulian
Returns the Julian date of the first valid value.
int *lastJulian
Returns the Julian date of the last valid value
Returns:
STATUS_OKAY (0): Successful.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.
Remarks:
Works for both regular and irregular interval data. This function is much faster than ztsGetFirstLastRecordTimes as it does not need to get the time also. (Dates are store with pathname, whereas data has to be read to get times.)
See Also:
ztsGetFirstLastRecordTimes and ztsGetDateTimeRange
ztsGetDateTimeRange
Description: Returns the Julian date of the first valid value in a time series dataset or record, and the last valid value. Will work with either a single record or a full dataset (multiple records).
Declaration:
int ztsGetDateTimeRange(long long *ifltab, const char *pathname, int boolFullSet, int *firstValidJulian, int *firstSeconds, int *lastValidJulian, int *lastSeconds);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
const char* pathname
The pathname or seed pathname of the dataset.
int boolFullSet
A boolean flag set to 0 to return dates of the single record, or set to 1 to return the dates of the entire dataset (multiple records).
int *firstJulian
Returns the Julian date of the first valid value.
int *firstSeconds
Returns the time of day in seconds (for firstJulian) of the first valid value
int *lastJulian
Returns the Julian date of the last valid value
int *lastSeconds
Returns the time of day in seconds of the last valid value
See Also:
ztsGetFirstLastRecordTimes
ztsGetDateRange
Remarks:
Works for both regular and irregular interval data.
ztsGetEPartFromInterval
Description: Gets the (standard) E part from a time interval in seconds for time series data. A convienence function that calls ztsGetStandardInterval
Declaration:
int ztsGetEPartFromInterval(int intervalSeconds, char ePart, size_t sizeofEpart);
Parameters:
int intervalSeconds (input)
The time interval, in seconds.
char *Epart (output)
Returns with the E part for that time interval.
size_t sizeofEpart (input)
The size of the E part, used when returning the E part from the interval.
Returns:
0 for regular interval
1 for irregular interval
STATUS_NOT_OKAY for error or end of list
Remarks:
See Chapter 4 for a list of standard intervals.
ztsGetFirstLastPathnames
Description: Finds the first and last pathnames in a time series data set from a seed pathname. For example, if you have a path like "/A/B/C/01JAN1988/1DAY/F/", or "/A/B/C//1DAY/F/" this will find the earliest and latest pathnames for that dataset, (For example "/A/B/C/01JAN1932/1DAY/F/" and "/A/B/C/01JAN2012/1DAY/F/")
Declaration:
int ztsGetFirstLastPathnames(long long *ifltab, const char *pathnameSeed, char *firstPath, size_t sizeofFirstPath, char *lastPath, size_t sizeofLastPath);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
const char* pathnameSeed
One pathname from the dataset. Although the pathname doesn't have to have a D (date) part, it is much faster to provide a vaild D part.
char *firstPath (output)
Returns the earliest pathname in the dataset.
size_t sizeofFirstPath
The size of firstPath (recommended MAX_PATHNAME_LENGTH)
char *lastPath (output)
Returns the latest pathname in the dataset.
size_t sizeofLastPath
The size of lastPath (recommended MAX_PATHNAME_LENGTH)
Returns:
STATUS_RECORD_FOUND (0) for valid time series pathname.
STATUS_RECORD_NOT_FOUND (-1) Cannot find any pathnames that match.
<-1: Error code. See zerrorSpecifics for more information.
Remarks:
Generally function ztsGetDateRange is intended to be used instead.
ztsGetFirstLastRecordTimes
Description: For a single time series record, get the start and ending dates for valid data, and, optionally, times.
Declaration:
int ztsGetFirstLastRecordTimes (long long *ifltab, const char *pathname, int *firstJulian, int *firstSeconds, int *lastJulian, int *lastSeconds, int boolGetSecondsAlso);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
const char* pathname
The pathname of the record to querry.
int *firstJulian
Returns the julian date of the first valid value.
int *firstSeconds
Returns the time in seconds from midnight of julian date of the first valid value, if boolGetSecondsAlso is set to 1.
int *lastJulian
Returns the julian date of the last valid value.
int *lastSeconds
Returns the time in seconds from midnight of julian date of the last valid value, if boolGetSecondsAlso is set to 1.
int boolGetSecondsAlso
A boolean flag passed in to have the seconds returned also (slower). Set to 0 (zero) not to return seconds, 1 to return seconds. Additional resources are used to return seconds.
Returns:
STATUS_RECORD_FOUND (0) for valid time series pathname.
STATUS_RECORD_NOT_FOUND (-1) Cannot find any pathnames that match.
<-1: Error code. See zerrorSpecifics for more information.
Remarks:
Works for both regular and irregular interval data.
Getting only the dates is more efficient then the dates and times (i.e., if you don't need times, set boolGetSecondsAlso = 0).
ztsGetPathTimeWindow
Description: Gets the time window for the given path. The path may have a time window for the D part, e.g., .../12JUL2002 - 13SEP2004/1DAY/... Adjusts E part if not standard.
Declaration:
int ztsGetPathTimeWindow(int version, char* pathname, size_t sizeofPathname, ztsTimeWindow *timeWindow);
Parameters:
int version
The DSS file version (6 or 7). Different versions have different intervals. Use zgetVersion(ifltab).
int blockSize
A flag that tells the size of the block. To decrement by one, set this to negative.
char* pathname
The pathname to evaluate. The E part will be changed to standard one, if not standard.
size_t sizeofPathname
The size of the pathname char array, so that the E part can be changed if not standard.
ztsTimeWindow *timeWindow
The time window struct to contain time window from path.
Returns:
1 if time series and dates obtained from path (/12JUL2002 - 13SEP2004/1Day/).
0 if time series, but no dates (/01JAN2002/1Day)
STATUS_NOT_OKAY (-1) if not time series
ztsGetSizes
Description: Gets size information about a time series record or data set (series of records) blocks.
Declaration:
int ztsGetSizes(long long *ifltab, zStructTimeSeries *tss, zStructRecordSize *recordSize);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
zStructTimeSeries *tss
A pointer to a time series struct that identifies the start and end dates/times of the blocks. To retrieve the sizes for a single record only, set this to zero (void *)0. Note: This reports sizes for blocks defined by the time window, not just the time window.
zStructRecordSize *recordSize
The time series record sizes struct that will be returned with the size of either the single record (ztsTimeWindow set to 0), or the accumulation of records using the dates/times identified in ztsTimeWindow.
Returns:
STATUS_OKAY (0): Successful.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.
Remarks:
Time Series may be either regular or irregular.
Reports sizes for blocks, not within blocks.
Set time window to null for single record and read info before use.
Assumes correct data types, pathname, etc. Does minimal error checking - it is assumed that error checking is done prior to this function being called.
ztsOffset
Description: Computes the time offset between a date/time and the "standard DSS EOP" date and time for the given interval.
Declaration:
int ztsOffset(int intervalSeconds, int julian, int seconds);
Parameters:
int intervalSeconds
The time interval, in seconds. This must be a standard interval, as described below.
int julianStart
The julian day.
int secondsStart
The time, in seconds.
Returns:
The time offset from standard time for that interval.
Remarks:
The time offset is given in seconds from the START of the interval. This is because for intervals of different length (e.g., monthly), the end of the interval is ragged and the day would be different for each month.
DSS "standard time" is considered End of Period (EOP), e.g., midnight or 2400 hours for daily data.
If on standard time, then the offset is zero. If not, then the offset is time from the standard time to the reported time (for compatibility with version 6). For example, for daily data, if the data is reported at 0100 (1 a.m.), the offset is 1 hour, or 3600 seconds. If data is reported at 2300 (11 p.m.), the offset is 23 hours or 23 * 3600 = 82800 seconds. (The offset is not the difference between the reported time to the standard time, but standard to reported.)
See Chapter 4 for a list of standard intervals.
ztsOffsetAdjustToOffset
Description: Takes a date / time and adjusts it to the date / time for the offset given.
Declaration:
int ztsOffsetAdjustToOffset(int offsetSeconds, int intervalSeconds, int *julian,
int *seconds);
Parameters:
int offsetSeconds
The time offset to adjust to, in seconds.
int intervalSeconds
The time interval, in seconds. This must be a standard interval, as provided in Chapter 4.
int julianStart (input - output)
The julian day.
int secondsStart (input - output)
The time, in seconds.
Returns:
STATUS_OKAY (0): Successful.
STATUS_NOT_OKAY: Invalid interval.
Remarks:
The time offset is given in seconds from the START of the interval. This is because for intervals of different length (e.g., monthly), the end of the interval is ragged and the day would be different for each month.
DSS "standard time" is considered End of Period (EOP), e.g., midnight or 2400 hours for daily data.
If on standard time, then the offset is zero. If not, then the offset is time from the standard time to the reported time (for compatibility with version 6). For example, for daily data, if the data is reported at 0100 (1 a.m.), the offset is 1 hour, or 3600 seconds. If data is reported at 2300 (11 p.m.), the offset is 23 hours or 23 * 3600 = 82800 seconds. (The offset is not the difference between the reported time to the standard time, but standard to reported.)
See Chapter 4 for a list of standard intervals.
ztsOffsetAdjustToStandard
Description: Takes a date / time and adjusts it to the standard date / time for that interval and returns the time offset
Declaration:
int ztsOffsetAdjustToStandard(int intervalSeconds, int *julian, int *seconds);
Parameters:
int intervalSeconds
The time interval, in seconds. This must be a standard interval, as shown below.
int julianStart (input - output)
The julian day.
int secondsStart (input - output)
The time, in seconds.
Returns:
The time offset from standard time for that interval.
Remarks:
The time offset is given in seconds from the START of the interval. This is because for intervals of different length (e.g., monthly), the end of the interval is ragged and the day would be different for each month.
DSS "standard time" is considered End of Period (EOP), e.g., midnight or 2400 hours for daily data.
If on standard time, then the offset is zero. If not, then the offset is time from the standard time to the reported time (for compatibility with version 6). For example, for daily data, if the data is reported at 0100 (1 a.m.), the offset is 1 hour, or 3600 seconds. If data is reported at 2300 (11 p.m.), the offset is 23 hours or 23 * 3600 = 82800 seconds. (The offset is not the difference between the reported time to the standard time, but standard to reported.)
See Chapter 4 for a list of standard intervals.
ztsPathCheckInterval
Description: Makes sure a time series pathname has a standard interval for the DSS version used
Declaration:
int ztsPathCheckInterval(long long *ifltab, char *pathname, size_t sizeofPathname);
Parameters:
long long *ifltab
The integer file table array passed among DSS functions. Used to get DSS version
char *pathname (input and output)
The time series pathname to check and set the interval to a vaild E part.
size_t sizeofPathname
The size of pathname.
Returns:
-1: Not time series
0: Regular interval time series
1: Irregular interval time series