Scripting > Reading and Writing to HEC-DSS Files


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: