PIRL.Database

## Class Database

- java.lang.Object
- - PIRL.Database.Database

All Implemented Interfaces:
  Data_Port

    public class Database
    extends Object
    implements Data_Port

A Database provides an implementation of a Data_Port to manage access to any database for which a driver is available.

Every Database will have a Configuration. If one is not specified when a Database object is created a default Configuration is created. The application may provide a Configuration directly to the new Database object. The Configuration is a group of PVL Parameters that provide needed characterization for accessing specific databases.

A Database is like a File in that instantitating an object of this class does not establish a data access connection to a database's contents. This is done with a ``Connect`` method. To Connect to a database server its type (e.g. "MySQL") must be specified or a default ``TYPE`` parameter must be found in the Configuration. The Database will extract from its Configuration only those Parameters applicable to the specified type and use them to ``Open`` the Data_Port. The Open method will load a Data_Port class, having a name beginning with the database type name and ending with "_Data_Port", that implements the Data_Port interface and knows how to access that type of database (it may, for example, load a JDBC driver class, perhaps named by a "Driver" parameter). The Database class implements the Data_Port interface itself by passing its Data_Port method calls on to its current dynamically loaded Data_Port object.

If a specific database catalog to access from the server is specified with the `Connect` method, then a ``CATALOG`` parameter will be set in the Data_Port Configuration. The Data_Port is likely to supplement the Configuration it is given with its own default Parameters.

There are a set of parameter names that are known to the Database class:

`Server`
  The list of server configuration groups in a Configuration. Each group must have the name of one of the names in the Server list. The first name in the list is the default server.
`Type`
  The type of database server to connect to. This name, with the addition of "_Data_Port", is the name of the Data_Port class providing access to the server. There is no default; it must be specified.
`Driver`
  The formal name, as a Java pathname, of a database driver class that might be needed by a Data_Port. Usually each Data_Port class implementation provides its own default.
`Catalog`
  The name of the data catalog to use on the server.
`Table`
  The name of one or more tables within a catalog to be accessed for data. The first table listed is the default table.
`Fields`
  The name of one or more fields within a table.

See Also:
  `Configuration`, `Data_Port`

### Field Summary

Fields
`static String` `CATALOG` The parameter name for a container of data tables: "Catalog".
`static String` `DATABASE` The parameter name for the name of the database on the server to be used: "Database".
`static String` `DEFAULT_CONFIGURATION_FILENAME` The default configuration filename: "Database.conf".
`static String` `DRIVER` The parameter name for the driver class to provide access to the database server: "Driver".
`static String` `FIELDS` The parameter name for the name of one or more fields within a table: "Field".
`static String` `ID` Class name and version identification.
`static String` `NL` The new-line sequence for the local host system.
`static String` `NULL_VALUE` The "value" to specify when setting a field to NULL.
`static String` `SERVER` The parameter name for the default database server: "Server".
`static String` `TABLE` The parameter name for the name of one or more tables within a catalog: "Table".
`static String` `TYPE` The parameter name for the type of database server which corresponds to the Data_Port class to use: "Type".

### Constructor Summary

Constructors
Constructor and Description
`Database()` Creates a Database with a default Configuration.
`Database(Configuration configuration)` Creates a Database with a specific Configuration.

### Method Summary

