zcheck

Description: Function to check if an individual record exists.

Declaration:

int zcheck(long long ifltab, const char pathname);

Parameters:

long long *ifltab
The file table of the opened DSS file (from zopen).

const char * pathname

The pathname of the record to check. Must be the full unique pathname (not part of a dataset; e.g., correct D part for time series.)

Returns:

int status

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

zdataType

Description: Obtains the data type (time series, paired, etc.) for a record. Does not guarantee that the record exists (use zcheck for that)

Declaration:

int zdataType (long long ifltab, const char pathname);

Parameters:

long long *ifltab
The file table of the opened DSS file (from zopen).

const char * pathname

The pathname of the record to check. Must be the full unique pathname (not part of a dataset; e.g., correct D part for time series.)

Returns:

int datatype

> 0 The data type for the record. See file zdssRecordDescriptions.h for data types and descriptions.
STATUS_NOT_OKAY (-1) if the data type can not be determined < -1.
< -1: error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.

Remarks:

datatype is a positive number.
There is no guarantee that the record exists (especially for time series.)

See Also:

ztypeName - returns the name of the data type:
const char *ztypeName(int recordType, int boolAbbreviation);

ztypeName

Description: Short utility function to return the character name of a data type

Declaration:

const char *ztypeName(int recordType, int boolAbbreviation);

Parameters:

int recordType

The data type number (from zdataType), such as 110 for irregular-interval time series.

int boolAbbreviation

Set to 1 to obtain the 3-character abbreviation, or 0 for the full name

Returns:

const char *dataTypeName

The character name of the data type. For example, if the type number is 110 and if boolAbbreviation is 1, "ITS" is returned. If boolAbbreviation is 0, "Irregular-interval time series" is returned.

zcopyRecord

Description: Copy or duplicate a record

Declaration:

int zcopyRecord(long long *ifltabFrom, long long *ifltabTo, const char *pathnameFrom, const char *pathnameTo);

Parameters:

long long * ifltabFrom
The file table of the DSS file being copied from. May be either version 6 or 7.

long long * ifltabTo
The file table of the DSS file being copied to. May be either version 6 or 7.

const char *pathnameFrom
The pathname to copy. Must be a full valid pathname; a single record, not a dataset

const char *pathnameTo
The pathname to copy to. Often the same as pathnameFrom.

Returns:

int status

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

Remarks:

This function will convert datasets between different DSS versions, and can be used to duplicate records, if the file table is the same but the pathnames are different.

zduplicateRecord

Description: Duplicate a record within a DSS file.

Declaration:

int zduplicateRecord(long long *ifltab, const char *pathnameFrom, const char *pathnameTo);

Parameters:

long long ifltab

The ifltab of the DSS file. Maybe either version 6 or 7.

const char *pathnameFrom

The pathname of the record to duplicate. Must be a full valid pathname; a single record, not a dataset.

const char *pathnameTo

The new pathname for the duplicated record. Must be a full valid pathname; a single record, not a dataset. If time series, you cannot change the D or E parts.

Returns:

int status

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

zrename

Description: Renames a single DSS record

Declaration:

int zrename(long long ifltab, const char oldPathname, const char* newPathname);

Parameters:

long long ifltab

The ifltab of the DSS file. Maybe either version 6 or 7.

const char *oldPathname

The pathname of the record to be renamed. Must be a full valid pathname; a single record, not a dataset.

const char *newPathname

The pathname to rename the record to. Must be a full valid pathname; a single record, not a dataset. If time series, you cannot change the D or E parts.

Returns:

int status

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

zdelete

Description: Marks a single record as deleted in a DSS file. Record is not actually removed until file is squeezed or space is reclaimed. Version 6 and 7.

Declaration:

int zdelete(long long *ifltab, const char *pathname);

Parameters:

long long ifltab

The ifltab of the DSS file. Maybe either version 6 or 7.

const char * pathname

The pathname of the record to be deleted. Must be a full valid pathname; a single record, not a dataset.

Returns:

int status

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

Notes:

The record is not physically removed until a squeeze is preformed. A record cannot be undeleted if the file uses space reclamation, as the deleted space is moved into the reclamation array.

zundelete

Description: Marks a single record as existing in a DSS file.

Declaration:

int zundelete(long long *ifltab, const char *pathname);

Parameters:

long long ifltab

The ifltab of the DSS file.

const char * pathname

The pathname of the record to be restored. Must be a full valid pathname; a single record, not a dataset.

Returns:

int status

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

See Also:

zundeleteAll()

zundeleteAll

Description: Undeletes all records previously deleted

Declaration:

