zpdRetrieve
Description: Primary function to retrieve paired data
Declaration:
int zpdRetrieve(long long *ifltab, zStructPairedData *pds, int retrieveFlag);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
zStructPairedData *pds
A struct that will contain all data and information read. This struct must be created by the following method:
zStructPairedData* zstructPdNew(const char* pathname);
int retrieveFlag
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.
1: Return floats
2: Return doubles.
Returns:
int status
STATUS_RECORD_FOUND
error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
When the retrieve is complete, the struct must be freed by a call to void zstructFree(zStructPairedData *pds)
Parameters within zStructPairedData allow you to retrieve just one or a set of curves, a set of rows, or a block of data (rows/curves). See struct description below.
The "independent variable" is the name of the parameter for the ordinate set. The "dependent variable" is the name of the parameter for the curve(s). For example, for a "Stage-Damage" function, the independent variable is "Stage" and the ordinates are the heights where damages are given. The dependent variable is "Damage", and may include several curves, such as "Total", "Residential", "Commercial", etc. Curves and columns are synonymous, as well as ordinates and rows.
Curves are stored, but the data is often displayed in columns.
The first curve is "1" (not "0".) The first ordinate is "1", not "0" (by convention).
zStructPairedData parameters used in this call:
Required:
const char* pathname
The pathname of the record to retrieve.
Optional - For retrieving part of a data set. You can retrieve part of a data set, such as a curve, a set of curves, a row or set of rows, a block or an individual value. For example, if you wanted to retrieve just an individual value, set startingOrdinate = endingOrdinate, and startingCurve = endingCurve (remember, the first row is "row 1", not "row 0") The oridnate array will correspond to the rows returned.
int startingCurve
The starting curve number (starting at 1) for the data you want. To ignore (.e.g, return an entire row), set to zero (the default)
int endingCurve
The ending curve number for the data you want. Set to "0" to ignore.
int startingOrdinate
The starting row (starting at 1) for the data you want. Set to "0" to ignore.
int endingOrdinate
The ending row for the data you want. Set to "0" to ignore.
Returned float *floatOrdinates
The float ordinate array containing the "independent variable" data, if retrieving floats (otherwise zero)
double *doubleOrdinates
The double ordinate array containing the "independent variable" data, if retrieving doubles (otherwise zero)
float *floatValues
A float array containing the "dependent variable" data. If a family of curves is stored in this record, then the second curve follows the first curve (not first row, then second row). Must match ordinate type.
double *doubleValues
A single array containing the "dependent variable" data. If a family of curves is stored in this record, then the second curve follows the first curve (not first row, then second row). Must match ordinate type. The dimensions of the values will be consistent with numberCurves; i.e., doubleValues[numberCurves][numberOrdinates]
int numberOrdinates
Number of ordinates in the data set. This can also be thought of as the number of rows.
int numberCurves
Number of curves or columns, often one. If the function was a "Stage-Damage" curve, and the curves were "Total", "Residential" and "Commerical", then this would be "3", and the residential values would follow (all of) the total values, and the commerical curve would follow the residental curve.
int numberOrdinatesInStruct
The number of ordinates in the ordinate array in this struct. If retrieving all data, this will equal numberOrdinates. If retrieving part of the record, then this will be the number retrieved. (Usually numberOrdinatesInStruct = endingOrdinate - startingOrdinate + 1)
int numberCurvesInStruct
The number of curves returned in this struct. If retrieving all data, this will equal numberCurves. If retrieving part of the record, then this will be the number retrieved. (Usually numberCurvesInStruct = endingCurve - startingCurve + 1)
int startingCurve
The starting curve number (starting at 1) of the data set.
int endingCurve
The ending curve number of the data set.
int startingOrdinate
The starting row (starting at 1) of the data set.
int endingOrdinate
The ending row of the data set.
const char *unitsIndependent
The units of the independent data (ordinates), such as "Feet".
const char *typeIndependent
Defines the ordinates type and can be "Linear", "Log", or "Probability".
const char *unitsDependent
The units of the dependent data (curves), such as "Dollars".
const char *typeDependentt
The curve type. The type can be "Linear", "Log", or "Probability".
int boolIndependentIsXaxis
A 0/1 flag indicating if the independent variable is to be plotted on the X axis.
int precision
A 2 digit int that represents the precision, or number of decimal places, for values. The precision is the number of digits past the decimal. For example, 0 gives a number like 123. 1 gives a number like 123.4, 2 1234.56, etc. The first digit is for the independent variable, the second for the dependent. For example, "21" provides a pair such as 12.34, 123.4 -1 indicates that this has not been set.
char *labels
A character string the contains a label for each curve, if used. Each label must be null terminated. The total length of labels is given in labelsLength. For example, in a "Stage-Damage" curve, this might be "Total\0Residential\0Commerical\0"
int labelsLength
The number of characters in labels. If zero, no labels were stored.
char *timeZoneName
The time zone name for this record, if set.
int *userHeader
An int array to hold any additional information for the record, usually from the user.
int userHeaderNumber
The number of int words to be stored in the userHeader