Completed instructions, first commit

docs/Users_Guide/load_data.rst

@@ -1,8 +1,112 @@
-Load Data
-=========
+Background
+==========
 
-METdbload is used to insert MET output data into the database. The usage
-statement:
+The METdbLoad module provides support for inserting MET output data into the database.
+
+Before using the METdbLoad module, the database must exist and have the proper permissions
+(i.e. grant privileges to insert, delete, update, and index).  A schema file, *mv_mysql.sql* is available in the
+METdataio/METdbLoad/sql/ directory for importing into the database.
+
+The METdbLoad script *met_db_load.py* performs the loading of data based on settings in an XML specification file.
+
+In the METdataio/METdbLoad/sql/scripts directory, there are two configuration files:
+
+  * db_load_specification.xml
+
+  * data_loading_config.yaml
+
+The *db_load_specification.xml* is a template XML specification file, and *data_loading_config.yaml*
+is a template YAML configuration file.  The *data_loading_config.yaml* file contains
+information about the database (username, password, database name, etc.). This information is used by the
+*generate_xml_spec.py* script to generate the XML specification file which is then used to load data into the database.
+
+Generate the XML specification file
+-----------------------------------
+
+Copy the *data_loading_config.yaml* file to a secure location in your workspace, as this file will contain the username
+and password to the database. **Do not put this file where it can be read by anyone who should not have access to this
+information.**
+
+.. code-block:: ini
+
+cp data_loading_config.yaml /path-to-your-dir/
+
+Replace the *path-to-your-dir* with the actual path to where this file is to be saved.
+
+Change directory to the location where the *data_loading_config.yaml* file was copied.
+
+Open the data_loading_config.yaml file:
+
+.. literalinclude:: ../../METdbLoad/sql/scripts/data_loading_config.yaml
+
+Update the database information with information relevant to the database you are using:
+
+* dbname
+
+* username
+
+* password
+
+* host
+
+* port
+
+
+Update the path to the schema location, provide the full path to the *mv_sql_mysql.sql* schema file:
+
+* schema_location
+
+Provide the name and full path to the *db_load_specification.xml* template file, this will be updated
+with the settings in this YAML configuration to create a new XML specification file using these settings:
+
+* xml_specification
+
+Provide the group and description.  The databases in METviewer are grouped, provide the name of the appropriate
+group and a brief description of the database in which the data is to be loaded:
+
+* group
+
+* description
+
+Provide the full path to the directory where the MET data to be loaded is saved:
+
+* data_dir
+
+Indicate which data types are to be loaded by setting the appropriate settings to True:
+
+* load_stat
+
+* load_mode
+
+* load_mtd
+
+* load_mpr
+
+* load_orank
+
+Generate the new XML specification file by running the following:
+
+.. code-block:: ini
+
+   cd path-to-METdataio-source/METdataio/METdbLoad/sql/scripts
+
+   *Replace path-to-METdataio-source to the location where the METdataio source code is saved.
+
+   python generate_xml_spec.py path-to/data_loading_config.yaml
+
+   *Replace the path-to with the path to the directory you created to store the copy of the data_loading_config.yaml
+   file as specified earlier.
+
+A new XML specification file *load_met.xml*, will be generated and saved in the
+same directory where the YAML configuration file was copied.
+
+Load data
+---------
+
+Now the MET data can be loaded in the database using the *met_db_load.py* script in the path-to/METdataio/METdbLoad/ush
+directory.  The *path-to* is the directory where the METdataio source code is saved.
+
+The usage statement:
 
 .. code-block:: ini
 
@@ -18,7 +122,7 @@ statement:
     -h, --help  show this help message and exit
     -index      Only process index, do not load data
 
-The **xmlfile** passes information about the MET output files to load
+The **xmlfile** is the XML specification file that passes information about the MET output files to load
 into the database to METdbload. It is an XML file whose top-level
 tag is <load_spec> and it contains the following elements, divided into
 functional sections:
@@ -141,6 +245,9 @@ functional sections:
 Example
 _______
 
+The data to be loaded can be filtered by date and field names (i.e. by model, valid_time, vx_mask, etc.).
+The load_met.xml specification file can be further modified to accomplish this.
+
 Here is a simple example:
 
 .. code-block:: XML
@@ -228,4 +335,3 @@ _______________
       row already exists in the table with the insert information, then
       the existing record will be used instead of trying to insert a
       dupilcate.
-