| Back to HOW_TO  |  Back to General Information  |


File types, naming conventions
Instruction files (*.ins)  | printable files (*.prt)  |  Time series files: tide gauges (tgg*.dat) , "tide potential sensors" (tgp*.dat)  |  loading effect time series (evl*.rad  evl*.eas  evl*.nor)  |  Arrays on files  |  Other binary data files  |

Instruction files

File names *.ins
belonging to a specific main program. Example: main program cream, instruction file MODEL/cream.ins
Contain records to guide main program through the process. General structure depends on main program
organisation. However, two features recur frequently, OPEN-FILE BLOCKS and NAMELISTS.

The main program can be started as in
otem92 MODEL/
and a  $ can be given at the first prompter ("a one dollar tip for the effort")  if the file name (stripped of path) is as shown in the prompt message. Also see open_ins  manual page.

A Fortran feature. Between &name and &end a set of data assignment records can be placed.
The old Fortran conventions ask to code the namelist with a free first column.
The parameter names that can be assigned are declared in the main progam's NAMELIST /name/ statement.
The manual pages that belong to the main programs (or, if the main programs are short utilities the
source code comments) will describe the meaning of the parameters that can be loaded with values.

Common errors consist in: spelling parameter names wrong, assigning too many values to array
variables, assigning constants of wrong type, forgetting string quotes and commas.

The virtue of namelist assignment is its pairing with DATA statements. In the DATA statements,
parameters are given default values which the user can optionally alter in the namelist section of
an instruction file.

Printable files:

File name *.prt

Regularly contain flag arrays represented with MS-DOS line drawing characters.
Once upon a time the could be viewed on UNIX platforms using special fonts. Recommended font name spc08x14h
E.g. start  a window with this font using
   xterm -fn spc08x14h &
For editing etc. utilize
   nedit -fn spc08x14h filename &
This command is usually aliased to nes filename
Denser fonts are spc08x08v7 and spc08x08e, but their character width is still too wide to get the full width of a model like GOMSL on one page.
Presently, the best method to view these files is to download them to a Windows platform and view them in an "MS_DOS" window or with QuickViewPlus in MS-DOS font mode. In OTEQ/bin there are two GMT-based plotting routines, prpbound and solplot that process and show the passive boundaries in postscript.

After cream, prflm.prt also contains the flag update information that has been entered
at the keyboard. These records (after <UPDFLM>>>... ) can be pasted into cream.ins
for rerunning (iterating) the process.

Time series files

Tide gauge files  (tgg)  and Tide generating  potential  (tgp)  sensor files

Produced by the main programs of tide modelling. Programs otemt1 and otemt1 for instance
can be instructed to output tide gauge time series on file unit 75 (tgp: 77)

A typical tide gauge file looks as follows:
10 sites
                                 Boston          St.John NBrunsw Sackville       Corner Brooke   Port Menier 
                                         Yarmouth NScotiaTruro           Riviere du loup Flower's cove   Portland Maine 

                         Time (h)     Tide elevation (mm) ...
1997-09-02 00:00:00         .000        .0      .0      .0      .0      .0      .0      .0      .0      .0      .0
1997-09-02 01:00:05        1.002       4.6    -2.1     7.8     3.1     3.2      .5     7.0     1.6     4.2     5.2
1997-09-02 02:00:11        2.003     -37.2    -1.1     7.0     -.3    10.2     -.2    12.3     1.8    16.8    17.6
1997-09-02 02:59:42        2.995    -100.8  -132.3  -172.4     1.0    16.6      .5     9.6    -3.9    22.2   -82.2
1997-09-02 03:59:48        3.997     -97.6  -187.9  -161.3      .8    18.1     4.3   -67.0     1.0   -12.4  -205.5
1997-09-02 04:59:54        4.998    -177.5  -215.4  -219.9     1.8    16.9    15.1  -110.8    -8.5   -59.4  -249.8
1997-09-02 06:00:00        6.000    -189.9  -192.6  -139.5     2.2    -8.9    33.1  -119.2  -195.7   -58.4   -57.0
1997-09-02 07:00:05        7.002    -137.5  -180.6  -177.4    -4.5  -149.8    46.7  -124.9  -329.8   -96.0  -152.2
1997-09-02 08:00:11        8.003    -127.5  -117.5  -155.4   -69.5  -335.8     9.4  -124.7  -234.5  -126.9  -227.2

         1         2         3         4         5         6         7         8         9         0         1         2

There are four header lines, the first telling how many tide gauges are included (10 sites) . The following two lines are staggered  column headers, the first column header shows the names of tide gauge 1,3,5 etc., the second line 2,4,6 etc.  Each string is exactly 16 charaters long.

Thus  'Yarmouth NScotiaTruro           ' designate tide gauge column 2, Yarmouth, Nova Scotia, and tide gauge column 4, Truro. The third line gives measurement units for the time and elevation.

The date part format is (i4,5(1x,i2)),  the hours-after-start part has format (t23,f10.3), and the column field for tide gauge number j starts in character column 27+j*8. Thus, to extract Truro, the format would be (t59,f8.1).

We can use tslist to create binary time series for more convenient use:
  tslist ~alla/OTEQ/GOMSL/tggw5.dat -s4 -g'(i4,5(1x,i2),t59,f8.1)' -k3 -r1.0 -Ff10.1 -o TRURO_tgg.ts
Here, output is to file tggw5.ts

