PROCESS SEGDDIN
                           ------- -------

Parameters, alphabetically:
decimf    descale   fday      fcset     ffilen    fgmt      
filinc    format    ftr       ipath     lcset     lday      
ldeolist  lfilen    lgmt      listpath  logpath   lprint
ltr       nspfile   ntrgat    renum     retrac    secs
stack     stime     trinc

Document date: 2 February 2024

Modifications:
ver 2024.1.1 (1 February 2024) - Make SEGD format 8015 work
ver 2022.1.2 (26 Apr 2022) - Create FORMAT LG2019 for Langseth 2019 cruise that
                             had 4 extra bytes.
    - Only use the first 1000 bytes of the extended and external headers and
      skip the remainder
ver 2020.3.1002 (16 April 2020) - Detect and skip Rev 2 "Storage Unit" header
    - Add FORMAT ARAM and correct their nsamps and allow multiple shots
    and allow for there not being as many traces as indicated in the channel sets.
ver 2020.1.5 (24 Jan. 2020) - Allow IEEE 16 bit floating Point (format 8024)
         - Allow Rev 2 2 byte DESCALE or MP factor
         - Under format LDEO read an extra 4 bytes - thus older LDEO will break
ver 2016.2.3 (13 Apr. 2016) - Rewrote GPGGA to catch more bad NMEA strings.
ver 2016.2.1 (29 Mar 2016) - Accomodate bad $GPGGA formats.  Ignore the timestamp
    if bad.  Extrapolate latitude and longitude if bad.  Ignore rest of $GPGGA
