Search:
wiki:menlo_report
Last modified 17 months 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

### Download in other formats:

- Plain Text