The HEC-DSS library (heclib) has vertical-datum-aware for time series and paired data with elevation parameters. The updates have been implemented in such a way to be as compatible with the CWMS database vertical datum capabilities as practical.

Concepts and Terminology

Specific to Elevation Parameters

Like the CWMS database, the HEC-DSS vertical datum capabilities apply only to time series and paired data sets of elevation. For time series this means that the operations are restricted to data sets with parameter (C pathname parts) that start with "Elev" in any case. For paired data sets the independent and/or dependent parameter must start with "Elev" in any case. Offices that use the parameter "Stage" to indicate elevations will need to change to using an elevation parameter to use the vertical datum capabilities.

Recognized Vertical Datums

This list of recognized vertical datum names includes:

• UNSET   - indicates an unknown or uninitialized vertical datum
• NAVD-88 - indicates the vertical datum of the same name
• NGVD-29 - indicates the vertical datum of the same name
• OTHER   - indicates a vertical datum that is neither NAVD-88 nor NGVD-29; the name of the datum may or may not be known/specified
• LOCAL   - identical with OTHER, used for compatibility with the CWMS database.

Vertical Datum Roles

Two important vertical datum roles are native and current.

• The native vertical datum specifies the datum that elevations are stored in. Neither the CWMS database nor HEC-DSS tracks the vertical datum for individual elevations or groups of elevations. This necessitates that all elevations for a location be stored in the same vertical datum, which can be associated with the location as the native vertical datum. 
• The current vertical datum specifies the datum that a dataset of elevations in memory is currently in. Since the need often arises to work with elevations in a vertical datum other than their native datum, the elevations are converted to the desired datum to work with.

There is no importance associated with the native vertical datum. For primary data storage it is usually a matter of history as elevations continue to be stored in the same vertical datum as previous elevations. It is also not necessary that different data stores use the same native datum for the same locations. For example, extracting elevations from a CWMS database to a forecast HEC-DSS file does not necessitate the use of the same native datum in the HEC-DSS file that is used in the CWMS database for a given location.

Two other vertical datum roles are default/requested and specified.

• The default vertical datum indicates that:
  • Unless overridden, all elevations being stored should be interpreted as having the default vertical datum as their current vertical datum.
  • All elevations being retrieved should be converted, if necessary, so that their current vertical datum is the default vertical datum. In this context, the role is also called the requested vertical datum.
• The specified vertical datum overrides the default vertical datum for a specific call to store elevations.
  • There is no equivalent for retrieving elevations.

Setting the default or specified vertical datums when storing data are methods of specifying the current vertical datum of the elevations on input.

Setting the requested vertical datum when retrieving tells the library to make that datum the current vertical datum of the elevations on return.

Vertical Datum Offsets

In order to convert between vertical datums, numeric offsets between vertical datums are obviously required. Since the native (stored) data can only be in NAVD-88, NGVD-29, or OTHER, only two offsets are required:

• Native to NAVD-88
• Native to NGVD-29

The only case in which it is necessary to specify both offsets is when the native vertical datum is OTHER/LOCAL. Otherwise, one of the offsets is by definition zero, and doesn't need to be specified.

Note that the offsets are always specified as a number to add to the native datum.

Vertical Datum Information (VDI)

VDI is a set of data that identifies the native vertical datum and the offsets required to convert elevations to non-native datums. The current vertical datum is not included in the VDI, nor are the default/requested or specified vertical datums.

Uninitialized vertical datum offsets default to the value ‑3.4028234663852886e+38. This value is defined in as UNDEFINED_VERTICAL_DATUM_VALUE in the verticalDatum.h C header file for the library. It also happens to be the same value as the C constant ‑FLT_MAX, and Java constant ‑Float.MAX_VALUE. The HEC java library also uses this value for the constants  hec.lang.const.UNDEFINED_FLOAT and hec.lang.const.UNDEFINED_DOUBLE.

In the context of the CWMS database and HEC-DSS, VDI comprises the following:

