Notes on "Format for the Oceanographic and Atmospheric Master Library Tide Constituent Database"

The following notes by David Flater apply to the 2003-06-06 revision of the TCD documentation, "Format for the Oceanographic and Atmospheric Master Library (OAML) Tide Constituent Database" by Jan Depner.

Re: page 24

As should have been obvious from the fact that open_tide_db returns no context to the caller, libtcd is only designed to handle one open database at a time.  Prior to the 2003-10-14 patch, XTide was calling open_tide_db repeatedly with no matching calls to close_tide_db, causing a memory leak.  One solution would have been just to add the matching calls to close_tide_db.  Instead, the patch from Phil Thornton causes libtcd to free the previous database context automatically if a new database is opened and to reuse the "cached" context if it is the same database.


The following notes by David Flater apply to the 2002-09-21 revision of the TCD documentation, "Format for the Oceanographic and Atmospheric Master Library (OAML) Tide Constituent Database" by Jan Depner.  All have been incorporated into the 2003-06-06 revision except for the first one regarding the ordering of the constituents.

Re: page 5

Although it is not a requirement of XTide nor of the TCD format, Mr. Depner has requested that the ordering of the existing constituents in TCD files be frozen for the convenience of other applications.  New constituents may be appended but existing ones should not be reshuffled.

Re: page 6

Clarification of nulls

Field descriptions include the phrase "or 0" when a value of zero should be interpreted as "null."  "Null" means that the field is omitted and/or not applicable, and the application should do the right thing for that case.

Change to interpretation of slack offsets

Prior to 2003-03-18, zero was used as the "null" value for slack offsets (floodbegins, ebbbegins).  Unfortunately, this caused a conflict with subordinate stations that did need to specify zeros for slack offsets.

It is not correct to default slack offsets to zero when they are omitted.  Consider an example where max timeadd is 6 hours, min timeadd is 5 hours, and slack offsets are omitted.  If the slack offsets are defaulted to zero, the results are nonsense.  Instead, the slack offsets must be defaulted to values that are "reasonable" given the skew of the max and min offsets.  XTide simply averages the two.

This conflict was resolved in the 2003-03-18 revision of libtcd, tcd-utils, and XTide by changing the "null" value.  Omitted slack offsets are now represented with the value NULLSLACKOFFSET defined in libtcd/tcd.h, which is 0xA00 (2560).

"Simplified" type 2 records

Prior to the revisions of 2003-03-27, a simplified representation could be used for type 2 records where the max and min values were identical and there were no slack offsets, current directions, or average levels.  In such cases, the max fields were all set to their null values and only the min fields were used.  This corresponds to a shorthand notation that is used in the offsets.xml format.  It is also analogous to a certain implementation detail in XTide, where a simpler algorithm can be used for simple offsets.  However, XTide does its own simplifications and its behavior is not impacted by the choice of representation in the database.

Unfortunately, "simplified" type 2 records also caused a conflict.  A station having a nonzero min time offset and a zero max time offset with no other fields being relevant would be mistaken for a simplified case, and the min time offset would incorrectly be used for both max and min.  This conflict was resolved in the 2003-03-27 revision of libtcd, tcd-utils, and XTide by doing away with "simplified" type 2 records (which were undocumented to begin with).

Re: page 23

Since "simplified" type 2 records were abolished, the check_simple function documented on page 23 now is used only to determine whether restore_tide_db should output the shorthand form to offsets.xml.  The boolean value that it returns (erratum:  return documented as void) is only a convenience and does not impact the interpretation of the record any longer.


David Flater
$Id: tcd_notes.html,v 1.11 2003/10/14 18:04:23 flaterco Exp $