EARTHWORM GETLIST

Getlist - view list of Events

User's Guide

Lucky Vidmar

March 12, 2002

Getlist is the CGI program that allows the users to retrieve and view events from the database. It operates in two modes:

Change Map - allows zooming and panning around the world
View Data - allows more information about events to be retrieved

In both modes, the map shows the list of events from the database located in the selected region, and matching the additional criteria specified in the form just below the map:

Origin Time
Depth
Magnitude

The user can also navigate directly to one of the pre-defined rectangular regions shown on the right side of the map.

Change Map Mode

Here, the user can "walk" around the world by zooming in and out, re-centering the map, or selecting from the list of pre-defined rectangular regions. The idea is that the user would find the region of interest, then click on View Data to gain access to the desired information about events.

View Data Mode

Here, the user is shown a list of events within the region of interest that match the Origin Time, Depth, and Magnitude criteria from the selection form. The user is shown the origin time, location, depth, magnitude, and author fields for each event. Depending on the configuration (see below), the user may be given the option to enter Quick Review for an event, see a GIF snapshot of the waveforms, download trace data, either in counts or ground motion, as well as review the alarms that have been sent for this event.

Configuration

Getlist requires that getlist.d configuration file be present in web/params directory. The following types of configuration options are available:

Web connection parameters

db_user; db_pwd; db_service

Page appearance parameters

background color, header and footer logo, if desired

Map display options

Maximum number of events or stations to display on the map

Event list options

Maximum number events to retrieve from the database
How many events to show per page - allows paging through a potentially very long list of events within a time/space region
What attributes (columns) to show

Picks
Trace data
Alarms
Ground motion data

Pre-set maps - the user can specify a hierarchy of arbitrary lat/lon regions. For example, there could be a USA map which is the parent of several regional maps. On the same level as the USA map might be maps of other countries. Therefore, the use creates parent-child relationships, as well as sibling relationships among maps. Then, the map pages will allow navigation to parent maps, sibling maps, and children maps only.

Map Creation

Getlist maps are created dynamically based on the area of interest specified by the user. They are generated using GMT. Therefore, GMT must be properly installed on the system before getlist will work.

Since GMT produces output in PostScript, it is necessary to convert it to GIF in order to be displayed through the web-server. Currently, we use ImageMagick's convert utility to do this conversion. Therefore, ImageMagick must also be correctly installed on the system.

Besides setting up getlist.d, the user must ensure that there is the map creation script called make_map under web/bin. The user may need to configure the paths in the script to reflect the local installation points of GMT and ImageMagick.

SAMPLE FILES

Getlist.d configuration file

# Config file for getlist

DBuser db_user

DBpassword db_passwd

DBservice db_service

Logfiledir ../log/

# hostname of the machine holding up web pages

WebHost webhost.domain

##############################################################################

# OPTIONAL APPEARANCE CONFIGURATION:

# Set the following to customize the appearance of the page:

# - BackgroundColor: Set to any valid HTML color string

# - HeaderLogo: Full path to the file containing the picture to be

# displayed on the top of the page.

# - FooterLogo: Full path to the file containing the picture to be

# displayed on the bottom of the page.

# Logo note: The logo file must be a valid HTML picture file (gif, jpeg..)

# sized to the desired size. It will be placed at the top or the

# bottom exactly as it appears in the file. The file name

# must be relative to the web-server's root directory.

##############################################################################

BackgroundColor lemonchiffon

HeaderLogo ../images/c_USGSid.jpg

FooterLogo ../images/c_USGSid.jpg

# Which columns to show

ShowPickCol

ShowStasCol

ShowTraceCol

ShowAlarmsCol

MapPixelWidth 400

MapPixelHeight 400

MaxNumOfStationsDisplayed 5000

# Maximum number of events that will be displayed on the map

MaxNumOfEventsDisplayed 100

# Maximum number of events that will be displayed in the list

MaxNumOfEventsRetrieved 10000

#NumOfDaysToShow 7 # Number of days in the past from the current time

# that should be shown by default

#MinNumStasToShow 3 # If present, only events with more than

# this many stations will be shown in

# the event list

EventsPerPage 10 # If present, Show this many events

# on each page, and include links to

# navigate back and forth

DefaultMapID 1.6.6

#Map Num Name Lat1 Lon1 Lat2 Lon2 Riv Pol L/L Lines Border Proj Focal PtCtr LatCtr Lon

Map 1 World(West) -100 0 90 360 1 8 0 0 a Y 10 270

Map 2 World(East) -100 0 90 360 1 8 0 0 a Y 10 90

Map 2.1 Africa -37 -20 40 62 3 8 0 0 m N

Map 2.2 Asia 15 55 57 125 3 8 0 0 s Y 35 90

Map 2.3 Aust/Indo/NZ -55 90 20 195 3 8 0 0 m N

Map 1.3 Canada 41 -142 85 -50 3 8 0 0 s Y 63 -96

Map 2.4 Europe 30 -30 72 50 3 8 0 0 m N

Map 2.5 Japan 27 120 55 160 3 8 0 0 s Y 40 140

