zstructCatalogNew

Description: Creates a new catalog struct to hold a list of pathnames in a DSS file

Declaration:

zStructCatalog* zstructCatalogNew();

Parameters: None

Returns:

zStructCatalog*

An address to the catalog struct created. Call function zstructFree(struct) when finished.

zStructCatalog

typedef struct {
        // Private
        int structType; 
        // Optional input
        // For normal catalog, statusWanted = 0, and typeWanted = 0.
        int statusWanted;
        int typeWantedStart;
        int typeWantedEnd; 
        // Search according to record last write time (e.g., records written to
        // since a previous time (using file header write time)
        // Times are system times, in mills
        // lastWriteTimeSearch == 0 for ignore (default)
        // lastWriteTimeSearchFlag:
        // -2: time < lastWriteTimeSearch
        // -1: time <= lastWriteTimeSearch
        // 0: time == lastWriteTimeSearch
        // 1: time >= lastWriteTimeSearch
        // 2: time > lastWriteTimeSearch
        long long lastWriteTimeSearch;
        int lastWriteTimeSearchFlag; 
        // Output
        // An array of the pathnames in the DSS file
        char **pathnameList;
        int numberPathnames; // number of valid pathnames in list
        int boolSorted;
        int boolIsCollection; 
        // Attributes are descriptors for records, usually used for searching in a list,
        // but are not used for unique identity.
        // "::" separates key from attribute, ";;" separates attribute sets
        // For example
        //  pathnameList[43] = /Tulare/Delano/Flow/01Jan1980/1Day/Obs/"
        //  attribues[43] = "County::Kern;;State::CA;;Region::Southern"
        //  pathnameList[78] = /American/Fair Oaks Local/Flow/01Jan2200/1Hour/ReReg/"
        //  attribues[78] = "Type::Subbasin;;Order::142"
        int boolHasAttribues;
        char **attributes;

// If boolIncludeDates == 1 on input, then startDates and endDates
// will be int arrays of the Julian first and last date for each
// record (pathname)
int boolIncludeDates;
int *startDates;
int *endDates;

// Always returns these (right there)
int *recordType;
long long *pathnameHash;
long long *lastWriteTimeRecord;
long long lastWriteTimeFile;

// CRC values - Resource intensive! Only use if you really needed
unsigned int *crcValues;
int boolGetCRCvalues; // Set to 1 to have CRC values computed

} zStructCatalog;

CODE

zcatalog

Description: Primary function to retrieve a catalog (list of pathnames) in the DSS file

Declaration:

int zcatalog(long long *ifltab, const char *pathWithWild, zStructCatalog *catStruct,
int sortCollectionFlag);

Parameters:

long long ifltab
The ifltab of the DSS file.

const char *pathWithWildChars

