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:
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).# 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).
#
#
# 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)
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
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 secondsDefault: 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