# 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:
> - 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		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

- 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

Module Index | Menlo_report Overview