$Id: libtcd.html,v 1.32 2004/10/13 20:27:33 flaterco Exp $

Tide Constituent Database

Comments on this documentation should be returned to David Flater.

Contents

Introduction
Tide record (version 1.100)
Public database header (version 1.100)
libtcd 1.100 API
Changelog
References

1. Introduction

The Tide Constituent Database (TCD) file format and schema are used by XTide to retrieve constituent definitions (speeds, equilibrium arguments, and node factors), harmonic constants, subordinate station offsets and associated metadata for use in generating tide predictions.

The TCD file format and schema were originally designed by Jan Depner to improve the performance of XTide and to meet additional requirements of the U.S. Naval Oceanographic Office (NAVO). A software API for reading and writing TCD files is provided by libtcd, which is bundled with XTide but can be compiled and used separately.

The design goals for TCD included:

Available without installing heavy external packages.
Efficient for indexing and loading of stations.
Compact file format.
Translatable without loss from legacy XTide .txt and .xml files.
Exportable to legacy .txt and .xml formats.
Modifiable by end user using tideEditor.
Resistant to inept editing using generic tools.

The TCD file format and schema and libtcd are in the public domain. XTide is covered by the GNU General Public License.

For additional background, see Jan Depner, "Format for the Oceanographic and Atmospheric Master Library (OAML) Tide Constituent Database," rev. 2003-06-06.

2. Tide record (version 1.100)

This section documents the tide record schema of the Tide Constituent Database as it stands in libtcd version 1.100. The schema has known problems that are slated to be fixed in libtcd 2.0. For details, see tcd2.html.

Fields designated as "header" fields are retrieved at indexing time and stored in memory for quick access. The rest are retrieved only when individual tide stations are loaded.

Type 1 records are for reference stations; type 2 records are for subordinate stations. Some fields are only encoded for one record type while others are encoded for both.

intX means signed X-bit integer. uintX means unsigned X-bit integer. TCD files are encoded with a bit-packing function that allows odd-sized fields to be stored efficiently. int varying and uint varying indicate fields whose lengths in bits are dynamically configured for each TCD file.

Floating-point numbers are encoded in the TCD file using scaled integers. An integer with a scale of X represents the real number obtained by dividing the integer by X.

All character strings use the character set ISO-8859-1.

