PIRL.Database

## Interface Data_Port

All Known Implementing Classes:
  Database, JDBC_Data_Port, MySQL_Data_Port, PostgreSQL_Data_Port

    public interface Data_Port

A Data_Port is the interface for accessing the content of a Database.

See Also:
  `Database`

### 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<String>` `Catalogs()` Gets the list of catalogs on the database server.
`void` `Close()` Closes access to the database through the Data_Port.
`Configuration` `Configuration()` Gets the Configuration of the Data_Port object.
`Connection` `Connection()` Gets the JDBC Connection object for the Data_Port, if there is one.
`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<String> fields, Vector<String> types)` Creates data tables with their fields and the data types of the fields.
`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.
`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<String> fields)` Deletes fields from a data table, or the entire table.
`String` `Description()` Gets a multi-line description of the Data_Port.
`Vector<String>` `Field_Names(String table)` Gets the list of field names in a table on the database server.
`Vector<String>` `Field_Types(String table)` Gets the list of field data types in a table on the database server.
`Vector<String>` `Fields(String table, String field_info)` Obtains a list of field information for the table of a catalog.
`int` `Insert(String table, Vector<String> fields, Vector<Object> values)` Inserts values for selected fields into a table.
`boolean` `is_Open()` Tests if the Data_Port is currently open.
`Vector<String>` `Keys(String table)` Gets a list of primary keys for a table.
`void` `Open(Configuration configuration)` Opens the Data_Port using the parameters from the Configuration to access a database.
`Configuration` `Parameters()` Gets the required and optional parameters used by the Data_Port.
`Vector<Vector<String>>` `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<String> fields, Vector<String> names)` Renames fields in a table.
`Vector<Vector<String>>` `Select(Vector<String> tables, Vector<String> 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.
`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<String>` `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<String> fields, Vector<Object> values, String conditions)` Updates values for selected fields into a table.

### Method Detail

#### Configuration

    Configuration Configuration()

Gets the Configuration of the Data_Port object.

Returns:
  The current Configuration of the Data_Port.
See Also:
  `Configuration`

#### Parameters

    Configuration Parameters()
                             throws Database_Exception,
                                    Configuration_Exception

Gets the required and optional parameters used by the Data_Port.

The Configurtion that is returned will contain two groups: "Required" and "Optional" with lists of parameters naming those in each group. Each parameter may have a value indicating the default that will be used if the parameter is not provided in the Configuration used to ``Open`` the Data_Port. A parameter without a value has no default; a Required parameter without a default must be in the provided Configuration or the `Open` will fail.

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.

#### Open

    void Open(Configuration configuration)
              throws Database_Exception,
                     Configuration_Exception

Opens the Data_Port using the parameters from the Configuration to access a database.

Parameters:
  `configuration` - The Configuration parameters for access to a database through the Data_Port.
Throws:
  `Database_Exception` - If the Data_Port could not be opened.
  `Configuration_Exception` - If the database Configuration could not be accessed.
See Also:
  `Configuration`

#### Close

    void Close()
               throws Database_Exception

Closes access to the database through the Data_Port.

Throws:
  `Database_Exception` - If there was a problem releasing any of the resources associated with the Data_Port.

#### is_Open

    boolean is_Open()

Tests if the Data_Port is currently open.

Returns:
  true if the Data_Port has access to a database; false otherwise.

#### Connection

    Connection Connection()

Gets the JDBC Connection object for the Data_Port, if there is one. There is no guarantee that any particular Data_Port will ever use a JDBC Connection object.

Returns:
  The JDBC Connection object for the Data_Port. This will be null if the Data_Port does not have a Connection, either because it does not have an active Connection or because it does not use a JDBC Connection .

#### Add_SQL_Listener

    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.

Parameters:
  `listener` - A SQL_Listener to be added. If null, or the listener is already listed, nothing is done.
Returns:
  This Data_Port.
See Also:
  `SQL_Listener`

#### Remove_SQL_Listener

    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.

Parameters:
  `listener` - A SQL_Listener to be removed.
Returns:
  true if the listener was removed; false if the listener was not listed.
See Also:
  `SQL_Listener`

#### toString

    String toString()

Gets a one line String identifying the Data_Port.

Overrides:
  `toString` in class `Object`
Returns:
  The identifification line for the Data_Port.

#### Description

    String Description()

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.

Returns:
  The multi-line description of the Data_Port and any active database connection.

#### Contents

    String Contents(String catalog,
                  String table)

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.

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.

#### Catalogs

    Vector<String> Catalogs()
                            throws Database_Exception

Gets the list of catalogs on the database server.

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.

#### Tables

    Vector<String> Tables(String catalog)
                          throws Database_Exception

Gets the list of tables in a catalog on the database server.

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.

#### Field_Names

    Vector<String> Field_Names(String table)
                               throws Database_Exception

Gets the list of field names in a table on the database server.

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.

#### Field_Types

    Vector<String> Field_Types(String table)
                               throws Database_Exception

Gets the list of field data types in a table on the database server.

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.

#### Fields

    Vector<String> Fields(String table,
                        String field_info)
                          throws Database_Exception

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.

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.

#### Keys

    Vector<String> Keys(String table)
                        throws Database_Exception

Gets a list of primary keys for a table.

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.

#### Query

    Vector<Vector<String>> Query(String SQL_query,
                               int limit)
                                 throws Database_Exception

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.

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.

#### Select

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

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.

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.

#### Update

    int Update(String SQL_update)
               throws Database_Exception

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.

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.

#### Create

    void Create(String catalog)
                throws Database_Exception

Creates a catalog in the database.

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.

#### Delete

    void Delete(String catalog)
                throws Database_Exception

Deletes a catalog from the database.

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.

#### Create

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

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.

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:
  `Configuration()`

#### Delete

    void Delete(String table,
              Vector<String> fields)
                throws Database_Exception

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.

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:
  `Configuration()`

#### Rename

    void Rename(String table,
              String name)
                throws Database_Exception

Renames a table.

If the table does not exist, nothing is done.

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.

#### Rename

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

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.

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.

#### Insert

    int Insert(String table,
             Vector<String> fields,
             Vector<Object> values)
               throws Database_Exception

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.

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.

#### Update

    int Update(String table,
             Vector<String> fields,
             Vector<Object> values,
             String conditions)
               throws Database_Exception

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.

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.

#### Delete

    int Delete(String table,
             String conditions)
               throws Database_Exception

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.

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.

#### Table_Reference

    String Table_Reference(String catalog,
                         String table)
                           throws Database_Exception

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.

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.

#### Catalog_Name

    String Catalog_Name(String table_reference)
                        throws Database_Exception

Gets the catalog name portion of a table reference.

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:
  `Table_Reference(String, String)`

#### Database_Catalog_Name

    String Database_Catalog_Name(String catalog)
                                 throws Database_Exception

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.

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.

#### Table_Name

    String Table_Name(String table_reference)
                      throws Database_Exception

Gets the table name portion of a table reference.

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:
  `Table_Reference(String, String)`

#### Database_Table_Name

    String Database_Table_Name(String table)
                               throws Database_Exception

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.

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.

#### Table_Reference_Component_Delimiter

    String Table_Reference_Component_Delimiter()
                                               throws Database_Exception

Gets the table reference component delimiter.

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:
  `Table_Reference(String, String)`

#### Case_Sensitive_Identifiers

    boolean Case_Sensitive_Identifiers()
                                       throws Database_Exception

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.

Returns:
  true if identifiers will be matched with case sensitive comparisons; false if matching will ignore case.
Throws:
  `Database_Exception`
See Also:
  `Database.Matches(String, String)`

#### Case_Sensitive_Identifiers

    void Case_Sensitive_Identifiers(boolean case_sensitive)
                                    throws Database_Exception

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.

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:
  `Case_Sensitive_Identifiers()`