zpdStore
Description: Primary function to store paired data
Declaration:
int zpdStore(long long *ifltab, zStructPairedData *pds, int storageFlag);
Parameters:
long long *ifltab
The file table of the opened DSS file (from zopen).
zStructPairedData *pds
A struct that will needs to contain all data and information related to this data set to store. This struct must be created by the following methods:
zStructPairedData* zstructPdNew(const char* pathname);
zStructPairedData* zstructPdNewDoubles(const char* pathname, double *doubleOrdinates, double *doubleValues, int numberOrdinates, int numberCurves, const char *unitsIndependent, const char *typeIndependent, const char *unitsDependent, const char *typeDependent);
zStructPairedData* zstructPdNewFloats(const char* pathname, float *floatOrdinates, float *floatValues, int numberOrdinates, int numberCurves, const char *unitsIndependent, const char *typeIndependent, const char *unitsDependent, const char *typeDependent);
int storageFlag
A flag indicating how to store data:
storageFlag = 0 Normal write, store data as either floats or doubles, depending on which arrays are used in struct
storageFlag = 1 Store as floats, regardless of the arrays in the struct.
storageFlag = 2 Store as doubles, regardless of the arrays in the struct.
storageFlag = 10 Pre-allocate space for storing a large family of curves. Array type determines float or double
storageFlag = 11 Pre-allocate space for storing a large family of float curves.
storageFlag = 12 Pre-allocate space for storing a large family of double curves.
Returns:
int status
STATUS_OKAY
error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
When the store is complete, the struct must be freed by a call to void zstructFree(zStructPairedData *pds)
NEVER REUSE A zStructPairedData, always free and create a new on.
Parameters within zStructPairedData allow you to store just one or a set of curves, a set of rows, or a block of data (rows/curves). See struct description below. Space MUST BE PRE-ALLOCATED when storing only parts of the record.
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 store. The "C" part is to contain the name of the "independent variable", followed by a dash, then the "dependent variable" name; e.g., "Stage-Flow".
float *floatOrdinates
The float ordinate array containing the "independent variable" data. If storing doubles, this must be zero.
double *doubleOrdinates
The double ordinate array containing the "independent variable" data. If storing floats, this must be zero.
float *floatValues
A single or double dimensioned float array containing the "dependent variable" data. If double dimensioned, then the second curve follows the first curve (not first row, then second row). Must match ordinate type.
double *doubleValues
A single or double dimensioned double array containing the "dependent variable" data. If double dimensioned, then the second curve follows the first curve (not first row, then second row). Must match ordinate type. The dimensions of the values array must be consistent with numberCurves; i.e., doubleValues[numberCurves][numberOrdinates]
int numberOrdinates
Number of values in the ordinate array. 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 "Commercial", then this would be "3", and the residential values would follow (all of) the total values, and the commercial curve would follow the residential curve.
const char *unitsIndependent
The units of the independent data (ordinates), such as "Feet". The number of characters not limited, but generally should not be greater than 25 for showing up nicely in tables.
const char *typeIndependent
Defines the ordinates type and can be "Linear", "Log", or "Probability". The number of characters is not limited, but generally should not be greater than 25.
const char *unitsDependent
The units of the dependent data (curves), such as "Dollars". The number of characters not limited.
const char *typeDependentt
The curve type. The type can be "Linear", "Log", or "Probability". The number of characters is not limited.
Optional (Set after new):
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 will be stored.
For Storing part of a data set:
If you have allocated space for a data set, or have an existing data set, you can store values, 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 replace an individual value, put the number in the values array and set startingOrdinate = endingOrdinate, and startingCurve = endingCurve (remember, the first row is "row 1", not "row 0") When setting part of a data set, the ordinate array is ignored, and the values array must correspond to to these rows and curve numbers.
Note: Curves and coordinates start at ONE (1), Not ZERO
int startingCurve
The starting curve number (starting at 1) for the data you are replacing/storing. To ignore (.e.g, replacing an entire row), set to zero (the default)
int endingCurve
The ending curve number for the data you are replacing/storing. Set to "0" to ignore.
int startingOrdinate
The starting row (starting at 1) for the data you are replacing/storing. Set to "0" to ignore.
int endingOrdinate
The ending row for the data you are replacing/storing. Set to "0" to ignore.
Also
char *timeZoneName
The time zone name for this data 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.