• Native datum¹ (required)
• Local datum name¹ (optional, and only if native datum is OTHER/LOCAL)
• Offset unit (required, only feet and meters supported)²
• Offset from native to NAVD-88 (optional, but necessary if native is not NAVD-88)
  • Offset value (required, in elevation unit, defaults to 0.0 or UNDEFINED_VERTICAL_DATUM_VALUE)³
  • Is estimate⁴ (optional, defaults to FALSE)
• Offset from native to NGVD-29 (optional, but necessary if native is not NGVD-29)
  • Offset value (required, in elevation unit, defaults to 0.0 or UNDEFINED_VERTICAL_DATUM_VALUE)³
  • Is estimate⁴ (optional, defaults to FALSE)

VDI obtained from a CWMS database also includes the name of the location to which it applies, the elevation of the location, and the name of the office that owns that location in the database. These are not used in HEC-DSS.

¹These are only separate in CWMS. For HEC-DSS any native datum other than NAVD-88 and NGVD-29 is signifies a native datum of OTHER/LOCAL and is taken as the local datum name. The native datum and local datum name are both limited to 16 characters.

²The units accepted are the same as the CWMS units and aliases for feet and meters. Currently any of the following in any case: ft, feet, foot, m, meter, meters, metre, metres.

³The default offset from to the native vertical datum is 0.0. The default offset to any other vertical datum is UNDEFINED_VERTICAL_DATUM_VALUE.

⁴These items aren't used in vertical datum transformation.

HEC-DSS User Header/SupplementalInfo

HEC-DSS records contain an optional, variable size buffer called the user header. The purpose of the user header is to allow applications to store and retrieve application level information about the records. The user header is exposed in Java to the hec.io.DataContainer class (and so its subclasses TimeSeriesContainer and PairedDataContainer) as the supplementalInfo String field. The VDI passed between the application and the HEC-DSS file is passed in the user header, which is stored in the file in a manner dependent on the HEC-DSS version.

The user header is also used to pass the current vertical datum to and from the HEC-DSS library. Unlike the VDI, the current vertical datum is transient and not stored on disk.

• When storing data, the current vertical datum is used to select the correct vertical datum offset (if any) to convert the elevations to their native vertical datum before storing.
• When retrieving data, the current vertical datum is generated to be the either the requested vertical datum (to which the elevations are converted, if necessary, after being read from disk) or the native vertical datum (when no requested vertical datum is specified).

The format of text in the user header and DataContainer.supplementalInfo field is parameter:value;[parameter:value;...], with parameters separated from their associated values by the colon character (:) and each value appended with the semicolon character (;). The HEC-DSS version 7 zlocationStruct structure has an optional String field named supplemental, whose purpose is to store application level information for a location record. Although zlocationStruct->supplemental allows additional formats, the user header format is used for storing VDI for the location.

VDI and Current Vertical Datum Representations

VDI is retrieved from a CWMS database as XML text. As mentioned above, the XML includes the location name, office name, and the location's elevation. These items are not necessary for use with HEC-DSS, and are ignored if they are present. Unlike the flags of whether the vertical datum offsets are estimates, which although not used by the library are preserved in HEC-DSS, the location name, office name, and elevation are not preserved. These items will not be present in VDI retrieved from HEC-DSS. When VDI is put into a user header/supplementalInfo field the XML is first compressed with the gzip algorithm and the resulting binary string encoded with the base64 algorithm. This process results in representations of the VDI that uses only alphanumeric characters plus "+", "/", and "=".

Examples:

1. VDI XML =

<vertical-datum-info unit="ft">
  <native-datum>NGVD-29</native-datum>
  <offset estimate="true">
    <to-datum>NAVD-88</to-datum>
    <value>0.3855</value>
  </offset>
</vertical-datum-info>

VDI representation = 

H4sIAAAAAAAAAGWOwQrCMBBE7/2KkHuMKIUI6YIg9ObR+6IbWGgTaDf5ftMGBfG4b2Ye6wstwk+czAslz4ZjSCpHlkEH0dAp5SMKF2o53MfHzZwu3v7QrZZCWEkUrcIzCg1alky7oYaSPvtr3Tvn7Ze0QsEpExwPZ9f33rZrs9qmha7C/0/hDdt+n5y/AAAA

2. VDI XML =

<vertical-datum-info office="SWT" unit="ft">
  <native-datum>OTHER</native-datum>n
  <local-datum-name>Pensacola</local-datum-name>
  <offset estimate="true">
    <to-datum>NAVD-88</to-datum>
    <value>1.457</value>
  </offset>
  <offset estimate="false">
    <to-datum>NGVD-29</to-datum>
    <value>1.07</value>
  </offset>
</vertical-datum-info>

VDI representation =

H4sIAAAAAAAAAHWQwQrCMAyG7z5F2X1WRXFCVxAUPamo6DnMFApdC2u657ezosjmMX/+fB9EtNiQrsDkD6BQ59oqx5xSusIyu9yvGQtWU5kpyuSIMWGBdIupLI/X/fYs+E9mu5ZxX6KFGuUJrYfKGRC8t+sOotEjMfSka6CopibgyxiX5N7sw/q2yYtC8E+SCi2YgHI6ni+Wgqehg/JEHRYoMH7AsIuG2eqvYTIsiGH/jfIJAezqnlwBAAA=

When VDI is put into a user header, supplementalInfo field, or zlocationStruct‑>supplemental field it is associated with the parameter verticalDatumInfo

• verticalDatumInfo:H4sIAAAAAAAAAGWOwQrCMBBE7/2KkHuMKIUI6YIg9ObR+6IbWGgTaDf5ftMGBfG4b2Ye6wstwk+czAslz4ZjSCpHlkEH0dAp5SMKF2o53MfHzZwu3v7QrZZCWEkUrcIzCg1alky7oYaSPvtr3Tvn7Ze0QsEpExwPZ9f33rZrs9qmha7C/0/hDdt+n5y/AAAA;

When the current vertical datum is put into a user header, supplementalInfo field, or zlocationStruct‑>supplemental field it is associated with the parameter verticalDatum

• verticalDatum:NAVD-88;

Setting Default/Requested and Specified Vertical Datums

• The default/requested vertical datum is set by calling the zset library routine with a parameter of "VDTM" and a character value of "NAVD-88", "NGVD-29" or the local datum name, which may be "OTHER", "LOCAL", or an actual datum name (limited to 16 characters), or a integer value of 1 for NAVD-88, 2 for NGVD-29, or 3 for OTHER/LOCAL. If both a character value and integer value are specified, the character value takes precedence.
• The specified vertical datum, used only for storing data, can be indicated in either/both of the following ways:
  1. Specify in the user header. If the user header parameter verticalDatum is set, its associated value is used as the current vertical datum (e.g., verticalDatum:NAVD-88;) The library will remove this from the user header before storing to disk.
  2. Specify in the data unit. The elevation unit may be modified to be of the form U=unit|V=vertical_datum (e.g., change ft to U=ft|V=NAVD-88). The library will use the specified unit and use the vertical datum as the current vertical datum. After parsing, the unit is set to the unit portion (e.g., ft).

If neither of these methods are used, the default vertical datum is used as the current vertical datum. If both methods are used, the data unit specification is used.

Functional Differences Between HEC-DSS Versions 6 and 7

HEC-DSS version 7 operates in much the same way as the CWMS database with respect to vertical datums, in that the VDI belongs to a location. Time series and paired data records do not need to keep track of VDI. HEC-DSS version 6 lacks this capability and requires that the VDI be duplicated among all of the time series and paired data records that it pertains to. This means that for version 6, any record that was stored without accompanying VDI cannot use VDI on retrieval.

As described further below, the Application Programming Interface (API) differs between C and Fortran, and not between versions 6 and 7. However, all version 6 storage and retrieval is implemented in the library in Fortran and all version 7 storage and retrieval is implemented in the library in C, regardless of the language of the originating API call. As such, the version 6 functional steps listed below use the Fortran style where data values and user header are parameters to the API call, while the version 7 steps use the C style where a data structure that includes the data values and user header is a single parameter to the API call. 

Acronyms used below:

• VDI. Vertical Datum Information - the data set described above
• UH. User header
• CVD. Current vertical datum
• DVD. Default vertical datum
• RVD. Requested vertical datum
• NVD. Native vertical datum
• DS. Data structure - either a zstructTimeSeries or zstructPairedData structure
• DSUH. Data structure user header - the user header portion of the data structure

Version 6

• Storing

    +--------------------------------------------+--------------------------------------------------------+
    | Application                                | Library                                                |
    +--------------------------------------------+--------------------------------------------------------+
    | 1. Put elevation values in desired datum   |                                                        |
    | 2. Put VDI in UH                           |                                                        |
    | 3. Specify DVD/CVD using zset("VDTM")      |                                                        |
    |           and/or                           |                                                        |
    |    Specify CVD in UH                       |                                                        |
    |           and/or                           |                                                        |
    |    Specify CVD in elevation units          |                                                        |
    | 4. Call HEC-DSS library store routine with |                                                        |
    |    elevation values and UH                 |                                                        |
    |                                            | 5. Get VDI from UH (VDI remains in UH)                 |
    |                                            | 6. If no VDI in UH, get VDI from UH on disk            |
    |                                            | 6. Get CVD using zinqir("VDTM")                        |
    |                                            | 7. Override CVD from UH and remove CVD from from UH    |
    |                                            | 8. Override CVD from units and remove CVD from units   |
    |                                            | 9. Select appropriate offset using VDI and CVD         |
    |                                            |10. Subtract offset from elevation values to put in NVD |
    |                                            |11. Store NVD elevation values and UH to disk           |
    +--------------------------------------------+--------------------------------------------------------+

• Retrieving

    +--------------------------------------------+--------------------------------------------------------+
    | Application                                | Library                                                |
    +--------------------------------------------+--------------------------------------------------------+
    | 1. Specify RVD using zset("VDTM")          |                                                        |
    | 2. Call HEC-DSS library retrieval routine  |                                                        |
    |                                            | 3. Retrieve NVD elevation values and UH from disk      |
    |                                            | 4. Get VDI from UH (VDI remains in UH)                 |
    |                                            | 5. Get RVD using zinqir("VDTM")                        |
    |                                            | 6. Select appropriate offset using VDI and RVD         |
    |                                            | 7. Add offset to elevation values to put in RVD        |
    |                                            | 8. Put CVD (=RVD) in UH                                |
    |                                            | 9. Return RVD elevation values and UH to application   |
    +--------------------------------------------+--------------------------------------------------------+

Version 7

• Storing

    +-----------------------------------------------+---------------------------------------------------------+
    | Application                                   | Library                                                 |
    +-----------------------------------------------+---------------------------------------------------------+
    | 1. Put elev values in DS in desired datum     |                                                         |
    | 2. Put VDI in DSUH                            |                                                         |
    | 3. Specify DVD/CVD using zset("VDTM")         |                                                         |
    |           and/or                              |                                                         |
    |    Specify CVD in DSUH                        |                                                         |
    |           and/or                              |                                                         |
    |    Specify CVD in DS elevation units          |                                                         |
    | 4. Call HEC-DSS library store routine with DS |                                                         |
    |                                               | 5. Get VDI from location record on disk                 |
    |                                               | 6. Get VDI from DSUH                                    |
    |                                               | 7. If no DSUH VDI then                                  |
    |                                               |      use location record VDI                            |
    |                                               |    else if no location record VDI                       |
    |                                               |      use DSUH VDI                                       |
    |                                               |    else if equivalent VDIs                              |
    |                                               |      use common VDI                                     |
    |                                               |    else if zquery("VDOW") is TRUE                       |
    |                                               |      use DSUH VDI and update location record VDI        |
    |                                               |    else                                                 |
    |                                               |      abort                                              |
    |                                               | 8. Get CVD using zquery("VDTM")                         |
    |                                               | 9. Override CVD from DSUH and remove CVD from from DSUH |
    |                                               |10. Override CVD from units and remove CVD from units    |
    |                                               |11. Select appropriate offset using VDI and CVD          |
    |                                               |12. Subtract offset from DS elev values to put in NVD    |
    |                                               |13. Remove VDI from DSUH and put in location record      |
    |                                               |14. Store DS to disk                                     |
    +-----------------------------------------------+---------------------------------------------------------+

• Retrieving

    +-----------------------------------------------+---------------------------------------------------------+
    | Application                                   | Library                                                 |
    +-----------------------------------------------+---------------------------------------------------------+
    | 1. Specify RVD using zset("VTDM")             |                                                         |
    | 2. Cal HEC-DSS library retrieval routine      |                                                         |
    |                                               | 3. Retrieve NVD elevations and location record VDI from |
    |                                               |    disk in DS                                           |
    |                                               | 4. Get RVD using zquery("VDTM")                         |
    |                                               | 5. Select appropriate offset using VDI and RVD          |
    |                                               | 6. Add offset to DS elevations to put in RVD            |
    |                                               | 7. Put the VDI in the DSUH                              |
    |                                               | 8. Put the CVD (=RVD) in the DSUH                       |
    |                                               | 9. Return DS to application                             |
    +-----------------------------------------------+---------------------------------------------------------+

Using the API

The static library (heclib.a or heclib.lib) provides routines for storing and retrieving time series and paired data for both C and Fortran programming languages. Either language may be used to store and retrieve data for both versions 6 and 7 HEC-DSS files. In addition, the dynamic library (libjavaHeclib.so or javaHeclib.dll), combined with the hec.heclib.dss Java package code provides the same capability for Java. Thus the choice of API should depend only on the programming language of the application accessing HEC-DSS files.

C API

All of the instructions below use the DVD as the CVD when storing. The C API also supports specifying the CVD via the user header or data units, but these methods are not demonstrated.

C programs need to include the verticalDatum.h header file distributed with the library in order to have access to constants, data structures, and functions necessary to work with HEC-DSS VDI.
Constants Expand source
Structures Expand source
Functions Expand source

Storing Time Series

• Create and populate a zStructTimeSeries structure for storing by calling one of the following functions:
  • ts = zstructTsNewRegDoubles(pathname, values, numValues, startDate, startTime, unit, type);
  • ts = zstructTsNewRegFloats(pathname, values, numValues, startDate, startTime, unit, type);
  • ts = zstructTsNewIrregDoubles(pathname, values, numValues, times, granularity, baseDate, unit, type);
  • ts = zstructTsNewIrregFloats(pathname, values, numValues, times, granularity, baseDate, unit, type);
• Set the VDI for the zStructTimeSeries structure
  • If you don't have an existing XML instance of the VDI (as from the CWMS database), then
    • Create and populate a verticalDatumInfo structure for the location of the time series
    • Create an XML instance from the VDI by calling verticalDatumInfoToString(&xml, vdi, FALSE);
  • Set the user header by calling ts->userHeader = stringToUserHeader(xml, &ts->userHeaderNumber);
• Set the DVD to be the CVD by calling zset("VDTM", CVD, 0);
• Store the time series by calling status = ztsStore(ifltab, ts, 0);
  • The call returns a status of zero on success, meaning the values were converted to the NVD and stored.
  • If there are vertical datum conversion problems:
    • No values will be stored.
    • Informative error messages will be printed if the message level is greater than zero

Retrieving Time Series

• Create and populate a zStructTimeSeries structure for retrieving by calling ts = zstructTsNewTimes(pathname, startDate, startTime, endDate, endTime);
• Set the RVD by calling zset("VDTM", RVD, 0);
• Retrieve the time series by calling status = ztsRetrieve(ifltab, ts, retrieveFlag, retrieveDoubles, retrieveQualityAndNotes);
  • The call returns a status of zero on success, meaning the values have been converted to the RVD.
  • If there are vertical datum conversion problems:
    • No values will be retrieved.
    • Informative error messages will be printed if the message level is greater than zero

Storing Paired Data

• Create and populate a zstructPairedData structure for storing by calling one of the following functions:
  • pd = zstructPdNewDoubles(pathname, ordinates, values, numOrdinates, numCurves, indUnit, indType, depUnit, depType);
  • pd = zstructPdNewFloats(pathname, ordinates, values, numOrdinates, numCurves, indUnit, indType, depUnit, depType);
