zclose

Description: Closes a DSS file. This function must be called at end of use of the DSS file to ensure that memory is released.

Declaration:

int zclose (long long *ifltab);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen)

Returns:

STATUS_OKAY: Successful
1: File already closed
<0: Error code. See zerrorSpecifics for more information.

Note:

Opening and closing files is resource intensive. Generally, a file should be opened and closed only once during an execution, or closed if another user wants to access.

Once a file is closed, it must be repoended (with zopen) to access again.

zfileName

Description: Determines if a DSS file exists and returns the full path and file name and its permissions.

Declaration:

int zfileName (char *fullDssFilename, size_t sizeofFilename, const char *dssFileName, int *permission)

Parameters:

char *fullDssFilename (output)

A char array dimensioned to _MAX_PATH, which is returned with the full, absolute DSS file name with drive, path and extension (".dss").

size_t sizeofFilename

The size of fullDssFilename. Should be _MAX_PATH.

const char *dssFileName

The input name of the DSS file to get the full path for.

int *permission (output)

Returns the file access permission:
           0 - Normal, read and write or does not exist
           1 - Read only
           2 - No access

Returns:

0 (zer0): File does not exist
1 (one): File exists
STATUS_NOT_OKAY: Error, such as invalid file name, etc.

Notes:

Use function zgetFileVersion to determine if a file exists, instead of zfileName. zfileName is primarily for obtaining the full path for the file.

A machine / compiler specific function.

zgetFileVersion

Description: Returns the version number of an unopened DSS file.

Declaration:

int zgetFileVersion(const char *dssFilename);

Parameters:

char *dssFilename

The DSS file name to check the version of. The file does not have to exist.

Returns:

< -3: Error. System open or read error
-3: Open error (undefined)
-2: Invalid file name
-1: Not a DSS file (but file exists)
0: File does not exist
6: A DSS version 6 file
7: A DSS version 7 file

Note:

This function is for unopened files. If the file has already been opened, use zgetVersion.

zgetVersion

Description: Returns the (major) version number of an opened DSS file.

Declaration:

int zgetVersion(long long *ifltab);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen)

Returns:

0: File not opened or error
6: A DSS version 6 file
7: A DSS version 7 file

zopen

Description: Opens an existing or new (creates) DSS file.

Declaration:

int zopen (long long *ifltab, const char *dssFilename);

Parameters:

long long *ifltab

An integer array dimensioned to int*8 [250] that contains file specific information. This should be considered as a "handle" array and is to be passed to any function that accesses that file.

const char *dssFilename

The name of the HEC-DSS file to open.  The file name may be relative or absolute. The file may exist or will be created if it does not. If the file extension is not ".dss", that extension will be added to the file name.

Returns:

STATUS_OKAY (0): Successful
<-1:  Error code. Usually a large negative number containing information about the error.  See zerrorDecode to decode the value.  Error information is printed to the message file.

Notes: 

zopen must be called to access a file.  The programmer is responsible for dimensioning ifltab and passing that array to functions that access that file.  When done with the file, zclose needs to be called to close and deallocate memory used by DSS.

Opening and closing files is resource intensive.  Generally, a file should be opened and closed only once during an execution, or closed if another user wants to access.

Alternatives:

int zopen6(long long *ifltab, const char *dssFilename);
int zopen7(long long *ifltab, const char *dssFilename);

If a file does not exist, you have it created as a version 6 file with zopen6, or a version 7 file with zopen7 (default).  If the file already exists, the correct version will be used (e.g., you can call zopen6 for an existing version 7 file.)

zopenLog, zcloseLog

Description: Open a text file to save transactions and messages from DSS.

Declaration:

int zopenLog(const char *logFileName);
void zcloseLog();

Parameters:

const char *logFileName

The full name of the file to write messages to

Returns:

STATUS_OKAY: Successful
Other: System status from open.

Notes:

Always call zcloseLog before exiting the program. If you want to display the log file, you should close it first to cause messages to be flushed to it.

zstructFree

Description: Frees allocated space for standard DSS data structs (allocated by a zstructNew... function)

Declaration:

void zstructFree(void *zstruct);

Parameters:

void *zstruct
One of the standard DSS data structs

Notes:

Always call zstructFree when you are done with a struct created by a zstructNew… function. Failure to do so will create a significant memory leak.

Only frees space allocated by DSS functions; does not free any space allocated outside of it.

Do not "reuse" a struct. Free it and create a new one, if needed.