zstructTransferNew

Description: Creates a new transfer struct, the struct that is used for all basic reads and writes.

Declaration:

zStructTransfer* zstructTransferNew(const char* pathname, int mode);

Parameters:

const char* pathname

        The pathname for this struct. Must be a valid pathname. A copy of the pathname is used in struct.

int mode

A flag/value assigned to all array modes. Use only 0 or 1 for this call. Generally, set mode to 0 for storing, mode to 1 for reading. If mode == 0, then no space will be allocated for the array (when needed) If mode == 1, then whatever space is needed will be allocated (when needed) If mode > 1, then this is the space allocated for the array. Will not access > mode.

Returns:

zstructTransferNew*

        An address to the transfer struct created. Always call function zstructFree(struct) when finished using.

Remarks:

This is the basic struct used for all low level reads and writes.

See: zread and zwrite for use.

zread

Description: Primary function to read a record.

Declaration:

int zread(long long *ifltab, zStructTransfer* ztransfer);

Parameters:

long long ifltab
        The ifltab of the DSS file.

zStructTransfer* zStructTransfer

A struct that will contain all the data for this record. The struct should be created by a call to zStructTransfer* zstructTransferNew(const char* pathname, int mode) and freed when complete by a call to void zstructFree(zStructTransfer *ztransfer).  Never reuse a zStructTransfer, always free and create a new one.

Returns:

STATUS_RECORD_FOUND for successful read.
STATUS_RECORD_NOT_FOUND for non-existent record.
< -1.   error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.

Remarks:

zcheck() may be called prior to zread to be sure the record exists, and to load the info block.

zStructTransfer parameters used in this call:

Input Parameters:

const char* pathname

The pathname of the record to read.  The pathname must be exact, but is case insensitive (i.e., "Apart" is the same as "APART")

Output Parameters (these will be returned):

int dataType
        The record data type associated with this record, as defined in zdssVals.h

int version
        The number of times this record has been written.

int lastWrittenTime

The system time of the last write, in seconds since Jan 01, 1970. System time means that the time zone is included, but daylight time is not.

int fileLastWrittenTime

The system time of the files last write, in seconds since Jan 01, 1970. If this record was the last write, then the lastWrittenTime will be the same.

int *internalHeader
        An array to hold the internal header of the record

int internalHeaderMode
        A flag indicating how to handle this array:

0:  Do not read this array.
1:  zread will allocate (the correct amount of) space needed for this array when it is to be read.
> 1:  The space has already been allocated (by you!) and this is the size of the array.

int internalHeaderNumber

Returns the number read (and size) into the array. If you allocated space, it will not be larger than internalHeaderMode.

int *header2

An array to hold the second header of the record.  The second header usually holds compression information for the data.

int header2Mode
        A flag indicating how to handle this array:

0:  Do not read this array.
1:  zread will allocate (the correct amount of) space needed for this array when it is to be read.
> 1:  The space has already been allocated (by you!) and this is the size of the array.

int header2Number

Returns the number read (and size) into the array. If you allocated space, it will not be larger than header2Mode.

int *header3

An array to hold the second header of the record.  The third header is reserved for any additional information needed to be stored.  It is often not used.

int *values1

The main array to hold the data to be read.  This array is usually floats or doubles, but is declared as int for an minimum element size of 4 bytes.

int values1Mode
        A flag indicating how to handle this array:

0:  Do not read this array.
1:  zread will allocate (the correct amount of) space needed for this array when it is to be read.
> 1:  The space has already been allocated (by you!) and this is the size of the array.

int values1Number

Returns the number read (and size) into the array. If you allocated space, it will not be larger than values1Mode.

int *values2
        The secondary data array.

int values2Mode
        A flag indicating how to handle this array:

0:  Do not read this array.
1:  zread will allocate (the correct amount of) space needed for this array when it is to be read.
> 1:  The space has already been allocated (by you!) and this is the size of the array.

int values2Number

Returns the number read (and size) into the array. If you allocated space, it will not be larger than values2Mode.

int *values3
        The third data array.

int values3Mode
        A flag indicating how to handle this array:

0:  Do not read this array.
1:  zread will allocate (the correct amount of) space needed for this array when it is to be read.
> 1:  The space has already been allocated (by you!) and this is the size of the array.

int values3Number

Returns the number read (and size) into the array. If you allocated space, it will not be larger than values2Mode.

int numberValues

Returns the number of values associated with this data set. For example, if the data is stored as doubles, it will often be values1Number / 2.

