# NRLDB Documentation

## Overview, Installation, Usage

## Table of Contents

Overview [3](#overview)

Installation Instructions [4](#installation-instructions)

Configuration [5](#__RefHeading___Toc30059695)

User Documentation [6](#user-documentation)

Logging [7](#logging)

Automation [9](#automation)

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## 

## Overview

The National River Location Database, NRLDB, is a software package that
transfers data from the IHFS database at each Weather Forecast Office to
a national database at NWS HQ. The purpose of this package is to have
the ability to have a record of all WFO IHFS information stored in one
place. This capability will allow for an easy way to backup this
important data and give a single admittance point to any office that
needs access to multiple other offices information.

The software is designed to run on a WFO Linux workstation.

Perl Packages that are required to run this script include the
following:

**[DBI]{.smallcaps}** - Used for accessing psql database.

**[A]{.smallcaps}ppConfig** -- Used to control command line parameters.

The nrldb.pl script requires that a control file and configuration file
be in place before normal operation can occur. More detail about these
files can be found below.

## 

## Installation Instructions

### A. Download and Install NRLDB tar file from LAD

Perform the following steps to complete the download:

1.  As the **user oper**, log on to **DX1**

2.  Change directory

**cd /awips/hydroapps/whfs/local/data/backup_db**

3.  Remove nrldb directory if it currently exists

> **rm --fr nrldb**

4.  Make a new nrldb directory

> **mkdir nrldb**
>
> **chmod 777 nrldb**

5\. Change directory

**cd nrldb**

6\. Place the NRLDB tar file (nrldb.tgz) in that newly created
directory:

**/awips/hydroapps/whfs/local/data/backup_db/nrldb**

7\. Untar the contents of the nrldb.tgz file using the command:

**tar --xvzf nrldb.tgz**

8\. Change the permissions on the nrldb.csh file

**chmod 755 nrldb.csh**

B.  **Check out and setup the NRLDB configuration**

1\. Test installation with following command:

**./nrldb.pl \--check**

The script should return the string 'installation complete' if all perl
paths and modules are correct. If errors print out on the screen some or
one components are not installed correctly.

2\. Set your local configuration by editing the **nrldb.conf** file with
the editor of your choice.

Edit the line that reads:

**site = "LWX"**

So that the line reads:

**site = "XXX"**

where XXX is **your** office's three letter site identifier.

Do not make any other edits to this file.

## User Documentation

**Usage**: nrldb.pl --t WFO\|RFC\|HQ \[ -i 'infile', -w 'wfo', -o
'output file'\]

**Options:**

-t, -type=office_type office type, mandatory option. Can be wfo, rfc or
hq.

-w, -wfo-id=wfo_id identifier for extracting secondary office data.

-r, -rfc-id identifier for extracting data from RCF

-o, -out-xmlfile=outfile xml output file if default name is not to be
used.

-i, -input-xmlfile=infile xml input file to use when running office type
HQ.

-local-control-file=contol_file use specified file as nrldb extraction
control file.

-u, -upload upload the xml to the national nrldb server.

-c, -check check for proper installation.

-v, -verbose print output to screen.

To run the NRLDB software as a WFO, navigate into the NRLDB directory
and execute the following command:

\> ./nrldb.pl --t wfo

This command will extract the primary office data from the IHFS database
and write it to an xml file. The default file name will have the format
WFO_nrldb.xml, where WFO is the identifier used in nrldb.conf. The xml
file will be created in the same directory as nrldb.pl is executed.

If you need to extract secondary office data from the database you can
use the --w option.

\> ./nrldb.pl --t wfo --w ILN

Running the above command would extract ILN data from your database and
create an xml file called ILN_nrldb.xml. (The data must exist in your
database for it to be extracted.)

### If you only want to upload the copy of xml in the NRLDB/ directory use the upload option: 

\> ./nrldb.pl --t wfo --u

To execute the process at an RFC, the --r option is required to let
specify what data should be extracted.

\> ./nrldb.pl --t rfc --r OHRFC

## Logging

nrldb.pl automatically creates an nrldb.log in the same directory as
nrldb.pl itself.

It will always create this log, but output to the screen is optional. To
have the log output displayed to your screen use the '-v' option for
verbosity.

\> ./nrldb.pl --v --t wfo

**The Control File**

The nrldb control file is a text formatted file that is downloaded from
the nrldb server each time the nrldb.pl script is run. There are two
files, nrldb_control_wfo and nrldb_control_rfc. Which one you receive
depends on what type you are running as.This file controls which tables
and which fields in those tables will be extracted to the xml file. This
file located on the NRLDB server so that a change in tables/fields would
not have to be configured at each wfo. You can specify a control file to
use of your own if need be. Using the --local-control-file option with
nrldb causes the national control file not to be downloaded and for the
specified control file to be used.

\> ./nrldb.pl --t wfo --local-control-file somefile.txt

The above would use 'somefile.txt' as the control file instead of
downloading the default nrldb control file.

The format of this file should be

\[table1\]

fields = *field1, field2,field3....*

\[table2\]

fields = *field1, field2,field3....*

\[table3\]

fields = ALL

You can use the 'ALL' value in the 'field' section if you want all the
fields from a table.

**Output**

All output is automatically written to the 'NRLDB.log' file in the nrldb
directory.

This file is appended to and the most recent execution can be found at
the bottom of the file. Unless specified with the --v option, no output
will be placed on your screen. If the --v option is used, it will
display the log data.

## Automation

This script is intended to run automatically without user input. To
accomplish this you must place an entry in the crontab. The crontab
requires certain env variables that are not contained within nrldb.pl.
For this reason, when running from the cron you must execute nrldb.csh
from the cron instead. This csh script will set up all env variables and
execute the default configuration for nrldb.pl

Add the execution of the nlrdb.csh script to your local DX1 cron
(SITEdx1cron) to run the nrldb process every day between 0600Z and
0700Z. Please follow the schedule below which details the time for each
site to execute the script on your local DX1 cron. For example, site OKX
would add the following to their SITEdx1cron file to execute the nrldb
software daily at **0645Z**:

**45 6 \* \* \* oper cd
/awips/hydroapps/whfs/local/data/backup_db/nrldb; ./nrldb.csh;**

ABQ 0600Z

ABR 0600Z

AFC 0601Z

AFG 0601Z

AJK 0602Z

AKQ 0602Z

ALY 0603Z

AMA 0603Z

APX 0604Z

ARX 0604Z

BGM 0605Z

BIS 0605Z

BMX 0606Z

BOI 0606Z

BOU 0607Z

BOX 0607Z

BRO 0608Z

BTV 0608Z

BUF 0609Z

BYZ 0609Z

CAE 0610Z

CAR 0610Z

CHS 0611Z

CLE 0611Z

CRP 0612Z

CTP 0612Z

CYS 0613Z

DDC 0613Z

DLH 0614Z

DMX 0614Z

DTX 0615Z

DVN 0615Z

EAX 0616Z

EKA 0616Z

EPZ 0617Z

EWX 0617Z

EYW 0618Z

FFC 0618Z

FGF 0619Z

FGZ 0619Z

FSD 0620Z

FWD 0620Z

GGW 0621Z

GID 0621Z

GJT 0622Z

GLD 0622Z

GRB 0623Z

GRR 0623Z

GSP 0624Z

GUM 0624Z

GYX 0625Z

HFO 0625Z

HGX 0626Z

HNX 0626Z

HUN 0627Z

ICT 0627Z

ILM 0628Z

ILN 0628Z

ILX 0629Z

IND 0629Z

IWX 0630Z

JAN 0630Z

JAX 0631Z

JKL 0631Z

LBF 0632Z

LCH 0632Z

LIX 0633Z

LKN 0633Z

LMK 0634Z

LOT 0634Z

LOX 0635Z

LSX 0635Z

LUB 0636Z

LWX 0636Z

LZK 0637Z

MAF 0637Z

MEG 0638Z

MFL 0638Z

MFR 0639Z

MHX 0639Z

MKX 0640Z

MLB 0640Z

MOB 0641Z

MPX 0641Z

MQT 0642Z

MRX 0642Z

MSO 0643Z

MTR 0643Z

OAX 0644Z

OHX 0644Z

OKX 0645Z

OTX 0645Z

OUN 0646Z

PAH 0646Z

PBZ 0647Z

PDT 0647Z

PHI 0648Z

PIH 0648Z

PQR 0649Z

PSR 0649Z

PUB 0650Z

RAH 0650Z

REV 0651Z

RIW 0651Z

RLX 0652Z

RNK 0652Z

SEW 0653Z

SGF 0653Z

SGX 0654Z

SHV 0654Z

SJT 0655Z

SJU 0655Z

SLC 0656Z

STO 0656Z

TAE 0657Z

TBW 0657Z

TFX 0658Z

TOP 0658Z

TSA 0659Z

TWC 0659Z

UNR 0700Z

VEF 0700Z