Either null (for ignore) or a String that represents a pathname with wild characters represented by a star (*) to match any string in the pathname part. Wild characters can only be at the beginning or end of a part, not inside of a part. An example is a C part with "Flow" , which will match all pathnames that have "Flow" anywhere in the C part, such as "Flow", "Inflow", "Outflow-Reg", etc. A part such as "Flow*Reg" is not legal. A null (//) will only match a null, where only a star (*) will match all.

zStructCatalog *catStruct

A struct created by function zstructCatalogNew(). This struct will hold a list of all pathnames returned by this call. See zStructCatalog.h for definition. Be sure to call function zstructFree(struct) when finished.

int sortCollectionFlag

A flag indicating if the pathname list should be sorted (in order ABCFDE) or sorted for collections. Sorting takes considerable more resources, so only use if you need to.

0: Do not sort (fastest)
1: Normal sort
2: Collection sort (slowest)

Returns:

Number of pathnames in the file (a positive number)
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

Remarks:

For both DSS Version 6 and DSS Version 7 files.

See Also: zstructCatalogNew(), zcatalogToFile(), zcatalogFile().

zcatalogFile

Description: Writes a list of pathnames in a DSS file to an (external) file.

Declaration:

int zcatalogFile(long long *ifltab, const char *catalogFilename, int boolSorted,
const char *pathWithWildChars);

Parameters:

long long ifltab
The ifltab of the DSS file.

const char *catalogFilename

The name of the file to write the list of pathnames to. The file does not need to exist. To write to the default name (file.dsc), then set this to null.

int sortCollectionFlag

A flag indicating if the pathname list should be sorted (in order ABCFDE) or sorted for collections. Sorting takes considerable more resources, so only use if you need to.

0: Do not sort (fastest)
1: Normal sort
2: Collection sort (slowest)

const char *pathWithWildChars

Either null (for ignore) or a String that represents a pathname with wild characters represented by a star (*) to match any string in the pathname part. Wild characters can only be at the beginning or end of a part, not inside of a part. An example is a C part with "Flow" , which will match all pathnames that have "Flow" anywhere in the C part, such as "Flow", "Inflow", "Outflow-Reg", etc. A part such as "Flow*Reg" is not legal. A null (//) will only match a null, where only a star (*) will match all.

Returns:

Number of pathnames in the file (a positive number)
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

Remarks:

This is very similar to function zcatalogToFile, except here, you just provide the name of the DSS File. This function is usually used when the calling function does not have many resources.

zcatalogToFile

Description: Writes a list of pathnames in a DSS file to an (external) file controlled by the calling program

Declaration:

int zcatalogToFile(long long *ifltab, int catalogHandle, int fortranUnit,
int boolSorted);

Parameters:

long long ifltab
The ifltab of the DSS file.

int catalogHandle

A C handle (file descriptor) connected to a file opened by the calling function, usually with sopen or similar. If the pathnames are to be written to a FORTRAN unit, then this should be zero.

int fortranUnit

A Fortran unit number connected to a file opened by the calling function. If the pathnames are to be written to a C handle, then this should be zero.

int boolSorted

An int boolean flag set to "1" to indicate that the pathnames should be sorted, or "0" if they should not. Sorting can take considerable more resources and time

Returns:

Number of pathnames in the file (a positive number)
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

Remarks:

This is very similar to function zcatalogFile, except here, you are responsible for opening and closing the catalog file.

zcollectionCat

Description: Convenience function to retrieve a pathname collection set (all paths in a collection.)

Declaration:

int zcollectionCat(long long *ifltab, const char *seedPathname,
zStructCatalog *catStruct);

Parameters:

long long ifltab
The ifltab of the DSS file.

const char *seedPathname

A valid collection pathname for the collection set desired. Wild character are not supported for this call. Collections are identified by an F part of /C:000000|REST OF FPART/ Where 00000 is generally a sequence number, for example:
/YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/C:000042|OPERATION A/

zStructCatalog *catStruct

A struct created by function zstructCatalogNew(). This struct will hold a list of all the collection pathnames returned by this call. See zStructCatalog.h for definition. Be sure to call function zstructFree(struct) when finished.

Returns:

Number of pathnames in the file (a positive number)
< -1: errorCode for error errorCode may be decoded by function zerrorDecode().

Remarks:

For both DSS Version 6 and DSS Version 7 files.

zwhatChangedSetStart

Description: Sets a catalog structure to use for compare later for records that have changed.

Declaration:

int zwhatChangedSetStart(long long *ifltab, zStructCatalog *catStruct,
const char *pathWithWildChars, int boolUseCRC);

Parameters:

long long ifltab
The ifltab of the DSS file.

zStructCatalog *catStruct (optional)

A catalog struct to be made before an operation (e.g., compute) to compare with. This can be null (0), if you are only doing one comparison and want DSS to hold the catalog struct internally. If you want to do multiple comparisons, then create this struct using function zstructCatalogNew(). Be sure to call function zstructFree(struct) when finished.

const char *pathWithWildChars

Either null (for ignore) or a String that represents a pathname with wild characters represented by a star (*) to match any string in the pathname part. Wild characters can only be at the beginning or end of a part, not inside of a part. An example is a C part with "Flow" , which will match all pathnames that have "Flow" anywhere in the C part, such as "Flow", "Inflow", "Outflow-Reg", etc. A part such as "Flow*Reg" is not legal. A null (//) will only match a null, where only a star (*) will match all.

int boolUseCRC

Use cyclic redundancy check to compare data values instead of last write times for the same records that are in the file before and after. The use of CRC is resource intensive; only use when you really need to. Set to 1 to use CRC and determine if data values have changed, or set to 0 to just check last written time. This must be included when catStructBefore was filled out (catStructBefore->boolGetCRCvalues = boolUseCRC

Returns:

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

Note: DSS Version 7 only.

zwhatChanged

Description: Gets the pathnames for records that have changed since calling zwhatChangedSetStart (with a null zStructCatalog). This is usually called after running a program "compute" or similar.

Declaration:

int zwhatChanged(long long *ifltab, zStructCatalog *catStructChanged);

Parameters:

long long ifltab
The ifltab of the DSS file.

zStructCatalog *catStructChanged (output)

An empty catalog struct created by zstructCatalogNew that will contain changed pathnames, etc. Be sure to free it with zstructFree(struct) when finished.

Returns:

Number of records that have changed.

Remarks:

DSS Version 7 only.

zwhatChangedCompare

Description: Gets the pathnames for records that have changed since calling zwhatChangedSetStart (with a valid zStructCatalog). This is usually called after running a program "compute" or similar.

Declaration:

int zwhatChangedCompare(long long *ifltab, zStructCatalog *catStructBefore, zStructCatalog *catStructChanged, const char *pathWithWild, int boolUseCRC);

Parameters:

long long ifltab
The ifltab of the DSS file.

zStructCatalog *catStructBefore

The zStructCatalog from zwhatChangedSetStart to compare it with, normally called prior to a compute or similar.

zStructCatalog *catStructChanged (output)

An empty catalog struct created by zstructCatalogNew that will contain changed pathnames, etc. Be sure to free it with zstructFree(struct) when finished.

const char *pathWithWildChars

Either null (for ignore) or a String that represents a pathname with wild characters represented by a star (*) to match any string in the pathname part. Wild characters can only be at the beginning or end of a part, not inside of a part. An example is a C part with "Flow" , which will match all pathnames that have "Flow" anywhere in the C part, such as "Flow", "Inflow", "Outflow-Reg", etc. A part such as "Flow*Reg" is not legal. A null (//) will only match a null, where only a star (*) will match all.

int boolUseCRC

Use cyclic redundancy check to compare data values instead of last write times for the same records that are in the file before and after. The use of CRC is resource intensive; only use when you really need to. Set to 1 to use CRC and determine if data values have changed, or set to 0 to just check last written time. This must be included when catStructBefore was filled out (catStructBefore->boolGetCRCvalues = boolUseCRC

Returns: Number of records that have changed.

Remarks: DSS Version 7 only.

zstructCatalogNew

zStructCatalog

zcatalog

zcatalogFile

zcatalogToFile

zcollectionCat

zwhatChangedSetStart

Note: DSS Version 7 only. zwhatChanged

zwhatChangedCompare

Note: DSS Version 7 only.

zwhatChanged