PIRL.PVL

## Class PVL_to_DB

- java.lang.Object
- - PIRL.Database.Update_DB
  - - PIRL.PVL.PVL_to_DB

    public class PVL_to_DB
    extends Update_DB

PVL_to_DB maps a source of parameter values to database table field values.

A Map is used to define the assignment of PVL Parameter Values, or constant values, to Database fields. The map is defined using PVL Parameters. The Map defines the assignment from the value of a resolved source parameter reference to a resolved database field reference where the value is deposited. PVL_to_DB binds a PVL source of Parameter Values and a Database target to the Map. In addition, a set of configuration parameters may be specified that will supplement every PVL source mapped to the Database; these may be thought of as default parameters.

The name of each Assignment Parameter in the map specifies a database reference to a single database field. The database reference may specify either an update of an existing record or an insert of a new record. A database reference may be flagged to try an update and, if this fails, to fallback to an insert. Field reference Assignment Parameters may be contained in an Aggregate Parameter for a single update or insert operation on the Database of the collected assignments.

The value of each Parameter in the map specifies a parameter source reference. This is resolved against the PVL source, unless it is a constant value. A constant value may be a quoted string or the result of a mathematical expression that evaluates to a constant.

Both database references and parameter source references may contain nested references of either type, which themselves may contain nested references.

The map is processed in the order in which the parameters occur. The map may be processed in a loop until either no source references are resolved or a specified number of passes have been accomplished.

See Also:
  `Parameter`, `Value`, `Database`, `Reference_Resolver`

### Field Summary

Fields
`static char` `ALTERNATIVE_MARKER` Alternative source parameter reference token character.
`static String` `CWD_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the current working directory pathname: "CWD".
`static String` `DEFAULT_SOURCE_PARAMETERS_NAME` The name given to the `Source_Parameters` when the Aggregate is based on an Assignment Parameter: "Source".
`static int` `EXIT_INVALILD_SYNTAX` Exit status: Invalid syntax was found in the map.
`static int` `EXIT_PVL_ERROR` Exit status: PVL processing problem.
`static int` `EXIT_SUCCESS` Exit status: Success.
`static int` `EXIT_UNRESOLVED_REFERENCE` Exit status: An unresolved reference was encountered.
`static String` `HOSTNAME_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the system hostname: "Hostname".
`static String` `ID` The Class identification.
`static String` `LOOP_COUNTER_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the current mapping loop counter: "Loop_Counter".
`int` `Loop_Limit` The `Loop` limit: 256.
`static String` `MAP_NAME` The Group name of the map parameters: "PVL_to_DB_Map".
`static char` `NO_MATH_MARKER` Non-math expression source parameter reference token character.
`static String` `PVL_to_DB_GROUP` The Parameter Group for this class: "PVL_to_DB".
`static String` `RESOLVER_DEFAULT_VALUE` Default value if a reference can not be resolved.
`boolean` `Retry_Group_with_Source` Whether to retry failed resolving of Group name nested references with both configuration and source parameters.
`static String` `SOURCE_DIRECTORY_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the directory pathname of the current `PVL_Source` name: `SOURCE_DIRECTORY_PARAMETER`.
`static String` `SOURCE_FILENAME_EXTENSION_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the portion of the `SOURCE_FILENAME_PARAMETER` value following the last period ('.') character: `SOURCE_FILENAME_PARAMETER`.
`static String` `SOURCE_FILENAME_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the filename of the current `PVL_Source` name: `SOURCE_FILENAME_PARAMETER`.
`static String` `SOURCE_FILENAME_ROOT_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the portion of the `SOURCE_FILENAME_PARAMETER` value without the extension (the portion preceding the last period character): `SOURCE_FILENAME_ROOT_PARAMETER`.
`static String` `SOURCE_NAME_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the name of the current `Source_Parameters`: "Source_Name".
`static String` `SOURCE_PATHNAME_PARAMETER` The name of the Parameter in the PVL_to_DB group that has the absolute pathname of the current `PVL_Source` name: `SOURCE_PATHNAME_PARAMETER`.
`static String` `UNRESOLVED_SOURCE_REFERENCE_PARAMETER` The Configuration parameter which, if `enabled`, will cause any unresolved source parameter reference to throw an Invalid_Map_Syntax exception.
`static boolean` `UNRESOLVED_SOURCE_REFERENCE_THROWS` Whether an unresolved source parameter reference will throw an Invalid_Map_Syntax exception by default.
`static char` `UPDATE_OR_INSERT_MARKER` Update-or-insert database reference marker character.

### Fields inherited from class PIRL.Database.Update_DB

`DEFAULT_CONFIGURATION_FILENAME, Delete, EXIT_CONFIGURATION_PROBLEM, EXIT_DATABASE_ERROR, EXIT_ILLEGAL_ARGUMENT, EXIT_INVALID_COMMAND_LINE_SYNTAX, EXIT_IO_ERROR, EXIT_STATUS_LIMIT, Ignore_Multiple_Updates, KEY_DELIMITER, NL, The_Database, Update_One_Only, VALUE_DELIMITER, Verbose`

### Constructor Summary

Constructors
Constructor and Description
`PVL_to_DB(Database database, Parameter map)` Constructs from a Database and a Parameter map Aggregate.
`PVL_to_DB(Database database, String map_source)` Constructs from a Database and a map source.

### Method Summary

