As with other files, one "opens" a DSS file, reads and writes to the file, then closes the file when done. The opens and closes are implicit in the HEC-DSS Java code. When you set a DSS file name, the Java 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. If the file already exists, the name is saved and the file is implicitly opened on the first access request. The programmer does not normally need to deal with opening or closing DSS files, unless there is a special circumstance, such as renaming a DSS file or you are handing off a DSS file to another process.


An implicit close is performed by the .done() function, and an explicit close by the .close() function If, after a certain amount of time (about 1 minute), a DSS file has not been accessed, the Java code will close the file to allow outside access to it without having to enter multi-user access mode. If the file is accessed again, it is automatically reopened.


If you are handing off a DSS file 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 and keep the file from entering multi-user access mode, which is slower. If you do not close the file, reading and writing will still work, just slower.


HecDataManager is considered the base class which most HEC-DSS classes inherit from (there are lower classes, but the Java programmer should not access them.) This class will be frequently mentioned in this documentation.
If your program will be accessing only one HEC-DSS file, then you can make a call to the static member "setDefaultDSSFileName":


HecDataManager public static void setDefaultDSSFileName (String dssFileName);
JAVA


This will create the HEC-DSS file, if it does not exist and the file name does not need to be given after that, unless a different HEC-DSS file is accessed.
If your program will be accessing more than one HEC-DSS file, then call the function "setDSSFileName" for each class where you will access that file. For example:


HecTimeSeries timeSeries = new HecTimeSeries();
int openStatus = timeSeries.setDSSFileName(String dssFileName);
JAVA


setDSSFileName will create the file if it does not exist. It will open the DSS file using internal handle arrays when the file is first accessed. You can explicitly open the file by calling the function "open".
When an object is finished with a HEC-DSS file, call the function "done" to indicate it is okay to release the file when appropriate. If you call done() and the file is closed, but then you call a function that accesses a file, it will automatically be reopened.


If you need to explicitly close a HEC-DSS file, you can do so with the function "close()". You can close any open files at the end of your program by calling "closeAllFiles()".
Useful functions in this category include:

HecDataManager public int setDSSFileName(String dssFileName, boolean fileMustExist);
HecDataManager public int setDSSFileName(String dssFileName, boolean fileMustExist, int dssVersion);
HecDataManager public int open(String dssFileName, boolean fileMustExist, int dssVersion);
HecDataManager public void close();
HecDataManager public static void closeAllFiles ();
HecDataManager public static boolean doesDSSFileExist (String dssFileName);
HecDataManager public int getDssFileVersion(); // Returns a 6 or 7 (fast)
HecDataManager public static int getDssFileVersion (String dssFileName); // Slow, file cannot be opened. 
JAVA


 

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.