• Set the VDI for the zstructPairedData structure
  • If you don't have an existing XML instance of the VDI (as from the CWMS database), then
    • Create and populate a verticalDatumInfo structure for the location of the time series
    • Create an XML instance from the VDI by calling verticalDatumInfoToString(&xml, vdi, FALSE);
  • Set the user header by calling pd->userHeader = stringToUserHeader(xml, &pd->userHeaderNumber);
• Set the DVD to be the CVD by calling zset("VDTM", CVD, 0);
• Store the paired data by calling status = zpdStore(ifltab, pd, 0);
  • The call returns a status of zero on success, meaning the values were converted to the NVD and stored.
  • If there are vertical datum conversion problems:
    • No values will be stored.
    • Informative error messages will be printed if the message level is greater than zero

Retrieving Paired Data

• Create and populate a zstructPairedData structure for retrieving by calling pd = zstructPdNew(pathname);
• Set the RVD by calling zset("VDTM", RVD, 0);
• Retrieve the paired data by calling status = zpdRetrieve(ifltab, pd, 0);
  • The call returns a status of zero on success, meaning the values have been converted to the RVD.
  • If there are vertical datum conversion problems:
    • No values will be retrieved.
    • Informative error messages will be printed if the message level is greater than zero

Fortran API

All of the instructions below use the DVD as the CVD when storing. The Fortran API also supports specifying the CVD via the user header or data units, but these methods are not demonstrated.

Fortran programs can use the following module definition to gain access to vertical datum functionality in the library.
modVerticalDatumInfo Expand source

Storing Time Series

• Declare variables:

integer   (kind=4)      :: userHeader(100), userHeaderLen
character (len=400)     :: userHeaderStr
character (len=300)     :: errmsg, vdiStr
type(verticalDatumInfo) :: vdi

• Equivalence the user header integer and character variables

equivalence (userHeader, userHeaderStr)

• Initialize the VDI

call initVerticalDatumInfo(vdi)

• Populate the VDI fields
• Generate a compressed VDI string:

          call verticalDatumInfoToString(    &
              vdiStr,                        &
              errmsg,                        &
              vdi%nativeDatum,               &
              vdi%unit,                      &
              vdi%offsetToNgvd29,            &
              vdi%offsetToNgvd29IsEstimate,  &
              vdi%offsetToNavd88,            &
              vdi%offsetToNavd88IsEstimate,  &
              .true.)

• Generate a user header from the compressed VDI string

userHeaderStr = VERTICAL_DATUM_INFO_PARAM//':'//vdiStr//';'
userHeaderLen = byteCountToIntCount(len_trim(userHeaderStr))
if (bigEndian()) then
    do i = 1, userHeaderLen
        userHeader(i) = iswap(userHeader(i))
    end do
end if

• Set the DVD to be the CVD using call zset('VDTM', CVD, 0)

• Pass userHeader and userHeaderLen as the 11th and 12th parameters (formal parameters IHEADU and NHEADU), respectively, to one of zsrtsx, zsrtsxd, zsitsx, or zsitsxd, depending on the type of time series and type of values.
  • The calls set the last parameter (formal parameter ISTAT) to zero on success, meaning the values were converted to the NVD and stored.
  • If there are vertical datum conversion problems:
    • No values will be stored.
    • Informative error messages will be printed if the message level is greater than zero

Retrieving Time Series

• Set the RVD using call zset('VDTM', RVD, 0)
• Call one of zrrtsx, zrrtsxd, zritsx, or zritsxd depending on the type of time series and type of values.
  • The calls set the last parameter (formal parameter ISTAT) to zero on success, meaning the values have been converted to the RVD.
  • If there are vertical datum conversion problems:
    • No values will be retrieved.
    • Informative error messages will be printed if the message level is greater than zero

Storing Paired Data

• Declare variables:

integer   (kind=4)      :: userHeader(100), userHeaderLen
character (len=400)     :: userHeaderStr
character (len=300)     :: errmsg, vdiStr
type(verticalDatumInfo) :: vdi

