wiki:menlo_report
Last modified 8 years ago Last modified on 05/02/12 09:20:33

Earthworm Module: menlo_report

Contributed by:

Function

Transfers single-event HYPOINVERSE archive files to a remote machine.

Details

Menlo_report is a module that writes earthquake information to disk and transfers it to a remote computer. Menlo_report watches the configured transport ring for hypoinverse archive messages (TYPE_HYP2000ARC) and summary messages (TYPE_H71SUM2K). When it finds a message of interest, menlo_report writes the message to a disk file, then copies it to the remote computer via "rcp". If the rcp succeeds, the local file is removed (unless menlo_report has been configured to "KeepLocalCopy"). If the rcp fails, the local file is NOT removed, and an error message is sent to the statmgr.

Configuration File Commands

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!).

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

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

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.

The following list is organized by:

command [argument here]

ArcSuffix [suffix]
Processed by: menlo_report_config
Function: 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
Processed by: menlo_report_config
Function: output

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

  • event origin time,

last 2 digits of the event id
and ArcSuffix/SumSuffix
(i.e. 201011040930_57.arc) THIS IS DEFAULT.

  • event origin time,

all digits of the event id,
version of the event id,
and ArcSuffix/SumSuffix
(i.e. 201011040932_0000097658_2.arc)
to create long file names declare parameter EnableLongFileName

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

GetEventsFrom [inst mod_id]
Processed by: menlo_report_config
Fucntion: 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]
Processed: menlo_report_config
Function: Earthworm setup

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

Default:  none				Calnet:  HeartBeatInterval 15

KeepLocalCopy
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: machine info

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

Default:  none

RemoteHost [host]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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]
Processed by: menlo_report_config
Function: 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"

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.

SETTING UP PERMISSIONS ON A REMOTE SUN MACHINE & LOCAL MACHINE

  • For menlo_report to work, make sure that the following files are set up properly on the Sun machine specified in the "RemoteHost" command:
      /etc/hosts         must contain the local_hostname and its IP address
    
      /etc/hosts.equiv   must contain local_hostname
    
      .rhosts            in the home directory of the user specified by
    		     the "RemoteUser" command must contain a line:
                         local_hostname local_username
                         describing who is running menlo_report (and thus
    		     who is trying to write the files).
    
  • Additionally, the user identified by "RemoteUser" command must have write permission in the "RemoteDir" directory.
  • On the local machine, make sure that entries for the remote host are included in these files:
       c:\WINNT\system32\drivers\etc\hosts   for a local NT machine
    
       /etc/hosts	      for a local Solaris machine
       /etc/hosts.equiv
    

Helpful Hints