Record type	TIDE_RECORD field	TIDE_RECORD data type	File encoding	Encodable range	Semantics
all	`header.record_number`	int32	none	N/A	Records in TCD file are implicitly numbered [0, N-1].
all	`header.record_size`	uint32	uint12	[0, 4095]	Length of encoded record in bytes.
all	`header.record_type`	uint8	uint4	[0, 15]	Type 1 is reference station. Type 2 is subordinate station. Others are as yet undefined.
all	`header.latitude`	float64	int25, scale 100000	[-167.77216, 167.77215]	Latitude in degrees north; use [-90.00000, 90.00000]. Lat,lng of 0,0 is interpreted as NULL.
all	`header.longitude`	float64	int26, scale 100000	[-335.54432, 335.54431]	Longitude in degrees east; use [-180.00000, 180.00000]. Lat,lng of 0,0 is interpreted as NULL.
all	`header.reference_station`	int32	int18	[-131072, 131071]	Index, references record_number of reference station for type 2 records, or -1 for none.
all	`header.tzfile`	int16	uint10	[0, 1023]	Index, references table of time zone values like ":America/New_York" that control which time zone output should be rendered into.
all	`header.name`	char[90]	0-terminated string	Length constrained by TIDE_RECORD.	Station name.
all	`country`	int16	uint9	[0, 511]	Index, references table of country names.
all	`pedigree`	int16	uint7	[0, 127]	Index, references table of pedigree values like "-2000000000 (Traceable to authority)." A meaningless indicator of data quality and source used by Harmbase 1 to rank data sets.
all	`source`	char[90]	0-terminated string	Length constrained by TIDE_RECORD.	Where you got the data, or "" for NULL.
all	`restriction`	uint8	uint4	[0, 15]	Index, references table of restrictions like "Public domain," "Non-commercial use only," "DoD/DoD contractors only."
all	`comments`	char[1500]	0-terminated string	Length constrained by TIDE_RECORD.	Human-readable text that is not provided to the user of a data set at the time of use but may be retrieved on demand. Use "" for NULL.
1	`units`	uint8	uint varying	[0, 255]	Index, references table of units like "feet," "meters," "knots," "knots^2." This field is used only to indicate the units of the datum and the amplitudes for reference stations.*
1	`datum_offset`	float32	int28, scale 10000	[-13421.7728, 13421.7727]	The datum (Z0).
1	`datum`	int16	uint7	[0, 127]	Index, references table of datum kinds like "Mean Lower Low Water."
1	`zone_offset`	int32	int13	[-4096, 4095]	Meridian to which epochs are adjusted, in hours and minutes east of UTC, encoded Hours * 100 + Minutes.
1	`expiration_date`	uint32	uint27	[0, 134217727]	Use-until date for data set, encoded Year * 10000 + Month [1, 12] * 100 + Day [1, 31], or 0 for NULL.
1	`months_on_station`	uint16	uint10	[0, 1023]	Number of months in time series used to derive harmonic constants, or 0 for NULL.
1	`last_date_on_station`	uint32	uint27	[0, 134217727]	Last date in time series used to derive harmonic constants, encoded Year * 10000 + Month [1, 12] * 100 + Day [1, 31], or 0 for NULL.
1	`confidence`	uint8	uint4	[0, 15]	A meaningless indicator of data quality, generally initialized to 10. (Jan wants to keep this.)
1	`amplitude`	float32[255]	uint19, scale 10000 (each)	[0.0000, 52.4287]	Amplitudes of constituents. Constituents with amplitude less than `AMPLITUDE_EPSILON` are not encoded.
1	`epoch`	float32[255]	uint16, scale 100 (each)	[0.00, 655.35]	Epochs (phases) of constituents, in degrees. Use [0.00, 359.99]. Constituents with zero amplitude are not encoded.
2	`level_units`	uint8	uint varying	[0, 255]	Index, references table of units like "feet," "meters," "knots," "knots^2." This field is used only to indicate the units of the level_add fields in type 2 records.
2	`avg_level_units`	uint8	uint varying	[0, 255]	Index, references table of units like "feet," "meters," "knots," "knots^2." This field is used only to indicate the units of the avg_level fields in type 2 records.
2	`direction_units`	uint8	uint varying	[0, 255]	Index, references table of units like "degrees true." This field is used only to indicate the units of the direction fields in type 2 records.
2	`min_time_add`	int32	int13	[-4096, 4095]	The time adjustment for Low Tide or Max Ebb events, encoded Hours * 100 + Minutes. 0 and NULL are equivalent (no adjustment).**
2	`min_level_add`	float32	int17, scale 1000	[-65.536, 65.535]	Additive adjustment for Low Tide or Max Ebb events.*** 0 and NULL are equivalent (no adjustment).
2	`min_level_multiply`	float32	int16, scale 1000	[-32.768, 32.767]	Ratio for Low Tide or Max Ebb events, or 0 for NULL (equivalent to 1, no adjustment).***
2	`min_avg_level`	float32	int17, scale 1000	[-65.536, 65.535]	Mean Low Water, or something like it, or 0 for NULL.
2	`min_direction`	int32	uint9	[0, 511]	Direction of ebb current. Use [0, 359], or 361 for NULL.
2	`max_time_add`	int32	int13	[-4096, 4095]	The time adjustment for High Tide or Max Flood events, encoded Hours * 100 + Minutes. 0 and NULL are equivalent (no adjustment).**
2	`max_level_add`	float32	int17, scale 1000	[-65.536, 65.535]	Additive adjustment for High Tide or Max Flood events.*** 0 and NULL are equivalent (no adjustment).
2	`max_level_multiply`	float32	int16, scale 1000	[-32.768, 32.767]	Ratio for High Tide or Max Flood events, or 0 for NULL (equivalent to 1, no adjustment).***
2	`max_avg_level`	float32	int17, scale 1000	[-65.536, 65.535]	Mean High Water, or something like it, or 0 for NULL.
2	`max_direction`	int32	uint9	[0, 511]	Direction of flood current. Use [0, 359], or 361 for NULL.
2	`flood_begins`	int32	int13	[-4096, 4095]	The time adjustment for Slack Water or Min Flood before Max Flood, encoded Hours * 100 + Minutes, or 2560 for NULL.**
2	`ebb_begins`	int32	int13	[-4096, 4095]	The time adjustment for Slack Water or Min Ebb before Max Ebb, encoded Hours * 100 + Minutes, or 2560 for NULL.**