Methods
`Data_Port` `Add_SQL_Listener(SQL_Listener listener)` Adds a SQL_Listener to the list of listeners to be notified of SQL statements before they are sent to the database server.
`boolean` `Case_Sensitive_Identifiers()` Tests if identifier names are treated as case sensitive by the Data_Port.
`void` `Case_Sensitive_Identifiers(boolean case_sensitive)` Attempts to set whether identifier names are treated as case sensitive by the Data_Port.
`String` `Catalog_Name(String table_reference)` Gets the catalog name portion of a table reference.
`Vector` `Catalogs()` Gets the list of catalogs on the database server.
`void` `Close()` Closes the Database connection to the database server.
`Configuration` `Configuration()` Gets the Configuration for the Database.
`Database` `Connect()` Connects the Database to the default database server.
`Database` `Connect(String server)` Connects the Database to a named database server.
`Database` `Connect(String server, String catalog)` Connects the Database to a named database server and a specific catalog of the database as a data source.
`Connection` `Connection()` Gets the JDBC Connection object.
`String` `Contents(String catalog, String table)` Gets a String describing the contents of selected catalogs and tables.
`void` `Create(String catalog)` Creates a catalog in the database.
`void` `Create(String table, Vector fields, Vector types)` Creates data tables with their fields and the data types of the fields.
`Data_Port` `Data_Port()` Gets the current Data_Port backing the Database.
`String` `Database_Catalog_Name(String catalog)` Gets the name known to the database server for a catalog name.
`String` `Database_Table_Name(String table)` Gets the name known to the database server for a table name.
`String` `Default_Server_Name()` Gets the default server name from the Database Configuration.
`void` `Delete(String catalog)` Deletes a catalog from the database.
`int` `Delete(String table, String conditions)` Deletes selected records from a table.
`void` `Delete(String table, Vector fields)` Deletes fields from a data table, or the entire table.
`String` `Description()` Gets a multi-line description of the Data_Port.
`void` `Disconnect()` Disconnect the Database (its backing Data_Port) from its database server.
`static String` `Escape_to_Special(String string)` Substitutes special characters for escape sequences.
`Vector` `Field_Names(String table)` Gets the list of field names in a table on the database server.
`Vector` `Field_Types(String table)` Gets the list of field data types in a table on the database server.
`Vector` `Fields(String table, String field_info)` Obtains a list of field information for the table of a catalog.
`static Hashtable` `Hash_Map(Vector keys, Vector values)` Constructs a Hashtable from a Vector of keys and a corresponding Vector of values.
`int` `Index(String[] array, String string)` Gets the index of the string that matches an element of an array.
`static int` `Index(String[] array, String string, boolean case_sensitive)` Gets the index of the string that matches an element of an array.
`int` `Index(Vector vector, String string)` Gets the index of the string that matches an element of a Vector.
`static int` `Index(Vector vector, String string, boolean case_sensitive)` Gets the index of the string that matches an element of a Vector.
`int` `Insert(String table, Vector records)` Inserts the set of records into a table.
`int` `Insert(String table, Vector fields, Vector values)` Inserts values for selected fields into a table.
`boolean` `is_Open()` Tests if a connection to the database server is open.
`Vector` `Keys(String table)` Gets a list of primary keys for a table.
`boolean` `Matches(String string_1, String string_2)` Tests if two strings match.
`static boolean` `Matches(String string_1, String string_2, boolean case_sensitive)` Tests if two strings match.
`boolean` `Matches(Vector vector, String string)` Tests if a string matches any element of a Vector.
`static boolean` `Matches(Vector vector, String string, boolean case_sensitive)` Tests if a string matches any element of a Vector.
`void` `Open(Configuration configuration)` Opens a Data_Port using the Configuration.
`Configuration` `Parameters()` Gets the required and optional parameters used by the default Data_Port.
`Configuration` `Parameters(String type)` Gets the required and optional parameters used by a Data_Port type.
`Vector` `Query(String SQL_Query)` Unlimited Query.
`Vector` `Query(String SQL_Query, int limit)` Submit an SQL query.
`boolean` `Remove_SQL_Listener(SQL_Listener listener)` Removes a SQL_Listener from the list of listeners to be notified of SQL statements before they are sent to the database server.
`void` `Rename(String table, String name)` Renames a table.
`void` `Rename(String table, Vector fields, Vector names)` Renames fields in a table.
`Vector` `Select()` Selects the entire default table.
`Vector` `Select(String table)` Selects an entire single table.
`Vector` `Select(String table, String conditional)` Selects all fields conditionally from a single table.
`Vector` `Select(String table, Vector fields)` Selects unconditionally from the fields of a single table.
`Vector` `Select(String table, Vector fields, String conditional)` Selects fields conditionally from a single table.
`Vector` `Select(Vector fields)` Selects fields unconditionally from the default table.
`Vector` `Select(Vector fields, String conditional)` Selects fields conditionally from the default table.
`Vector` `Select(Vector tables, Vector fields, String conditional)` Selects fields conditionally from a list of tables with no limit on the number of records returned.
`Vector` `Select(Vector tables, Vector fields, String conditions, int limit)` Selects from one or more tables the data values from one or more named fields from the data records that satisfy the selection conditions.
`Configuration` `Server_Configuration()` Gets the default server configuration.
`Configuration` `Server_Configuration(String server)` Gets a copy of the configuration for a database server.
`static String` `Special_to_Escape(String string)` Substitutes escape sequences for special characters in a String.
`String` `Table_Name(String table_reference)` Gets the table name portion of a table reference.
`String` `Table_Reference_Component_Delimiter()` Gets the table reference component delimiter.
`String` `Table_Reference(String catalog, String table)` Generates a table reference from a catalog and table name.
`Vector` `Tables(String catalog)` Gets the list of tables in a catalog on the database server.
`String` `toString()` Gets a one line String identifying the Data_Port.
`int` `Update(String SQL_Update)` Submit an SQL update.
`int` `Update(String table, Vector fields, Vector values, String conditions)` Updates values for selected fields into a table.
`static String` `Value_Syntax(String value, String type)` Filters a data value to protect special characters.

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

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

### Field Detail

#### ID

    public static final String ID

Class name and version identification.

See Also:
  Constant Field Values

#### SERVER

    public static final String SERVER

The parameter name for the default database server: "Server".

See Also:
  Constant Field Values

#### TYPE

    public static final String TYPE

The parameter name for the type of database server which corresponds to the Data_Port class to use: "Type".

See Also:
  Constant Field Values

#### DRIVER

    public static final String DRIVER

The parameter name for the driver class to provide access to the database server: "Driver".

See Also:
  Constant Field Values

#### DATABASE

    public static final String DATABASE

The parameter name for the name of the database on the server to be used: "Database".

N.B.: Some database servers require the value of this parameter to make a client connection (e.g. PostgreSQL), while others do not use it (e.g. MySQL).

See Also:
  `CATALOG`, Constant Field Values

#### CATALOG

    public static final String CATALOG

The parameter name for a container of data tables: "Catalog".

N.B.: The meaning of the term "catalog" to the Database class is the database server structure that contains a collection of data tables. For some database servers the corresponding term is "database" (e.g. MySQL), while for others it is "schema" (e.g. PostgreSQL).

See Also:
  Constant Field Values

#### TABLE

    public static final String TABLE

The parameter name for the name of one or more tables within a catalog: "Table".

See Also:
  Constant Field Values

#### FIELDS

    public static final String FIELDS

The parameter name for the name of one or more fields within a table: "Field".

See Also:
  Constant Field Values

#### NULL_VALUE

    public static final String NULL_VALUE

The "value" to specify when setting a field to NULL.

See Also:
  Constant Field Values

#### DEFAULT_CONFIGURATION_FILENAME

    public static final String DEFAULT_CONFIGURATION_FILENAME

The default configuration filename: "Database.conf".

See Also:
  Constant Field Values

#### NL

    public static final String NL

The new-line sequence for the local host system.

### Constructor Detail

#### Database

    public Database()
             throws Database_Exception

Creates a Database with a default Configuration.

Throws:
  `Database_Exception`

#### Database

    public Database(Configuration configuration)
             throws Database_Exception

Creates a Database with a specific Configuration.

Parameters:
  `configuration` - The Configuration to use when `connecting` to the database server. If the configuration is null, a default Configuration is created.
Throws:
  `Database_Exception`

### Method Detail

#### Configuration

    public Configuration Configuration()

Gets the Configuration for the Database.

Specified by:
  `Configuration` in interface `Data_Port`
Returns:
  The Configuration of the Database.
See Also:
  `Configuration`

#### Data_Port

    public Data_Port Data_Port()

Gets the current Data_Port backing the Database.