int logicalNumberValues

Returns the logical number of values stored.  This is the number after expansion and including all missing data values.  For example a year of daily data, this number would always be 365 or 366.

int totalAllocatedSize

The size allocted on disk for values1 and values2 (in 4 byte ints.) Note, this can be larger then the actual size needed, to allow for some expansion.

int totalExpandedSize
        The total logical size of values1 and values2 (in 4 byte ints.)

char programName[17]
        The name of the program that last wrote this record (if set).

int insufficientSpace

If arrays are pre-allocated and there is more data to be read from disk than space allocated, insufficientSpace will contain the number of ints that could not be read due to allocation limits (combined space)


zwrite

Description: Primary function to read a record.

Declaration:

int zwrite(long long ifltab, zStructTransfer ztransfer);

Parameters:

long long ifltab
        The ifltab of the DSS file.

zStructTransfer* zStructTransfer

A struct that should contain all the data to write for this record. The struct should be created by a call to zStructTransfer* zstructTransferNew(const char* pathname, int mode) and freed when complete by a call to void zstructFree(zStructTransfer *ztransfer). Never reuse a zStructTransfer, always free and create a new one.

Returns:

STATUS_OKAY for a successful write.
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.

zStructTransfer parameters used in this call:

int *internalHeader
        The internal header array to write. This usually contains information about the data, such as units.

int internalHeaderNumber
        The number of integer (int*4) words to write in the internal header array.

int *header2
        The second header array to write. This usually contains compression information.

int header2Number
        The number of integer (int*4) words to write in the second header array.

int *userHeader
        The user's header array to write. This is additional information that the user wishes to save.

int userHeaderNumber
        The number of integer (int*4) words to write in the user header array

void *values1
        The primary data array to store. This can be ints, floats, doubles, or multiples

int values1Number

The number of integer (int*4) words to write for the values1 array. If this number is negative, then the single values1 is written (filled) (-)values1Number times.

void *values2
        The secondary data array to store. This can be ints, floats, doubles, or multiples

int values2Number

The number of integer (int*4) words to write for the values2 array. If this number is negative, then the single values2 is written (filled) (-)values2Number times.

void *values3
        The third data array to store. This can be ints, floats, doubles, or multiples

int values3Number

The number of integer (int*4) words to write for the values3 array. If this number is negative, then the single values3 is written (filled) (-)values3Number times.

int numberValues

The number of values to store, in whatever size values is given in. For example, if you are storing 100 double values, then this would be 100. This number is informational only and not used for storage.

int logicalNumberValues

The number of values to report to the user, in whatever size values is given in. The logical number is the fully expanded data set and includes missing flags. The difference between numberValues and logicalNumberValues is that numberValues might not include trailing missing place holders and logicalNumberValues does. For example, if you are only storing 30 daily values, numberValues would be 30, but logicalNumberValues would be 365, the entire logical record size. This number is informational only and not used for storage.

int totalAllocatedSize (Optional)

The number of integer (int 4) words to allocate for the data area (values) for this record. If you are expecting this record to grow over time, then you can allocate additional space to accommodate that growth (without having to re-write the record at the end of the file.) This parameter is used to allocate additional space when a record is expanding. For example, if storing hourly real-time reporting data, and you are at the beginning of the month, most of the data for the month will be missing place holders, which will be removed by data compression and lesser space will be allocated on disk. This value is the amount to allocate to accommodate some of the expected expansion.
(Usually totalAllocatedSize < totalExpandedSize) If too small of a value is used, an expanded record will just be written at the end of the file (less efficient). Too large will just waste some space. Set to 0 (zero) to use default (values1Number), with no additional expansion space.

int totalExpandedSize (Optional)

The number of integer (int 4) words that the record would be if totally expanded. This parameter is used to limit the amount of space to allocate, if the record is expanding. For example, if storing daily real-time reporting data, you can set this to 366 so that no more than 366 values will be allocated by the expansion algorithm of the data compression software.

int dataType
        The record type flag (e.g., regular interval time-series), as defined in zdssVals.h 

zcompareDataSets

Description: A set of compare functions primarily used for unit testing. These functions are not accessed during normal use.

Declaration:

int zcompareDataSets(long long *ifltab, void *struct1, void *struct2, int verboseLevel, int boolExact, const char *message);

Parameters:

long long *ifltab:

The ifltab, used for messaging. If a DSS file is not opened, make this an array with 0 (zero) as the first element. The rest will not be used.

