Location information
HEC-DSS can store information about the location of a site, such as the latitude, longitude and elevation. This data is stored in a "location" record which is defined by the struct zStructLocation and is included in time-series and paired data structs. For storage, if that struct is not null and contains data, it will automatically be saved in a location record. On retrieval, the struct is automatically created and populated if a location record exists.
For other types of data, such as arrays or text, location information is not stored automatically, but can be created, retrieved and stored by the following functions:
- zStructLocation* zstructLocationNew(const char* pathname);
- int zlocationStore(long long *ifltab, zStructLocation *locationStruct, int storageFlag);
- int zlocationRetrieve(long long *ifltab, zStructLocation *locationStruct);
storageFlag:
- 0 Do not write over an existing location record (no update)
- 1 Overwrite an existing location record (update)
A location record's pathname has the same A and B parts as the dataset's pathname and a C part of "Location info". The D, E and F parts are null. When either zlocationRetrieve or zlocationStore is called, the dataset's pathname can be used, as those functions will modify it to match the location conventions. A location pathname appears as follows
/Part A/Part B/Location Info////
Where Part A and Part B will be replaced with the parts from the dataset pathname. You can also call function x to create a location pathname from a dataset pathname:
- char* zlocationPath(const char* pathname);
zStructLocation Definition
typedef struct {
// Private
int structType;
char *pathname; // Can be any pathname from the data set. Will be use to form location path.
/* ____________ All are Optional __________________________ */
// Location Description parameters
/* Location Identifiers */
/* Longitude, Easting or decimal degrees (negative for Western Hemisphere) */
double xOrdinate;
/* Latitude, Northing or decimal degrees */
double yOrdinate;
/* Elevation */
double zOrdinate;
/**
* coordinateSystem <p>
* <li>0 - no coordinates set </li>
* <li>1 - Lat/long</li>
* <li>2 - State Plane, FIPS </li>
* <li>3 - State Plane, ADS</li>
* <li>4 - UTM</li>
* <li>5 - Local (other)</li>
*/
int coordinateSystem;
/* coordinateID = UTM zone #, or FIPS SPCS # ADS SPCS # */
int coordinateID;
/**
* Horizontal Units can be one of the following:
* <li>0 - unspecified</li>
* <li>1 - feet</li>
* <li>2 - meters</li>
* <li>3 - Decimal Degrees</li>
* <li>4 - Degrees Minutes Seconds </li>
*/
int horizontalUnits;
/**
* horizontalDatum can be one of the following:
* <li>0 - unset</li>
* <li>1 - NAD83</li>
* <li>2 - NAD27</li>
* <li>3 - WGS84</li>
* <li>4 - WGS72</li>
* <li>5 - Local (other)</li>
*/
int horizontalDatum;
/**
* Vertical Units can be one of the following:
* <li>0 - unspecified</li>
* <li>1 - feet</li>
* <li>2 - meters</li>
*/
int verticalUnits;
/**
* verticalDatum can be one of the following:
* <ul>
* <li>0 - unset</li>
* <li>1 - NAVD88</li>
* <li>2 - NGVD29</li>
* <li>3 - Local (other)</li>
*/
int verticalDatum;
/*
* Location time zone, not necessarily time zone associated with data (maybe GMT?)
* e.g., "PST" or "America-Los Angeles". Never "PDT" (daylight)
*/
char *timeZoneName;
/*
* Additional information about the location (NOT data)
* This is a null-terminated string
* Separate "pieces" of information should be separated by
* a new-line character '\n'
*/
char *supplemental;
// Private - knowing which variables were allocated by the ztsNew functions,
// instead of the calling program
char *pathnameInternal;
char allocated[zSTRUCT_length];
} zStructLocation;
The zStructLocation variables are as follows:
double xOrdinate - Longitude, Easting or decimal degrees (negative for Western Hemisphere)
double yOrdinate - Latitude, Northing or decimal degrees
double zOrdinate – Elevation
int coordinateSystem – int representing coordinate system:
0 - no coordinates set
1 – Latitude / Longitude
2 - State Plane, FIPS
3 - State Plane, ADS
4 – UTM
5 - Local (other)
int coordinateID - UTM zone #, or FIPS SPCS # ADS SPCS #
int horizontalUnits – int representing the horizontal units:
0 - unset
1 – Feet
2 - Meters
3 - Decimal Degrees
4 – Degrees / Minutes / Seconds
5 - Local (other)
int horizontalDatum – int representing the horizontal datum:
0 - unset
1 – NAD83
2 - NAD27
3 - WGS84
4 – WGS72
5 - Local (other)
int verticalUnits – int representing the vertical units:
0 - unset
1 – feet
2 - meters
int verticalDatum – int representing the vertical datum:
0 - unset
1 – NAVD88
2 – NGVD29
3 - Local (other)
char* locationTimezone – The (Java) time zone name at the location (not the data). “America/New York” is preferred, but “EST” may be acceptable. Daylight savings time is a component of a time zone, not a time zone itself, so “EDT” would be rejected by Java (although you can save anything here.)
char* supplementalInfo – Any additional information that describes the location. When stored, supplementalInfo will be null terminated. You can separate segments within supplementalInfo using a new line character (\n), or you can use an XML format, or you can use a "Keyword:Item;" format, where the keyword is separated from the item by a colon (:), and the item is terminated by a semi-colon (;). Keyword1:Item1;Keyword2:Item2;Keyword3:Item3;
For example:
Offset:1.2;Shift:3.4;Datum:5.6;Transform:LogLog;
Example: Saving location information
#include "heclib.h"
// A simple sample of code to demonstrate Location data
// Use for the rating table "/Russian/Healdsburg/Stage-Flow//NWIS RATING//"
// Showing the location information
// USGS 11464000 RUSSIAN R NR HEALDSBURG CA
// Latitude 38°36'48", Longitude 122°50'07" NAD27
// Sonoma County, California, Hydrologic Unit 18010110
// Drainage area: 793 square miles
// Datum of gage: 77.01 feet above NGVD29.
int ExampleLocation()
{
long long ifltab[250];
zStructLocation *zsl;
char* locationPath;
int status;
// Open the DSS file; Create if it doesn't exist
status = zopen(ifltab, "C:/temp/Example7.dss");
// If an error occured, messages will be printed to standard out
if (status != STATUS_OKAY) return status;
// Get the location path from the data path
locationPath = zlocationPath("/Russian/Healdsburg/Stage-Flow//NWIS RATING//");
if (!locationPath) return -1;
printf("Location path: %s\n", locationPath);
// Create the location struct
zsl = zstructLocationNew(locationPath);
zsl->xOrdinate = -122.8353; // Longitude, negative for western hemp
zsl->yOrdinate = 38.6133; // Latitude
zsl->coordinateSystem = 1; // Lat/Long
zsl->horizontalUnits = 3; // Decimal Degrees
zsl->horizontalDatum = 2; // NAD27
zsl->zOrdinate = 77.01; // Elevation
zsl->verticalUnits = 1; // Feet
zsl->verticalDatum = 2; // NGVD29
zsl->timeZoneName = mallocAndCopy("America/Los Angeles");
zsl->supplemental = (char *)calloc(400, 1);
stringCopy(zsl->supplemental, 400, "USGS 11464000 RUSSIAN R NR HEALDSBURG CA\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "Sonoma County, California, Hydrologic Unit 18010110\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "Drainage area: 793 square miles\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "SHIFTED=20161214140000 PST\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "BREAKPOINT1=1.74, OFFSET1=0.20, OFFSET2=0.30\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "STAGE1=4.33, SHIFT1=0.23, STAGE2=8.00, SHIFT2=0.00\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "Rating 50 has been developed in response to the\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "scour of the channel found during WY2015.\n", _TRUNCATE);
stringCat(zsl->supplemental, 400, "Comes into effect on the peak of 12/11/14.", _TRUNCATE);
status = zlocationStore(ifltab, zsl, 1);
free(zsl→timeZoneName);
free(zsl→supplemental);
free(locationPath);
zstructFree(zsl);
zclose(ifltab);
return 0;
}Location information can be view and edited from HEC-DSSVue using the “Display” menu and selecting “Supplemental Information” for a data record, or “Tabulate” for a location record:
