HecDss
Retrieve and Store Functions
HecDss objects are used to retrieve and store data sets in a DSS file, as
well as several utility functions for DSS files. Data is retrieved and stored using
DataContainers. DataContainers are simple classes that are database
independent and are how most Hec classes exchange data. DataContainers are a base
class for several data types, such as time series data, paired data, gridded data,
etc. DataContainers and their related classes are described following the HecDss
class. If the data set you are retrieving does not exist, the DataContainer will
have the numberValues set to 0 (zero).
HecDss, and most classes accessed through scripts, use Java Exceptions for error handling. Use a try block to catch and process errors. If data cannot be stored, HecDss will throw an exception. Refer to "Handling Exceptions" for more information.
Tip: From the HEC-DSSVue main screen, select a pathname, right click and select Copy Pathnames to Clipboard. You can then paste the pathname into your script and avoid having to type it. You cannot use condensed pathnames for these functions.
The HecDss primary retrieve and storage methods are described in the first table below. Additional primary methods are shown below in the second table and secondary methods are shown in the third table below. Time Series Data Storage Methods (Regular and Irregular) are shown in the last table below.
HecDss Retrieval and Storage Methods
|
Method |
Returns |
Description |
|
get(String pathname) |
DataContainer |
Retrieves data for the single pathname and returns in a DataContainer. DataContainer will be a TimeSeriesContainer, PairedDataContainter, etc., depending on the data type |
|
get(string pathname, 0/1 getEntireDataSet) |
DataContainer |
Ignores the “D” part of time series data and retrieves data for the entire date span in the DSS file. |
|
get(DSSIdentifier dssid) |
DataContainer |
Retrieves data for the pathname and time window given in the dssid |
|
put(DataContainer dataContainer) |
None |
Store the data in dataContainer in DSS. The DataContainer must be a TimeSeriesContainer or PairedDataContainter, etc. Throws an exception if the data cannot be stored |
HecDss Additional Primary Methods
|
Method |
Returns |
Description |
|
done() |
None |
Tells HEC-DSS that you are finished using it and releases the file. Use this instead of close() |
|
getPathnameList() |
list |
Returns a list of the pathnames in the file |
|
getPathnameList() |
list |
Returns a list of the pathnames in the file |
|
getTimeSeriesExtents(String pathname, HecTime start, HecTime end) |
0/1 |
Returns in HecTime the date/time of the first and last piece of data in the entire data span. Returns if the pathname exists |
|
isOpened () |
0/1 |
Returns if the DSS file is accessible |
|
open(String dssFileName) |
HecDss |
Opens the DSS file and returns a HecDss object for further access. Creates the file if it does not exist. Throws an exception if the file cannot be created or opened |
|
open(String dssFileName, 0/1 fileMustExist)
|
HecDss |
Opens the DSS file and returns a HecDss object for further access. Throws an exception if you indicate the file must exist and it does not |
|
recordExists(String pathname) |
0/1 |
Tests to see if the single record exists. |
|
Example: Reading from DSS
from hec.script import * from hec.heclib.dss import * import java
try : try : myDss = HecDss.open(“C:/temp/sample.dss”) flow = myDss.get(“/RUSSIAN/NR UKIAH/FLOW/01MAR2006/1HOUR//”) plot = Plot.newPlot(“Russian River at Ukiah”) plot.addData(flow) plot.showPlot() except Exception, e : MessageBox.showError(‘ ‘.join(e.args), “Python Error”) except java.lang.Exception, e : MessageBox.showError(e.getMessage(), “Error”) finally : myDss.done()
|
Reading from DSS Example Results
|
Example: Reading a complete data set from DSS
from hec.script import * from hec.heclib.dss import * import java
try : try : myDss = HecDss.open(“C:/temp/sample.dss”) flow = myDss.get(“/MISSISSIPPI/ST. LOUIS/FLOW//1DAY/OBS/”, 1)
if flow.numberValues == 0 : MessageBox.showError(“No Data”, “Error”) else : plot = Plot.newPlot(“Mississippi”) plot.addData(flow) plot.showPlot()
except Exception, e : MessageBox.showError(‘ ‘.join(e.args), “Python Error”) except java.lang.Exception, e : MessageBox.showError(e.getMessage(), “Error”) finally : myDss.done()
|
Reading a Complete Data Set from DSS Example 18 Results
|
Example: Writing time series data to DSS
from hec.script import * from hec.heclib.dss import * from hec.heclib.util import * from hec.io import * import java
try : try : myDss = HecDss.open(“C:/temp/test.dss”) tsc = TimeSeriesContainer() tsc.fullName = “/BASIN/LOC/FLOW//1HOUR/OBS/” start = HecTime(“04Sep1996”, “1330”) tsc.interval = 60 flows = [0.0,2.0,1.0,4.0,3.0,6.0,5.0,8.0,7.0,9.0] times = [] for value in flows : times.append(start.value()) start.add(tsc.interval) tsc.times = times tsc.values = flows tsc.numberValues = len(flows) tsc.units = “CFS” tsc.type = “PER-AVER” myDss.put(tsc)
except Exception, e : MessageBox.showError(‘ ‘.join(e.args), “Python Error”) except java.lang.Exception, e : MessageBox.showError(e.getMessage(), “Error”) finally : myDss.done()
Output: -----DSS---ZOPEN: New File Opened, File: C:/temp/test.dss Unit: 71; DSS Version: 6-QD -----DSS---ZWRITE: /BASIN/LOC/FLOW/01SEP1996/1HOUR/OBS/ -----DSS---ZCLOSE Unit: 71, File: C:/temp/test.dss Pointer Utilization: 0.25 Number of Records: 1 File Size: 70.2 Kbytes Percent Inactive: 0.0
|
HecDss Secondary Methods
|
Method |
Returns |
Description |
|
close() |
None |
Close the DSS file. Only call this when you need the file closed (e.g. to rename it); otherwise call done() |
|
copyRecordsFrom(String toDSSFilename, list of strings pathnameList) |
integer Success = 0 Fail < 0 |
Copy records from the open DSS file to the DSS file name specified in the call. |
|
copyRecordsFrom(String toDSSFilename, Vector pathnameList) |
integer Success = 0 Fail < 0 |
Copy records from the open DSS file to the DSS file name specified in the call. |
|
copyRecordsInto(String fromDSSFilename, list of strings pathnameList) |
integer Success = 0 Fail < 0 |
Copy records from the file specified in the call into the currently open DSS file |
|
copyRecordsInto(string fromDSSFilename, Vector pathnameList) |
integer Success = 0 Fail < 0 |
Copy records from the file specified in the call into the currently open DSS file |
|
delete(list of strings pathnameList) |
integer Success = 0 Fail < 0 |
Deletes the records corresponding the list of pathnames |
|
delete(Vector pathnameList) |
integer Success = 0 Fail < 0 |
Deletes the records corresponding the list of pathnames |
|
duplicateRecords(list of strings pathnameList, list of strings newPathnameList) |
integer Success > 0 Fail < 0 |
Duplicates the records in the first list giving the names in the second list (same DSS file) |
|
duplicateRecords(Vector pathnameList, Vector newPathnameList) |
integer Success > 0 Fail < 0 |
Duplicates the records in the first list giving the names in the second list (same DSS file) |
|
getCatalogedPathnames() |
list of strings |
Returns a list of all cataloged pathnames without generating a new catalog. |
|
getCatalogedPathnames(0/1 forceNew) |
list of strings |
Returns a list of all cataloged pathnames, optionally generating a new catalog first. |
|
getCatalogedPathnames(string pattern) |
list of strings |
Returns a list of all cataloged pathnames that match the specified pattern without generating a new catalog. |
|
getCatalogedPathnames(string pattern, 0/1 forceNew) |
list of strings |
Returns a list of all cataloged pathnames that match the specified pattern, optionally generating a new catalog first. |
|
getDataManager() |
CombinedDataManager |
Gets the data manager for this DSS file |
|
getEndTime() |
string |
Returns the end time set |
|
getFileName() |
string |
Returns the name of the DSS file |
|
getStartTime() |
String |
Returns the start time set |
|
isRemote() |
0/1 |
Returns if the DSS file is being served on a remote machine (client/server mode) |
|
read(string pathname)1 |
HecMath |
Returns an HecMath object that holds the data set specified by pathname. |
|
read(string pathname, string timeWindow) 1 |
HecMath |
Returns an HecMath object that holds the data set specified by pathname with the specified time window. |
|
read (string pathname, string startTime, string endTime) 1 |
HecMath |
Returns an HecMath object that holds the data set specified by pathname with the specified time window. |
|
renameRecords (list of strings pathnameList, list of strings newPathnameList) |
integer Success > 0 Fail < 0 |
Renames the records in the first list to those in the second list. |
|
renameRecords (Vector pathnameList, Vector newPathnameList) |
integer Success > 0 Fail < 0 |
Renames the records in the first list to those in the second list. |
|
setIrregularStoreMethod (integer storeMethod) |
None |
See table following |
|
setRegularStoreMethod (integer storeMethod) |
None |
See table following |
|
setTimeWindow(string timeWindow) |
None |
The default time window for this DSSFile. |
|
setTimeWindow(string startTime, string endTime) |
None |
The default time window for this DSSFile. |
|
setTrimMissing(0/1 trim) |
None |
Sets whether TimeSeriesMath objects retrieved via calls to read(…) will have missing data trimmed from the beginning and end of the time window. 2 |
|
write(HecMath dataset) 1 |
integer |
Write the data set to the DSS file. A return value of zero indicates success. |
|
write (TimeSeriesMath timeSeriesData, string storeMethod) |
integer |
See table following |
1 Currently, the read(…) and write(…) methods can operate only on time-series data, paired data and stream rating data represented by TimeSeriesMath, PairedDataMath, and StreamRatingMath objects, respectively. Other record types, such as text data and gridded data are not yet supported by these methods.
2 By default, TimeSeriesMath objects retrieved via calls to read(…) contain data only between the first non-missing value and the last non-missing value within the specified time window. Calling setTrimMissing(Constants.FALSE) causes the data retrieved to include all data for the specified time window, including blocks of missing values at the beginning and end of the time window.
Time Series Data Storage Methods (Regular and Irregular)
|
|
Integer |
String |
Description |
|
Regular |
0 |
REPLACE_ALL |
Overwrite every value in the existing data |
|
1 |
REPLACE_MISSING_VALUES_ONLY |
Don’t overwrite non-missing values in the existing data |
|
|
2 |
REPLACE_ALL_CREATE |
REPLACE_ALL + if new data has entire records of missing data, create empty records in existing data |
|
|
3 |
REPLACE_ALL_DELETE |
REPLACE_ALL + if new data has entire records of missing data, delete records from existing data |
|
|
4 |
REPLACE_WITH_NON_MISSING |
Overwrite every value in the existing data only if replacement is non-missing |
|
|
Irregular |
0 |
MERGE |
Result for time window will be combination of existing and specified data |
|
1 |
DELETE_INSERT |
Result for time window will be specified data only |
More: