Menlo_report Configuration File Commands

(last revised 3 November 2010)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Menlo_report's file-naming convention
5. Setting up permissions on a remote Sun machine & local machine

On startup, menlo_report reads the configuration file named on the command line. Commands in this file set up all parameters used in transferring event files to a remote machine. In the control file, lines may begin with a valid menlo_report 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

#
# This is menlo_report's parameter file

#  Basic Earthworm setup:
#
MyModuleId         MOD_REPORT     # module id for this instance of report
RingName           HYPO_RING      # ring to get input from
LogFile            1              # 0 to completely turn off disk log file
HeartBeatInterval  15             # seconds between heartbeats

# List the message logos to grab from transport ring
#              Installation       Module          Message Types
GetEventsFrom  INST_WILDCARD    MOD_EQPROC      # hyp2000arc & h71sum2k

# Set suffixes for output filenames
# NOTE: If a suffix is "none", no file will
#       be reported for that type of message
ArcSuffix     ".arc"              # suffix for archive (hinvarc message) files
SumSuffix     ".sum"              # suffix for summary (h71sum message) files
TmpRemoteFile "temp.tmp"          # name for remote file while it's being copied

# Local directory to write temporary files in
LocalDir      /home/earthworm/run/log
KeepLocalCopy

# Create name for local file using the event origin time and
#   - last 2 digits of the event id and ArcSuffix/SumSuffix
#     this is the default
#     (i.e.  201011040930_57.arc)
#   - all digits of the event id, plus id-version,  and ArcSuffix/SumSuffix
#     (i.e.  201011040932_0000097658_2.arc)
#     to create long file names declare parameter EnableLongFileName
#     This parameter is useful only when KeepLocalCopy is also declared
# EnableLongFileName

# Info about remote machine to write files on
RemoteHost    squash                	# copy eq files to this machine
RemoteDir     /home/earthworm/quakes    # put them in this directory
RemoteUser    whoever            	# as this user
RemotePasswd  whatever                  # with this password;
                                        #  Required for NT version
                                        #  Not used by Solaris version

2. FUNCTIONAL COMMAND LISTING

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

	Earthworm system setup:
                GetEventsFrom         required
		HeartBeatInterval  			required
 		MyModuleId                	required
		RingName	                  required

	Local/Remote machine info:
		LocalDir	   	required
		RemoteDir	   	required
		RemoteHost	   	required
		RemoteUser	   	required
		RemotePasswd	   	required
                TmpRemoteFile           required

	Output Control:
		ArcSuffix		required
		SumSuffix		required
                KeepLocalCopy
                EnableLongFileName
		LogFile		   	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 the values used by Calnet are listed after each command description.


command arg1				processed by		function

ArcSuffix suffix			menlo_report_config	output
Sets a character string suffix that is used in naming the output files which contain hypoinverse archive messages. See section 3 below for a full description of menlo_report's file-naming convention. suffix can be enclosed in double-quotes, but is not required to be. suffix may be given with or without the period (for example, both ".arc" and "arc" are valid suffixes and will result in the same file name). If suffix is "none", menlo_report will not write or deliver files for hypoinverse archive messages.

Default:  none				Calnet:  ArcSuffix ".arc"

EnableLongFileName				menlo_report_config 	output
The parameter EnableLongFileName is useful only when KeepLocalCopy is also declared.
File name can be created in two different ways:

Default:                    # File name will be like 201011040930_57.arc
Example: EnableLongFileName # File name will be like 201011040932_0000097658_2.arc

GetEventsFrom inst mod_id		menlo_report_config	Earthworm setup
Controls the earthquake messages input to menlo_report. menlo_report will only process hypoinvserse-archive and hypo71-summary messages that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Only 1 "GetEventsFrom" command may be issued; wildcards (INST_WILDCARD and MOD_WILDCARD) will force menlo_report to process all archive and summary messages, regardless of their place of origin.

Default:  none
Calnet:   GetEventsFrom  INST_MENLO  MOD_EQPROC

HeartBeatInterval nsec			menlo_report_config	Earthworm setup
Defines the number of seconds nsec between TYPE_HEARTBEAT messages issued by menlo_report.

Default:  none				Calnet:  HeartBeatInterval 15

KeepLocalCopy				menlo_report_config 	output
Sets a flag such that local copies of archive and summary files are NOT deleted after they are sent to the remote machine. This command is optional; if it is omitted, local files are deleted after they have been successfully copied to the remote machine (local files are always saved if there is an error in sending the file to the remote machine).

Default:  delete local archive & summary files

LocalDir path				menlo_report_config	machine info
Defines the local directory into which menlo_report should write its temporary event files. menlo_report changes its working directory to path. On OS/2, path must be on the same disk that menlo_report was started from. The local temporary files are removed after they have been successfully transferred to the remote machine. If an error occurs on transfer, menlo_report sends an error message and does not remove the local file.

Default:  none
Calnet:   LocalDir /home/earthworm/run/log

LogFile switch				menlo_report_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, menlo_report will write a daily log file(s) called menlo_reportxx.log_yymmdd where xx is menlo_report'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			menlo_report_config	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_REPORT

RemoteDir path				menlo_report_config	machine info
Defines the directory path on the remote machine in which to place the event files.

Default:  none

RemoteHost host				menlo_report_config	machine info
Specifies the remote machine host to place the event files on. host is a character string; it can be either the remote host's name or its IP address. See section below on setting up permissions on remote machine.

Default:  none

RemoteUser username			menlo_report_config	machine info
Copy the event files to the remote host as username. The files on the remote machine will be owned by username. username must have permission to write in the directory assigned by "RemoteDir" command.

Default:  none

RemotePasswd passwd			menlo_report_config	machine info
Specifies the password passwd for the remote user on the remote machine. The OS/2 version requires that passwd be the actual password for the remote user. The Solaris version, on the other hand, does not need to use passwd; therefore, it should be set to a dummy character string for security reasons.

Default:  none

RingName ring				menlo_report_config	Earthworm setup
Tells menlo_report which shared memory region to use for input/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.

Default:  none				Calnet:  RingName HYPO_RING

SumSuffix suffix			menlo_report_config	output
Sets a character string suffix that is used in naming the output files which contain hypo71-format summary messages. See section 3 below for a full description of menlo_report's file-naming convention. suffix can be enclosed in double-quotes, but is not required to be. suffix may be given with or without the period (for example, both ".sum" and "sum" are valid suffixes and will result in the same file name). If suffix is "none", menlo_report will not write or deliver files for hypo71-format summary messages.

Default:  none				Calnet:  SumSuffix ".sum"

TmpRemoteFile tmpname 			menlo_report_config	machine info
Specifies a character string tmpname to use for the name of the remote file while it is being transferred to the remote machine. tmpname can be enclosed in double-quotes, but is not required to be. After the file transfer is complete, the remote file is renamed with the final file name (using the convention described in section 3.)
Warning: if more than one copy of menlo_report is transferring files to the same remote directory, be sure that they are using different tmpnames, otherwise they may over-write each other's files!

Default:  none
Example:  TmpRemoteFile "report.tmp"

4. MENLO_REPORT'S FILE-NAMING CONVENTION

Menlo_report writes one temporary file for each message it processes. The prefix of each file name is unique for each event; it is derived from the event origin time and follows the convention "yyyymmddhhmm_xx" where:

   yyyymmdd is the UTC date of the event origin time,
   hhmm   is the UTC hour-minute of the event origin time, and
   xx     is the last 2 digits of the event id assigned by binder.

The suffix denotes the type of message the file contains. The suffix is set by the user in menlo_report's configuration file with these commands:
   ArcSuffix   sets the suffix for files containing a
               hypoinverse archive message   (ex: ArcSuffix ".arc").
   SumSuffix   sets the suffix for	files contain a
               hypo71-format summary message (ex: SumSuffix ".sum").

Example file names:   199602131145_78.arc
		      199602131145_78.sum
Menlo_report writes its local temporary files into the directory set by the "LocalDir" command. The local temporary files are removed after they have been successfully transferred to the remote machine. If an error occurs on transfer, menlo_report sends an error message and does not remove the local file.

5. SETTING UP PERMISSIONS ON A REMOTE SUN MACHINE & LOCAL MACHINE


Module Index | Menlo_report Overview

Contact:
Questions? Issues? Subscribe to the Earthworm Google Groups List.