int zundeleteAll(long long *ifltab;

Parameters:

long long ifltab
The ifltab of the DSS file.

Note:

A deleted record cannot be undeleted in version 7 file that uses space reclamation. If you really need the data, you can try turning reclamation off, then undelete. If space has been reclaimed since deletion, then the data set may be bad. A file squeeze will remove all deleted records (and cannot be undeleted after that).

zstructRecordBasicsNew

Description: Creates a new struct about basic information for a record

Declaration:

zStructRecordBasics* zstructRecordBasicsNew(const char* pathname);

Parameters:

const char* pathname
The pathname of the record to query.

Returns:

zStructRecordBasics*

An address to the struct created ready to be used with zgetRecordBasics().

Remarks:

Always call function zstructFree(struct) when finished using. Never reuse a zStructRecordBasics, always free and create a new one.

zgetRecordBasics

Description: Function to get basic information about a record, such as type, version, last written, etc.

Declaration:

int zgetRecordBasics(long long *ifltab, zStructRecordBasics *recordBasics);

Parameters:

long long ifltab
The ifltab of the DSS file.

zStructRecordBasics *recordbasics

A struct will contain information for a single record. See zStructRecordBasics.h for description of zStructRecordBasics contents. This struct is created by the following method: zStructRecordBasics* zstructRecordBasicsNew(const char* pathname); When you are finished with the struct, the struct must be freed by a call to void zstructFree(zStructRecordBasics *recordBasics).

Returns:

int status

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

Remarks:

Generally, one does not need to get size information, as a read allocates the appropriate space for a record automatically. Gets basic size information for all records, and specific sizes for time series and paired data records.

See Also:

int zgetRecordSize (long long *ifltab, zStructRecordSize *recordSize);
int ztsGetSizes(long long *ifltab, zStructTimeSeries *tss, zStructRecordSize *timeSeriesRecordSizes); // Gives the combined sizes for a group of time series records spanning the time window defined in zStructTimeSeries.

zStructRecordBasics

typedef struct {

   //  Private
   int structType;

   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;

CODE

zstructRecordSizeNew

Description: Creates a new record size struct so internal functions can calculate the amount of space to allocate

Declaration:

zStructRecordSize* zstructRecordSizeNew(const char* pathname);

Parameters:

const char* pathname
The pathname of the record to query.

Returns:

zStructRecordSize*
An address to the paired struct created ready to be used with zgetRecordSize().

Note:

Always call function zstructFree(struct) when finished using. You must not reuse this struct. Make a new one for every record.

See Also:

zgetRecordSize()

zgetRecordSize

Description: Function to get size information about a single record, including type specific (e.g., Time Series)

Declaration:

int zgetRecordSize(long long *ifltab, zStructRecordSize *recordSize);

Parameters:

long long ifltab
The ifltab of the DSS file.

zStructRecordSize *recordSize

recordSize A struct will contain size and information for a single record. See zStructRecordSize.h for description of zStructRecordSize contents This struct is created by the following method: zStructRecordSize* zstructRecordSizeNew(const char* pathname); When you are finished with the struct, the struct must be freed by a call to void zstructFree(zStructRecordSize *recordSize).

Returns:

int status

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

Remarks:

Generally, one does not need to get size information, as a read allocates the appropriate space for a record automatically. Gets basic size information for all records, and specific sizes for time series and paired data records.

See Also:

int ztsGetSizes(long long *ifltab, zStructTimeSeries *tss, zStructRecordSize *timeSeriesRecordSizes); // Gives the combined sizes for a group of time series records spanning the time window defined in zStructTimeSeries.

zStructRecordSize

typedef struct {

   //  Private
   int structType;

   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;

   //  Private
   char allocated[zSTRUCT_length];

} zStructRecordSize;

CODE

zset

Description: Sets global parameters (independent of file being operated on)

Declaration:

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

Parameters:

const char* parameter:
The parameter to be set

const char* charVal:
The character value associated with this parameter, if any. If none, this should be "".

int integerValue:
The integer value associated with this parameter, or zero

Returns:

STATUS_OKAY for successful operation.
STATUS_NOT_OKAY if parameter not recognized.

See Also:

zsetFile for setting parameters for an individual file.

Remarks:

Although compatible with most of the version 6 parameters, there are a few whose purpose was to set a parameter for the next record written. This methodology is not applicable in version 7 (and not thread safe), so those parameters are not.

Valid zset parameters are:

Parameter	Alpha	int number	Action
mlvl	ignored	0-15	Set global message level, with 2 terse, 4 normal, > 6 debug levels. For compatibility only, use function zsetMessageLevel instead
munit	ignored	Fortran unit	Sets the Fortran unit number to write messages to. File must be opened prior to calling.
mhandle	ignored	C Handle	Sets the C handle number to write messages to. File must be opened prior to calling.
program	Program name	ignored	Sets the name of the program writing data to the file. For informational purposes only.
maxpath	ignored	any	Sets the expected maximum number of pathnames for the next new file to be created to correctly size tables.
collection	ignored	ignored	Cause the next new file to be created to be sized for collections. A collection set uses the same hash code for all records in the set, so that the collection can be quickly traversed.
empty	ignored	1	When the file is copied, this causes empty time series records (all missing data) to be copied also. Normally empty records are not copied

zquery

Description: Query global parameters

Declaration:

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

Parameters:

const char* parameter:
The parameter to obtain the value for.

char* charVal (output)
Returns the character value associated with this parameter.

size_t sizeofCharVal:
The size of charVal, in bytes.

int *integerValue (output)
Returns the integer value associated with this parameter.

Returns:

STATUS_OKAY for successful operation.
STATUS_NOT_OKAY if parameter not recognized.

See Also:

zinquire for parameters associated with an individual file.
For zquery, valid parameters are:

Parameter	Returns	Returns in stringContainer
mlev	The current message level (0-15)	Nothing
muni	The message (Fortran) unit	Nothing
vers	The primary software version (7)	The charater string for the software version. For example "7-AB"
date	7	The software (library) version date
erro	The last error code encountered, or 0 if no errors	The error message

zinquire

Description: Query numerical file parameters

Declaration:

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

Parameters:

long long ifltab
The ifltab of the DSS file.

const char* parameter:
The parameter to obtain the value for.

Returns:

Numerical value for the file parameter, as in the following table.

See Also:

zquery for general global parameters.

For zinquire, valid parameters are:

Parameter	Returns
handle	The handle of the DSS file
write	1, if there is write access to the file. 0, if no write access
nrecords	Total number of records (pathnames) in the file
npirmary	number of primary (non-alias) records
nalias	number of alias recors
mlevel	message level, DSS-6 equivalent
mhandle	handle of the message file, if set
munit	Fortran unit of the message file, if set.
error	The last error code, or zero if none
fversion	The 5 digit version number for the file. For example, 7-AB would be 70102
size	The size of the DSS file in Kbytes
fsize	The size of the DSS file in 64 bit words
dsize	Unused (deleted) space in 64 bit words
dead	Precentage deleted (dead) space
readmode	"1" if the file is in read-only mode, "0" if the file is in read and write mode
reclaim	The reclaim level for this file
collection	The number of collection records
expansion	The number of expansions that have occurred for this file
deleted	The numbe of deleted records in the file
renamed	The number of renamed records in the file
maxa	The length of the longest A pathname part
maxb	The length of the longest B pathname part
maxc	The length of the longest C pathname part
maxd	The length of the longest D pathname part
maxe	The length of the longest E pathname part
maxf	The length of the longest F pathname part
multiuser	The multi user access mode
nother	The number of other processes accessing the file
squeeze	1 if a squeeze is suggested, 0 if not
ftime	File last write time in miliseconds
mtime	Last write time of this process, in miliseconds
total	For a loop process, the total number of records
current	For a loop process, the number of the current record being processed
nerrors	For a loop process, the number of errors that have been encountered (such as record does not exist)

zinquireChar

Description: Query character file parameters

Declaration:

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

Parameters:

long long ifltab
The ifltab of the DSS file.

const char* parameter:
The parameter to obtain the value for.

char *creturn (output)
A character string containing the result of the query.

size_t creturnSize
The size of creturn

int *number (output)
The numerical value associated with the result of the query.

Returns:

The numerical value associated with the result of the query.

For zinquireChar, valid parameters are:

Parameter	Returns	Returns in string
erro	The last error code, or zero if none	The last error message
fver	The 5 digit version number for the file. For example, 7-AB would be 70102	The charater string for the file version. For example "7-AB"
vers	The primary software version (7)	The charater string for the software version. For example "7-AB"
name	zero	The DSS file name
read	"1" if the file is in read-only mode, "0" if the file is in read and write mode	"ON" if read-only, "OFF if read/write
rver	The version (number of writes) for the last record accessed	Nothing
type	The numeric data type for the last record accessed (e.g., 100 for regular interval time series)	The 3-character string representing the last record data type (e.g., "RTS" for regular interval time series)
prog	Nothing	The name of the program that wrote the last record accessed (if set)

zcopyFile

Description: Copies or merges one DSS file into another. The file being copied to can be version 6 or 7. If the versions are different, zcopyFile will perform the appropriate conversion. If the file is damaged, this function will recover all data that is recoverable.

Declaration:

int zcopyFile(long long *ifltabFrom, long long *ifltabTo, int handleIfDamaged,
int statusWanted);

Parameters:

long long ifltabFrom

The ifltabFrom of the DSS file being copied from. This can either be a version 6 or 7 file.

long long *ifltabTo

The ifltabFrom of the DSS file being copied to. This can either be a version 6 or 7 file.

int statusWanted

Usually 0. This is the status of the records to copy, normally all valid = 0.
However, you could copy only records with status:

REC_STATUS_VALID (0): All valid (primary and alaises)
REC_STATUS_PRIMARY (1): Primary only
REC_STATUS_ALIAS (2): Alias only
REC_STATUS_DELETED (11): Deleted only
REC_STATUS_RENAMED (12): Renamed only
REC_STATUS_ANY (100): Any, regardless if deleted, renamed, etc.

Returns:

STATUS_OKAY for successful operation.
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

Remarks:
This function uses a "brute force" approach. If the file or tables have been corrupted, this function will recover all available data, making it the method to call to restore a damaged file.

zconvertVersion

Description: Copies a DSS-7 file into a DSS-6 file, or a DSS-6 file into a DSS-7 file. DSS files must be closed.

Declaration:

int zconvertVersion(const char* fileNameFrom, const char* fileNameTo);

Parameters:

char *fileNameFrom:
The DSS file name to convert from. The file has to exist.

char *fileNameTo:

The DSS file name to convert to The file should not exist, as it will be created with the other version from fileNameFrom. If the file does exist and is the same version as fileNameFrom, an error will be returned

Returns:

STATUS_OKAY for successful operation.
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

zcheckFile

Description: Thorough checking of the integrity of all components and addresses in a DSS file. Combines all of the file checking function into one. Intent is to look for any damage within the DSS file (Note: Resource intensive; most intensive function in DSS.) Prints any errors to the DSS message log (provided that the message level is normal or above.)

Declaration:

int zcheckFile(long long *ifltab);

Parameters:

long long ifltab
The ifltab of the DSS file.

Returns:

STATUS_OKAY for no errors.
> 0 for number of errors in the file detected (some errors will generate multiple errors)
< -1 errorCode for severe error

zsqueeze

Description: Squeezes a DSS file. A squeeze rebuilds a file, which removes inactive space, rebuilds internal tables and adjust table sizes to optimize data access. Squeezing uses a brute force approach, which will recover any data sets that may have broken links (rare), usually from a crash or disk damage. This is also similar to de-fragmenting your file system. Once a squeeze has been accomplished, deleted data cannot be recovered.

Declaration:

int zsqueeze(const char *dssFilename);

Parameters:

const char *dssFilename

The name of the file to squeeze. The file must be closed and you must be able to have exclusive access - no one else can have any access to the file during a squeeze.

Returns:

STATUS_OKAY for successful operation.
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

See Also:

int zsqueeze7(long long *ifltab, int boolOnlyIfNeeded, int boolInPlace);
int zsqueezeNeeded(long long *ifltab);

zsqueeze7

Description: Squeezes a DSS version 7 file. A squeeze rebuilds a file, which removes inactive space, rebuilds internal tables and adjust table sizes to optimize data access. Squeezing uses a brute force approach, which will recover any data sets that may have broken links (rare), usually from a crash or disk damage. This is also similar to de-fragmenting your file system. Once a squeeze has been accomplished, deleted data cannot be recovered.

Declaration:

int zsqueeze7(long long *ifltab, int boolOnlyIfNeeded, int boolInPlace);

Parameters:

long long ifltab

The ifltab of the opened DSS file to squeeze. You must have exclusive access - no one else can have any access to the file during a squeeze.

int boolOnlyIfNeeded

Set to 1 to squeeze only if the file needs to be squeezed.
Set to 0 to force a squeeze.

int boolInPlace

Set to 1 to force an in-place squeeze, retaining ownership, etc. Copies back so the same file is used. This takes twice as long as a normal squeeze.
Set to 0 for a normal squeeze, where a file rename takes place (preferred).

Returns:

STATUS_OKAY for successful operation.
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

zsqueezeNeeded

Description: Determines if a DSS file needs squeezing or not.

Declaration:

int zsqueezeNeeded(long long *ifltab);

Parameters:

long long ifltab
The ifltab of the opened DSS file.

Returns:

0 if a squeeze is not needed.
1 if a squeeze should be preformed

Remarks:

Set message level to MESS_LEVEL_USER_DIAG for the reason a squeeze is needed.