Returns:
  The Data_Port currently being used by the Database. This will be null if the Database does not have a connection to a database server.

#### Connect

    public Database Connect(String server,
                   String catalog)
                     throws Database_Exception,
                            Configuration_Exception

Connects the Database to a named database server and a specific catalog of the database as a data source.

To connect to a database server the Configuration parameters used to ``Open`` the connection must be found in the Configuration of this Database in a ``Group`` with the database server name. The case sensitivity of the search for the server name is controlled by the Configuration ``Case_Sensitive`` setting. If the name of this Database Configuration matches the server name, then the entire Configuration is used. If the server name is null, then the value of the top_level ``SERVER`` parameter will be used, if present; otherwise the value of the top level ``TYPE`` parameter will be used.

Note: The use of the `TYPE` parameter is deprecated; it is provided for backwards compatibility with previous versions of the Database configuration rules in which the database server was known by its `TYPE` name.

If a non-null catalog name is provided, a ``CATALOG`` parameter is set in the server Configuration group with this name.

Once the server Configuration group has been setup it is used to `Open` the `Data_Port` of this Database.

Parameters:
  `server` - The name of the database server to use. If null the `default server name` is used.
  `catalog` - The name of database catalog to use. This may be null if no specific catalog is selected.
Returns:
  This Database.
Throws:
  `Configuration_Exception` - If the database server name can not be found in the Configuration, or its server group does not contain a ``TYPE`` parameter.
  `Database_Exception` - If the Data_Port could not be `Open`ed.
See Also:
  `Configuration.Group(String)`, `Open(Configuration)`

#### Connect

    public Database Connect(String server)
                     throws Database_Exception,
                            Configuration_Exception

Connects the Database to a named database server.

Parameters:
  `server` - The name of the database server to use.
Returns:
  This Database.
Throws:
  `Database_Exception` - If establishing the Data_Port Configuration failed, or there was a problem opening the Data_Port.
  `Configuration_Exception`
See Also:
  `Connect(String, String)`

#### Connect

    public Database Connect()
                     throws Database_Exception,
                            Configuration_Exception

Connects the Database to the default database server.

Returns:
  This Database.
Throws:
  `Database_Exception` - If establishing the Data_Port Configuration failed, or there was a problem opening the Data_Port.
  `Configuration_Exception`
See Also:
  `Connect(String, String)`

#### Disconnect

    public void Disconnect()
                    throws Database_Exception

Disconnect the Database (its backing Data_Port) from its database server.

If the Data_Port is already closed, nothing is done.

Throws:
  `Database_Exception`

#### Parameters

    public Configuration Parameters(String type)
                             throws Database_Exception,
                                    Configuration_Exception

Gets the required and optional parameters used by a Data_Port type.

Parameters:
  `type` - The name of the Data_Port type. If null, the currently connected Data_Port will be queried.
Returns:
  A Configuration of Required and Optional Data_Port parameters.
Throws:
  `Database_Exception` - If the Data_Port class can not be loaded.
  `IllegalArgumentException` - If the Data_Port type is null and there is no currently connected Data_Port.
  `Configuration_Exception` - If the Data_Port could not be loaded.
See Also:
  `Data_Port.Parameters()`

#### Parameters

    public Configuration Parameters()
                             throws Database_Exception,
                                    Configuration_Exception

Gets the required and optional parameters used by the default Data_Port.

Specified by:
  `Parameters` in interface `Data_Port`
Returns:
  A Configuration of Required and Optional Data_Port parameters.
Throws:
  `Database_Exception` - If the Data_Port could not be accessed.
  `Configuration_Exception` - If the database Configuration could not be accessed.
See Also:
  `Parameters(String)`

#### Default_Server_Name

    public String Default_Server_Name()

Gets the default server name from the Database Configuration.

If a ``Server`` parameter is not found in the `Configuration` of the Database the ``Type`` parameter is obtained. These parameters must be at the top level of the Configuration.

Returns:
  The default server name for use in making a `connection` to a database server. This will be null if the Database Configuration does not contain the required information.

#### Server_Configuration

    public Configuration Server_Configuration(String server)
                                       throws Configuration_Exception

Gets a copy of the configuration for a database server.

The server name is expected to be the name of a Configuration Group in the Database Configuration.

If the server name matches the name of the Database Configuration a copy of the entire Database Configuration is returned. Otherwise a copy of the first Group in the Database Configuration with the server name is returned.

Parameters:
  `server` - The server name. If null the `default server name` is used.
Returns:
  A Configuration for the server. This will be null if the server name is null and no default server could be identified, or if no Group with the server name could be found.
Throws:
  `Configuration_Exception` - If there was a problem while manipulating a Configuration.
See Also:
  `Configuration()`

#### Server_Configuration

    public Configuration Server_Configuration()
                                       throws Configuration_Exception

Gets the default server configuration.

Returns:
  A Configuration for the default server. This will be null if no default server can be found.
Throws:
  `Configuration_Exception` - If there was a problem while manipulating a Configuration.
See Also:
  `Server_Configuration(String)`

#### Open

    public void Open(Configuration configuration)
              throws Database_Exception,
                     Configuration_Exception

Opens a Data_Port using the Configuration.

If the Data_Port for this Database is already open, it is closed and then re-opened.

Before a Data_Port can be opened its implementing class must be loaded. The configuration must contain a ``Type`` parameter which is used to select the Data_Port class that will be loaded to manage access to the database server. The name of this class must be "type"_Data_Port, where "type" is the value of the Configuration TYPE parameter. If the class is not found in the current classpath, it is presumed to be in PIRL.Database package. The `Open` method of the new Data_Port instance will be given the configuration to use in establishing its connection to the database server.

Note: The configuration of the Data_Port may be completely separate from the configuration associated with this Database; the preferred method to open access to a database is to use one of the ``Connect`` methods.

Specified by:
  `Open` in interface `Data_Port`
Parameters:
  `configuration` - The Configuration for the Data_Port. If the configuration is null the default ``Connect`` method is used to select a database type and its configuration.