void *struct1:

The first struct (original) to compare. This has to be one of the primary structs, such as zStructTimeSeries.

void *struct2:
        The second struct to compare to.

verboseLevel:

0: None, just returns status flag
1: Normal. Prints when test fails + message passed in
2: Verbose. Prints when test passed + message passed in

int boolExact:

A boolean flag to indicate if everything should match, including last write time, program name, etc. Usually set to false (0) for normal data sets.

const char *message
        The message to print on failure

Returns:

0 (zero) if the structs match.
1 (one) if the structs are not the same.

Remarks:

Does not work for anything except standard DSS structs

Deviates (functions used by zcompareDataSets):

int zcheckStatus(long long *ifltab, int status, int verbose, const char *message);

int zcompareTimeArrays(long long *ifltab, zStructTimeSeries *struct1, zStructTimeSeries *struct2, int verboseLevel, const char *message);

int zcompareInts(long long *ifltab, int number1, int number2, int verbose, const char *message);

int zcompareStrings(long long *ifltab, const char *string1, const char *string2, int totalLength, int boolIgnoreCase, int verbose, const char *message);

int zcompareLongs(long long *ifltab, long long number1, long long number2, int verbose, const char *message);

int zcompareFloats(long long *ifltab, float number1, float number2, int verbose, const char *message);

int zcompareDoubles(long long *ifltab, double number1, double number2, int verbose, const char *message);

int zcompareIntArrays(long long *ifltab, int *array1, int *array2, int numberArray, int verbose, const char *message);

int zcompareFloatArrays(long long *ifltab, float *array1, float *array2, int numberArray, int verbose, const char *message);

int zcompareDoubleArrays(long long *ifltab, double *array1, double *array2, int numberArray, int verbose, const char *message);

int zcompareStringArrays(long long *ifltab, const char *string1, const char *string2, int totalBytes, int boolIgnoreCase, int verbose, const char *message);

void zprintFailMessage(long long *ifltab, int verboseLevel, const char *name, const char *pathname, const char *message);
int zcompare_zStructRecordSize(long long *ifltab, zStructRecordSize *struct1, zStructRecordSize *struct2, int verboseLevel, const char *message);

int zcompare_zStructTsRecordSizes(long long *ifltab, zStructRecordSize *struct1, zStructRecordSize *struct2, int verboseLevel, const char *message);

int zcompare_zStructRecordInfo(long long *ifltab, zStructRecordAddresses *struct1, zStructRecordAddresses *struct2, int verboseLevel, const char *message);

int zcompare_zStructLocation(long long *ifltab, zStructLocation *struct1, zStructLocation *struct2, int verboseLevel, const char *message);

int zcompare_zStructTimeSeries(long long *ifltab, zStructTimeSeries *struct1,
zStructTimeSeries *struct2, int verboseLevel, int boolExact, const char *message);

int zcompare_zStructArray(long long *ifltab, zStructArray *struct1, zStructArray *struct2, int verboseLevel, int boolExact, const char *message);

zgetLastWriteTimeFile

Description: Returns the last write time of the file in milliseconds since 01 Jan 1970

Declaration:

long long zgetLastWriteTimeFile(long long *ifltab);

Parameters:

long long ifltab
        The ifltab of the DSS file.

Returns:

long long timeMillis

The system time of the last write for the file, in milliseconds. No conversion of time (e.g., timezone) is done. This time is identical of the last record written (unless other writes occurred.)

See Also:

long long zgetLastWriteTimeRec()

zgetLastWriteTimeRec

Description: Returns the last write time of a record in milliseconds since 01 Jan 1970

Declaration:

long long zgetLastWriteTimeRec(long long *ifltab, const char *pathname);

Parameters:

long long ifltab
        The ifltab of the DSS file.

const char *pathname

The pathname of the individual record to get the last time for. This must be a valid pathname, not a deviate or group.

Returns:

long long timeMillis

The system time of the last write for that record, in milliseconds No conversion of time (e.g., timezone) is done. This time is also updated in the file header.

See Also:

long long zgetLastWriteTimeFile()

zgetMyLastWriteTime

Description: Returns the last write time for this process in milliseconds since 01 Jan 1970 (for use in muti-user access)

Declaration:

long long zgetMyLastWriteTime(long long *ifltab);

Parameters:

long long ifltab
        The ifltab of the DSS file.

Returns:

long long timeMillis
        The system time of the last write for this process, in milliseconds.