For output to labelled multicomponent files we have the utility /geo/hgs/PC/OTEQ/bin/TGL
   TGL -h
to get help text.

The command
   TGL -I -o tggw5.mc tggw5.dat 1 2 3 4 5
will copy the first five columns into a binary data file.

In order to get a list of labels, use
   tslist tggw5.mc -l

to obtain a screen list of single site (example again: Truro), use
   tslist tggw5.mc -lTruro -Ff10.1

to obtain a screen plot, use
   tsd -l Truro tggw5.mc

A reminder about labels:
   The first few letters will suffice to locate the label.
   Use the spelling that is returned by the label scanning command
      tslist tggw5.mc -l | fgrep Loc
   You will see that blanks are converted into underscores.
   If you need to ignore upper/lower case, code the label in upper case and use the -L option instead of -l
    tslist tggw5.mc -LTRURO -Ff10.1
    tsd -L TRURO tggw5.mc

   For your convenience, truncate a label as long as it stays unique. If ambiguous, the first encountered label will indicate the section to retrieve.

   (Apologies for the blank that is needed in tsd between the option and the value.)

Loading effect time series

These files are similar to tide gauge files. They contain time series of loading effects, earth surface displacements. There is one file for each displacement component, radial (same as vertical), east and north. They are usually output in the tide model programs on file units 65, 66 and 67.
01 sites
                                 WESTFORD    7205
   Date     Time         Hour     Radial  
1997-09-02 00:00:00         .000       .00
1997-09-02 01:00:05        1.002       .39
1997-09-02 02:00:11        2.003       .67
1997-09-02 02:59:42        2.995       .94
1997-09-02 03:59:48        3.997      1.19
1997-09-02 04:59:54        4.998      1.32
1997-09-02 06:00:00        6.000      1.38
1997-09-02 07:00:05        7.002      1.26

There is a utility EVL in /geo/hgs/OTEQ/bin to collect the displacements into one 3-D multicomponent binary time series file for each site. Use
   EVL -h
to obtain a short note on its usage.

If the evl-files are named   evlw5r.daf evlw5e.daf and  evlw5n.daf , the appropriate copy command to create a binary file   evlw5.mc is
   EVL -o evlw5.mc -lcc 1 -I evlw5 1
The data can be retrieved using
   tslist evlw5.mc -Ff10.3 -L'WEST|RAD'
or, if you want all three components side-by-side
   tslist evlw5.mc -Ff10.3 -L'WEST|RAD' -L'WEST|EAS' -L'WEST|NOR'

If the evl-files are named  evls5.rad evls5.eas  and  evls5.nor , the appropriate copy command is
   EVL -o evls5.mc -x - -I evls5. 1

Arrays on files:

File name FLZ*.DAT: binary data, two segments: Z-flags and /CAREA/
Z-flags:   Header record= N,M, grid type = Z, variable type FLAG.
     N records containing M 4-byte words each follow (Fortran type INTEGER).
/CAREA/: Header record= none
                   One record with one  8-byte word (Fortran type REAL*8) and
      nine  4-byte words (Fortran type REAL*4) follow.
      Contains area outline (longitudes and latitudes), projection
      centre and scale (grid mesh width).
File name FLM*.DAT: binary data, two segments: M-flags and depth array (H).

Other binary data files:

Data files *.DAT  or  *.dat
Can contain FLAG, REAL or CMPX data. REAL and FLAG (Integer) have been introduced above.  In the case of  CMPX (complex) data there are two extra values saved in the header, a version number an a two-character tag.

CMPX data is typically a harmonic tide potential, a harmonic tide solution or a field of harmonic tide loading effects, pertaining to a certain tide frequency.

Header record= N,M, grid type character  (one character), tag string (two characters), version number (integer number, Fortran type INTEGER), variable type string CMPX. Example: 124 112 Z M2 1 CMPX heads a 124x112 complex field supposed to be solution number 1 of tide M2.

File name  *.PKD  or  *.pkd
Packed data, typically CMPX data arrays (fields) like solutions or potentials or loading effects. Packed means that land nodes are removed. There is only one record (N=1) with M complex numbers (8 bytes per word, Fortran type COMPLEX*8). An accompanying flag array is needed in order to unpack the array for use. These files are routinely written by the OTEQuation solver otemt1.

A file can contain many segments of (packed) arrays. In order to find out their version numbers and tags the following utility is available:
More information about otecat is obtained by starting otecat and entering :H  for help. Quit by  entering :Q
otecat can copy CMPX arrays from one file to another, change version numbers and tags.

Packed or not?
If otecat lists the array size as 1 followed by a large number you can be almost certain that the array is stored packed.
If otecat lists the array size as a number greater or equal 2 followed by another number greater or equal 2, the array is definitely not packed.

Ocean Tide Effective Potential, variable type CMPX, oftentimes not packed because the field might be interesting at land points too. Produced in stages prep (program otem92) and solve (program otemt*).

Active boundary geometry data.

Out-of-area tides and active boundary tides.

Dump files containing the state arrays of the differential equation solver. Written and read back in stage solve by subroutines OTEQ and TTEQ, cannot be interchanged though. Special structure.

The driving force arrays and tide information concerning the Explicitly Time-Dependent modelling (TTEQ). Written in stage prep by program otem16 and read in stage solve by otemt1.

| Back to HOW_TO  |  Back to General Information  |