Accessing HEC-DSS Files (Open and Close)
As with other types of files, a HEC-DSS file is opened (using function "zopen") before use, accessed (read / write), and when finished closed with function "zclose". A file cannot be accessed until it is opened, nor accessed after it has been closed, without re-opening the file. When you open a DSS file, the code checks to see if that file exists. If it does not, the file is created and opened in DSS version 7, unless directed to create a version 6 file. When you are finished accessing a DSS file, or if you hand off to another process, be sure to close the file before you do so. This will make sure the internal tables and buffers are saved to disk.
Do not open and close a file for each access; keep a file opened until you are fully done with it or need to do a system operation such as rename. Data will not be lost if a file is inadvertently not closed; write operations write data to disk, not a buffer. (i.e., file closes are somewhat optional.)
Avoid having a file opened twice or more at the same time, as this may cause the file access switch to a "multi-user access" mode. While having a file in multi-user access mode works, file access may be slower, as data is physically written to disk (verses logically written) to insure the "other user" sees new data after each write, and address tables are correctly written. On MS Windows systems, multi-user access writes can be on the order of one-hundred times slower than normal mode.
Multi-user access mode is handled automatically by HEC-DSS. The programmer or user(s) does not need to do anything to turn it on. (Once on, it stays on until the file is closed.) Multi-user access allows multiple users, multiple processes, to read and write to the same HEC-DSS file at the same time. This is true for a network drive as well as a local drive. You can have a shared network HEC-DSS file that has several people / processes reading and writing to it at the same time. The only drawback is that file access may be slower, depending on the operating system.
IFLTAB
ifltab (the file table) is a long long array that the programmer must allocate for each HEC-DSS file. It is similar to a file handle, but is an array that carries additional file information. The program must declare this array as 250 long longs, i.e.
long long ifltab[250];
This array must be passed to all DSS functions accessing that file. You need to pass this array to your functions that will access the DSS file; you cannot create a new ifltab for the same DSS file.
Function returns
Most HEC-DSS functions return a status variable (rather than an exception) to indicate the success of the operation. In general, a status return of 0 (zero, or STATUS_OKAY) indicates a successful operation. A status of -1 (minus one, or STATUS_NOT_OKAY) usually indicates that operation could not be preformed because the record to operate on was not found, or similar; however, DSS does not consider this an "error", just an operation that could not be preformed.
A return status of less than -1 (actually a large negative number) indicates an error, and information about that error is encoded in the status. When such an error is encountered, the calling program needs to take an appropriate action (not ignore the error.) See the chapter on DSS error handleing for more information.
Example Code
Code described in this documentation is also provided in sample code files. Generally, you should compile and link sample code first, to insure that there are no compiler or linking issues. You can also follow through sample code (with a debugger) to understand how it operates.
Note: Much of the normal error checking that should be included in a program has been left out of the examples in order to make the focus more clear. It is expected that error checking would always be included in a program.
Open / Close functions
zopen
zopen will open a HEC-DSS version 6 or version 7 file. If the file does not exist, it will be created as a version 7 file. zopen must be called before accessing a DSS file.
Declaration
int zopen(long long *ifltab, const char *dssFilename);
Parameters
long long ifltab
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
int status
STATUS_OKAY for successful operation.
errorCode for error (a negative number)
Alternatives
To create a version 6 or 7 file, if it does not exist (otherwise the correct version is used.)
int zopen6(long long *ifltab, const char *dssFilename);
int zopen7(long long *ifltab, const char *dssFilename);
zclose
zclose releases memory and resources used for a specific HEC-DSS file, then closes the file. Generally, files are closed when they will no longer be accessed, often at the end of a program. There should be a matching close for each zopen. Should a file not be closed, no data should be lost – only resources not released. If a file is to be renamed or deleted, etc., it must be closed before that action.
Declaration
int zclose(long long *ifltab);
Parameters
long long ifltab
Returns
int status
STATUS_OKAY for successful operation.
errorCode for error (a negative number)
zgetFileVersion
You can determine a HEC-DSS file's version and if it exists prior to opening with the call zgetFileVersion. Only use on unopened files. Use zgetVersion for opened files.
Declaration
int zgetFileVersion(const char *dssFilename);
Parameters
const char *dssFilename
Returns
int status
0 – File does not exist
6 – Version 6 HEC-DSS file
7 – Version 7 HEC-DSS file
< 0 – Error or file exists, but is not HEC-DSS
zgetVersion
zgetVersion will return the HEC-DSS version number (6 or 7) of the file being accessed. Use zgetFileVersion for unopened files.
Declaration
int zgetVersion(long long *ifltab);
Parameters
long long *ifltab
Returns
int status
0 – File not opened or error
6 – Version 6 HEC-DSS file
7 – Version 7 HEC-DSS file
Example Open and Close
#include "heclib.h"
int ExampleOpen()
{
long long ifltab[250];
int status;
// Open the DSS file.
// If it doesn't exisit, it will be created as a version 7 file.
// See advanced for checking a file version and setting version to create.
status = zopen(ifltab, "C:/temp/Example7.dss");
if (status != STATUS_OKAY) return status;
// Do DSS stuff (reads / writes)
status = myFunction(ifltab, ...);
// When all done (near end of program), close the file
zclose(ifltab);
return 0;
}