zlocationPath

Description: Utility functions to create a location pathname from a regular pathname

Declaration:

char* zlocationPath(const char* pathname);

Parameters:

const char* pathname

A regular pathname to obtain the A and B parts to create a location pathname. A location pathname is in the form: /A part/B part/Location Info////

Returns:

A malloc'ed location pathname. Be sure to free this when done.

See Also:

zlocationStore and zlocationRetrieve

zstructLocationNew

Description: Creates a new location struct

Declaration:

zStructLocation* zstructLocationNew(const char* pathname);

Parameters:

const char* pathname

The pathname for this location or dataset. Does not need the location C part, as this function calls zlocationPath to obtain the correct pathname.

Returns:

zStructLocation*
        An address to the location struct created. Always call function zstructFree(struct) when done.

See: zStructLocation.h for contents.

zStructLocation


typedef struct {

        //  Private
        int structType;

        char *pathname;  //  Can be any pathname from the data set.  Will be use to form location path.

        /*  ____________ All are Optional __________________________   */

        //  Location Description parameters

        /*  Location Identifiers  */
         /* Longitude, Easting or decimal degrees (negative for Western Hemisphere) */
         double xOrdinate;
         /* Latitude, Northing or decimal degrees */
        double yOrdinate;
         /* Elevation */
        double zOrdinate;

        /**
         * coordinateSystem <p>
         *  <li>0 - no coordinates set </li>
         *  <li>1 - Lat/long</li>
         *  <li>2 - State Plane, FIPS </li>
         *  <li>3 - State Plane, ADS</li>
         *  <li>4 - UTM</li>
         *  <li>5 - Local (other)</li>
         */
         int coordinateSystem;
         /* coordinateID = UTM zone #, or FIPS SPCS # ADS SPCS #  */
         int coordinateID;
         /**
         * Horizontal Units can be one of the following:
         * <li>0 - unspecified</li>
         * <li>1 - feet</li>
         * <li>2 - meters</li>
         * <li>3 - Decimal Degrees</li>
         * <li>4 - Degrees Minutes Seconds </li>
         */
         int horizontalUnits;
         /**
         * horizontalDatum  can be one of the following:
         * <li>0 - unset</li>
         * <li>1 - NAD83</li>
         * <li>2 - NAD27</li>
         * <li>3 - WGS84</li>
         * <li>4 - WGS72</li>
         * <li>5 - Local (other)</li>
         */
         int horizontalDatum;
         /**
         * Vertical Units can be one of the following:
         * <li>0 - unspecified</li>
         * <li>1 - feet</li>
         * <li>2 - meters</li>
         */
         int verticalUnits;
         /**
          * verticalDatum  can be one of the following:
          * <ul>
          * <li>0 - unset</li>
          * <li>1 - NAVD88</li>
          * <li>2 - NGVD29</li>
          * <li>3 - Local (other)</li>
          */
          int verticalDatum;

          /*
          *  Location time zone, not necessarily time zone associated with data (maybe GMT?)
          *  e.g., "PST" or "America-Los Angeles".  Never "PDT" (daylight)
          */
          char *timeZoneName;

          /*
          *       Additional information about the location (NOT data)
          *       This is a null-terminated string
          *       Separate "pieces" of information should be separated by
          *       a new-line character '\n'
          */
          char *supplemental;

          //  Private - knowing which variables were allocated by the ztsNew functions,
          //  instead of the calling program
          char *pathnameInternal;
          char allocated[zSTRUCT_length];

} zStructLocation;
CODE

zlocationRetrieve

Description: Retrieves location information for a dataset

Declaration:

int zlocationRetrieve(long long *ifltab, zStructLocation *locationStruct);

Parameters:

long long ifltab
        The ifltab of the DSS file.

zStructLocation *locationStruct
        A location struct that will contain the location information.

Returns:

STATUS_RECORD_FOUND
STATUS_RECORD_NOT_FOUND
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.

Remarks:

Location information belongs to a point that several datasets can share. A location pathname is in the form: /A part/B part/Location Info////

zStructLocation:

public double xOrdinate
        Longitude, Easting or decimal degrees (negative for Western Hemisphere)

public double yOrdinate
        Latitude, Northing or decimal degrees

public double zOrdinate
        Elevation

public int coordinateSystem
        int representing coordinate system:
                0 - no coordinates set
                1 – Latitude / Longitude
                2 - State Plane, FIPS
                3 - State Plane, ADS
                4 – UTM
                5 - Local (other)

