# gcf2ew Configuration File Commands

(Version 1.0.0 - last revised 17 May, 2006)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Descriptor file example

On startup, gcf2ew reads the configuration file named on the command line. As always, the configuraton file contains comments:

>     #  marks the line as a comment (example: # This is a comment).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). gcf2ew supports one diagnostic command line option, -v is for verbose mode so that you can see packets coming in.

## 1. EXAMPLE CONFIGURATION FILE

    #
    # gcf2ew configuration file
    #
    # This code receives GCF packets from an MSS100, converts them into
    # Earthworm trace buf messages, and stuffs them into a wave ring.
    #
    #
     ModuleId	MOD_GCF2EW	# module id for this import,
     RingName	WAVE_RING	# transport ring to use for input/output,

     HeartbeatInt	10		# Heartbeat interval in seconds
    				# this should be half the g2ew.desc heartbeat!

     LogFile	1		# If 0, don't write logfile at all,

     SaveSOH2LOG 	1		#  write LOG chans to log file
    				# this is useful for debugging timing or
    				# data logger problems.

    TimeoutNoSend	5		# If no data for X seconds from GCF for
    				# X seconds, then kill process (HB and
    				# main thread).
    				# NOTE: this timeout does not take effect until
    				# a trace data packet comes from the MSS100. That
    				# is, LOG channels do not count!
    				#
    				# Iff TimeoutNoSend == 0, then this data
    				# check is DISABLED and gcf2ew will only die
    				# if EW dies.

    #
    # one of the following input modes should be used
    #

    HostAddress     mss             # the IP or hostname of the MSS100 unit
    PortNumber      3001            # the port number of the MSS100 unit

    # OR

    #gcfservAddress  isti		# the IP or hostname of the gcfserv program
    #PortNumber      45670          # the port number of the gcfserv program

    # OR

    #SerialPort     /dev/term/a     # the serial port to which the DM is connected
    #BaudRate       19200a		# an allowed baud rate for the solaris serial ports

    # The following mapping is used to map a system_id and stream_id to an SCN and as
    # a SELECTOR on those channels which should be passed along to Earthworm...channels not
    # matching the criteria below are dumped.
    # Example
    #               Sys     Strm    S       C       N
    InfoSCN         0D0081  1031Z2  ISTI    HHZ     CI
    InfoSCN         0D0081  1031N2  ISTI    HHN     CI
    InfoSCN         0D0081  1031E2  ISTI    HHE     CI

## 2. FUNCTIONAL COMMAND LISTING

Below are the configure commands recognized by gcf2ew, grouped by the function they influence. Most of the commands are required.

             Earthworm system setup:
     		MyModuleId	   	required
    		RingName	   	required
    		HeartbeatInt	   	required
    		TimeoutNoSend	   	required

    	Input Control:
    		HostAddress	  	required
    		PortNumber	  	required

    			or

    		gcfservAddress	  	required
    		PortNumber	  	required

    			or

    		SerialPort	  	required
    		BaudRate	  	required

    	Output Control:
    		LogFile		   	required
    		SaveSOH2LOG		optional
    		InfoSCN			required
    		InfoSCNL			required

## 3. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

    command arg1				processed by		function

    HeartbeatInt beat			HeartBeat		Earthworm setup

> Beat the gcf2ew heart every beat seconds. This is implemented as a separate thread in gcf2ew.

    HostAddress IPname or number			main		Earthworm setup

> Connect to the mss100 at the ip address IP address. This option accepts fully qualified domain names as well as IP numbers. Note that the PortNumber is also required.

    gcfservAddress IPname or number			main		Earthworm setup

> Connect to the gcfserv module at the ip address IP address. This option accepts fully qualified domain names as well as IP numbers. Note that the PortNumber is also required. Default port numbers for gcfserv are 45670.

    SerialPort SerialDevice			main		Earthworm setup

> Connect to the DM24 at the SerialDevice specified. To use this input mode, a BaudRate must also be provided.

    BaudRate rate			main		Earthworm setup

> Connect to the DM24 at the BaudRate rate specified. To use this input mode, the SerialPort directive must also be used. The baud rates are the standard allowable rates on a solaris host: 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.

    SaveSOH2LOG switch			none 		Main gcf2ew Thread

> Sets the on-off switch for writing GSL GCF STATUS channels to the LogFile. If switch is 0, no LOG channels will be written to the log. If switch is 1, gcf2ew will write all LOG channels to the LogFile. Turning this on will automatically turn on writing of a LogFile.

>     Default:  0 - do not use logit() for LOG channels

    LogFile switch				GetConfig		Earthworm Setup

> Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, gcf2ew will write a daily log file(s) called gcf2ewxx.log_yymmdd where xx is gcf2ew's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