Methods
`boolean` `Default_Parameter(String name, Object value)` Adds a new parameter to the default PVL_to_DB Group.
`Parameter` `Default_Parameters()` Gets the default PVL_to_DB Group of parameters.
`PVL_to_DB` `Default_Parameters(Parameter parameter)` Adds new parameters to the default PVL_to_DB Group.
`String` `Default_Value()` Gets the default that will be used when a nested configuration parameter reference can not be resolved.
`PVL_to_DB` `Default_Value(String default_value)` Sets the default value for unresolved nested references.
`int` `Loop_Count()` Gets the value of the loop counter.
`boolean` `Loop()` Tests if map looping is enabled.
`PVL_to_DB` `Loop(boolean enable)` Enables or disables map looping.
`static void` `main(String[] arguments)` Runs a PVL_to_DB application.
`Parameter` `Map()` Gets the map Parameters.
`PVL_to_DB` `Map(Parameter map)` Sets the map parameters.
`PVL_to_DB` `Map(String source)` Assembles a map of PVL source parameter references assigned to Database field references.
`int` `Match_Mode()` Gets the parameter match mode.
`PVL_to_DB` `Match_Mode(int match_mode)` Sets the `match mode` used to resolve both nested configuration parameter references and `Map` parameter source references from the `PVL source`.
`boolean` `No_Op()` Tests if no-op mode is enabled.
`PVL_to_DB` `No_Op(boolean enable)` Enables or disables database update operations.
`int` `PVL_Source()` The current source of PVL parameters is mapped into the Database.
`int` `PVL_Source(Parameter source)` Supplies a source of PVL Parameters which is mapped into the Database.
`int` `PVL_Source(String source)` Names a source of PVL Parameters which is mapped into the Database.
`static Parameter` `PVL_to_DB_Group(Parameter parameters)` Finds a PVL_to_DB Group in a Parameter list.
`static Parameter` `Remove_PVL_to_DB_Group(Parameter parameters)` Removes all PVL_to_DB Groups in a Parameter list.
`String` `Resolve_Source_References(String source_reference)` Resolves a Source reference to its value.
`Reference_Resolver` `Resolver()` Gets the Reference_Resolver being used to resolve all references.
`Parameter` `Source_Parameters()` Gets the current set of source parameters.
`PVL_to_DB` `Source_Parameters(Parameter source)` Sets the source parameter(s) to be mapped.
`PVL_to_DB` `Source_Parameters(String source)` Sets the source parameter(s) to be mapped.
`boolean` `Unresolved_Source_Reference_Throws()` Test whether an unresolved source reference will throw an Unresolved_Reference exception.
`PVL_to_DB` `Unresolved_Source_Reference_Throws(boolean enabled)` Force an unresolved source reference to throw an Unresolved_Reference exception.
`static void` `Usage(boolean verbose)` Prints the command-line usage syntax.

### Methods inherited from class PIRL.Database.Update_DB

`Database, Delete, Delete, Ignore_Multiple_Updates, Ignore_Multiple_Updates, Update_Database, Update_Database, Update_One_Only, Update_One_Only, Verbose, Verbose`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### ID

    public static final String ID

The Class identification.

See Also:
  Constant Field Values

#### PVL_to_DB_GROUP

    public static final String PVL_to_DB_GROUP

The Parameter Group for this class: "PVL_to_DB".

This group will be extracted from the Configuration parameters, or an empty group of this name will be created if it is not present in the Configuration. Then a set of common parameters are added. It is appended to the PVL source parameters.

See Also:
  Constant Field Values

#### DEFAULT_SOURCE_PARAMETERS_NAME

    public static final String DEFAULT_SOURCE_PARAMETERS_NAME

The name given to the `Source_Parameters` when the Aggregate is based on an Assignment Parameter: "Source".

See Also:
  Constant Field Values

#### HOSTNAME_PARAMETER

    public static final String HOSTNAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the system hostname: "Hostname".

See Also:
  Constant Field Values

#### CWD_PARAMETER

    public static final String CWD_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the current working directory pathname: "CWD".

See Also:
  Constant Field Values

#### SOURCE_NAME_PARAMETER

    public static final String SOURCE_NAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the name of the current `Source_Parameters`: "Source_Name".

See Also:
  Constant Field Values

#### SOURCE_PATHNAME_PARAMETER

    public static final String SOURCE_PATHNAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the absolute pathname of the current `PVL_Source` name: `SOURCE_PATHNAME_PARAMETER`.

See Also:
  Constant Field Values

#### SOURCE_DIRECTORY_PARAMETER

    public static final String SOURCE_DIRECTORY_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the directory pathname of the current `PVL_Source` name: `SOURCE_DIRECTORY_PARAMETER`.

See Also:
  Constant Field Values

#### SOURCE_FILENAME_PARAMETER

    public static final String SOURCE_FILENAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the filename of the current `PVL_Source` name: `SOURCE_FILENAME_PARAMETER`.

See Also:
  Constant Field Values

#### SOURCE_FILENAME_ROOT_PARAMETER

    public static final String SOURCE_FILENAME_ROOT_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the portion of the `SOURCE_FILENAME_PARAMETER` value without the extension (the portion preceding the last period character): `SOURCE_FILENAME_ROOT_PARAMETER`.

See Also:
  Constant Field Values

#### SOURCE_FILENAME_EXTENSION_PARAMETER

    public static final String SOURCE_FILENAME_EXTENSION_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the portion of the `SOURCE_FILENAME_PARAMETER` value following the last period ('.') character: `SOURCE_FILENAME_PARAMETER`.

See Also:
  Constant Field Values

#### LOOP_COUNTER_PARAMETER

    public static final String LOOP_COUNTER_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the current mapping loop counter: "Loop_Counter".

The value of this parameter is incremented for each mapping `Loop` through the `Source PVL` parameters. It is initialized to 0.

See Also:
  Constant Field Values

#### Loop_Limit

    public int Loop_Limit

The `Loop` limit: 256.

The maximum number of times that a mapping loop is allowed to occur.

#### MAP_NAME

    public static final String MAP_NAME

The Group name of the map parameters: "PVL_to_DB_Map".

See Also:
  Constant Field Values