public int coordinateID
        UTM zone #, or FIPS SPCS # ADS SPCS #

public int horizontalUnits
        int representing the horizontal units:
                0 - unset
                1 – Feet
                2 - Meters
                3 - Decimal Degrees
                4 – Degrees / Minutes / Seconds
                5 - Local (other)

public int horizontalDatum
        int representing the horizontal datum:
                0 - unset
                1 – NAD83
                2 - NAD27
                3 - WGS84
                4 – WGS72
                5 - Local (other)

public int verticalUnits
        int representing the vertical units:
                0 - unset
                1 – feet
                2 - meters

public int verticalDatum
        int representing the vertical datum:
                0 - unset
                1 – NAVD88
                2 – NGVD29
                3 - Local (other)

public String locationTimezone

The (Java) time zone name at the location (not the data). "America/New York" is preferred, but "EST" may be acceptable. Daylight savings time is a component of a time zone, not a time zone itself, so "EDT" would be rejected by Java (although you can save anything here.)

public String supplementalInfo

Any additional information that describes the location. When stored, supplementalInfo will be null terminated. You can separate segments within supplemental Info using a new line character (\n), or you can use an XML format, or you can use a "Keyword:Item;" format, where the keyword is separated from the item by a colon ((smile), and the item is terminated by a semi-colon ((wink). Keyword1:Item1;Keyword2:Item2;Keyword3:Item3; For example: Offset:1.2;Shift:3.4;Datum:5.6;Transform:LogLog;

See Also: zlocationStore

zlocationStore

Description: Store location information for a dataset

Declaration:

int zlocationStore(long long *ifltab, zStructLocation *locationStruct, int storageFlag);

Parameters:

long long ifltab
        The ifltab of the DSS file.

zStructLocation *locationStruct
        The location struct that contains the location information.

int storageFlag

0 = Do not write over an existing location record (no update)
1 = Overwrite an existing location record (update)

Returns:

STATUS_OKAY for a successful write.
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.

Remarks:

Location information belongs to a point that several datasets can share. A location pathname is in the form: /A part/B part/Location Info////

zStructLocation:

public double xOrdinate
        Longitude, Easting or decimal degrees (negative for Western Hemisphere)

public double yOrdinate
        Latitude, Northing or decimal degrees

public double zOrdinate
        Elevation

public int coordinateSystem
        int representing coordinate system:

0 - no coordinates set
1 – Latitude / Longitude
2 - State Plane, FIPS
3 - State Plane, ADS
4 – UTM
5 - Local (other)

public int coordinateID
        UTM zone #, or FIPS SPCS # ADS SPCS #

public int horizontalUnits

        int representing the horizontal units:

0 - unset
1 – Feet
2 - Meters
3 - Decimal Degrees
4 – Degrees / Minutes / Seconds
5 - Local (other)

public int horizontalDatum
        int representing the horizontal datum:

0 - unset
1 – NAD83
2 - NAD27
3 - WGS84
4 – WGS72
5 - Local (other)

public int verticalUnits
        int representing the vertical units:

0 - unset
1 – feet
2 - meters

public int verticalDatum
        int representing the vertical datum:

0 - unset
1 – NAVD88
2 – NGVD29
3 - Local (other)

public String locationTimezone

The (Java) time zone name at the location (not the data). "America/New York" is preferred, but "EST" may be acceptable. Daylight savings time is a component of a time zone, not a time zone itself, so "EDT" would be rejected by Java (although you can save anything here.)

public String supplementalInfo

Any additional information that describes the location. When stored, supplementalInfo will be null terminated. You can separate segments within supplemental Info using a new line character (\n), or you can use an XML format, or you can use a "Keyword:Item;" format, where the keyword is separated from the item by a colon (:), and the item is terminated by a semi-colon (;). Keyword1:Item1;Keyword2:Item2;Keyword3:Item3; For example: Offset:1.2;Shift:3.4;Datum:5.6;Transform:LogLog;

See Also: zlocationRetrieve

getEndian

Description: Gets the endian-ness for this OS / Chip

Declaration:

int getEndian();

Returns:

Zero (0) for Little Endian
One (1) for Big Endian

Remarks:

Endianness is how low-level bytes are ordered, and is a reminiant of the history of the development of chips.

Big endian is for Sun Solairs / RISC chips. Bytes are stored in this order: 12345678

Little endian is for Windows / Intel chips. Bytes are stored in this order: 87654321