# Coaxtoring Configuration File Commands

(last revised 29 July 1998)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description

On startup, coaxtoring reads the configuration file named on the command line. Commands in this file set up all parameters used in receiving UDP broadcast Earthworm messages from the network and placing them into shared memory. In the control file, lines may begin with a valid coaxtoring command (listed below) or with one of 2 special characters:

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

>     @  allows control files to be nested; one control file can be
>        accessed from another with the command "@" followed by
>        a string representing the path name of the next control file
>        (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

## 1. EXAMPLE CONFIGURATION FILE

    #
    #
    # coaxtoring configuration file
    #
    #   The setup is different for Solaris and NT. The specified address
    #   will be used to receive class c subnet broadcasts.
    #
    # Solaris:    InAddress must be of the form xxx.xxx.xxx.255
    # Windows NT: InAddress must be the complete local address, eg
    #             192.168.4.107
    #
    MyModuleId   MOD_COAXTORING_A   # Module id for this process
    RingName     WAVE_RING          # Write to this shared memory region
    LogFile      1                  # 1=write log file on disk; 0=don't
                                    # 2=write to module log but not stderr/stdout
    nMsgBuf      16                 # There should be at least one buffer per logo
    MsgMaxBytes  51740              # Size of biggest message to be received
    InAddress    192.168.4.255      # IP address of ethernet line to read

    PortNumber   990                # Usually 990 (waveforms) or 5555 (picks)
                                    # Under Solaris, if the port number is at
                                    #  or below 1024, the program must run as root.

    ScrnMsg      1                  # 1=print messages on screen; 0=don't
    HeartbeatInt 30                 # Heartbeat interval in seconds
    BufferReportInt 300             # Print high buffer count every n seconds

    RcvBufSize   260000             # Size of socket receive buffer, in bytes.
                                    # Set RcvBufSize to a large number to avoid
                                    #   dropping packets.
                                    # Max value is system dependent
                                    #  (typically 260000)
                                    # If you set =0, it will default to the
    				        # system default. (typically 8192)

## 2. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by coaxtoring, grouped by the function they influence. All of the commands are required; they must be specified in the control file in order for coaxtoring to operate.

             Earthworm system setup:
    		HeartBeatInt 	 	required
     		MyModuleId	   	required
    		RingName	   	required

    	Network Information:
    		InAddress	   	required
    		PortNumber	   	required

    	Message Handling:
    		nMsgBuf	   		required
    		MsgMaxBytes	   	required
    		RcvBufSize	   	required

    	Output Control:
    		ScrnMsg	   		required
    		LogFile		   	required
    		BufferReportInt   	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

    BufferReportInt nbytes			coaxtoring_config	msg handling

> Print high buffer count every n seconds

>     Default:  none
>     Calnet:   BufferReportInt 300

    HeartBeatInt nsec 			coaxtoring_config	Earthworm setup

> Defines the number of seconds nsec between TYPE_HEARTBEAT messages issued by coaxtoring.

>     Default:  none
>     Calnet:   HeartBeatInt 5

    InAddress a.b.c.d			coaxtoring_config	network info

> Tells coaxtoring the TCP/IP address of the ethernet line that it should listen to. a.b.c.d is a character string in tcp/ip's standard dotted-decimal notation that coaxtoring uses along with the port number from the "PortNumber" command to set up a socket from which it will receive UDP Datagram packets. Under Solaris, the "d" part of the address should be set to 255 (for example a.b.c.255). Under NT, the "d" part of the address should be set to the complete local address, eg 192.168.4.107.

>     Default:  none
>     Example:  InAddress 130.118.49.255 (Solaris)
>     Example:  InAddress 192.168.4.107 (NT)

    LogFile switch				coaxtoring_config	output

> 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, coaxtoring will write a daily log file(s) called coaxtoringxx.log_yymmdd where xx is coaxtoring'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

    MsgMaxBytes nbytes			coaxtoring_config	msg handling

> Sets the size, in bytes, of the working buffers that coaxtoring uses for rebuilding complete Earthworm messages out of the UDP packets. nbytes should be the size of the largest message you expect coaxtoring to receive. If coaxtoring receives a message larger than nbytes, it will drop the entire message and issue a TYPE_ERROR message containing the string "Message buffer overflow" and the logo of the dropped message.

>     Default:  none
>     Calnet:   MsgMaxBytes 51740

    MyModuleId mod_id			coaxtoring_config	Earthworm setup

> Sets the module id for labeling all outgoing heartbeat and error 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. All messages that coaxtoring receives from ethernet are tagged with their original logos when they are placed into shared memory.

>     Default:  none
>     Calnet:   MyModuleId MOD_COAXTORING

    nMsgBuf nbuf				coaxtoring_config	msg handling

> Defines the number of working buffers nbuf that coaxtoring should allocate. Coaxtoring uses the buffers for rebuilding complete Earthworm messages out of the UDP packets it receives from ethernet. There should be at least one buffer for each different message logo that coaxtoring might see. The maximum allowed number of buffers is controlled by MAX_BUF, currently defined to be 16 in coaxtoring.c. The size of each buffer is set with the "MsgMaxBytes" command.

>     Default:  none
>     Calnet:   nMsgBuf 16

    PortNumber port				coaxtoring_config	network info

> Defines the well-known port number port which coaxtoring will listen to. port is an integer that coaxtoring uses along with the address from the "InAddress" command to set up a socket from which it will receive UDP Datagram packets.
> NOTE: The port number must be greater than 1024. Smaller port numbers require root permission.

>     Default:  none
>     Example:  PortNumber 2025

    RcvBufSize ring				coaxtoring_config	Earthworm setup

> Tells coaxtoring the size of the socket receive buffer, in bytes. Set RcvBufSize to a large number to avoid dropping packets. Maximum value is system dependent, typically 260000. If no buffering desired, use the system default size, typically 8192. To determine the default size, set RcvBufSize to zero. When coaxtoring is restarted, it will log a message giving you the default buffer size. The maximum size can be found by trial and error. If the value exceeds the maximum value, coaxtoring will log the message: "Error resetting receive buffer size" and exit.

>     Default:  none
>     Example:  RcvBufSize 260000

    RingName ring				coaxtoring_config	Earthworm setup

> Tells coaxtoring which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. All messages that coaxtoring receives from ethernet are tagged with their original logos when they are placed into shared memory.

>     Default:  none
>     Example:  RingName WAVE_RING

    ScrnMsg switch				coaxtoring_config	output

> Sets a switch for writing messages to the screen. If switch is 1, a line is printed to the screen detailing the logo and the sequence number of each Earthworm message received from the ethernet. If switch is 0, no messages are written to the screen.

>     Default:  none
>     Example:  ScrnMsg 0

Module Index | Coaxtoring Overview