Messaging and Logging
HEC-DSS provides informational messages for operations. The default message level includes file open statements, write statements and error messages, but not read messages. You can set the message level to have HEC-DSS write more or less message information, or turn off messaging all together (although not recommended.) Generally, users need to review the HEC-DSS messages when issues or errors come up; often something as simple as a miss-spelled pathname part.
To better accommodate users, messages are generally directed to a log file, which can be displayed when the user wants to review that file. The HEC-DSS Java code has convenience functions to create a unique log file based on the program name, and display it in a text dialog.
For HecDataManager:
public static int setLogFile(String programName) // Generates a log file with a unique name
public static hec.util.TextDialog displayLogFile(Component parent) // Don't need to close log to use
public static void closeLogFile ()
public static String getLogFileName()
public static int setMessageFile(String filename) // Same as setLogFile, but you specify the name of the file.
public static void closeMessageFile()
// Optional
public static void flushMessageFile () // You need to flush buffer to look at, if you didn't close
public static void windMessageFile () // advance to the end of a file. Used to aAppend to end ofexisting file
public static void setMessageLevel (int level) // DSS Version 6 style (works with version 7 too)
public static void zsetMessageLevel (int methodID, int levelID); // DSS Version 7
You need to set the log file before any other HEC-DSS calls, so all HEC-DSS messages will be written to that file. The setLogFile will create a unique file, which will avoid collisions if another instance of your program is running. setLogFile will create a log file with a name similar to the following:
C:\Users\me\AppData\Local\Temp\1\programName_dss.log
The function displayLogFile will return a hec.util.TextDialog that you need to setVisible. It will have a default size and location, which you can change, if desired. displayLogFile can be called at any time; you do not need to close it or wind it.
The message level IDs are as follows
Level ID | Description |
MESS_LEVEL_NONE | No messages, including errors (not guaranteed). Highly discourage |
MESS_LEVEL_CRITICAL | Critical (Error) messages only. Use discouraged. |
MESS_LEVEL_TERSE | Minimal (terse) output: zopen, zclose, critical errors. |
MESS_LEVEL_GENERAL | General Log Messages. Default. |
MESS_LEVEL_USER_DIAG | Diagnostic User Messages (e.g., input parameters) |
MESS_LEVEL_INTERNAL_DIAG_1 | Diagnostic Internal Messages level 1 (debug). Not recommended for users |
MESS_LEVEL_INTERNAL_DIAG_2 | Diagnostic Internal Messages level 2 (full debug) |
The regular method IDs are as follows
Method / Group ID | Description |
MESS_METHOD_GENERAL | All methods for both DSS version 6 and 7 |
MESS_METHOD_GLOBAL | All methods for DSS version 7 |
MESS_METHOD_GET | Low-level read I/O |
MESS_METHOD_PUT | Low-level write I/O |
MESS_METHOD_READ | Read methods, except time series |
MESS_METHOD_WRITE | Write methods, except time series |
MESS_METHOD_PERM | Operations for the file header |
MESS_METHOD_OPEN | Opening and creating a DSS file |
MESS_METHOD_CHECK | Checking for records |
MESS_METHOD_LOCKING | Locking and unlocking methods |
MESS_METHOD_TS_READ | Time series read operations |
MESS_METHOD_TS_WRITE | Time series write operations |
MESS_METHOD_ALIAS | Record alias methods |
MESS_METHOD_COPY | Record copying functions |
MESS_METHOD_UTILITY | General utility functions (rename, delete, etc.) |
MESS_METHOD_CATALOG | Cataloging |
MESS_METHOD_FILE_CHECK | Checking file integrity |
MESS_METHOD_JNI | Java Native Interface |
Refer to the section on debug messages for further information.
Example: HEC-DSS Logging
import javax.swing.UIManager;
import hec.heclib.dss.*;
import hec.util.TextDialog;
public class ExampleLog {
public static void main (String args[]) {
try {
javax.swing.UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
}
catch (Exception ignore) {}
// This will create a log file in the users temp directory
int status = HecDataManager.setLogFile("MyProgramName");
if (status != 0) return;
HecDataManager.setMessageLevel(HecDataManager.MESS_LEVEL_USER_DIAG, HecDataManager.MESS_METHOD_GENERAL);
// HecDataManager.setMessageLevel(15);
// Do some DSS stuff here
HecDataManager dataManager = new HecDataManager();
dataManager.setDSSFileName("C:/temp/Sample7.dss");
// Display the DSS log
TextDialog textDialog = HecDataManager.displayLogFile(null);
if (textDialog != null) {
textDialog.setVisible(true);
}
HecDataManager.closeLogFile();
}
}