Throws:
  `Database_Exception` - If the TYPE parameter could not be found in the configuration; the implementing Data_Port class could not be loaded; or the Data_Port Open failed.
  `Configuration_Exception` - If the database Configuration could not be accessed.
See Also:
  `Configuration`

#### Close

    public void Close()
               throws Database_Exception

Closes the Database connection to the database server.

Specified by:
  `Close` in interface `Data_Port`
Throws:
  `Database_Exception` - If there was a problem releasing any of the resources associated with the Data_Port.
See Also:
  `Disconnect()`

#### is_Open

    public boolean is_Open()

Tests if a connection to the database server is open.

Specified by:
  `is_Open` in interface `Data_Port`
Returns:
  true if the Data_Port is open; false otherwise.

#### Connection

    public Connection Connection()

Gets the JDBC Connection object. Note: A Data_Port is not required to use a JDBC Connection.

Specified by:
  `Connection` in interface `Data_Port`
Returns:
  A JDBC Connection object associated with the Data_Port backing the Database. This will be null if the Data_Port is closed or it does not use a JDBC Connection.

#### Add_SQL_Listener

    public Data_Port Add_SQL_Listener(SQL_Listener listener)

Adds a SQL_Listener to the list of listeners to be notified of SQL statements before they are sent to the database server.

Specified by:
  `Add_SQL_Listener` in interface `Data_Port`
Parameters:
  `listener` - A SQL_Listener to be added. If null, or the listener is already listed, nothing is done.
Returns:
  This Data_Port, or null if the Data_Port is closed.
See Also:
  `SQL_Listener`

#### Remove_SQL_Listener

    public boolean Remove_SQL_Listener(SQL_Listener listener)

Removes a SQL_Listener from the list of listeners to be notified of SQL statements before they are sent to the database server.

Specified by:
  `Remove_SQL_Listener` in interface `Data_Port`
Parameters:
  `listener` - A SQL_Listener to be removed.
Returns:
  true if the listener was removed; false if the listener was not listed or the the Data_Port is closed.
See Also:
  `SQL_Listener`

#### toString

    public String toString()

Description copied from interface: `Data_Port`
Gets a one line String identifying the Data_Port.

Specified by:
  `toString` in interface `Data_Port`
Overrides:
  `toString` in class `Object`
Returns:
  The identifification line for the Data_Port.
See Also:
  `Data_Port.toString()`

#### Description

    public String Description()

Description copied from interface: `Data_Port`
Gets a multi-line description of the Data_Port. If the Data_Port is currently ``Open``, this may include a description of the database connection.

Specified by:
  `Description` in interface `Data_Port`
Returns:
  The multi-line description of the Data_Port and any active database connection.
See Also:
  `Data_Port.Description()`

#### Contents

    public String Contents(String catalog,
                  String table)

Description copied from interface: `Data_Port`
Gets a String describing the contents of selected catalogs and tables.

For each table being described each field name and its data type is listed. Each Data_Port implementation may provide other details.

Specified by:
  `Contents` in interface `Data_Port`
Parameters:
  `catalog` - The catalog to have its contents described. If it is in catalog.table format, the catalog portion of the name will be used. If null, all catalogs on the database server will be described.
  `table` - The table to have its contents described. If it is in catalog.table format, the table portion of the name will be used. If null, all tables in the catalog (or all catalogs) will be described.
Returns:
  A descriptive String.
See Also:
  `Data_Port.Contents(String, String)`

#### Catalogs

    public Vector Catalogs()
                    throws Database_Exception

Description copied from interface: `Data_Port`
Gets the list of catalogs on the database server.

Specified by:
  `Catalogs` in interface `Data_Port`
Returns:
  A Vector of catalog name Strings.
Throws:
  `Database_Exception` - If the Data_Port is not open, or the operation on the database server failed.
See Also:
  `Data_Port.Catalogs()`

#### Tables

    public Vector Tables(String catalog)
                  throws Database_Exception

Description copied from interface: `Data_Port`
Gets the list of tables in a catalog on the database server.

Specified by:
  `Tables` in interface `Data_Port`
Parameters:
  `catalog` - The name of the catalog to be examined. If null, the ``CATALOG`` from the Data_Port `Configuration` will be used.
Returns:
  A Vector of table name Strings. If the catalog does not exist in the database, null will be returned. An empty Vector will be returned for a catalog that does not contain any tables.
Throws:
  `Database_Exception` - If the Data_Port is not open, or the operation on the database server failed.
See Also:
  `Data_Port.Tables(String)`

#### Field_Names

    public Vector Field_Names(String table)
                       throws Database_Exception

Description copied from interface: `Data_Port`
Gets the list of field names in a table on the database server.

Specified by:
  `Field_Names` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If null, then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
Returns:
  A Vector of field name Strings. If the table does not exist in the Database, null will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open, no catalog name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Field_Names(String)`

#### Field_Types

    public Vector Field_Types(String table)
                       throws Database_Exception

Description copied from interface: `Data_Port`
Gets the list of field data types in a table on the database server.

Specified by:
  `Field_Types` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If null, then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
Returns:
  A Vector of field type name Strings. If the table does not exist in the Database, null will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Field_Types(String)`

#### Fields

    public Vector Fields(String table,
                String field_info)
                  throws Database_Exception

Description copied from interface: `Data_Port`
Obtains a list of field information for the table of a catalog.

The field_info tag corresponding to one of the field information names known to the database server. The possible tag lists should be available from the description of the particular Data_Port implementation being used, or in the database server documentation.

Specified by:
  `Fields` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `field_info` - The tag String for selecting field information.