Map 1.4 Middle_America 6 -118 33 -58 3 8 0 0 m N

Map 2.6 Middle_East 5 30 50 75 3 8 0 0 m N

Map 1.5 South_America -60 -95 15 -25 3 8 0 0 m N

Map 1.6 USA 15 -128 60 -64 3 8 0 0 m N

Map 1.7 Western_Pacific -25 120 35 210 3 8 0 0 m N

Map 1.6.1 Montana 41 -117 50 -103 3 8 0 0 m Y 47.00 -110

Map 1.6.2 California 45.25 -110 29.75 -132 2051 8 0 0 m Y 37.50 -122

Map 1.6.3 Pac_NW 54.25 -110 38.75 -132 2051 8 0 0 m Y 46.50 -122

Map 1.6.4 New_Madrid 40.25 -93 32.75 -85 2051 8 0 0 m Y 36.50 -89

Map 1.6.5 Hawaii 24 -154.50 18 -160.50 2051 8 0 0 m N

Map 1.6.6 Utah_Region 35.43 -119.52 46.68 -103.52 2051 8 0 0 m N

Map 1.6.6.1 Utah 36.75 -114.25 42.50 -108.75 2051 8 0 0 m N

Map 1.6.6.2 Yellowstone 44 -111.50 45.17 -109.75 2051 8 0 0 m N

Map 1.6.7 Alaska 45 -109 72 -179 3 8 0 0 a Y 65 -150

Map 2.7 Asia2 0 40 80 160 3 8 0 0 m Y 40 100

Map 1.6.2.1 Mammoth 37.85 -119.10 37.35 -118.40 1027 8 0 0 m Y 37.60 -118.75

Map 1.6.2.2 Geysers 38.55 -123.15 39.05 -122.45 1027 8 0 0 m Y 38.80 -122.80

# River Codes (use the sum of the desired rivers)

# 1 = Permanent major rivers

# 2 = Additional major rivers

# 4 = Additional rivers

# 8 = Minor rivers

# 16 = Double lined rivers

# 32 = Intermittent rivers - major

# 64 = Intermittent rivers - additional

# 128 = Intermittent rivers - minor

# 256 = Major canals

# 512 = Minor canals

# 1024 = All rivers and canals (1-10)

# 2048 = All permanent rivers (1-4)

# 4096 = All intermittent rivers (6-8)

# 8192 = All canals (9-10)

# Political Border Codes (use the sum of the desired boundaries)

# 1 = National boundaries

# 2 = State boundaries within the Americas

# 4 = Marine boundaries

# 8 = All boundaries (1-3)

Make_map script

#!/bin/csh -f

# make_map : Lucky Vidmar Fri Jan 22 13:02:01 MST 1999

# This csh script creates a map in GIF format according to the

# incomming arguments:

# $1 - File name of the resulting GIF file

# $2 - File name of the file containing the error indication number

# $3 - List of arguments used for creating the map. These should be

# valid arguments to be passed on to GMT's pscoast utility

# $4 - Unique ID, to append to temp filenames to ensure that

# simultaneous calls to make_map do not corrupt each other

# Since this script is intended to be called from a C function (as

# a part of a map server), it does not return any values directly.

# Instead, it writes a predefined error number (see list below)

# into the file given by the second argument $2.

# Valid error codes:

# 0 - No error. Map successfully generated.

# 1 - Error reported by GMT's pscoast - no map produced

# 2 - Error reported by pstogif - no map produced

# define error codes

set ERR_NOERR = 0

set ERR_GMT = 1

set ERR_CONVERT = 2

# Make sure we have the correct number of arguments

# If there is a problem here, we obviously can't write to the

# error file - simply report error and exit

if ($#argv != 4) then

echo "Usage: make_map map_file error_file GMT_parameters UniqueID"

exit -1

endif

# set the correct path

setenv PATH "$PATH":/usr/local/gnu/bin:/usr/local/pbmplus/bin:/usr/local/gmt/bin

set tmpfile = /tmp/EWPS_tmpfile_$4

set errfile = /tmp/EW_make_map_error_file_$4

set CREATE_MAP = pscoast

# Write the ERR_NOERR error code

echo $ERR_NOERR > $2

# set GMT defaults

# 1. Degrees lat and long should be displayed using NS and EW method

gmtset DEGREE_FORMAT 3 >& /dev/null

# Create the PostScript map using GMT's pscoast

($CREATE_MAP $3 > $tmpfile) >& $errfile

# Check the errfile for any errors

set foo = `cat $errfile | wc -l`

if ($foo != 0) then

echo "Call to $CREATE_MAP failed"

echo $ERR_GMT > $2

exit -1

endif

# Convert the PS file into gif

/usr/local/ImageMagick/bin/convert -crop 0x0 -colors 128 $tmpfile $1 >& $errfile

# Check the errfile for any errors

set foo = `cat $errfile | wc -l`

if ($foo != 0) then

echo "Call to convert failed"

echo $ERR_CONVERT > $2

exit -1

endif

rm -f $tmpfile

rm -f $errfile