#### RESOLVER_DEFAULT_VALUE

    public static String RESOLVER_DEFAULT_VALUE

Default value if a reference can not be resolved.

#### Retry_Group_with_Source

    public boolean Retry_Group_with_Source

Whether to retry failed resolving of Group name nested references with both configuration and source parameters.

#### ALTERNATIVE_MARKER

    public static final char ALTERNATIVE_MARKER

Alternative source parameter reference token character.

See Also:
  Constant Field Values

#### NO_MATH_MARKER

    public static final char NO_MATH_MARKER

Non-math expression source parameter reference token character.

See Also:
  Constant Field Values

#### UPDATE_OR_INSERT_MARKER

    public static final char UPDATE_OR_INSERT_MARKER

Update-or-insert database reference marker character.

A database reference prefixed with this marker will be used for an insert operation if the initial update operation fails. If the database reference does not include a record key specification the marker will simply be ignored. N.B.: The marker is not part of the database reference; it is removed before the database reference is used.

See Also:
  Constant Field Values

#### UNRESOLVED_SOURCE_REFERENCE_THROWS

    public static boolean UNRESOLVED_SOURCE_REFERENCE_THROWS

Whether an unresolved source parameter reference will throw an Invalid_Map_Syntax exception by default.

#### UNRESOLVED_SOURCE_REFERENCE_PARAMETER

    public static final String UNRESOLVED_SOURCE_REFERENCE_PARAMETER

The Configuration parameter which, if `enabled`, will cause any unresolved source parameter reference to throw an Invalid_Map_Syntax exception.

If this parameter is not found, the `UNRESOLVED_SOURCE_REFERENCE_THROWS` value will be used by default.

See Also:
  Constant Field Values

#### EXIT_SUCCESS

    public static final int EXIT_SUCCESS

Exit status: Success.

See Also:
  Constant Field Values

#### EXIT_PVL_ERROR

    public static final int EXIT_PVL_ERROR

Exit status: PVL processing problem.

See Also:
  Constant Field Values

#### EXIT_INVALILD_SYNTAX

    public static final int EXIT_INVALILD_SYNTAX

Exit status: Invalid syntax was found in the map.

See Also:
  Constant Field Values

#### EXIT_UNRESOLVED_REFERENCE

    public static final int EXIT_UNRESOLVED_REFERENCE

Exit status: An unresolved reference was encountered.

See Also:
  Constant Field Values

### Constructor Detail

#### PVL_to_DB

    public PVL_to_DB(Database database,
             String map_source)
              throws Configuration_Exception,
                     PVL_Exception

Constructs from a Database and a map source.

Parameters:
  `database` - The Database to be target.
  `map_source` - The source of the database map. May be a URL refering to an appropriate database map.
Throws:
  `Configuration_Exception` - If there is a problem with the configuration file.
  `Database_Exception` - If there is a problem connecting with the database.
  `PVL_Exception` - If there is a problem parsing the PVL from the database map file.

#### PVL_to_DB

    public PVL_to_DB(Database database,
             Parameter map)
              throws Configuration_Exception

Constructs from a Database and a Parameter map Aggregate.

The `update mode` is set to only allow one record per update operation.

Parameters:
  `database` - The Database to be updated.
  `map` - The Parameter map aggregate.
Throws:
  `Configuration_Exception` - If there is a problem with the Database configuration.

### Method Detail

#### No_Op

    public PVL_to_DB No_Op(boolean enable)

Enables or disables database update operations.

As an aid in debugging complex references in map parameter syntax final database update operations may be disabled so that the results of resolving map parameter references may be viewed without affecting the database contents. This mode is implicitly `verbose`.

Note: No-op mode is disabled by default.

Parameters:
  `enable` - true if no-op mode is to be enabled (database update operations are disabled); false otherwise.
Returns:
  This PVL_to_DB object.

#### No_Op

    public boolean No_Op()

Tests if no-op mode is enabled.

Returns:
  true if no-op mode is enabled; false otherwise.
See Also:
  `No_Op(boolean)`

#### Loop

    public PVL_to_DB Loop(boolean enable)

Enables or disables map looping.