• Equivalence the user header integer and character variables

equivalence (userHeader, userHeaderStr)

• Initialize the VDI

call initVerticalDatumInfo(vdi)

• Populate the VDI fields
• Generate a compressed VDI string:

          call verticalDatumInfoToString(    &
              vdiStr,                        &
              errmsg,                        &
              vdi%nativeDatum,               &
              vdi%unit,                      &
              vdi%offsetToNgvd29,            &
              vdi%offsetToNgvd29IsEstimate,  &
              vdi%offsetToNavd88,            &
              vdi%offsetToNavd88IsEstimate,  &
              .true.)

• Generate a user header from the compressed VDI string

userHeaderStr = VERTICAL_DATUM_INFO_PARAM//':'//vdiStr//';'
userHeaderLen = byteCountToIntCount(len_trim(userHeaderStr))
if (bigEndian()) then
    do i = 1, userHeaderLen
        userHeader(i) = iswap(userHeader(i))
    end do
end if

• Set the DVD to be the CVD using call zset('VDTM', CVD, 0)

• Pass userHeader and userHeaderLen as the 13th and 14th parameters (formal parameters IUHEAD and NUHEAD), respectively, to one of zspd or zspdd, depending on the type of values.
  • The calls set the last parameter (formal parameter ISTAT) to zero on success, meaning the values were converted to the NVD and stored.
  • If there are vertical datum conversion problems:
    • No values will be stored.
    • Informative error messages will be printed if the message level is greater than zero

Retrieving Paired Data

• Set the RVD using call zset('VDTM', RVD, 0)
• Call one of zrpd, or zrpdd depending on the type of values.
  • The calls set the last parameter (formal parameter ISTAT) to zero on success, meaning the values have been converted to the RVD.
  • If there are vertical datum conversion problems:
    • No values will be retrieved.
    • Informative error messages will be printed if the message level is greater than zero

Java API

The Java API automatically specifies the CVD in the user header, overriding any DVD, so there is no need to set the DVD via zset. The Java API also supports specifying the CVD via the data units, but these methods are not demonstrated.

Java programs have a variety of methods available to store and retrieve time series and paired data using both local and remote HEC-DSS files.

• Local HEC-DSS Files
  
  • HecDataManager. Use methods of subclasses of hec.heclib.dss.HecDataManager with data in subclasses of hec.io.DataContainer
  • DataContainer. Use methods of hec.heclib.dss.HecDss with data in subclasses of hec.io.DataContainer
  • HecMath. Use methods of hec.heclib.dss.HecDss with data in subclasses of hec.hecmath.HecMath
• Remote HEC-DSS Files¹
  • DssFileManager. Use methods of hec.server.DSSFileManager with data in subclasses of hec.io.DataContainer
  • TSRecordImpl. (Time series only) use methods of hec.model.TSRecordImpl, which may or may not hold the data as well

¹These methods can also be used for local HEC-DSS files but are generally not worth the extra effort of initializing and shutting down a local hec.server.DSSFileManager object. This is necessary, however, for code that heavily utilizes the hec.model.TSRecord interface.

Storing Time Series

• HecDataManager

// hts   : hec.heclib.dss.HecTimeSeries
// tscvd : hec.io.TimeSeriesContainerVertDatum
hts.write(tscvd);

• DataContainer

// dssFile  : hec.heclib.dss.HecDss
// tscvd    : hec.io.TimeSeriesContainerVertDatum
dssFile.put(tscvd);

• HecMath

// dssFile  : hec.heclib.dss.HecDss
// tsmvd    : hec.hecmath.TimeSeriesMathVertDatum
dssFile.write(tsmvd);

• DssFileManager

// dssFileManager : hec.server.DSSFileManager
// tscvd          : hec.io.TimeSeriesContainerVertDatum
// regStoreMethod : int
// irrStoreMethod : int
dssFileManager.writeTS(tscvd, regStoreMethod , irrStoreMethod);

• TSRecordImpl (object holds data)