Returns:
  A Vector of field information Strings, one per field. For info that is originally numeric (as indicated in the table) a String representation is returned. If the table does not exist in the Database, a null will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Fields(String, String)`

#### Keys

    public Vector Keys(String table)
                throws Database_Exception

Description copied from interface: `Data_Port`
Gets a list of primary keys for a table.

Specified by:
  `Keys` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
Returns:
  A Vector of field name Strings.
Throws:
  `Database_Exception` - If no catalog or table name is available, or the database server rejected the operation.
See Also:
  `Data_Port.Keys(String)`

#### Query

    public Vector Query(String SQL_Query,
               int limit)
                 throws Database_Exception

Description copied from interface: `Data_Port`
Submit an SQL query.

The SQL_query String is an SQL statment that requests data to be extracted (not removed) from the database. The syntax, though "standardized", is likely to vary in its particulars dependent on the database server implementation.

A query always returns a table. The table is in the form of a Vector of data record Vectors. The first record contains the names (String) of each field for the data in corresponding locations of all the field value records that follow; i.e. these are the table column names. The field values in each data record are always provided in String representation regardless of the data type stored in the database. However, NULL field values remain unchanged as they are distinct from an otherwise valid field value.

Note: A field value will either be a String or null.

Specified by:
  `Query` in interface `Data_Port`
Parameters:
  `SQL_Query` - The syntax of the query string is database dependent. A typical example is an SQL "SELECT" statement.
  `limit` - The maximum number of records to return. If negative, there will be no limit to the number of records returned. If zero, no records will be returned.
Returns:
  A data table in form of a Vector of String Vectors (records). The first record is the field names for the field values in all subsequent records.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.
See Also:
  `Data_Port.Query(String, int)`

#### Select

    public Vector Select(Vector tables,
                Vector fields,
                String conditions,
                int limit)
                  throws Database_Exception

Description copied from interface: `Data_Port`
Selects from one or more tables the data values from one or more named fields from the data records that satisfy the selection conditions.

Note: Each table name that is not in the format catalog.table will have the ``CATALOG`` from the `Configuration` prepended.

Specified by:
  `Select` in interface `Data_Port`
Parameters:
  `tables` - The Vector of database tables from which to select records. If this is null, the table specified in the Configuration will be used.
  `fields` - A Vector of field name Strings specifying the data fields (columns) to be extracted. If this is null, all data fields will be extracted.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied; all data records will be used.
  `limit` - The maximum number of records to return. If negative, there will be no limit to the number of records returned. If zero, the returned vector will contain a single string that is the SQL statement that would have been submitted to the Query method.
Returns:
  A Vector of String Vectors data table,as provided by the ``Query`` method.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Select(Vector, Vector, String, int)`

#### Update

    public int Update(String SQL_Update)
               throws Database_Exception

Description copied from interface: `Data_Port`
Submit an SQL update.

The syntax of the SQL_update String is database dependent. These operations modify the database and return a count of the number of modifications, which may be 0 in some cases (e.g. when a catalog or table is created). Typical examples are SQL "UPDATE", "INSERT", and "ALTER" statements.

Specified by:
  `Update` in interface `Data_Port`
Parameters:
  `SQL_Update` - The SQL_update statement.
Returns:
  A count of the number of modifications.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.
See Also:
  `Data_Port.Update(String)`

#### Create

    public void Create(String catalog)
                throws Database_Exception

Description copied from interface: `Data_Port`
Creates a catalog in the database.

Specified by:
  `Create` in interface `Data_Port`
Parameters:
  `catalog` - The name of the catalog to create. A null catalog name, or a name of a catalog already in the database, is ignored.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.
See Also:
  `Data_Port.Create(String)`

#### Delete

    public void Delete(String catalog)
                throws Database_Exception

Description copied from interface: `Data_Port`
Deletes a catalog from the database.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `catalog` - The name of the catalog to delete. A null catalog name, or a name that is not a catalog in the database, is ignored.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.
See Also:
  `Data_Port.Delete(String)`

#### Create

    public void Create(String table,
              Vector fields,
              Vector types)
                throws Database_Exception

Description copied from interface: `Data_Port`
Creates data tables with their fields and the data types of the fields.

If the table does not exist, a new one is created. For each name String in the fields Vector, if the field does not exist, it is created with the data type from the corresponding entry in the types Vector. If the field is already present in the table, its data type is changed if needed.

A table name that is not in the format catalog.table will have the ``CATALOG`` from the `Configuration` prepended.

Specified by:
  `Create` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be created. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be used.
  `types` - The Vector of data type names to be applied to the corresponding fields.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and types are not the same, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Create(String, Vector, Vector)`

#### Delete

    public void Delete(String table,
              Vector fields)
                throws Database_Exception

Description copied from interface: `Data_Port`
Deletes fields from a data table, or the entire table.

Each field in the fields list is deleted from the table. If the field is not present in the table, it is ignored. If the fields list is null, the entire table is deleted from the catalog. N.B.: A table is not deleted even if all of its fields are deleted.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be deleted. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be used.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Delete(String, Vector)`

#### Rename

    public void Rename(String table,
              String name)
                throws Database_Exception

Description copied from interface: `Data_Port`
Renames a table.

If the table does not exist, nothing is done.

Specified by:
  `Rename` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be renamed. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `name` - The new name for the table. If this is null, nothing is done.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Rename(String, String)`

#### Rename

    public void Rename(String table,
              Vector fields,
              Vector names)
                throws Database_Exception

Description copied from interface: `Data_Port`
Renames fields in a table.

Each field name in the fields Vector that exists in the table is renamed to the corresponding name in the names Vector. If the table does not exist, nothing is done.

Note: The existing type for the field, obtained from the ``Field_Types`` method, is re-applied to the field (due to requirments of the SQL syntax). This could alter other characteristics of the field.

Specified by:
  `Rename` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be renamed.
  `names` - The Vector of new field names.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and names are not the same, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Rename(String, Vector, Vector)`

#### Insert

    public int Insert(String table,
             Vector fields,
             Vector values)
               throws Database_Exception

Description copied from interface: `Data_Port`
Inserts values for selected fields into a table.

A new data record is created in the table. The fields Vector lists the names of the fields to be assigned a data value from the corresponding entry in the values Vector. The Vector of data values does not necessarily have to contain Strings, as long as each object's toString method produces a valid representation of the field value. Though the fields and values Vectors must be the same size, not all fields in the table need to be included; the database is expected to provide the default for missing fields.