ver 2014.2.6 (29 Apr. 2014) - Change DESCALE preset to yes (apply the SEG-D scalar)
ver 2013.4 - Change DESCALE preset to yes (apply the SEG-D scalar
April 2011 - Change RETRAC so multi-channel sets can match UKOOA
July 2008 - Add odd/even to parameter STACK.
April 2008 - Add FORMAT LDEO.
July 2007 - Honor $SDDBT in general header for water depth.
October 2006 - Honor $DBT in general header for water depth.
June 2005 - Add LPRINT 32 to print ASCII External header.
July 2004 - Add parameter DESCALE.
May 2004 - FORMAT GEOMETRICS generates Geometrics file names.
         - Honor $GPGGA (nav) in external header.
         - Honor record length in General Header #2.
March 2004 - Allow FORMAT HTI.
             Honor SEG-D format 8015 (24 bit integer).
October 2003 - Create parameter LDEOLIST.

      PROCESS SEGDDIN reads SEG-D formatted disk files.  The SEG-D
shot files may be listed in a separate "list" file or all the shots
may be in a single file or the shots may be in a "realtime" shot
directory.
      The demultiplexed data formats available are: 
  8015 = 20 bit SEGD floating point (4 bit hex exponent)
  8022 = 8 bit integer
  8024 = 16 bit IEEE floating point (not the same as UTIG F.P.)
  8036 = 24 bit integer (new in rev 2)
  8038 = 32 bit integer
  8048 = 32 bit IBM FP
  8058 = 32 bit IEEE FP


     SIOSEIS considers the SEG-D file number to be a count of the
SEG-D files produced by the recording system.  This file number is
used as the SEG-Y trace header "Original field record number", word 3,
as well as the "Energy source point number", word 5, EXCEPT on LDEO
systems.  The LDEO system "shot point number" is put the SEG-Y word 3
and the file number in word 5.


Example:
segddin
    listpath file_list end
end

PARAMETER DICTIONARY
--------- ----------

IPATH   - The pathname of a single SEG-D file that contains one or
          more shots.  The SEG-D File number is used to control which
          shots are read though parameters FFILEN and LFILEN.
          Preset = none   e.g. /export/home/bigfile.segd

LISTPATH - The pathname of a list of SEG-D files to be read and
         processed.  Only one SEG-D file name may be on each line in
         the list.  The list is read in order from the first line to
         the last line.  There are many ways to create a list of files.
         ls -lt /export/home3/seisnet/BOL38/FFID_2* | sort -r | awk '{print $9}'
         or something using the Unix ls -1tr command (one, not l).
         The shell script below generates a partial list of a directory:
         #!/bin/csh -f
         set first = 2746
         set last = 4165
         set i = $first
         while ( $i < $last )
            ls -1 /export/home3/seisnet/BOL38/FFID_$i%*
             @ i = $i + 1
         end
         Preset = none    e.g. listpath list     where list contains:
               /data/project_xyz/FFID0001
               /data/project_xyz/FFID0002
               /data/project_xyz/FFID0003

STACK  - pathname [odd/even]
         The pathname of a file containing a push down-stack 
         containing at least two SEG-D shots.  The file on the second
         line of the push-down stack is read and processed.  The file of
         SEG-D filenames (the stack) is reread and the shot on the second
         line is read and processed if it is different from the previous
         shot.  One way of creating a push down stack is to run a shell
         script with a loop with ls -1t in it.  e.g.
         #!/bin/csh -f
         set forever = 1
         while( $forever ) 
            ls -t /export/home/public/seisnet_tmp/* | head -n 2 > /tmp/latest
            sleep 5
         end
         end

         The second file from the top of the stack is used since the
         write of the top file may not be completed.  In this manner,
         new SEG-D shots may be read and processed continuously.

         ls /pathname/* includes the pathname in the listing.  Otherwise use:
         sed '1,2 s%^%/export/home/public/seisnet_tmp/%;w latest' /tmp/latest

         SIOSEIS jobs using the STACK parameter may be stopped
         gracefully by creating a file "in" with a negative number
         when there are no more files to be added to the stack.

odd/even - An additional part of the STACK parameter indicating that
         only ODD or EVEN shot numbers are processed.

         E.G.    stack /tmp/latest  even

LDEOLIST - The pathname to a list of files used in conjunction with
         the Seisnet real-time system on the Ewing.  SEGDDIN reads
         and processes the seisnet files listed in the LDEOLIST file.
         When the list is exhausted the LDEOLIST file is deleted.
         Processing resumes when a new LDEOLIST file is detected.
         Process SEGDDIN is in a sleep loop until the new file is
         found, so the user should stop the sioseis job by using a
         negative number in file "in".

FCSET  - First channel set.  The SEG-D format allows all traces with
         similar characteristics to be grouped together.  If traces
         have different trace length, all traces with the same length
         are grouped together.  Likewise, auxiliary traces belong
         to a different set from seismic traces.
       = 99, then all channel sets are processed.
         Preset = 99 

LCSET  - Last channel set.  Each channel starts with trace 1, however
         SEGDDIN will renumber the traces if more than 1 channel set
         is processed.
         Preset = The last channel set

FFILEN - The first file number to read from IPATH.  File numbers
         less than FFILEN will be omitted.  Only used with 
         FORMAT GEOMETRICS
         Preset = 99999

LFILEN - The last file number to read from IPATH.  File numbers
         greater than LFILEN will be omitted.  Only used with
         FORMAT GEOMETRICS
         Preset = 999999999

FILINC - The increment between FFILEN and LFILEN.  FILINC 99999
         indicates that all shots between FFILEN and LFILEN will
         be used regardless of order.  Only valid when FFILEN is
         given.
         Preset = 99999

FTR    - The first trace within each channel set to process.
         Trace numbers less than FTR will be omitted.
         Preset = 1     e.g.   ftr 97

LTR    - The last trace within each channel set to process.  Traces
         with numbers larger than LTR will be omitted.
         Preset = The largest data trace number in the channel scan.

TRINC  - The increment between traces.  The trace skip increment.
         preset = 1      e.g.  trinc 2  every other trace is skipped

SECS   - The maximum number of seconds of data to process.  Zero fill
         or padding will NOT be done if SECS exceeds the SEG-D
         record length.
         Preset = length in the header.     e.g.   secs 6

STIME  - The time of the first data to output.  The delay of the 
         trace after reformatting.  The data times will be from STIME
         to STIME + SECS.  The first portion of the data trace will
         be discarded whenever STIME is greater than the delay of the
         recorded data.  STIME less than the recorded delay will NOT
         result in zero padding.  e.g. STIME must be greater than or
         equal to the deep water delay.
         Preset - The recorded delay.   e.g. stime 4.0

DECIMF - Sample interval decimation factor.  
         Preset = 1,     e.g.   decimf 2   decimates by a factor of 2

NTRGAT - The number of traces per gather.  SIOSEIS requires RPs to be
         terminated with a -1 in word 51 of the SEGY trace header.  
         Because this is unique to SIOSEIS, gathers from other 
         computers may be converted by setting NTRGAT to the proper
         value.  SEGDIN will set every NTRGAT trace to be a
         terminator.  e.g. ftr 91 ltr 96 ntrgat 6 will read only
         traces 91 - 96 and will set every trace 96 (the sixth trace
         to be read) to be a gather terminator.
         Preset = 0,    e.g.  ntrgat 12

RENUM  - Renumbers the shots (file numbers) so that the first shot
         read will be RENUM and successive shots will be incremented
         by 1.
         Preset = 0,    e.g.   renum 1

RETRAC - Renumber the trace numbers within each shot/rp.  Most recording
         systems start each channel set with trace 1.
       <0, The trace number is the accumulated trace count within each
         file.  When there are multiple channel sets the trace numbers
         will always increase.  This is what is used by UKOOA.
       =0, The trace number is the trace number within the SEG-D shot.
       >0, The first trace of each shot starts with RETRAC.
         Preset = 0.

FORMAT - The type of SEG-D format.
       = SEG-D, the preset.  The SEG-D external header is searched
         for NMEA strings $GPGGA, $DBT, and $SDDBT
       = seisnet,  The data from the PC used on the Ewing for splitting
         the seismic data from the Syntron.
       = GEOMETRICS, generates Geometrics style filenames (*.sgd) based
         on FFILEN and LFILEN.  IPATH must be the name of the directory
         containing the SEG-D shot files.  FFILEN and LFILEN are required.
       = LDEO, The LDEO Syntron external header is expected.  The
         Digiscan bird blocks, if present, are passed to process GEOM.
       = ARAM, Adds 1 to the SEGD trace "record length" setting.
       = LG2019, For the R/V Langseth 2019 cruise where the Syntron recorder
         wrote an extra word (4 bytes) on each trace.
         Preset SEG-D

NSPFILE - Number of Shots Per seg-y FILE.  SEGDDIN will set a flag for
          processes OUTPUT and DISKOX to start a new file after NSPFILE
          shots have been written.  The new output file includes the
          SEG-Y ASCII and binary headers.  The DISKOX opath parameter
          should be set to DATE or SHOTNO to automatically generate
          the output disk file names.
          Preset = none      e.g.    nspfile 100

LOGPATH - The pathname of a file that will contain a "log" of each
          shot.  The shot number, file number, time and position of
          each shot will be recorded.
          Preset = none       e.g.    logpath   log

DESCALE - A yes/no switch indicating whether to apply the SEG-D 
          "descalar" multiplier to every amplitude.  The descalar
          brings the data back to the recording system input
          level,  See the SEG standard for further information.
          PRESET = NO  (prior to rev. 2013.4)          e.g.   descale yes
          PRESET = YES (after rev. 2013.4)

LPRINT - The bit oriented debugging print switch.  
       = 32, The SEG-D External header is printed as an ASCII string.
       = 255, Turns all bits on.  May cause a lot of printing.
       


PARAMETERS FOR READING BY GMT
-----------------------------
NOTE:  GMT as used by these parameters is the time contained
       in the SEG-D General Header.  On the Ewing, this is the
       Syntron clock, not the external GPS clock used as
       "the Official Shot Time".

FDAY   - The Julian day of the first shot to be read from IPATH.
         preset = the day of the first shot    e.g. fday 365

LDAY   - The Julian day of the last shot to be processed.
         preset = fday.    e.g. lday 366

FGMT   - The GMT of the first data to extract from IPATH/FFILEN.  Shots
         prior to FGMT will not be processed.
         preset = the GMT of the first shot (FFILEN).

LGMT   - The GMT of the last shot to extract from IPATH.
         preset = the last shot (LFILEN).



DEPRECATED PARAMETERS
---------- ---------
FORMAT HTI, The HydroScience SS format with a 32 byte PC header and
         24 bit integer (SEG-D 8036) data word.
TR0    - A YES/NO switch indicating that the SEG-D external header
         should be written and saved in a disk file similar to the
         old Digicon/LDGO trace 0.  The disk file will start with 'tr0'
         and have the Syntron date of the first shot appended to it.
         Not to be confused with process diskox or output parameter 
         TRACE0.
         Preset = no      e.g. tr0 yes
************************************************************************
          SPECIAL INFORMATION FOR THE LDEO R/V MAURICE EWING
************************************************************************

     SEGDDIN uses the LDEO "shot point" number, "shot time", 
navigation (lat/long), and Hydrosweep water depth, which are in the
SEG-D external headers.
     LDEO supplies a daily navigation file that lists every shot
point number, "official shot time", and position.  This file is
called a ts.n file.  ts.n files do not contain the SEG-D file
number.
     SEGDDIN optionally carries the old DIGICON "trace 0" forward.
Trace 0 contains the nonseismic information in the SEG-D General
and External Headers.  SIOSEIS process OUTPUT parameter 
TRACE0 YES will write these headers as SEG-Y trace number 0 and
trace id 28 (see the SEG-Y documentation).

     The Hydrosweep water depth is inserted as a floating point
number into the 54th real word of the SEG-Y trace header and is
converted to time by dividing by 750. and placed in real word 50.
The new (2001) Spectra/Syntron system does not put the Digicourse
streamer depth in SEG-D data, instead it is now in an external
UKOOA navigation file.

     The SEGDIN code is:
(where ibuf is 16 bit integers, lbuf is 32bit integer, buf is REAL)

          lbuf(3) = ldgo_shotno   ! or SEGD shot number if not LDEO
          lbuf(4) = itrcno        ! shot trace number
          lbuf(5) = ifilen        ! SEGD file number
          ibuf(15) = 1            ! SEGY trace id
          buf(46) = AMAX1(delay(icsn),stime)  ! REAL delay
          ibuf(55) = NINT(buf(46) * 1000.)    ! delay in mils
          ibuf(58) = (nsamps + decimf - 1) / decimf  ! number of samples
          ibuf(59) = micros * decimf  ! sample interval in micros
          buf(49) = si * decimf   ! REAL sample interval in seconds
          lbuf(16) = wdepth       ! integer water depth
          ibuf(79) = ldgo_yr      ! year of "official shot time"
          ibuf(80) = ldgo_day     ! day of "official shot time"
          ibuf(81) = ldgo_hr      ! hour of "official shot time"
          ibuf(82) = ldgo_min     ! minute of "official shot time"
          ibuf(83) = ldgo_sec     ! second of "official shot time"
          ibuf(84) = ldgo_mil     ! "millisecond of "official shot time"
             ***   This use of word 84 is an SEG-Y violation  ****
          ibuf(36) = -10          ! scalar for coordinates
          lbuf(19) = NINT(ship_long*360.*60.*10.)  ! shot x-coordinate
          lbuf(20) = NINT(ship_lat*360.*60.*10.)   ! shot y-coordinate
          lbuf(21) = NINT(ship_long*360.*60.*10.)  ! shot x-coordinate
          lbuf(22) = NINT(ship_lat*360.*60.*10.)   ! shot y-coordinate
          ibuf(45) = 2
          buf(50) = wdepth / 750.
          buf(54) = wdepth

If process GEOM parameter GXP and BGP are used, the group offset and
streamer depth are added as:
          lbuf(10) = NINT(range)
          lbuf(11) = -NINT(depths(lbuf(4))*100.) | streamer depth in cm
.

SIOSEIS SEGDDIN LDEO error and warning messages:

1)  ***  WARNING  ***  Bad LDEO clock.
    This message occurs when the LDEO "official shot time" does not
have a '+' or '-' quality flag between the year and day of year.

2)  ***  WARNING  ***  Bad LDEO block.
    This message occurs when the LDEO nav block has garbage in place
of the GPS fix.

3)  ***  WARNING  ***  Bad LDEO Hydrosweep of XXXXXX
    This message occurs when the Hydrosweep center beam depth is
greater than 10000 or less than 100.  The previous depth is substituted.


Copyright (C) The Regents of the University of California
ALL RIGHTS RESERVED.
Written by Paul Henkart, Scripps Institution of Oceanography