When enabled a (@link #PVL_Source() PVL_Source} is repeatedly mapped until references are exhausted or the `Loop_Limit` is reached.

Map looping is used in conjuction with the `LOOP_COUNTER_PARAMETER` in the default `PVL_to_DB_GROUP` parameters. The value of the loop counter parameter is initialized to 0 when `PVL_Source` mapping begins, and then incremented at the end of each mapping loop. By using the LOOP_COUNTER_PARAMETER in the `Map` a sequence of parameters from the PVL source can be mapped to the Database. For example, the Map entry:

>             Group = catalog.table
>               field_1 = parameter@${PVL_to_DB/Loop_Counter}
>               field_2 = array[${PVL_to_DB/Loop_Counter}]
>               ...
>             End_Group

will insert a record in catalog.table with field_1 set to the value of the Nth parameter of that name and field_2 set to the Nth value of the array parameter, where N is the current value of the loop counter (starting with 0).

Note: Map looping is disabled by default.

Parameters:
  `enable` - true if map looping is to be enabled; false otherwise.
Returns:
  This PVL_to_DB object.

#### Loop

    public boolean Loop()

Tests if map looping is enabled.

Returns:
  true if map looping is enabled; false otherwise.
See Also:
  `Loop(boolean)`

#### Match_Mode

    public PVL_to_DB Match_Mode(int match_mode)
                         throws IllegalArgumentException

Sets the `match mode` used to resolve both nested configuration parameter references and `Map` parameter source references from the `PVL source`.

Parameters:
  `match_mode` - One of the `Reference_Resolver.CASE_SENSITIVE`, `Reference_Resolver.CASE_INSENSITIVE`, or `Reference_Resolver.PATTERN_MATCH` values.
Returns:
  This PVL_to_DB object.
Throws:
  `IllegalArgumentException` - If the match mode is not a valid value.

#### Match_Mode

    public int Match_Mode()

Gets the parameter match mode.

Returns:
  The current parameter match mode code.
See Also:
  `Match_Mode(int)`

#### Default_Value

    public PVL_to_DB Default_Value(String default_value)

Sets the default value for unresolved nested references.

Note: The default value may be set by using an `Unresolved_Reference` parameter in the Configuration of the Database provided when the PVL_to_DB object is constructed. If the value of this parameter starts with `"THROW"` (case insensitive) then unresolved nested references will throw an Unresolved_Reference exception.

N.B.: The default value only applies to unresolved nested configuration parameter references. Source parameter (non-nested) references never have a default value.

Parameters:
  `default_value` - The default String value for unresolved nested references. If null, unresolved references will throw an Unresolved_Reference expception.
Returns:
  This PVL_to_DB object.
See Also:
  `Reference_Resolver.Default_Value(String)`

#### Default_Value

    public String Default_Value()

Gets the default that will be used when a nested configuration parameter reference can not be resolved.

Returns:
  The String to use as the default. This is null if Unresolved_Reference will be thrown when a reference can not be resolved.
See Also:
  `Default_Value(String)`

#### Unresolved_Source_Reference_Throws

    public PVL_to_DB Unresolved_Source_Reference_Throws(boolean enabled)

Force an unresolved source reference to throw an Unresolved_Reference exception.

Unless the `configuration` `UNRESOLVED_SOURCE_REFERENCE_PARAMETER` or the `UNRESOLVED_SOURCE_REFERENCE_THROWS` default value is true, a source reference that is not `resolved` will result in the corresponding database field being ignored. Otherwise an unresolved source reference will result in an Unresolved_Reference exception being thrown.

N.B.: If `no-op` mode is enabled an exception will not be thrown in any case.

Parameters:
  `enabled` - If true an unresolved source reference will result in an Unresolved_Reference exception being thrown. If false an unresolved source reference will result in the mapped database field being ignored.
Returns:
  This PVL_to_DB object.

#### Unresolved_Source_Reference_Throws

    public boolean Unresolved_Source_Reference_Throws()

Test whether an unresolved source reference will throw an Unresolved_Reference exception.

Returns:
  true if an unresolved source reference will result in an Unresolved_Reference exception being thrown. false if an unresolved source reference will result in the mapped database field being ignored.
See Also:
  `Unresolved_Source_Reference_Throws(boolean)`

#### Resolver

    public Reference_Resolver Resolver()

Gets the Reference_Resolver being used to resolve all references.

Warning: Modifying the Reference_Resolver could produce unexpected source mapping results.

Returns:
  The Reference_Resolver being used.

#### Source_Parameters

    public Parameter Source_Parameters()

Gets the current set of source parameters.

Returns:
  The Aggregate Parameter containing the parameters for resolving source parameter references. N.B.: After `source mapping` the source parameters include the `default parameters` in a `PVL_to_DB_GROUP` Aggregate.
See Also:
  `Source_Parameters(Parameter)`

#### Source_Parameters

    public PVL_to_DB Source_Parameters(Parameter source)
                                throws Configuration_Exception

Sets the source parameter(s) to be mapped.

If the source is an Assignment a new Aggregate named `DEFAULT_SOURCE_PARAMETERS_NAME` is created to contain it.

The `default parameters` are updated: `SOURCE_NAME_PARAMETER` is set to the name of the source Aggregate and `SOURCE_PATHNAME_PARAMETER`, `SOURCE_DIRECTORY_PARAMETER`, `SOURCE_FILENAME_PARAMETER`, `SOURCE_FILENAME_ROOT_PARAMETER`, and `SOURCE_FILENAME_EXTENSION_PARAMETER` are set to the corresponding components of the source name taken to be a file pathname. If, however, the name does not refer to an existing file, then these parameters will all be given the empty string as their value.

Parameters:
  `source` - The Parameter source. If null, the current source is unchanged.
Returns:
  This PVL_to_DB object.
Throws:
  `Configuration_Exception` - If there was a problem updating the default parameters from the source name.
See Also:
  `Default_Parameters()`, `Reference_Resolver.Parameters(Parameter)`

#### Source_Parameters

    public PVL_to_DB Source_Parameters(String source)
                                throws PVL_Exception,
                                       Configuration_Exception

Sets the source parameter(s) to be mapped.

Parameters:
  `source` - A PVL source String. This may be a URL, local pathname, or a system resource. If null, nothing is done.
Throws:
  `PVL_Exception` - If there was a problem reading from or parsing the source stream.
  `Configuration_Exception` - If there was a problem updating the default parameters from the source name.
See Also:
  `Streams.Get_Stream(String)`, `Source_Parameters(Parameter)`

#### PVL_to_DB_Group

    public static Parameter PVL_to_DB_Group(Parameter parameters)

Finds a PVL_to_DB Group in a Parameter list.

Parameters:
  `parameters` - The Aggregate Parameter to search.
Returns:
  The top level `PVL_to_DB_GROUP` Aggregate, or null if not found. The first group found is returned.

#### Remove_PVL_to_DB_Group

    public static Parameter Remove_PVL_to_DB_Group(Parameter parameters)

Removes all PVL_to_DB Groups in a Parameter list.

Parameters:
  `parameters` - The Aggregate Parameter to search.
Returns:
  The last top level `PVL_to_DB_GROUP` Aggregate that was removed; null otherwise.

#### Default_Parameters

    public PVL_to_DB Default_Parameters(Parameter parameter)
                                 throws Configuration_Exception

Adds new parameters to the default PVL_to_DB Group.

The PVL_to_DB Group of parameters is used as defaults when resolving source parameter references in the map that are not resolved by the `Source Parameters`. Just before the `source mapping operation` begins the default parameters are appended to the source parameters which ensures that the default parameters will be present for source parameter resolution, but the default parameters will not override any source parameters having the same name.

If the parameter is an Assignment it is added to the `PVL_to_DB Group` of default parameters. If the Parameter is an Aggregate and it contains a PVL_to_DB Group, the parameters in that group are added to the PVL_to_DB Group; otherwise all the Parameters of the Aggregate are added to the PVL_to_DB Group. The PVL_to_DB Group is Coalesced with its `duplicate parameter action` set so that newly added duplicate parameter names will take precedence.

If the Parameter is null the PVL_to_DB Group is reset with the default parameters, which are always included:

`HOSTNAME_PARAMETER`
  The name of the host system.
`CWD_PARAMETER`
  The pathname to the current working directory.
`SOURCE_NAME_PARAMETER`
  The current `PVL_Source` name.
`SOURCE_PATHNAME_PARAMETER`
  The absolute pathname of the current `PVL_Source`. This will be empty if the file does not exist.
`SOURCE_DIRECTORY_PARAMETER`
  The directory pathname of the SOURCE_FILENAME_PARAMETER. This will be empty if the file does not exist.
`SOURCE_FILENAME_PARAMETER`
  The filename portion of the SOURCE_PATHNAME_PARAMETER. This will be empty if the file does not exist.
`SOURCE_FILENAME_ROOT_PARAMETER`
  The SOURCE_FILENAME_PARAMETER value with the extension removed. This will be empty if the file does not exist.
`SOURCE_FILENAME_EXTENSION_PARAMETER`
  The extension portion of the SOURCE_FILENAME_PARAMETER. This will be empty if the filename has no extension following a period ('.') character, or if the file does not exist.
`LOOP_COUNTER_PARAMETER`
  The `Loop` counter; initialized to 0.

Parameters:
  `parameter` - The parameter(s) to be added to the PVL_to_DB default source parameters group.
Returns:
  This PVL_to_DB object.
Throws:
  `Configuration_Exception` - If there is a problem adding a new parameter.
See Also:
  `Default_Parameter(String, Object)`

#### Default_Parameters

    public Parameter Default_Parameters()

Gets the default PVL_to_DB Group of parameters.

Returns:
  The PVL_to_DB Aggregate Parameter.

#### Default_Parameter

    public boolean Default_Parameter(String name,
                            Object value)
                              throws Configuration_Exception

Adds a new parameter to the default PVL_to_DB Group.

Parameters:
  `name` - The name of the parameter to be set.
  `value` - An Object to use for the parameter's value.
Returns:
  true if an existing parameter by the same name was replaced; false if the parameter is being set for the first time.
Throws:
  `Configuration_Exception` - If there is a problem adding a new parameter.
See Also:
  `Default_Parameters(Parameter)`

#### Loop_Count

    public int Loop_Count()

Gets the value of the loop counter.

This will be the number of times the last `PVL_Source` was successfully mapped to the Database.

#### Map

    public PVL_to_DB Map(String source)
                  throws PVL_Exception

Assembles a map of PVL source parameter references assigned to Database field references.

A PVL_to_DB map is used to assign Parameter (or constant) values to Database fields. It provides the mapping from resolved source reference values to resolved database field references where the values are deposited. Note: No map Parameter Value may be an Array; there must be only one Parameter Value for each Database field reference. However, this Value may contain multiple source references that are combined to produce a single field value.

Syntactically, the map is a Aggregate of PVL Parameters in which the name of each Assignment Parameter is a Database field reference and the Value is a source reference:

> Database_field_reference = Source_reference

#### Nested references -

Any reference may contain `nested references`. All nested references are recursively resolved before the reference that contains them. A nested reference may be either a configuration parameter reference or a database field reference. All nested references are enclosed in curly braces ('{' and '}'), with configuration parameter references being distinguished from database field references by the former having a leading dollar sign ('$') before the opening curly brace. All nested references will either be resolved to a value or the `Default_Value` will be used (if the default value is null an Unresolved_Reference exception will be thrown).

N.B.: Nested parameter references are resolved against the configuration parameters, not the source parameters. Only nested references are enclosed in curly braces. The final database field and parameter source references used to accomplish the value assignment must not be enclosed.

#### Database field reference -

> Catalog.Table.Field:Key

The components preceding the colon form a fully qualified field name, and the component following the colon is a match (SQL WHERE) criteria used to identify a specific record from the database.

##### Insert parameters

Map parameters that have a database reference without a key will insert a new record in the field of the table specified by the reference.

##### Update parameters

Map parameters that have a database reference with a key are used to specify existing database fields to be updated with a new value. The key is the criteria that identifies the specific record of the table that is to be updated. The key is required to uniquely identify a single record.

##### Update or Insert

A database reference may be flagged with an `UPDATE_OR_INSERT_MARKER` prefix character that will cause an update to be tried if the reference includes a key. If the update fails then an insert will be performed. If the reference does not include a key then only the insert is done. The special prefix marker is, of course, removed from the database reference before it is used.

#### Source reference -

A source reference is the Value of a map's Assignment Parameter. It is the expression that must be resolved to a value that is assigned to the database field. Ultimately each source reference must resolve to a single string value, which may be the text representation of a numeric value. However, a source reference is evaluated as a sequence of tokens that are individually resolved to string values that are concatenated to form the final source reference resolution. See the description of `source references resolving` for the details of the source reference expression syntax.

##### Parameter source reference -

The basic source reference names a parameter in the source file which has an assignment value that is used to satisfy the reference. The syntax of a parameter source reference is the sames as the syntax for a nested parameter reference, but without the enclosing "${" and "}" characters:

> Pathname@Sequence[Index]...

The Pathname is a simple, relative or absolute Parameter pathname used to `Find` the parameter in the `PVL source`. How the pathname matching is done - whether case sensitive or using a regular expression pattern - is controlled by by the `match mode`. The Sequence, with its preceeding "at" ('@') delimiter , is optional; if present it indicates which of a multiple sequence parameters that match the Pathname to select (the first parameter is 0, which is the default). The Index, with its enclosing square bracket ('[' and ']') characters, is also optional; if present it indicates which element of an Array Value to select (the first element is 0, which is the default). Multiple Array Value element specifiers may be provided to select from multidimensional Array Values. Both the Sequence and Index specifiers may contain nested references. They may also be mathematical expressions that evaluate to any numeric value, which is truncated to an integer for selecting Array Value elements. The typical parameter source reference is simply a name of a source parameter.

N.B.: Source parameter references are resolved against the source parameters, not the configuration parameters.

#### Groups

Map parameters that are contained within an Aggregate (Group) Parameter define the field values for a single record in the Database. The name of the Group is a Database `table reference` (in Catalog.Table notation) that specifies the table where the record will located; that is it is a database field reference without the Field portion. Each parameter within the Group specifies a field name and its source reference value, therefore its database reference can contain just the field name without the catalog and table name portions (if these are present, however, they must be the same as the table reference in the Group name); the table reference portion is implicitly the name of the Group.

N.B.: As a special case, if the Group name contains nested references that can not be resolved against the configuration parameters an attempt will be made to resolve against both the configuration parameters and the current source parameters, in that order. This is a deprecated feature that could result in confusion of the correct parameter to resolve a nested reference. Retry can be disabled by setting Retry_Group_with_Source to false.

The field names and values of a Group are all collected together to produce a single operation on the Database. Groups, therefore, are particularly useful for specifying all the fields of a single new record to be inserted into a table; the alternative is to insert a single field of a new record and then apply updates to this new record to provide additional field values. If the database reference of the Group name includes a key, then a single Database update operation will be done. N.B.: Depending on the particular database server, this could result in only some of the updates being completed if there is an error in one of the map references within the Group.

#### Quotes and Escapes

Because source references may be complex expressions and are likely to contain special PVL syntax characters (e.g. '{', '}', '=', quotes and spaces), the entire Value portion of a Map Parameter should be quoted (with either single or double quote characters) to prevent the misinterpretation of the special characters. This is a common source of syntax errors.

When characters that would otherwise be interpreted as nested reference enclosure characters, or other special parse control characters (such as quotes and parentheses), need to be passed through as the value of the reference preceed these characters with a backslash ('\') which will escape the usual interpretation of the following character and remove the backslash. The backslash character itself may be escaped in this way.

Parameters:
  `source` - The name of the PVL source (URL or pathname) containing the PVL that defines the map.
Returns:
  A PVL Parameter Aggregate containing the mapping structure.
Throws:
  `PVL_Exception` - If there is a problem parsing the PVL.

#### Map

    public PVL_to_DB Map(Parameter map)
                  throws IllegalArgumentException

Sets the map parameters.

Parameters:
  `map` - The map Parameter Aggregate.
Returns:
  This PVL_to_DB object.
Throws:
  `IllegalArgumentException` - If the map is not an Aggregate Parameter.

#### Map

    public Parameter Map()

Gets the map Parameters.

Returns:
  The map Parameter Aggregate.
See Also:
  `Map(Parameter)`

#### PVL_Source

    public int PVL_Source()
                   throws ParseException,
                          Database_Exception,
                          Invalid_Map_Syntax,
                          Unresolved_Reference

The current source of PVL parameters is mapped into the Database.

The `loop counter` is first reset to zero.

If there are no source parameters or map, then nothing is done.

Any top level `PVL_to_DB_GROUP` Aggregates are removed (as would occur if a source were reprocessed for any reason). Then the `default parameters` are appended to the `source parameters`.

The map processing loop is entered. The loop counter is incremented at the successful completion of this loop, but the loop number (the first loop is number 1) is reported in verbose mode. In verbose mode all mapping operations - insert or update - and their values - both before and after reference resolution - will be reported. At the end of each map processing loop the number of updates effected on the database and records that were affected is listed, and after map processing completes the totals of these values will be listed. If map `looping` has been enabled the map processing loop will be run until the loop counter reaches the `Loop_Limit` or no source parameters can be resolved during a processing loop. The map will be processed only once if looping is disabled.

Each map parameter is processed in the order it occurs in the map. A database reference is obtained from each parameter name and resolved of all nested references. From this a table reference and key is identified. Each database reference must contain a table reference, but the key is only present for update (not insert) operations. For Assignments the parameter value is resolved to a source reference (the details are provided in the description of the `map` syntax). For Aggregates all of the Assignment parameters it contains have their the database field references and resolved parameter references collected together before a database operation will be performed. If a source parameter reference can not be resolved the parameter is ignored. N.B.: Nested parameter references may be resolved by a `default value` or throw an Unresolved_Reference exception if no default has been specified, but this only applies to nested references; after resolving nested references the result is still treated as a parameter reference but without a default (or exception). If at least one source parameter reference has been resolved, and `no-op` mode has not been enabled, then the Database is updated.

Returns:
  The total number of database record updates/inserts.
Throws:
  `ParseException` - If a reference could not be resolved due to invalid syntax.
  `Database_Exception` - If there is a problem accessing the database.
  `Invalid_Map_Syntax` - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.
  `Unresolved_Reference` - If a nested reference could not be resolved and there was no `Default_Value`.
See Also:
  `Update_DB.Update_Database(String, String, Vector, Vector)`

#### PVL_Source

    public int PVL_Source(String source)
                   throws PVL_Exception,
                          Configuration_Exception,
                          ParseException,
                          Database_Exception,
                          Invalid_Map_Syntax,
                          Unresolved_Reference

Names a source of PVL Parameters which is mapped into the Database.

Parameters:
  `source` - The name of the PVL source (a local pathname or URL). If null, the previous PVL source is used. If there is no previous PVL source, nothing is done.
Returns:
  The total number of database record updates/inserts.
Throws:
  `PVL_Exception` - If there is a problem parsing the PVL from the input file.
  `Configuration_Exception` - If there was a problem updating the default parameters from the source name.
  `ParseException` - If a reference could not be resolved due to invalid syntax.
  `Database_Exception` - If there is a problem accessing the database.
  `Invalid_Map_Syntax` - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.
  `Unresolved_Reference` - If a nested reference could not be resolved and there was no `Default_Value`.
See Also:
  `Source_Parameters(String)`, `PVL_Source()`

#### PVL_Source

    public int PVL_Source(Parameter source)
                   throws Configuration_Exception,
                          ParseException,
                          Database_Exception,
                          Invalid_Map_Syntax,
                          Unresolved_Reference

Supplies a source of PVL Parameters which is mapped into the Database.

Returns:
  The total number of database record updates/inserts.
Throws:
  `Configuration_Exception` - If there was a problem updating the default parameters from the source name.
  `ParseException` - If a reference could not be resolved due to invalid syntax.
  `Database_Exception` - If there is a problem accessing the database.
  `Invalid_Map_Syntax` - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.
  `Unresolved_Reference` - If a nested reference could not be resolved and there was no `Default_Value`.
See Also:
  `Source_Parameters(Parameter)`, `PVL_Source()`

#### Resolve_Source_References

    public String Resolve_Source_References(String source_reference)
                                     throws ParseException,
                                            Database_Exception,
                                            Unresolved_Reference,
                                            Invalid_Map_Syntax

Resolves a Source reference to its value.

A PVL source reference, as occurs in `Map` Parameter Values, is resolved to a value. The steps taken to achieve a resolved value are:

The source reference is first resolved of all nested references. If there are no syntax errors or an exception due to an unresolved reference the result is evaluated for individual reference tokens.

The source reference expression is searched for individual reference tokens. Each identified individual reference is resolved to a string value. The resolved values are concatenated in the left-to-right order they occur in the source reference to produce its resolved value. N.B.: Unquoted whitespace characters (any of " \t\r\n") are compressed out of the expression during the process of resolution value accumulation.

Individual references are identified and resolved as follows, in the order in which they are listed:

A logically empty string.
  The source reference is trimmed of leading and trailing whitespace characters. If the result is an empty string the resolved value is an empty string.
A mathematical expression.
  An attempt is made to evaluate the source reference as a mathematical expression. If this succeeds the result, as a string representation, is the resolved value.

  The expression `parser` accepts both simple and complex syntax with numeric constants plus the symbolic constants pi and e, the usual mathematical operators (unary and binary + and -, * and /) plus exponentiation (either ^ or **) and a full complement of standard math functions (sin, cos, tan, cot, sec, csc, arcsin, arccos, arctan, exp, ln, log2, log10, sqrt, cubert, abs, round, floor, ceiling and trunc). Also, logical operators (&, |, ~, =, <, >, <>, <= and >=; the words "and", "or", and "not" can be used in place of &, | and ~) may be used in a conditional expression (with ? and :) as long as the result of the expression evaluation is a single numeric value. The evaluation will use double precision arithmetic and the result will be provided in its `string representation` form.

  N.B.: If the results of resolving a mathematical expression are equivalent to an integer, despite being returned as a double type, then the resolved value will be represented as an integer without a ".0" suffix.

  N.B.: Mathematical expression evaluation of an individual reference can be suppressed by preceding the reference with the `NO_MATH_MARKER` character. In this case the marker is stripped off an no attempt is made to evaluate the reference or its resolved value as a mathematical expression.

A quoted string.
  All characters within unescaped single or double quotes are taken verbatim. The quotation marks are stripped off and the resulting string is the resolved value. N.B.: Quoted strings do not need to be surrounded by whitespace; they may be embedded anywhere in a source reference. Conversely, to include whitespace characters in the resolved value of a source reference they must be quoted.

  A quotation mark without a closing unescaped matching quotation mark in the same source reference results in an `Invalid_Map_Syntax` exception being thrown that identifies the unclosed quoted string as the unresolved reference.

A parenthesized expression.
  The characters within unescaped parentheses are recursively processed as a source reference to produce a resolved value. The enclosing parentheses are stripped off. Nested parentheses are included and, unless escaped, will be recognized during the recursive procssing of the new source reference. N.B.: Parenthetical expressions do not need to be surrounded by whitespace; they may be embedded anywhere in a source reference.

  An opening parenthesis without a closing unescaped matching closing parenthesis, ignoring nested parentheses, in the same source reference results in an `Invalid_Map_Syntax` exception being thrown that identifies the unclosed parenthetical string as the unresolved reference.

An alternative marker.
  The occurance of an `ALTERNATIVE_MARKER` character causes all further accumulation of resolved references in the current source reference to stop if, and only if, the immediately preceeding source reference (if any) was successfully resolved. That is, if the immediately preceeding reference fails to resolve then the occurance of an alternative marker causes the failed reference to be ignored.

  N.B.: An alternative marker may be followed by any source reference other than an alternative marker, including an empty string. If another alternative marker follows in the current source reference then an `Invalid_Map_Syntax` exception is thrown that identifies the current source reference.

A source parameter reference.
  A contiguous sequence of non-whitespace characters that are not quoted or parenthesized and is not an alternative marker is evaluated as a source parameter reference. A source parameter reference is resolved against the current `source parameters`, with the `default parameters` appended, to produce a resolved value.

  If the source parameter reference is unresolved and the next reference in the current source reference is an alternative marker the unresolved reference is ignored and parsing continues with the next token. Note that if an alternative marker occurs at the end of a source reference it will never fail to resolve to at least the empty string value. However, if an alternative marker does not follow a source parameter reference that fails to resolve to a value then further parsing of the source reference stops and the enclosing source reference, if any, is signaled that an unresolved source reference occured; this source reference may be followed by an alternative marker. This enables any parenthesized expression to be provided with an alternative in case the entire parenthesized expression fails to resolve.

After each individual source reference has been successfully resolved another attempt is made to evaluate the results as a mathematical expression, unless this has been suppressed by the use of the `NO_MATH_MARKER` character in front of the reference. If this succeeds, the results are used as the resolved value; otherwise the original resolved value is used. N.B.: To include parameter source references in post-resolution mathematical expressions all parts of the expression that are not to be otherwise treated as resolvable references must be quoted. This is an admittedly awkward requirement, but otherwise all parameter source references would need special syntax identification which would be even more awkward.

Parameters:
  `source_reference` - The reference String to be resolved to a Parameter source value.
Returns:
  The resolved String value.
Throws:
  `ParseException` - If the evaluation of a mathematical expression in a nested reference encounters a syntax error.
  `Database_Exception` - If a nested database reference can not be resolved.
  `Unresolved_Reference` - If a nested reference can not be resolved and there is no `default reference value`.
  `Invalid_Map_Syntax` - If a parameter source reference can not be resolved, or a source parameter reference alternative is the quoted string constant `"THROW"` (case insensitive).

#### main

    public static void main(String[] arguments)

Runs a PVL_to_DB application.

N.B.: If a Database connection is establshed it is always Disconnected before the application exits for any reason.

Exit status values:

`EXIT_SUCCESS`
  Success
`Update_DB.EXIT_INVALID_COMMAND_LINE_SYNTAX`
  Invalid command line syntax
`Update_DB.EXIT_CONFIGURATION_PROBLEM`
  Configuration problem
`Update_DB.EXIT_DATABASE_ERROR`
  Database access error
`EXIT_PVL_ERROR`
  PVL processing problem
`EXIT_INVALILD_SYNTAX`
  Invalid syntax was found in the map
`EXIT_UNRESOLVED_REFERENCE`
  An unresolved reference was encountered

Parameters:
  `arguments` - The `command line` arguments.

#### Usage

    public static void Usage(boolean verbose)

Prints the command-line usage syntax.

>     Usage: PVL_to_DB <Options> -Map <source> <PVL source> [...]
>       Options -
>         -Database|-SERVER <server name>
>         -Configuration [<source>] (default: Database.conf)
>         -Set <parameter definition>
>         -Loop [<count>] (default: 0, no looping)
>         -Pattern Case_sensitive | Ignore_case | Regex (default: Case_sensitive)
>         -Verbose (default: false)
>         -Quiet (default: true)
>         -No-op (default: false)

#### PVL source:

The pathname or URL of a file containing PVL to be used as the source of parameter values to be mapped into database field values.

#### Map:

The pathname or URL of a file containing a `map` of PVL parameters to database fields.

#### Database server name:

The Configuration file may contain connection information for more than one database. The information for each database is organized by `server` name, which may be specified. If no server name is provided, the Database will attempt to use the default server specified in the Configuration.

#### Configuration:

If the pathname or URL of the `Configuration` file is not specified the filename "Database.conf" will be used by default. If the configuration file is not in the current working directory, it will be looked for in the user's home directory. The configuration file must contain the necessary information needed to identify and connect with the database server (as required by the `Database` constructor and its `Connect` method). These are typically the database server "Type", "Host", "User" and "Password" access values.

The configuration parameters are used to resolve "nested" parameter references (see the discussion of `map` parameters for the distinction between nested configuration parameter referenes and source parameter references). In addition, if the configuration file contains a `PVL_to_DB` Parameter group, then these parameters will be included in the `defaults` list to be used when resolving source parameter references.

#### Set:

Parameters defined on the command line supplement or override existing configuration file parameters. Parameters are specified using the usual `PVL` syntax. N.B.: Spaces, quotes and other special characters that are part of the parameter definition must be protected from interpretation by the command shell. Parameters may have simple - typically single word - names or absolute pathnames including groups that exist in the configuration file or new groups to be created. This option may be used repeatedly to define multiple paramters.

#### Loop:

Normally only one mapping pass is made through the PVL source parameters. If a `loop` count greater than 1 is specified then each PVL source parameters set will be mapped repeatedly up to the loop count or until no database updates occur. This allows sets of parameters having the same names to be collected and sequentially inserted into the database using the `LOOP_COUNTER_PARAMETER` in the corresponding parameter reference.

#### Pattern:

PVL source parameter names are matched with map parameter references by using case sensitive comparison, ignoring case in the comparision, or treating the map parameter reference as a regular expression. Case sensitive matching is used by default.

#### Verbose/Quiet:

The verbose option provides a log of operations, as they occur, to the standard output. The quiet option disables the verbose mode. By default quiet mode is in effect.

#### Unresolved_source_reference_throws:

Any unresolved source reference will result in an exception being thrown rather than the mapped database field being ignored.

#### No-op:

As an aid in debugging complex references in map parameter syntax final database update operations will be disabled so that the results of resolving map parameter references may be viewed without affecting the database contents. This mode is implicitly verbose.

#### Help:

List a command line summary description and immediately exit.

N.B.This method always results in a System.exit with a status of ``EXIT_INVALID_COMMAND_LINE_SYNTAX``.

Parameters:
  `verbose` - If true the usage is printed, otherwise silence.