Specified by:
  `Insert` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names for the data values.
  `values` - The Vector of data values corresponding the Vector of field names.
Returns:
  The number of records inserted; 1 if successful; 0 otherwise.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and values are not the same, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Insert(String, Vector, Vector)`

#### Update

    public int Update(String table,
             Vector fields,
             Vector values,
             String conditions)
               throws Database_Exception

Description copied from interface: `Data_Port`
Updates values for selected fields into a table.

The fields Vector lists the names of the fields to be assigned a new data value from the corresponding entry in the values Vector. The Vector of data values does not necessarily have to contain Strings, as long as each object's toString method produces a valid representation of the field value. The records to have their field values updated will be selected by the conditions expression. This is an SQL WHERE expression (without the "WHERE" keyword). If no conditions are provided, then all records will be updated.

Specified by:
  `Update` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names for the data values.
  `values` - The Vector of data values corresponding the Vector of field names.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied; all data records will be used.
Returns:
  The number of records that were modified.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and values are not the same, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Update(String, Vector, Vector, String)`

#### Delete

    public int Delete(String table,
             String conditions)
               throws Database_Exception

Description copied from interface: `Data_Port`
Deletes selected records from a table.

The records to be deleted will be selected by the conditions expression. This is an SQL WHERE expression (without the "WHERE" keyword).