// dssFileManager : hec.server.DSSFileManager
// tsr            : hec.model.TSRecordImpl
tsr.writeTSData(dssFileManager);

• TSRecordImpl (object does not hold data)

// dssFileManager : hec.server.DSSFileManager
// tsr            : hec.model.TSRecordImpl
// pathname       : String
// times          : hec.heclib.util.intArrayContainer
// values         : hec.heclib.util.doubleArrayContainer
// dataType       : String
tsr.writeTSData(dssFileManager, pathname, times, values, dataType);

Retrieving Time Series

• HecDataManager

// hts         : hec.heclib.dss.HecTimeSeries
// tscvd       : hec.io.TimeSeriesContainerVertDatum
// trimMissing : boolean
// rvd         : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
hts.read(tscvd, trimMissing);

• DataContainer

// dssFile  : hec.heclib.dss.HecDss
// tscvd    : hec.io.TimeSeriesContainerVertDatum
// rvd      : String
// pathname : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
tscvd = (hec.io.TimeSeriesContainerVertDatum)dssFile.get(pathname);

• HecMath

// dssFile  : hec.heclib.dss.HecDss
// tsmvd    : hec.hecmath.TimeSeriesMathVertDatum
// rvd      : String
// pathname : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
tsmvd = (hec.hecmath.TimeSeriesMathVertDatum)dssFile.read(pathname);

• DssFileManager

// dssFileManager : hec.server.DSSFileManager
// tscvd          : hec.io.TimeSeriesContainerVertDatum
// dssId          : hec.io.DSSIdentifier
// trimMissing    : boolean
// rvd            : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0)
tscvd = dssFileManager.readTS(dssId, trimMissing).expandVerticalDatum();

• TSRecordImpl

// dssFileManager : hec.server.DSSFileManager
// tsr            : hec.model.TSRecordImpl
// startTime      : hec.heclib.util.HecTime
// endTime        : hec.heclib.util.HecTime
// rvd            : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0)
tsr.loadTSData(dssFileManager, startTime, endTime);

Storing Paired Data

• HecDataManager

// hpd   : hec.heclib.dss.HecPariedData
// pdcvd : hec.io.PairedDataContainerVertDatum
hpd.write(pdcvd);

• DataContainer

// dssFile  : hec.heclib.dss.HecDss
// pdcvd    : hec.io.PairedDataContainerVertDatum
dssFile.put(pdcvd);

• HecMath

// dssFile  : hec.heclib.dss.HecDss
// pdmvd    : hec.hecmath.PairedDataMathVertDatum
dssFile.write(pdmvd);

• DssFileManager

// dssFileManager : hec.server.DSSFileManager
// pdcvd          : hec.io.PairedDataContainerVertDatum
dssFileManager.writePD(pdcvd);

Retrieving Paired Data

• HecDataManager

// hpd   : hec.heclib.dss.HecPariedData
// pdcvd : hec.io.PairedDataContainerVertDatum
// rvd   : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
hpd.read(pdcvd);

• DataContainer

// dssFile  : hec.heclib.dss.HecDss
// pdcvd    : hec.io.PairedDataContainerVertDatum
// rvd      : String
// pathname : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
pdcvd = (hec.io.PairedDataContainerVertDatum)dssFile.get(pathname);

• HecMath

// dssFile  : hec.heclib.dss.HecDss
// pdmvd    : hec.hecmath.PairedDataMathVertDatum
// rvd      : String
// pathname : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
pdmvd = (hec.hecmath.PairedDataMathVertDatum)dssFile.read(pathname);

• DssFileManager

// dssFileManager : hec.server.DSSFileManager
// pdcvd          : hec.io.PairedDataContainerVertDatum
// dssId          : hec.io.DSSIdentifier
// rvd            : String
hec.heclib.util.Heclib.zset("VTDM", rvd, 0);
pdcvd = dssFileManager.readPairedDataContainer(dssId).expandVerticalDatum();

Note that the following Fortran library routines are obsolete (as of DSS version 6) and/or do not include the user header in the parameter list. As such, they cannot be used to store and retieve data sets with vertical datum information.