* In case of units = knots^2 (hydraulic currents), it should be understood that only the amplitudes of the constants are such as to give results in knots squared. The datum and any level_add corrections are in plain knots; i.e., the square root of the amplitude is taken before the datum and any corrections are added in.

** Time corrections DO NOT incorporate adjustments to Local Standard Time when the reference and sub station are in different time zones. Time corrections are specified as if all calculations and predictions were done in UTC. Time zone differences are handled by adjusting the tzfile field. This differs from current NOS practice, in which LST adjustments are incorporated. When this "time warp" is undone for NOS sub stations that use reference stations across the International Date Line, time corrections in excess of 24 hours can result.

*** See http://www.flaterco.com/xtide/mincurrents.html regarding usage for Min Flood and Min Ebb events.

This section describes the "public portion" of the database header structure, which is declared in tcd.h and made available to applications via the get_tide_db_header operation.

char version[90];	libtcd version string.
uint32 major_rev;	libtcd major revision number.
uint32 minor_rev;	libtcd minor revision number.
char last_modified[90];	Last modification of TCD file.
uint32 number_of_records;	Number of records in TCD file.
int32 start_year;	Year corresponding to 0 index in speed, equilibrium argument, and node factor arrays.
uint32 number_of_years;	Number of years in speed, equilibrium argument, and node factor arrays.
uint32 constituents;	Number of constituents.
uint32 level_unit_types;	Number of entries in table used by `get_level_units`.
uint32 dir_unit_types;	Number of entries in table used by `get_dir_units`.
uint32 restriction_types;	Number of entries in table used by `get_restriction`.
uint32 pedigree_types;	Number of entries in table used by `get_pedigree`.
uint32 datum_types;	Number of entries in table used by `get_datum`.
uint32 countries;	Number of entries in table used by `get_country`.
uint32 tzfiles;	Number of entries in table used by `get_tzfile`.

The encodings of constituent speeds, equilibrium arguments, and node factors are as follows.

Name	Program data type	File encoding	Encodable range	Semantics
Speed	float64	uint varying (max 31), scale 10000000, with offset	[0.0000000, 214.7483647]*	Speed of constituent in degrees per hour.
Equilibrium argument	float32	uint varying (max 31), scale 100, with offset	[0.00, bignum]	Equilibrium argument in degrees. Use [0.00, 359.99].
Node factor	float32	uint varying (max 31), scale 10000, with offset	[0.0000, bignum]	Node factor.

The offsets are adjustments so that the minimum value in the data set is represented with a zero and the maximum by max - offset. For node factors, this can save bits. However, for speeds and equilibrium arguments they are a needless complication. Speeds in excess of the limit quoted above will overflow the integers before the offset is taken into account, and the minimum equilibrium argument is always zero anyway.

* The highest speed in the IHO list of constituents as of 2003-07-31 is 203.904625 degrees/hour for 6MS14.

4. libtcd 1.100 API

The API is provided in the C language, and is made available by including the header file tcd.h.

The data types NV_CHAR, etc. are defined in nvtypes.h, and are analogous to the informal types used above.

