There are several HEC-DSS utility functions available. There are utilities to check for the existence of a record, rename a record, delete a record, undelete a record, copy a record, rebuild (squeeze) a file, etc.
Most of the utility functions are relatively efficient. For example, when a record is checked (if it exists), its address information is left in memory (ifltab), so that if it is accessed again immediately, the code will go right to the file location of that record without having to access the address tables. Thus, checking and then reading a record takes the same amount of computer effort as just reading the record.

zinquire, zquerry

The function zinquire provides a means of determing information about the DSS file or records in the file. zinquire has two versions; "zinquire" which returns long values, and "zinquireChar" which returns character strings. (Function zinqir returns the same as zinquireChar, but for DSS version 6 files.) zinquire requires that the DSS file is opened and that the ifltab is passed to it.

The function zquerry will return global, non-file parameters and does not require the file to be opened.

The function calls are as follows:

long long zinquire(long long *ifltab, const char *request);

int zinquireChar(long long *ifltab, const char *request, char *creturn, size_t creturnSize, int *number);

int zquery(const char* parameter, char* charVal, size_t lenCharVal, int *integerValue);

For zquery, valid parameters are:

For zinquire, valid parameters are:

For zinquireChar and zinqir (version 6), valid parameters are:

zset

The function zset sets global (generally non-file) parameters. Its calling sequqnce is:

int zset (const char* parameter, const char* charVal, int integerValue)

Valid parameters are:

zgetRecordBasics and zgetRecordSize

zgetRecordBasics is a function to get basic information about a single record; however, not data within that record (you need to read the record to get that.) zgetRecordSize returns the same information as zgetRecordBasics along with several other parameters, and can be used for time series data sets (multiple records).

Be sure to free the structs when you are finished with them.

The calling sequences are:

zStructRecordBasics* zstructRecordBasicsNew(const char* pathname);
int zgetRecordBasics(long long *ifltab, zStructRecordBasics *recordBasics);
zStructRecordSize* zstructRecordSizeNew(const char* pathname);
int zgetRecordSize(long long *ifltab, zStructRecordSize *recordSize);

zStructRecordBasics

typedef struct {

       char *pathname;

       //  Basic record information for all data types
       int recordType;
       int version;
       int numberValues;          //  The actual number stored (excluding missing) (Daily = 1 to 365)
       int logicalNumberValues;   //  What the user expects including missing (Daily = 365)
       //  Length (4 byte) of each data array
       int values1Number;  //  (For TS, this is data values)
       int values2Number;  //  (For TS, this is quality array)
       int values3Number;  //  (For TS, this is notes array)
       //  Length (4 byte) of the 3 header arrays
       int internalHeaderNumber;
       int header2Number;
       int userHeaderNumber;
       int allocatedSize;  //  Total size of all (in ints)

       long long recLastWriteTimeMillis;
       long long recCreationTimeMillis;
       long long fileLastWriteTimeMillis;
       long long fileCreationTimeMillis;

       int tableHash;
       long long pathnameHash;

       //  Private
       char allocated[zSTRUCT_length];

} zStructRecordBasics;

zStructRecordSize

typedef struct {

       char *pathname;

       //  Record information for all data types
       int dataType;
       int version;
       int numberValues;
       int logicalNumberValues;
       //  Length (4 byte) of each data array
       int values1Number;  //  (For TS, this is data values)
       int values2Number;  //  (For TS, this is quality array)
       int values3Number;  //  (For TS, this is notes array)
       //  Length (4 byte) of the 3 header arrays
       int internalHeaderNumber;
       int header2Number;
       int userHeaderNumber;
       int allocatedSize;
       long long lastWriteTimeMillis;

       char programLastWrite[17];

       //  Time Series parameters
       int numberRecordsFound;
       int itsTimePrecisionStored;
       int tsPrecision;
       int tsTimeOffset;
       int tsProfileDepthsNumber;
       int tsBlockStartPosition;
       int tsBlockEndPosition;
       int tsValueSize;
       int tsValueElementSize;
       int tsValuesCompressionFlag;
       int tsQualityElementSize;
       int tsQualityCompressionFlag;
       int tsInotesElementSize;
       int tsInotesCompressionFlag;
       int tsCnotesLength;

       //  Paired Data parameters
       int pdNumberCurves;
       int pdNumberOrdinates;
       int ipdValueSize;
       int pdBoolIndependentIsXaxis;
       int pdLabelsLength;
       int pdPrecision;

} zStructRecordSize;

Record Level Functions

The following record level utility functions are available. The DSS file must be opened for their use. Note, if space reclaimation is on, zundelete and zundeleteAll will not be successful, if their space has already ben reused. If needed, you should call these functions as soon as possible after the delete action. A squeeze will also remove all deleted records.

int zcheck(long long ifltab, const char pathname); // Returns 1 if exits
int zdataType (long long ifltab, const char pathname); // Returns type, eg 100 for RTS
long long zgetLastWriteTimeRec (long long *ifltab, const char *pathname); // milliseconds
int zrename(long long ifltab, const char oldPathname, const char* newPathname);
int zduplicateRecord(long long *ifltab, const char *pathnameFrom, const char *pathnameTo);
int zdelete(long long ifltab, const char pathname);
int zundelete(long long ifltab, const char pathname);
int zundeleteAll(long long *ifltab);

File Level Functions

The following file level functions are available. Some of these functions are convience functions with duplicate capability in function zinquire.

zgetFileVersion does not require the DSS file to be opened, and can also determine if the DSS file exists. It will return 0 if the file does not exist, or the DSS version for the file.

int zgetFileVersion(const char *dssFilename); // 6 or 7. 0 if file does not exist
int zgetVersion(long long *ifltab);
long long zgetLastWriteTimeFile(long long *ifltab); // milliseconds
long long zgetMyLastWriteTime(long long *ifltab);
int zsqueezeNeeded(long long *ifltab); // 1 if true
int zsqueeze(const char *dssFilename); // Close file first
int zcheckFile(long long *ifltab); // Lengthy integrity check. Returns 0 if okay.
int zcopyFile(long long *ifltabFrom, long long *ifltabTo, int statusWanted); // statusWanted = 0
int zconvertVersion(const char* fileNameFrom, const char* fileNameTo); // to 7 or 6