>     Default:  none

    MyModuleId mod_id			GetConfig		Earthworm setup

> Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number.

>     Default:  none
>     Calnet:   MyModuleId MOD_Q2EW

    RingName ring				GetConfig		Earthworm setup

> This is the ring into which the waveforms and messages are sent.

>     Default:  none, required option
>     ATWC:   RingName WAVE_RING

    InfoSCN System Stream S C N			insertSCN		Main gcf2ew Thread

> This command is used to define how gcf2ew maps a System and Stream ID to a Station Channel Name. It is also used as a channel selector as only those streams specified get passed on to the Earthworm Wave Ring. System is for the DM System ID name, Stream is for the DM Stream ID name ...aka channel name in GCF, S is for station name, C is for channel identifier, and N is for network code.

>     #               Sys     Strm    S       C       N
>     InfoSCN         0D0081  1031Z2  ISTI    HHZ     CI
>     InfoSCN         0D0081  1031N2  ISTI    HHN     CI
>     InfoSCN         0D0081  1031E2  ISTI    HHE     CI

    InfoSCNL System Stream S C N L			insertSCN		Main gcf2ew Thread

> This command is used to define how gcf2ew maps a System and Stream ID to a Station Channel Name. It is also used as a channel selector as only those streams specified get passed on to the Earthworm Wave Ring. This forces the trace buf type to be of type TRACEBUF2. InfoSCN and InfoSCNL cannot be mixed. System is for the DM System ID name, Stream is for the DM Stream ID name ...aka channel name in GCF, S is for station name (5 chars), C is for channel identifier (3 chars), N is for network code (2 chars), and L is for location code (2 chars).

>     #                Sys     Strm    S       C       N   L
>     InfoSCNL         0D0081  1031Z2  ISTI    HHZ     CI  00
>     InfoSCNL         0D0081  1031N2  ISTI    HHN     CI  00
>     InfoSCNL         0D0081  1031E2  ISTI    HHE     CI  00

    PortNumber number			main		Earthworm setup

> Connect to the mss100 or gcfserv at the ip address specified and this port number. Note that the HostAddress or gcfservAddress is also required for this directive. PortNumber defaults to 3001 for mss and 45670 for gcfserv.

    TimeoutNoSend timeout			HeartBeat		Earthworm setup

> If no waveform packets come from the DM after timeout seconds, the gcf2ew module will notify statmgr and die. If timeout is set to 0, then the gcf2ew module will never check for this timeout. If set to 0, gcf2ew will only die if the Earthworm system calls for its termination. This timeout begins once the first Waveform packet is received from the DM served by this MSS100.

>     Default:  none, required option
>     ATWC:   TimeoutNoSend 0

## 4. DESCRIPTOR FILE EXAMPLE

Here is a copy of the gcf2ew.desc file as implemented. Note that all causes of death for gcf2ew feed through the function gcf2ew_die() which logs all causes of death using logit() and sends a message to the statmgr utility.

    modName  gcf2ew
    modId    MOD_GCF2EW
    instId   INST_UNKNOWN

    restartMe       # restart this sucker as it is critical to data collection
    #
    #
    #    Heartbeat Specification.  If the status manager does not receive
    #    a heartbeat message every  seconds from this module, an
    #    error will be reported (client module dead).   is the maximum
    #    number of pager messages that will be reported and  is the
    #    maximum number of email messages that will be reported.  If the
    #    page or mail limit is exceeded, no further errors will be reported
    #    until the status manager is restarted.
    #
    tsec: 30  page: 0  mail: 99

    # from die.h:
    #define GCF2EW_DEATH_SIG_TRAP     1
    #define GCF2EW_DEATH_EW_PUTMSG    2
    #define GCF2EW_DEATH_EW_TERM      3
    #define GCF2EW_DEATH_EW_CONFIG    4
    #define GCF2EW_DEATH_GCF_TIMEOUT  5

    # these are the statmgr messages that gcf2ew will send before dieing
    #
    err: 1  nerr: 1  tsec: 0  page: 5  mail: 20
    text: "SIGNAL caused gcf2ew to die"
    #
    err: 2  nerr: 1  tsec: 0  page: 5  mail: 20
    text: "EW tport_putmsg() failed, gcf2ew dead"
    #
    err: 3  nerr: 1  tsec: 0  page: 5  mail: 20
    text: "EW TERMINATE recv'd, gcf2ew dead"
    #
    err: 4  nerr: 1  tsec: 0  page: 5  mail: 20
    text: "EW config problems on startup, gcf2ew dead"
    #
    err: 5  nerr: 1  tsec: 0  page: 5  mail: 20
    text: "gcf2ew received NO DATA for configured TIMEOUT and died"
    #

Module Index | gcf2ew Overview