/* One-line character strings / #define ONELINER_LENGTH 90 / Verbose character strings */ #define MONOLOGUE_LENGTH 1500 #define MAX_CONSTITUENTS 255	These defines describe the sizes of the fixed-size arrays in the tide record.
typedef struct ... DB_HEADER_PUBLIC; typedef struct ... TIDE_STATION_HEADER; typedef struct ... TIDE_RECORD;	The structure for the database header, and the header and main part of the tide record.
#define NULLSLACKOFFSET 0xA00	Magic constant used to indicate NULL in the `flood_begins` and `ebb_begins` fields of the tide record.
#define AMPLITUDE_EPSILON 0.00005	This is the level below which an amplitude rounds to zero.
void dump_tide_record (TIDE_RECORD *rec);	Prints a low-level dump of the tide record to stderr.
NV_CHAR get_country (NV_INT32 num); NV_CHAR get_tzfile (NV_INT32 num); NV_CHAR get_level_units (NV_INT32 num); NV_CHAR get_dir_units (NV_INT32 num); NV_CHAR get_restriction (NV_INT32 num); NV_CHAR get_pedigree (NV_INT32 num); NV_CHAR *get_datum (NV_INT32 num);	For fields in the tide record that are indices into tables of character string values, these functions are used to retrieve the character string value corresponding to a particular index. The value "Unknown" is returned when no translation exists. The return value is a pointer into static memory.
NV_CHAR *get_constituent (NV_INT32 num);	Get the name of the constituent corresponding to index `num` [0,`constituents`-1]. The return value is a pointer into static memory.
NV_CHAR *get_station (NV_INT32 num);	Get the name of the station whose `record_number` is `num` [0,`number_of_records`-1]. The return value is a pointer into static memory.
NV_FLOAT64 get_speed (NV_INT32 num);	Returns the speed of the constituent indicated by `num` [0,`constituents`-1].
NV_FLOAT32 get_equilibrium (NV_INT32 num, NV_INT32 year); NV_FLOAT32 get_node_factor (NV_INT32 num, NV_INT32 year);	Get the equilibrium argument and node factor for the constituent indicated by `num` [0,`constituents`-1], for the year `start_year`+`year`.
NV_FLOAT32 get_equilibriums (NV_INT32 num); NV_FLOAT32 get_node_factors (NV_INT32 num);	Get all available equilibrium arguments and node factors for the constituent indicated by `num` [0,`constituents`-1]. The return value is a pointer into static memory which is an array of `number_of_years` floats, corresponding to the years `start_year` through `start_year`+`number_of_years`-1.
NV_INT32 get_time (NV_CHAR string); NV_CHAR ret_time (NV_INT32 time); NV_CHAR *ret_time_neat (NV_INT32 time);	Convert between character strings of the form "[+-]HH:MM" and the encoding Hours * 100 + Minutes. `ret_time` pads the hours with a leading zero when less than 10; `ret_time_neat` omits the leading zero and omits the sign when the value is 0:00. Returned pointers point into static memory.
NV_CHAR *ret_date (NV_U_INT32 date);	Convert the encoding Year * 10000 + Month [1, 12] * 100 + Day [1, 31] to a character string of the form "YYYY-MM-DD", or "NULL" if the value is zero. The returned pointer points into static memory. (The compact form, without hyphens, is obtainable just by printing the integer.)
NV_INT32 search_station (NV_CHAR *string);	When invoked multiple times with the same `string`, returns record numbers of all stations that have that string anywhere in the station name. This search is case insensitive. When no more records are found it returns -1.
NV_INT32 find_station (NV_CHAR name); NV_INT32 find_tzfile (NV_CHAR name); NV_INT32 find_country (NV_CHAR name); NV_INT32 find_level_units (NV_CHAR name); NV_INT32 find_dir_units (NV_CHAR name); NV_INT32 find_restriction (NV_CHAR name); NV_INT32 find_pedigree (NV_CHAR name); NV_INT32 find_datum (NV_CHAR name); NV_INT32 find_constituent (NV_CHAR *name);	Inverses of the corresponding `get_` operations. Return -1 for not found.
NV_INT32 add_restriction (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 add_pedigree (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 add_tzfile (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 add_country (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 add_datum (NV_CHAR name, DB_HEADER_PUBLIC db);	Add the value of `name` to the corresponding lookup table and return the index of the new value. If `db` is not NULL, the database header struct pointed to will be updated to reflect the changes. The maximum length of `name` is restricted by the corresponding size definition in `tide_db_default.h` (restriction 30, pedigree 70, tzfile 30, country 50, datum 70, including the terminating null).
NV_INT32 find_or_add_restriction (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 find_or_add_tzfile (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 find_or_add_country (NV_CHAR name, DB_HEADER_PUBLIC db); NV_INT32 find_or_add_datum (NV_CHAR name, DB_HEADER_PUBLIC db);	Add the value of `name` to the corresponding lookup table if and only if it is not already present. Return the index of the value. If `db` is not NULL, the database header struct pointed to will be updated to reflect the changes. (There is no pedigree function because pedigree is scheduled to be deleted in version 2.) The maximum length of `name` is restricted by the corresponding size definition in `tide_db_default.h` (restriction 30, tzfile 30, country 50, datum 70, including the terminating null).
void set_speed (NV_INT32 num, NV_FLOAT64 value);	Set the speed for the constituent corresponding to index `num` [0,`constituents`-1].
void set_equilibrium (NV_INT32 num, NV_INT32 year, NV_FLOAT32 value); void set_node_factor (NV_INT32 num, NV_INT32 year, NV_FLOAT32 value);	Set the equilibrium argument and node factor for the constituent corresponding to index `num` [0,`constituents`-1], for the year `start_year`+`year`.
NV_BOOL open_tide_db (NV_CHAR *file);	Opens the specified TCD file. If a different database is already open, it will be closed. libtcd maintains considerable internal state and can only handle one open database at a time. Returns false if the open failed.
void close_tide_db ();	Closes the open database.
NV_BOOL create_tide_db (NV_CHAR file, NV_U_INT32 constituents, NV_CHAR constituent[], NV_FLOAT64 speed, NV_INT32 start_year, NV_U_INT32 num_years, NV_FLOAT32 equilibrium[], NV_FLOAT32 *node_factor[]);	Creates a TCD file with the supplied constituents and no tide stations. Returns false if creation failed. The database is left in an open state.
DB_HEADER_PUBLIC get_tide_db_header ();	Returns a copy of the database header for the open database.
NV_BOOL get_partial_tide_record (NV_INT32 num, TIDE_STATION_HEADER *rec);	Gets "header" portion of tide record for the station whose `record_number` is `num` [0,`number_of_records`-1] and writes it into `rec`. Returns false if `num` is out of range. `num` is preserved in the static variable `current_index`.
NV_INT32 get_next_partial_tide_record (TIDE_STATION_HEADER *rec);	Invokes `get_partial_tide_record` for `current_index`+1. Returns the record number or -1 for failure.
NV_INT32 get_nearest_partial_tide_record (NV_FLOAT64 lat, NV_FLOAT64 lon, TIDE_STATION_HEADER *rec);	Invokes `get_partial_tide_record` for a station that appears closest to the specified `lat` and `lon` in the Cylindrical Equidistant projection. Returns the record number or -1 for failure.
NV_INT32 read_tide_record (NV_INT32 num, TIDE_RECORD *rec);	Gets tide record for the station whose `record_number` is `num` [0,`number_of_records`-1] and writes it into `rec`. `num` is preserved in the static variable `current_record`. Returns `num`, or -1 if `num` is out of range.
NV_INT32 read_next_tide_record (TIDE_RECORD *rec);	Invokes `read_tide_record` for `current_record`+1. Returns the record number or -1 for failure.
NV_BOOL add_tide_record (TIDE_RECORD rec, DB_HEADER_PUBLIC db); #ifdef COMPAT114 /* Omission of db parameter was a bug. / NV_BOOL update_tide_record (NV_INT32 num, TIDE_RECORD rec); #else NV_BOOL update_tide_record (NV_INT32 num, TIDE_RECORD rec, DB_HEADER_PUBLIC db); #endif NV_BOOL delete_tide_record (NV_INT32 num, DB_HEADER_PUBLIC *db);	Add a new record, update an existing record, or delete an existing record. If the deleted record is a reference station, all dependent subordinate stations will also be deleted. Add and update return false if the new record is invalid; delete and update return false if the specified `num` is invalid. If `db` is not NULL, the database header struct pointed to will be updated to reflect the changes.
NV_BOOL infer_constituents (TIDE_RECORD *rec);	Computes inferred constituents when M2, S2, K1, and O1 are given and fills in the remaining unfilled constituents. The inferred constituents are developed or decided based on Article 230 of "Manual of Harmonic Analysis and Prediction of Tides," Paul Schureman, C&GS Special Publication No. 98, October 1971. Returns false if M2, S2, K1, or O1 is missing.

For more information, see Jan Depner, "Format for the Oceanographic and Atmospheric Master Library (OAML) Tide Constituent Database," rev. 2003-06-06.

5. Changelog

libtcd 1.100 "enhanced edition"

David Flater
2004-10-13

With luck, this will be the final release in the version 1 series and the last release that will write files that can be read by libtcd 1.02 through 1.14. It includes an additional round of cleanups that will enhance upward compatibilty but should not break backward compatibility.

check_simple was placed inside #ifdef COMPAT114 (which is still defined in tcd.h). AFAIK, this function is now of interest only in restore_tide_db, which uses it to determine which XML format to output.

Copied the libtcd.html descriptions of operations into the header file.

Made the db parameters to add_ and find_or_add_ operations optional (can be null).

Gave delete_tide_record a return value. Gave update_tide_record a db parameter, conditional on COMPAT114 not being defined.

In delete_tide_record, assert that the record is found.

Deleted unused systemtime var in write_tide_db_header.

Deleted unnecessary file parameter to read_tide_db_header.

Added static function check_tide_record to do sanity checks on records before committing them to the database and called it from add_tide_record and update_tide_record.

Initialized an uninitialized var in search_station.

Added clip_string calls in find_tzfile and find_constituent.

Replaced some weird code in find_constituent with more normal code.

Got rid of unnecessary copy operations in add_ functions.

Renamed tname parms to name.

Added checks to ensure that database is open when expected to be open and closed when expected to be closed.

Added AMPLITUDE_EPSILON and used it where applicable.

Moved duplicate record-size-figuring code into a new function, figure_size. Fixed wasted byte when record size is even multiple of 8 bits. (The same bug exists for calculating the size of the speeds, equilibrium arguments, and node factors, but fixing that would break compatibility, and the wastage is at most 3 bytes.)

Changed months_on_station to uint16.

Fixed bounds checking on input to add_ functions -- they all have their own static limits. Added similar bounds checking in write_tide_db_header.

Lots of documentation nits fixed.

libtcd 1.99 "collector's edition"

David Flater
2004-10-05

With luck, this will be the final release in the version 1 series and the last release that will write files that can be read by libtcd 1.02 through 1.14. It includes a gigantic round of cleanups to libtcd code that were made in anticipation of the upcoming major revision. Except for the bug fixes, the changes should be invisible to all wholesome client applications. Unwholesome client code or the use of unwholesome databases built by old, buggy versions of libtcd may now trigger errors or warnings that did not appear with libtcd 1.14.

In the process of testing the cleanups, I discovered some unrelated, really horrible bugs.

(Bug) Constituents with zero phases were not being encoded by write_tide_record. The affected reference stations in harmonics-dwf-2004-09-14 are Delfzijl, Netherlands; The Battery, New York Harbor, NY; and South Pass, LA. write_tide_record now encodes any constituent with a positive amplitude. Constituents with zero amplitude but nonzero phase are dropped, and negative amplitudes yield assertion failures. Made analogous changes to update_tide_record (the counts were supposed to match).

(Bug) update_tide_record was counting constituents for subordinate stations.

(Bug) Backed out the change to the control flow in delete_tide_record made in 1.14, which broke the deletion of reference stations with sub stations.

(Bug) Fixed logic error in delete_tide_record that corrupted the database when reference stations with sub stations were deleted.

(Bug) Made read_next_tide_record return -1 if at end of file, instead of going off the deep end.

Following are details of the gigantic cleanup.

The defines NAME_LENGTH, SOURCE_LENGTH and COMMENTS_LENGTH were generalized to ONELINER_LENGTH to set the length of one-line character string buffers and MONOLOGUE_LENGTH to set the length of verbose character string buffers.

COMPAT114 is defined in tcd.h. The effects are:

NAME_LENGTH, SOURCE_LENGTH and COMMENTS_LENGTH get defined.
Pre-version-1.02 TCD files using the old checksum code are accepted.

Added commentary on the commentary about OS-specific defines in nvtypes.h and tide_db_header.h, noting that they are not actually used.

Cleaned up all warnings and errors compiling under g++ -Wall:

(Errors) Corrected casts in union initializers in tide_db_header.h.
(Warnings) Added casts or changed data types, as appropriate, to resolve flagged signed-unsigned conversions.
(Errors) Added casts where NV_U_BYTE buffers were passed to functions from string.h (invalid conversion from unsigned char* to const char*).

Added asserts everywhere that I came across potentially dangerous assumptions.

Changed -O2 to -O in Makefile (Forte doesn't like O2).

Moved changelogs from source files to libtcd.html.

Made write_tide_record static; no applications should be calling this directly.

In clip_string, expanded static buffer to MONOLOGUE_LENGTH, fixed a bug that was previously masked, simplified code and added bounds checking.

Eliminated repeated calls to clip_string in find functions.

Eliminated clip_string duplication in write_tide_record.

Changed 256-char static buffers in add_pedigree, add_tzfile, add_country, add_datum, and add_restriction to ONELINER_LENGTH and added bounds checking.

Made filename MONOLOGUE_LENGTH.

Made version and last_modified ONELINER_LENGTH.

Handled overlong strings in TCD file by complaining and truncating instead of returning garbarge.

Eliminated get_string.

Eliminated repeated parsing of input in read_tide_db_header. Changed input buffer size to ONELINER_LENGTH.

Made support for pre-version-1.02 header checksums conditional on COMPAT114.

Changed many int32 fields in the DB header that had no reason ever to be negative to uint32. Exceptions include start_year (in case some crazy goes B.C.) and the offsets for speeds, equilibrium arguments, and node factors (required to read pre-version-1.11 TCD files). Also changed record_size in the tide record header, but left alone the rest of the tide record because the risk of breaking client code is too great: build_tide_db temporarily stores negative results from find functions in these fields, and tideEditor puts -1 in the record_number field to flag a new record. -1 in reference_station means no reference, though normally it's only -1 for reference stations.

In signature of create_tide_db, constituents and num_years became unsigned.

Changed many looper, index, size, etc. variables from signed to unsigned.

Corrected unsigned scan formats in read_tide_db_header.

Removed unused fields, unused data types and overcomplicated infrastructure in tide_db_header.h and read_tide_db_header.

Corrected signature of bit_unpack in tide_db.c.

Made get_speed, get_equilibrium and get_node_factor give assertion failures instead of returning -1.0 when invoker attempts to retrieve nonsense values. Added a missing bounds check.

Made set_speed, set_equilibrium and set_node_factor give assertion failures instead of doing nothing when invoker attempts to set nonsense values. Added a missing bounds check.

Made record_size in TIDE_INDEX struct 32 bits.

Added a warning about TCD files with negative offsets for speeds, eq args or node factors (caused by the bug fixed in 1.11).

Changed format of date string in [LAST MODIFIED] to XTide style. Changed identifer in [VERSION] to libtcd.

Added these functions:

NV_FLOAT32 *get_equilibriums (NV_INT32 num);
NV_FLOAT32 *get_node_factors (NV_INT32 num);
NV_INT32 find_or_add_restriction (NV_CHAR *tname, DB_HEADER_PUBLIC *db);
NV_INT32 find_or_add_tzfile (NV_CHAR *tname, DB_HEADER_PUBLIC *db);
NV_INT32 find_or_add_country (NV_CHAR *tname, DB_HEADER_PUBLIC *db);
NV_INT32 find_or_add_datum (NV_CHAR *tname, DB_HEADER_PUBLIC *db);
NV_CHAR *ret_time_neat (NV_INT32 time);
NV_CHAR *ret_date (NV_U_INT32 date);

Added header fields for major and minor revision number. Added check for attempt to read higher major revision than supported.

libtcd 1.14

David Flater
2004-09-03

(tide_db.c) Certain database update operations that ended with closing and re-opening the database were broken by nulling out the filename in close_tide_db. Incorporated patch from Jan Depner that rectifies this and tweaks the control flow in delete_tide_record.

libtcd 1.13

David Flater
2004-08-15

(create_tide_db) Write a valid end_of_file record even if someone creates a database with no tide records.

(tide_db_default) Removed a superfluous space character in table of default datum types (after Lowest Astronomical Tide).

libtcd 1.12

David Flater
2003-12-04

(tcd.h) Deleted #include <malloc.h>.

libtcd 1.11

David Flater
2003-11-16

(create_tide_db) Fixed horrible bug: offsets for speeds, equilibrium args, and node factors were sign-reversed with respect to their usage in read_tide_db_header and write_tide_db_header, resulting in possible overflows.

(read_tide_db_header) Added handling for zero tide records, which happens on new database create.

(open_tide_db) Added check of modified flag to 2003-10-14 code.

(close_tide_db) Deleted repeat free of tindex introduced 2003-10-14. Cleared modified flag on close.

libtcd 1.10

David Flater
2003-10-14

Incorporated patch from Phil Thornton that closes a memory leak and improves performance on repeat calls to open_tide_db. See http://www.flaterco.com/xtide/tcd_notes.html

libtcd 1.09

Jan C. Depner
2003-09-04

Bug fix - modifying last record in file and changing size of record caused a big problem. Duh, I should have seen that one coming.

libtcd 1.08

Jan C. Depner
2003-07-23

Bug fix - deleting last record in file caused a big problem.

libtcd 1.07

David Flater
2003-03-27

(This version was also released briefly without an updated version string.)

Check_simple altered per resolution to abolish "simplified" type 2 records. See http://www.flaterco.com/xtide/tcd_notes.html

libtcd 1.06

David Flater
2003-03-18

(This version failed to report an updated version string.)

Added NULLSLACKOFFSET to tcd.h per 2003-03-18 change to slack offsets. See http://www.flaterco.com/xtide/tcd_notes.html

libtcd 1.05

David Flater
2003-03-11

Incorporated nit fixes from August Hahn: added clip_string(tname) to take care of cases when the country name had leading/trailing spaces, and removed a couple of unused variables.

libtcd 1.04

David Flater
2002-12-13

While integrating 1.03, deleted an unused variable (whoop de do).

libtcd 1.03

Wade Ladner/Jan C. Depner
2002-12-09

Small fix for Micro$oft Windoze. We don't need to add CR's to strings (apparently).

libtcd 1.02

August Hahn
2002-11-15

Replaced the simplistic checksum with a real CRC. If the first checksum fails it will check for an old-style checksum.

libtcd 1.01

David Flater
2002-10-01

Many changes since 2002-08-01. Bumped version upon integration with XTide distribution. Renamed resulting library to libtcd.

tidelib 1.00

Jan C. Depner
2002-08-01

First tested release.

tidelib 0.99

Jan C. Depner
2002-07-15

Prototype for testing.

6. References

Jan Depner, "Format for the Oceanographic and Atmospheric Master Library (OAML) Tide Constituent Database," rev. 2003-06-06.

libtcd version 1.100.

XTide.

ISO-8859-1.

Manual of Harmonic Analysis and Prediction of Tides. Special Publication No. 98, Revised (1940) Edition (reprinted 1958 with corrections; reprinted again 1994). United States Government Printing Office, 1994.