Warning: If no conditions are provided, then all records will be deleted leaving an empty table.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in catalog.table format, the ``CATALOG`` will be used.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied and all data records will be deleted.
Returns:
  The number of records that were deleted.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Delete(String, String)`

#### Table_Reference

    public String Table_Reference(String catalog,
                         String table)
                           throws Database_Exception

Description copied from interface: `Data_Port`
Generates a table reference from a catalog and table name.

A table reference in a Data_Port method may be a composite name combining a catalog name and a table name. The specific format for this combination is dependent on the syntax requirements of the database being used.

If a non-null, non-empty catalog name is specified it will override any catalog name portion that might be in a table name that is already in table reference format. The Data_Port may use appropriate defaults for null or empty table or catalog names; e.g. the value of ``CATALOG`` and ``TABLE`` Configuration parameters. Though how defaults, if any, are provided is at the discretion of the Data_Port.

Specified by:
  `Table_Reference` in interface `Data_Port`
Parameters:
  `catalog` - The catalog name portion for the table reference.
  `table` - The table name portion for the table reference.
Returns:
  A table reference suitable for use as a `table` argument of a Data_Port method.
Throws:
  `Database_Exception` - If a table reference can not be formed.
See Also:
  `Data_Port.Table_Reference(String, String)`

#### Catalog_Name

    public String Catalog_Name(String table_reference)
                        throws Database_Exception

Description copied from interface: `Data_Port`
Gets the catalog name portion of a table reference.

Specified by:
  `Catalog_Name` in interface `Data_Port`
Parameters:
  `table_reference` - A String that may be a composite name combining a catalog name and a table name in a database specific format.
Returns:
  The catalog name portion of the table reference. If the table reference does not have a catalog name portion the empty String is returned.
Throws:
  `Database_Exception` - If the Data_Port is not open.
See Also:
  `Data_Port.Catalog_Name(String)`

#### Database_Catalog_Name

    public String Database_Catalog_Name(String catalog)
                                 throws Database_Exception

Description copied from interface: `Data_Port`
Gets the name known to the database server for a catalog name.

Only accessible catalogs can be identified. If the database server determines that the connection does not have permission to access the specified catalog then it can not be identified.

N.B.: Identifying the catalog from the list of accessible catalogs is done using the `case sensitivity` of the Data_Port implementation. Therefore, if case sensitive matching is used this method can only return the specified catalog name or null; in this case this method is only useful for determining if a catalog is accessible or not.

Specified by:
  `Database_Catalog_Name` in interface `Data_Port`
Parameters:
  `catalog` - The name of the database calolog to examine. If this is a `table reference` only the catalog part will be used. If null or empty the ``CATALOG`` value from the `configuration`, if available, will be used.
Returns:
  The name of the catalog as it is known in the database. This will be null if a non-null, non-empty catalog name could not be identified in the database.
Throws:
  `Database_Exception` - If the Data_Port is not open, a catalog name was not provided, or the database rejects the operation.
See Also:
  `Data_Port.Database_Catalog_Name(String)`

#### Table_Name

    public String Table_Name(String table_reference)
                      throws Database_Exception

Description copied from interface: `Data_Port`
Gets the table name portion of a table reference.

Specified by:
  `Table_Name` in interface `Data_Port`
Parameters:
  `table_reference` - A String that may be a composite name combining a catalog name and a table name in a database specific format.
Returns:
  The table name portion of the table reference. If the table reference is null the empty String will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open.
See Also:
  `Data_Port.Table_Name(String)`

#### Database_Table_Name

    public String Database_Table_Name(String table)
                               throws Database_Exception

Description copied from interface: `Data_Port`
Gets the name known to the database server for a table name.

Only accessible catalogs can be identified. If the database server determines that the connection does not have permission to access the specified catalog then it can not be identified.

N.B.: Identifying the catalog from the list of accessible catalogs is done using the `case sensitivity` of the Data_Port implementation. Therefore, if case sensitive matching is used this method can only return the specified catalog name or null; in this case this method is only useful for determining if a catalog is accessible or not.

Specified by:
  `Database_Table_Name` in interface `Data_Port`
Parameters:
  `table` - The name of the table to identify in the database. If null, then the ``TABLE`` value from the `Configuration`, if present, will be used. If it is not in catalog.table format, the ``CATALOG`` value, if present, will be used.
Returns:
  The name of the catalog as it is known in the database. This will be null if a catalog name could not be identified in the database.
Throws:
  `Database_Exception` - If the Data_Port is not open, catalog and table names were not provided, or the database rejects the operation.
See Also:
  `Data_Port.Database_Table_Name(String)`

#### Table_Reference_Component_Delimiter

    public String Table_Reference_Component_Delimiter()
                                               throws Database_Exception

Description copied from interface: `Data_Port`
Gets the table reference component delimiter.

Specified by:
  `Table_Reference_Component_Delimiter` in interface `Data_Port`
Returns:
  The portion of a table reference that delimits the catalog component from the table component.
Throws:
  `Database_Exception` - If the Data_Port is not open.
See Also:
  `Data_Port.Table_Reference_Component_Delimiter()`

#### Case_Sensitive_Identifiers

    public boolean Case_Sensitive_Identifiers()
                                       throws Database_Exception

Description copied from interface: `Data_Port`
Tests if identifier names are treated as case sensitive by the Data_Port.

Because some database servers on some operating systems are not case sensitive in handling identifiers (the names of catalogs, tables, and field names) it is necessary to enforce case insensitivity when matching user specified names against identifiers returned from the database server. This method indicates how the Data_Port expects identifier names to be treated.

N.B.: The identifier case sensitivity that is reported by the Data_Port does not necessarily reflect the identifier case sensitivity of the database server under all circumstances. Some identifiers may be case sensitive and others not, a given identifier may be case sensitive on some systems but not on others, an identifier may be case sensitive if double quoted but otherwise not (PostgreSQL); the rules are database implementation specific.

What the Case_Sensitive_Identifiers flag indicates is how indentifiers provided the by the user will be matched against identifiers provided by the database server.

Specified by:
  `Case_Sensitive_Identifiers` in interface `Data_Port`
Returns:
  true if identifiers will be matched with case sensitive comparisons; false if matching will ignore case.
Throws:
  `Database_Exception`
See Also:
  `Data_Port.Case_Sensitive_Identifiers()`

#### Case_Sensitive_Identifiers

    public void Case_Sensitive_Identifiers(boolean case_sensitive)
                                    throws Database_Exception

Description copied from interface: `Data_Port`
Attempts to set whether identifier names are treated as case sensitive by the Data_Port.

N.B.: This setting does not itself determine the case sensitivity of the identifiers by the database server. The value is used to inform the Database software if case sensitive matches should be done. Setting the value to true when the database server uses case insensitive identifiers (mixed case identifiers provided by the user to the database server being always read back as all lowercase) will ultimately result in unexpected mismatches. Only set the value to true when it is known that the database server accessed by the Data_Port is capable of using case sensitive identifiers.

N.B.: A Data_Port implementation is free to ignore this setting, and may even through an exception if it thinks that the value would cause problems. In general, it is best to leave the case sensitive identifiers setting up to the Data_Port. Only when the application is aware of particular circumstances when using a particular database server that would call for a change of the Data_Port setting should the value be changed.

Specified by:
  `Case_Sensitive_Identifiers` in interface `Data_Port`
Parameters:
  `case_sensitive` - true if identifiers are to be matched with case sensitive comparisons; false if matching is to ignore case.
Throws:
  `Database_Exception` - If the Data_Port can not be accessed, or the Data_Port rejects the setting.
See Also:
  `Data_Port.Case_Sensitive_Identifiers(boolean)`

#### Select

    public Vector Select(Vector tables,
                Vector fields,
                String conditional)
                  throws Database_Exception

Selects fields conditionally from a list of tables with no limit on the number of records returned.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(String table,
                Vector fields,
                String conditional)
                  throws Database_Exception

Selects fields conditionally from a single table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select()
                  throws Database_Exception

Selects the entire default table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(String table)
                  throws Database_Exception

Selects an entire single table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(String table,
                Vector fields)
                  throws Database_Exception

Selects unconditionally from the fields of a single table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(String table,
                String conditional)
                  throws Database_Exception

Selects all fields conditionally from a single table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(Vector fields)
                  throws Database_Exception

Selects fields unconditionally from the default table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Select

    public Vector Select(Vector fields,
                String conditional)
                  throws Database_Exception

Selects fields conditionally from the default table.

Throws:
  `Database_Exception`
See Also:
  `Select(Vector, Vector, String, int)`

#### Query

    public Vector Query(String SQL_Query)
                 throws Database_Exception

Unlimited Query.

Throws:
  `Database_Exception`
See Also:
  `Query(String, int)`

#### Insert

    public int Insert(String table,
             Vector records)
               throws Database_Exception

Inserts the set of records into a table.

The set of records is like that returned from the ``Select`` or ``Query`` methods: a Vector of record Vectors, where the first Vector contains the String names of the fields corresponding to the data values in the subsequent Vectors. The data records do not necessarily have to contain Strings, as long as each object's toString method produces a valid representation of the field value. Though all the records must be the same size, not all fields in the table need to be included; the database is expected to provide the default for missing fields.

An entire table can be copied from an old_table into a new_table using:

    database.Insert (new_table, database.Select (old_table))

Parameters:
  `table` - The name of the table in which to insert the records. This may be null to use the default table.
  `records` - The field names record followed by a set of data records.
Returns:
  The number of records inserted.
Throws:
  `Database_Exception` - If an insertion failed.
See Also:
  `Insert(String, Vector, Vector)`

#### Hash_Map

    public static Hashtable Hash_Map(Vector keys,
                     Vector values)
                              throws Database_Exception

Constructs a Hashtable from a Vector of keys and a corresponding Vector of values.

Parameters:
  `keys` - The Vector of objects to be used as the Hashtable keys.
  `values` - The Vector of objects to be used as the Hashtable values.
Returns:
  A Hashtable of key/value pairs. This will be null if either the keys or values Vectors are null.
Throws:
  `Database_Exception` - If the keys and values Vectors are not the same size, there is a duplicate (equals) key object, or a key or value is null.
See Also:
  `Hashtable.put(Object, Object)`

#### Matches

    public static boolean Matches(String string_1,
                  String string_2,
                  boolean case_sensitive)

Tests if two strings match.

This is a helper function used by the Matches methods.

Parameters:
  `string_1` - A String to be compared.
  `string_2` - The other String for the comparison.
  `case_sensitive` - If true, the string comparison will be case sensitive; otherwise the comparison will ignore case.
Returns:
  true if the strings match, false otherwise. If both strings are null they match. If only one string is null, they do not match.
See Also:
  `Matches(String, String)`

#### Matches

    public boolean Matches(String string_1,
                  String string_2)

Tests if two strings match.

The `Matches` function will be used with case sensitivity determined by the `Data_Port identifier case sensitivity` or the `Case_Sensitive_Default` value if the Database is not bound to a Data_Port.

Parameters:
  `string_1` - A String to be compared.
  `string_2` - The other String for the comparison.
Returns:
  true if the strings match, false otherwise. If both strings are null they match.
See Also:
  `Matches(String, String, boolean)`

#### Matches

    public static boolean Matches(Vector vector,
                  String string,
                  boolean case_sensitive)

Tests if a string matches any element of a Vector.

This is a helper function used by the corresponding Matches method.

Parameters:
  `vector` - The Vector to search for a matching String. Each element of the Vector is cast to a String. If null, false is returned.
  `string` - The String to be compared. May be null, in which case the vector must contain a null element for true to be returned.
  `case_sensitive` - If true, the string comparison will be case sensitive; otherwise the comparison will ignore case.
Returns:
  true if the string matches any element of the vector, false otherwise.
See Also:
  `Matches(String, String, boolean)`

#### Matches

    public boolean Matches(Vector vector,
                  String string)

Tests if a string matches any element of a Vector.

The `Matches` function will be used with case sensitivity determined by the `Data_Port identifier case sensitivity` or the `Case_Sensitive_Default` value if the Database is not bound to a Data_Port.

Parameters:
  `vector` - The Vector to search for a matching String. Each element of the Vector is cast to a String. If null, false is returned.
  `string` - The String to be compared. May be null, in which case the vector must contain a null element for true to be returned.
Returns:
  true if the string matches any element of the vector, false otherwise.

#### Index

    public static int Index(Vector vector,
            String string,
            boolean case_sensitive)

Gets the index of the string that matches an element of a Vector.

This is a helper function used by the corresponding Index method.

Parameters:
  `vector` - The Vector to search for a matching String. Each element of the Vector is cast to a String. If null, -1 is returned.
  `string` - The String to be compared. May be null, in which case the index of the first null element of the vector, if any, will be returned.
Returns:
  The index of the first element of the vector that matches the string, or -1 if no match is found.
See Also:
  `Matches(String, String, boolean)`

#### Index

    public int Index(Vector vector,
            String string)

Gets the index of the string that matches an element of a Vector.

The `Index` function will be used with case sensitivity determined by the `Data_Port identifier case sensitivity` or the `Case_Sensitive_Default` value if the Database is not bound to a Data_Port.

Parameters:
  `vector` - The Vector to search for a matching String. Each element of the Vector is cast to a String. If null, -1 is returned.
  `string` - The String to be compared. May be null, in which case the index of the first null element of the vector, if any, will be returned.
Returns:
  The index of the first element of the vector that matches the string, or -1 if no match is found.

#### Index

    public static int Index(String[] array,
            String string,
            boolean case_sensitive)

Gets the index of the string that matches an element of an array.

This is a helper function used by the corresponding Index method.

Parameters:
  `array` - The array of Strings to search for a matching String. If null, -1 is returned.
  `string` - The String to be compared. May be null, in which case the index of the first null element of the array, if any, will be returned.
Returns:
  The index of the first element of the array that matches the string, or -1 if no match is found.
See Also:
  `Matches(String, String, boolean)`

#### Index

    public int Index(String[] array,
            String string)

Gets the index of the string that matches an element of an array.

The `Index` function will be used with case sensitivity determined by the `Data_Port identifier case sensitivity` or the `Case_Sensitive_Default` value if the Database is not bound to a Data_Port.

Parameters:
  `array` - The array of Strings to search for a matching String. If null, -1 is returned.
  `string` - The String to be compared. May be null, in which case the index of the first null element of the array, if any, will be returned.
Returns:
  The index of the first element of the array that matches the string, or -1 if no match is found.

#### Escape_to_Special

    public static String Escape_to_Special(String string)

Substitutes special characters for escape sequences.

The following escape sequences, and their corresponding special characters, are recognized:

> \b - Backspace (BS)
> \t - Horizontal tab (HT)
> \n - Newline (NL)
> \f - Form feed (FF)
> \r - Carriage return (CR)
> \X - The character X
> \0nnn - The character having the octal value nnn (0 <= nnn <= 377)

The escape sequences will be substituted for their corresponding special characters. All backslash characters, except those that are themselves escaped, will be removed.

Parameters:
  `string` - The String to be un-escaped.
Returns:
  The un-escaped String.

#### Special_to_Escape

    public static String Special_to_Escape(String string)

Substitutes escape sequences for special characters in a String.

All control characters - less than ' ' (32), plus single quote (39), double quote (34), backslash (92) and DEL (127) - will be substituted with escape sequences:

> \0 - for an ASCII 0 (NUL, 0) character
> \b - for backspace (BS, 8)
> \t - for horizontal tab (HT, 9)
> \n - for newline (NL, 10)
> \f - for form feed (FF, 12)
> \r - for carriage return (CR, 13)
> \' - for a single quote (', 39)
> \" - for a double quote (", 34)
> \ \ - for backslash (\, 92)
> \0nnn - for all other special characters where nnn is the octal value of the character.

Escape sequences in the string will be recognized and left unchanged.

Parameters:
  `string` - The String to be escaped.
Returns:
  The escaped String.

#### Value_Syntax

    public static String Value_Syntax(String value,
                      String type)

Filters a data value to protect special characters.

If the data type is non-numeric it is ``Special_to_Escape`` filtered and enclosed in single quote (') characters. A numeric data type is identified by containing in its name one of these (case insensitive) substrings:

- INT
- REAL
- FLOAT
- DOUBLE

The data value of a numeric data type is not altered.

Parameters:
  `value` - A String representing a data value.
  `type` - The JDBC name of the value's data type.
Returns:
  The possibly altered value string.