path: root/fpcdocs/sqldb.xml

<?xml version="1.0"?>
<fpdoc-descriptions>
<package name="fcl">
<!--
  ====================================================================
    sqldb
  ====================================================================
-->
<module name="sqldb">
<short>
A set of classes for connecting to SQL databases and running SQL commands on
them.
</short>
<descr>
<p>
The SQLDB unit defines four main classes to handle data in SQL based
databases.
</p>
<ol>
<li><link id ="TSQLConnection"/> represents the connection to the database.
Here, properties pertaining to the connection (machine, database, user
password) must be set. This is an abstract class, which should not be used
directly. Per database type (mysql, firebird, postgres, oracle, sqlite) 
a descendent should be made and used.</li> 
<li><link id ="TSQLQuery"/> is a <link id="#fcl.db.TDataset"/> descendent
which can be used to view and manipulate the result of an SQL select query.
It can also be used to execute all kinds of SQL statements.</li>
<li><link id="TSQLTransaction"/> represents the transaction in which an SQL
command is running. SQLDB supports multiple simultaneous transactions in a
database connection. For databases that do not support this functionality
natively, it is simulated by maintaining multiple connections to the
database.
</li>
<li>
<link id="TSQLScript"/> can be used when many SQL commands must be executed
on a database, for example when creating a database.
</li>
</ol>
<p>
There is also a unified way to retrieve schema information, and a
registration for connector types. More information on how to use these
components can be found in <link id="UsingSQLDB"/>.
</p>
</descr>

<topic name="UsingParams">
<short>Using parameters</short>
<descr>
<p>
SQLDB implements parametrized queries, simulating them if the native SQL
client does not support parametrized queries. A parametrized query means that the
SQL statement contains placeholders for actual values. The following is a
typical example:
</p>
<code>
SELECT * FROM MyTable WHERE (id=:id)
</code>
<p>
The <var>:id</var> is a parameter with the name <var>id</var>. 
It does not contain a value yet. The
value of the parameter will be specified separately. In SQLDB this happens
through the <var>TParams</var> collection, where each element of
the collection is a named parameter, specified in the SQL statement. The
value can be specified as follows:
</p>
<code>
Params.ParamByname('id').AsInteger:=123;
</code>
<p>
This will tell SQLDB that the parameter <var>id</var> is of type integer, and has value 123.
</p>
<p>
SQLDB uses parameters for 3 purposes:
</p>
<ol>
<li>When executing a query multiple times, simply with different values,
this helps increase the speed if the server supports parametrized queries:
the query must be prepared only once.</li>
<li>Master-Detail relationships between datasets can be established based on a parametrized
detail query: the value of the parameters in the detail query is
automatically obtained from fields with the same names in the master
dataset. As the user scrolls through the master dataset, the detail dataset
is refreshed with the new values of the params.
</li>
<li>
Updating of data in the database happens through parametrized update/delete/insert
statements: the <link id="TSQLQuery.UpdateSQL"/> , <link
id="TSQLQuery.DeleteSQL"/>, <link id="TSQLQuery.InsertSQL"/> properties of
<link id="TSQLQuery"/> must contain parametrized queries.
</li>
</ol>
<p>
An additional advantage of using parameters is that they help to avoid SQL
injection: by specifying a parameter type and value, SQLDB will
automatically check whether the value is of the correct type, and will apply
proper quoting when the native engine does not support parameters directly.
</p>
</descr>
<seealso>
<link id="TSQLQuery.Params"/>
<link id="UpdateSQLs"/>
</seealso>
</topic>

<topic name="UpdateSQLs">
<short>Automatic generation of update SQL statements</short>
<descr>
<p>
SQLDB (more in particular, <link id="TSQLQuery"/>) can automatically generate
update statements for the data it fetches. To this end, it will scan the SQL
statement and determine the main table in the query: this is the first table
encountered in the <var>FROM</var> part of the <var>SELECT</var> statement.
</p>
<p>
For <var>INSERT</var> and <var>UPDATE</var> operations, the SQL statement
will update/insert all fields that have <var>pfInUpdate</var> in their
<var>ProviderFlags</var> property. Read-only fields will not be added to the
SQL statement. Fields that are NULL will not be added to an insert query,
which means that the database server will insert whatever is in the
<var>DEFAULT</var> clause of the corresponding field definition.
</p>
<p>
The <var>WHERE</var> clause for update and delete statements consists 
of all fields with <var>pfInKey</var> in their <var>ProviderFlags</var> property.
Depending on the value of the <link id="TSQLQuery.UpdateMode">UpdateMode</link>
property, additional fields may be added to the <var>WHERE</var> clause:
</p>
<dl>
<dt>upWhereKeyOnly</dt>
<dd>No additional fields are added: only fields marked with <var>pfInKey</var>
are used in the WHERE clause</dd>
<dt>upWhereChanged</dt>
<dd>All fields whose value changed are added to the WHERE clause, using
their old value.</dd>
<dt>upWhereAll</dt>
<dd>All fields are added to the WHERE clause, using their old value.</dd>
</dl>
<p>
In order to let SQLDB generate correct statements, it is important to set
the <link id="#fcl.db.TField.ProviderFlags">ProviderFlags</link> properties
correct for all fields. 
</p>
<p>
In many cases, for example when only a single table is queried, and no <var>AS</var> field aliases
are used , setting <link id="TSQLQuery.UsePrimaryKeyAsKey"/> combined
with <var>UpdateMode</var> equal to <var>upWhereKeyOnly</var> is sufficient.
</p>
<p>
If the automatically generated queries are not correct, it is possible to
specify the SQL statements to be used in the 
<link id="TSQLQuery.UpdateSQL">UpdateSQL</link>,
<link id="TSQLQuery.InsertSQL">InsertSQL</link> and 
<link id="TSQLQuery.DeleteSQL">DeleteSQL</link> properties.
The new field values should be specified using params with the same name as the
field. The old field values should be specified using the <var>OLD_</var>
prefix to the field name. The following example demonstrates this:
</p>
<code>
INSERT INTO MYTABLE 
  (MYFIELD,MYFIELD2)
VALUES
  (:MYFIELD,:MYFIELD2);

UPDATE MYTABLE SET
  MYFIELD=:MYFIELD
  MYFIELD2=:MYFIELD2
WHERE
  (MYFIELD=:OLD_MYFIELD);
  
DELETE FROM MYTABLE WHERE (MyField=:OLD_MYFIELD);
</code>
</descr>
<seealso>
<link id="UsingParams"/>
<link id="TSQLQuery"/>
<link id="TSQLQuery.UpdateSQL">UpdateSQL</link>
<link id="TSQLQuery.InsertSQL">InsertSQL</link>
<link id="TSQLQuery.UpdateSQL">DeleteSQL</link>
</seealso>
</topic>

<topic name="RetrievingSchemaInformation">
<short>Retrieving Schema Information</short>
<descr>
<p>
Schema Information (lists of available database objects) can be retrieved using some
specialized calls in <link id="TSQLConnection"/>:
</p>
<ul>
<li>
<link id="TSQLConnection.GetTableNames"/> retrieves a list of available tables.
The system tables can be requested.
</li>
<li>
<link id="TSQLConnection.GetProcedureNames"/> retrieves a list of available
stored procedures.
</li>
<li>
<link id="TSQLConnection.GetFieldNames"/> retrieves a list of fields for a
given table.
</li>
</ul>
<p>
These calls are pretty straightforward and need little explanation.
A more versatile system is the schema info query: the <link
id="TCustomSQLQuery.SetSchemaInfo"/> method can be used to create a result
set (dataset) with schema information. The parameter <var>SchemaType</var>
determines the resulting information when the dataset is opened.
The following information can be requested: 
</p>
<dl>
<dt>stTables</dt>
<dd>
Retrieves the list of user Tables in database. 
This is used internally by <link id="TSQLConnection.GetTableNames"/>.
</dd>
<dt>stSysTables</dt>
<dd>
Retrieves the list of system Tables in database. This is
used internally by <link id="TSQLConnection.GetTableNames"/> when the system
tables are requested
</dd>
<dt>stProcedures</dt>
<dd>
Retrieves a list of stored procedures in database. This is used internally
by <link id="TSQLConnection.GetProcedureNames"/>.
</dd>
<dt>stColumns</dt>
<dd>
Retrieves the list of columns (fields) in a table. 
This is used internally by <link id="TSQLConnection.GetFieldNames"/>. 
</dd>
<dt>stProcedureParams</dt>
<dd>
This retrieves the parameters for a stored procedure.
</dd>
<dt>stIndexes</dt>
<dd>
Retrieves the indexes for one or more tables. (currently not implemented)
</dd>
<dt>
stPackages
</dt>
<dd>
Retrieves packages for databases that support them. (currently not implemented).
</dd>
</dl>
</descr>
</topic>

<topic name="UniversalConnectors">
<short>Using the universal TSQLConnector type</short>
<descr>
<p>
The normal procedure when using SQLDB is to use one of the <link id="TSQLConnection"/>
descendent components. When the database backend changes, another descendent
of <var>TSQLConnection</var> must be used. When using a lot of different
connection types and components, this may be confusing and a lot of work.
</p>
<p>
There is a universal connector component <link id="TSQLConnector"/> which can 
connect to any database supported by SQLDB: it works as a proxy. Behind the
scenes it uses a normal <var>TSQLConnection</var> descendent to do the real
work. All this happens transparantly to the user code, the universal
connector acts and works like any normal connection component.
</p>
<p>
The type of database can be set in its <link id="TSQLConnector.ConnectorType">ConnectorType</link> property. 
By setting the <var>ConnectorType</var> property, the connector knows which
<var>TSQLConnection</var> descendent must be created.
</p>
<p>
Each <var>TSQLConnection</var> descendent registers itself with a unique
name in the initialization section of the unit implementing it: this is the
name that should be specified in the <var>ConnectorType</var> of the
universal connection. 
The list of available connections can be retrieved with the <link id="GetConnectionList"/>
call.
</p>
<p>
From this mechanism it follows that before a particular connection type can be used, 
its definition must be present in the list of connector types. This means
that the unit of the connection type (<var>ibconnection</var>,
<var>pqconnection</var> etc.) must be included in the <var>uses</var> clause
of the program file: if it is not included, the connection type will not be
registered, and it will not be available for use in the universal
connector.
</p>
<p>
The universal connector only exposes the properties common to all connection
types (the ones in <var>TSQLConnection</var>). It does not expose properties 
for all the properties available in specific <var>TSQLConnection</var> descendents. 
This means that if connection-specific options must be used, they must be included in
the <link id="TSQLConnection.Params">Params</link> property of the universal 
connector in the form <var>Name=Value</var>. When the actual connection instance 
is created, the connection-specific properties will be set from the
specified parameters.
</p>
</descr>
<seealso>
<link id="TSQLConnection"/>
<link id="TSQLConnector"/>
</seealso>
</topic>

<topic name="UsingSQLDB">
<short>Using SQLDB to access databases</short>
<descr>
<p>
SQLDB can be used to connect to any SQL capable database. It allows to
execute SQL statements on any supported database type in a uniform way, 
and allows to fetch and manipulate result sets (such as returned by a SELECT
statement) using a standard <link id="#fcl.db.TDataset">TDataset</link>
interface. SQLDB takes care that updates to the database are posted
automatically to the database, in a cached manner.
</p>
<p>
When using SQLDB, 3 components are always needed:
</p>
<ol>
<li>
A <link id="TSQLConnection"/> descendent. This represents the
connection to the database: the location of the database, and the username
and password to authenticate the connection must be specified here.
For each supported database type (Firebird, PostgreSQL, MySQL) there 
is a separate connection component. They all descend from <var>TSQLConnection</var>.
</li>
<li>
A <link id="TSQLTransaction"/> component. SQLDB allows you to have
multiple active but independent transactions in your application.
(useful for instance in middle-tier applications). If the native database
client library does not support this directly, it is emulated using multiple
connections to the database.
</li>
<li>
A <link id="TSQLQuery"/> component. This encapsulates an SQL statement.
Any kind of SQL statement can be executed. The <var>TSQLQuery</var>
component is a <var>TDataset</var> descendent: If the statement returns a result
set, then it can be manipulated using the usual <var>TDataset</var>
mechanisms.
</li>
</ol>
<p>
The 3 components must be linked together: the connection must point to a
default transaction (it is used to execute certain queries for metadata), 
the transaction component must point to a connection component. The
TSQLQuery component must point to both a transaction and a database.
</p>
<p>
So in order to view the contents of a table, typically the procedure goes like this:
</p>
<code>
{$mode objfpc}{$h+}
uses sqldb, ibconnection;

Var
  C : TSQLConnection;
  T : TSQLTransaction;
  Q : TSQLQuery;
  
begin
  // Create a connection.
  C:=TIBConnection.Create(Nil);
  try
    // Set credentials.
    C.UserName:='MyUSER';
    C.Password:='Secret';
    C.DatabaseName:='/home/firebird/events.fb';
    // Create a transaction.
    T:=TSQLTransaction.Create(C);
    // Point to the database instance
    T.Database:=C;
    // Now we can open the database.
    C.Connected:=True;
    // Create a query to return data
    Q:=TSQLQuery.Create(C);
    // Point to database and transaction.
    Q.Database:=C;
    Q.Transaction:=T;
    // Set the SQL select statement
    Q.SQL.Text:='SELECT * FROM USERS';
    // And now use the standard TDataset methods.
    Q.Open;
    While not Q.EOF do
      begin
      Writeln(Q.FieldByName('U_NAME').AsString);
      Q.Next
      end;
    Q.Close;  
  finally
    C.Free;
  end;
end.  
</code>
<p>
The above code is quite simple. The connection type is
<var>TIBConnection</var>, which is used for Firebird/Interbase databases.
To connect to another database (for instance PostgreSQL), the exact same 
code could be used, but instead of a <var>TIBConnection</var>, a
<var>TPQConnection</var> component must be used:
</p>
<code>
{$mode objfpc}{$h+}
uses sqldb, pqconnection;

Var
  C : TSQLConnection;
  T : TSQLTransaction;
  Q : TSQLQuery;
       
begin
  // Create a connection.
  C:=TPQConnection.Create(Nil);
</code>
<p>
The rest of the code remains identical.
</p>
<p>
The above code used an SQL SELECT statement and the <var>Open</var> method to fetch data from the database.
Almost the same method applies when trying to execute other kinds of queries, such as DDL queries:
</p>
<code>
{$mode objfpc}{$h+}
uses sqldb, ibconnection;

Var
  C : TSQLConnection;
  T : TSQLTransaction;
  Q : TSQLQuery;
  
begin
  C:=TIBConnection.Create(Nil);
  try
    C.UserName:='MyUSER';
    C.Password:='Secret';
    C.DatabaseName:='/home/firebird/events.fb';
    T:=TSQLTransaction.Create(C);
    T.Database:=C;
    C.Connected:=True;
    Q:=TSQLQuery.Create(C);
    Q.Database:=C;
    Q.Transaction:=T;
    // Set the SQL statement. SQL is a tstrings instance.
    With Q.SQL do
      begin
      Add('CREATE TABLE USERS ( ');
      Add(' U_NAME VARCHAR(50), ');
      Add(' U_PASSWORD VARCHAR(50) ');
      Add(' ) ');
      end;
    // And now execute the query using ExecSQL 
    // There is no result, so Open cannot be used.
    Q.ExecSQL;
    // Commit the transaction.
    T.Commit;   
  finally
    C.Free;
  end;
end.  
</code>
<p>
As can be seen from the above example, the setup is the same as in the case
of fetching data. Note that <link id="TSQLQuery"/> can only execute 1 SQL statement
during ExecSQL.
If many SQL statements must be executed, <link id="TSQLScript"/> must be used.
</p>
<p>
There is much more to <var>TSQLQuery</var> than explained here: it can use
parameters (see <link id="UsingParams"/>) and it can automatically update
the data that you edit in it (see <link id="UpdateSQLs"/>).
</p>
</descr>
<seealso>
<link id="TSQLConnection"/>
<link id="TSQLTransaction"/>
<link id="TSQLQuery"/>
<link id="TSQLConnector"/> 
<link id="TSQLScript"/>
<link id="UsingParams"/>
<link id="UpdateSQLs"/>
</seealso>
</topic>


<!-- enumeration type Visibility: default -->
<element name="TSchemaType">
<short>Schema type to retrieve</short>
<descr>
<var>TSchemaType</var> describes which schema information to retrieve in the
<link id="TCustomSQLQuery.SetSchemaInfo"/> call. Depending on its value,
the result set of the dataset will have different fields, describing the
requested schema data. The result data will always have the same structure.  
</descr>
<seealso>
<link id="RetrievingSchemaInformation"/>
<link id="TCustomSQLQuery.SetSchemaInfo"/>
</seealso>
</element>

<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stNoSchema">
<short>No schema</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stTables">
<short>User Tables in database</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stSysTables">
<short>System tables in database</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stProcedures">
<short>Stored procedures in database</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stColumns">
<short>Columns in a table</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stProcedureParams">
<short>Parameters for a stored procedure</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stIndexes">
<short>Indexes for a table</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stPackages">
<short>Packages (for databases that support them)</short>
</element>

<!-- enumeration type Visibility: default -->
<element name="TConnOption">
<short>Connection options</short>
<descr>
This type describes some of the option that a particular connection type
supports.
</descr>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnOption.sqSupportParams">
<short>The connection type has native support for parameters.</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TConnOption.sqEscapeSlash">
<short>Escapes in string literals are done with backslash characters.</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TConnOption.sqEscapeRepeat">
<short>Escapes in string literals are done by repeating the character.</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TConnOption.sqQuoteFieldnames">
<short>Field names should be quoted in the SQL statements</short>
</element>
<!-- set type Visibility: default -->
<element name="TConnOptions">
<short>Set of <var>TConnOption</var></short>
<descr>
<var>TConnOptions</var> describes the full set of options defined by a
database.
</descr>
<seealso>
<link id="TConnOption"/>
</seealso>
</element>
<element name="TConnInfoType">
<short>Connection information to be retrieved</short>
</element>
<element name="citAll">
<short>All information, separated by commas.</short>
</element>
<element name="citServerType">
<short>Server type</short>
</element>
<element name="citServerVersion">
<short>Server version as a numeric value</short>
</element>
<element name="citServerVersionString">
<short>Server version as a string.</short>
</element>
<element name="citClientName">
<short>Client library name</short>
</element>
<element name="citClientVersion">
<short>Client library version</short>
</element>
<!-- alias type Visibility: default -->
<element name="TRowsCount">
<short>A type to contain a result row count.</short>
</element>
<!-- object Visibility: default -->
<element name="TSQLConnection">
<short>An abstract class representing a connection to a SQL Database</short>
<descr>
<p>
<var>TSQLConnection </var> is an abstract class for making a connection to a SQL
Database. This class will never be instantiated directly, for each database
type a descendent class specific for this database type must be created. 
</p>
<p>
Most of common properties to SQL databases are implemented in this class.
</p>
</descr>
<seealso>
<link id="TSQLQuery"/>
<link id="TSQLTransaction"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TSQLTransaction">
<short>Transaction in which a <var>TSQLQuery</var> is handled</short>
<descr>
<var>TSQLTransaction</var> represents the transaction in which one or more
<link id="TSQLQuery"/> instances are doing their work. It contains the
methods for committing or doing a rollback of the results of query.
At least one <var>TSQLTransaction</var> must be used for each <link
id="TSQLConnection"/> used in an application.
</descr>
<seealso>
<link id="TSQLQuery"/>
<link id="TSQLConnection"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TCustomSQLQuery">
<short>Custom Class to handle SQL commands (with or without result set)</short>
<descr>
<p>
<var>TCustomSQLQuery</var> encapsulates a SQL statement: it implements 
all the necessary <link id="#fcl.db.TDataset"/> functionality to be
able to handle a result set. It can also be used to execute SQL statements
that do not return data, using the <link
id="TCustomSQLQuery.ExecSQL">ExecSQL</link> method.
</p>
<p>
Do not instantiate a <var>TCustomSQLQuery</var> class directly, 
instead use the <link id="TSQLQuery"/> descendent.
</p>
</descr>
<seealso>
<link id="TSQLQuery"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TSQLQuery">
<short>Class to handle SQL commands (with or without result set)</short>
<descr>
<p>
<var>TSQLQuery</var> exposes the properties and some methods introduced in
<link id="TCustomSQLQuery"/>. It encapsulates a single SQL statement: it implements 
all the necessary <link id="#fcl.db.TDataset"/> functionality to be
able to handle a result set. It can also be used to execute a single SQL
statement that does not return data, using the <link id="TCustomSQLQuery.ExecSQL"/> method.
</p>
<p>
Typically, the <link id="TSQLQuery.Database"/> property must be set once, the <link
id="TSQLQuery.Transaction"/> property as well. Then the <link id="TSQLQuery.SQL"/> property can
be set. Depending on the kind of SQL statement, the <link
id="#fcl.db.TDataset.Open">Open</link> method can be used to retrieve 
data, or the <var>ExecSQL</var> method can be used to execute the SQL
statement (this can be used for DDL statements, or update statements).
</p>
</descr>
<seealso>
<link id="TSQLTransaction"/>
<link id="TSQLConnection"/>
<link id="TCustomSQLQuery.ExecSQL"/>
<link id="TSQLQuery.SQL"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TSQLScript">
<short>Component to execute various SQL statements</short>
<descr>
<var>TSQLScript</var> is a component that can be used to execute many SQL
statements using a <link id="TSQLQuery"/> component. 
The SQL statements are specified in a script <link id="TSQLScript.Script"/> separated
by a terminator character (typically a semicolon (;)). 
</descr>
<seealso>
<link id="TSQLTransaction"/>
<link id="TSQLConnection"/>   
<link id="TCustomSQLQuery.ExecSQL"/>
<link id="TSQLQuery.SQL"/>
</seealso>
</element>

<!-- enumeration type Visibility: default -->
<element name="TStatementType">
<short>Type describing the kind of SQL statement</short>
<descr>
<var>TStatementType</var> describes the kind of SQL statement that was
enteredin the <var>SQL</var> property of a <link id="TSQLQuery"/> component.
</descr>
<seealso/>
</element>

<!-- enumeration value Visibility: default -->
<element name="TStatementType.stNone">
<short>The statement type could not be detected.</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stSelect">
<short>The statement is a SQL SELECT statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stInsert">
<short>The statement is a SQL INSERT statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stUpdate">
<short>The statement is a SQL UPDATE statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stDelete">
<short>The statement is a SQL DELETE statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stDDL">
<short>The statement is a SQL DDL (Data Definition Language) statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stGetSegment">
<short>The statement is a SQL get segment statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stPutSegment">
<short>The statement is a SQL put segment statement</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stExecProcedure">
<short>The statement executes a stored procedure</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stStartTrans">
<short>The statement starts a transaction</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stCommit">
<short>The statement commits a transaction</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stRollback">
<short>The statement rolls back a transaction</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TStatementType.stSelectForUpd">
<short>The statement selects data for update</short>
</element>
<!-- object Visibility: default -->
<element name="TSQLHandle">
<short>Internal object representing a database internal handle</short>
<descr>
<p>
<var>TSQLHandle</var> is an abstract internal object representing a database
client handle. It is used by the various connections to implement the
connection-specific functionality, and usually represents a low-level handle. 
It is used by the <link id="TSQLQuery"/> component to communicate with the
<link id="TSQLConnection"/> descendent.
</p>
<p>
This object must not be used directly.
</p>
</descr>
<seealso>
<link id="TSQLQuery"/>
<link id="TSQLCursor"/>
</seealso>
</element>
<!-- object Visibility: default -->
<element name="TSQLCursor">
<short>Internal object representing a database result set</short>
<descr>
<p>
<var>TSQLCursor</var> is an abstract internal object representing a result
set returned by a single SQL select statement (<link id="TSQLHandle"/>).
statement. It is used by the <link id="TSQLQuery"/> component to handle
result sets returned by SQL statements.
</p>
<p>
This object must not be used directly.
</p>
</descr>
<seealso>
<link id="TSQLQuery"/>
<link id="TSQLHandle"/>
</seealso>
</element>

<!-- variable Visibility: public -->
<element name="TSQLCursor.FPrepared">
<short>Was the statement prepared</short>
</element>
<!-- variable Visibility: public -->
<element name="TSQLCursor.FInitFieldDef">
<short>Have the field definitions been initialized.</short>
</element>
<!-- variable Visibility: public -->
<element name="TSQLCursor.FStatementType">
<short>Statement type in the SQL property.</short>
</element>
<!-- constant Visibility: default -->
<element name="StatementTokens">
<short>Array of tokens used to determine the statement type.</short>
<descr>
<var>StatementTokens</var> contains an array of string tokens that are used
to detect the type of statement, usually the first SQL keyword of the token.
The presence of this token in the SQL statement determines the kind of
token.
</descr>
<seealso>
<link id="TStatementType"/> 
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TServerIndexDefs">
<short>SQLDB specific descendant of the <link id="#fcl.db.TIndexDefs">TIndexDefs</link></short>
class.
<descr>
<var>TServerIndexDefs</var> is a simple descendent of  <link
id="#fcl.db.TIndexDefs">TIndexDefs</link> that implements the necessary
methods to update the list of definitions using the <link
id="TSQLConnection"/>. It should not be used directly.
</descr>
<seealso>
<link id="TSQLConnection"/>"
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TServerIndexDefs.Create">
<short>Create a new instance of <var>TServerIndexDefs</var></short>
<descr>
<var>Create</var> will rais an exception if <var>ADataset</var> is not a
<link id="TCustomSQLQuery"/> descendent.
</descr>
<errors>
An <var>EDatabaseError</var> exception will be raised if <var>ADataset</var>
is not a <link id="TCustomSQLQuery"/> descendent.
</errors>
</element>

<!-- argument Visibility: default -->
<element name="TServerIndexDefs.Create.ADataSet">
<short>Dataset for which the index definition collection is created.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TServerIndexDefs.Update">
<short>Updates the list of indexes</short>
<descr>
<var>Update</var> updates the list of indexes, it uses the <link
id="TSQLConnection"/> methods for this.
</descr>
</element>

<!-- property Visibility: public -->
<element name="TSQLConnection.Handle">
<short>Low level handle used by the connection.</short>
<descr>
<var>Handle</var> represents the low-level handle that the TSQLCOnnection
component has received from the client library of the database. Under normal
circumstances, this property must not be used.
</descr>
</element>

<!-- destructor Visibility: public -->
<element name="TSQLConnection.Destroy">
<short>Destroys the instance of the connection.</short>
<descr>
<var>Destroy</var> removes the connection from memory.
When a connection is removed, all datasets are closed, and all transactions too. 
</descr>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.StartTransaction">
<short>Start the Transaction associated with this Connection</short>
<descr>
<p>
<var>StartTransaction</var> is a convenience method which starts the default
transaction (<link id="TSQLConnection.Transaction">Transaction</link>). It is equivalent to 
</p>
<code>
Connection.Transaction.StartTransaction
</code>
</descr>
<errors>
If no transaction is assigned, an exception will be raised.
</errors>
<seealso>
<link id="TSQLConnection.EndTransaction">EndTransaction</link>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.EndTransaction">
<short>End the Transaction associated with this connection</short>
<descr>
<p>
<var>StartTransaction</var> is a convenience method which ends the default
transaction (<link id="TSQLConnection.Transaction"/>). It is equivalent to 
</p>
<code>
Connection.Transaction.EndTransaction
</code>
</descr>
<errors>
If no transaction is assigned, an exception will be raised.
</errors>
<seealso>
<link id="TSQLConnection.StartTransaction">StartTransaction</link>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TSQLConnection.ConnOptions">
<short>The set of Connection options being used in the Connection</short>
<descr>
<var>ConnOptions</var> is the set of options used by this connection component.
It is normally the same value for all connections of the same type
</descr>
<seealso>
<link id="TConnOption"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.ExecuteDirect">

<short>Execute a piece of SQL code directly, using a Transaction if specified</short>

<descr>
<p>
<var>ExecuteDirect</var> executes an SQL statement directly. If
<var>ATransaction</var> is <var>Nil</var> then the default transaction is
used, otherwise the specified transaction is used.
</p>
<p>
<var>ExecuteDirect</var> does not offer support for parameters, so only
statements that do not need parsing and parameters substitution can be handled.
If parameter substitution is required, use a <link id="TSQLQuery"/>
component and its <link id="TCustomSQLQuery.ExecSQL">ExecSQL</link> method. 
</p>
</descr>
<errors>
If no transaction is assigned, and no transaction is passed, an exception
will be raised.
</errors>
<seealso>
<link id="TSQLQuery"/>
<link id="TCustomSQLQuery.ExecSQL">ExecSQL</link>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.ExecuteDirect.SQL">
<short>SQL statement to be executed</short>
</element>
<!-- argument Visibility: default -->
<element name="TSQLConnection.ExecuteDirect.ATransaction">
<short>Transaction to be used. The default transaction will be used if none is passed</short>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.GetTableNames">
<short>Get a list of the tables in the specified database</short>
<descr>
<p>
<var>GetTableNames</var> will return the names of the tables in the
database in <var>List</var>. If <var>SystemTables</var> is <var>True</var>
then only the names of system tables will be returned.
</p>
<p>
<var>List</var> is cleared before adding the names.
</p>
<remark>
Note that the list may depend on the access rights of the user.
</remark>
</descr>
<seealso>
<link id="TSQLConnection.GetProcedureNames"/>
<link id="TSQLConnection.GetFieldNames"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.GetTableNames.List">
<short>String list in which table names will be returned.</short>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.GetTableNames.SystemTables">
<short>If <var>True</var> then system table names will also be  returned</short>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.GetProcedureNames">
<short>Gets a list of Stored Procedures in the Database</short>
<descr>
<p>
<var>GetProcedureNames</var> will return the names of the stored procedures in the
database in <var>List</var>. 
</p>
<p>
<var>List</var> is cleared before adding the names.
</p>
</descr>
<seealso>
<link id="TSQLConnection.GetTableNames"/>
<link id="TSQLConnection.GetFieldNames"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.GetProcedureNames.List">
<short>String list in which table names will be returned.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.GetFieldNames">
<short>Gets a list of the field names in the specified table</short>
<descr>
<p>
<var>GetFieldNames</var> will return the names of the fields in
<var>TableName</var> in <var>list</var>
</p>
<p>
<var>List</var> is cleared before adding the names.
</p>
</descr>
<errors>
If a non-existing tablename is passed, no error will be raised.
</errors>
<seealso>
<link id="TSQLConnection.GetTableNames"/>
<link id="TSQLConnection.GetProcedureNames"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.GetFieldNames.TableName">
<short>Name of the table for to retrieve the field names.</short>
</element>

<!-- argument Visibility: default -->
<element name="TSQLConnection.GetFieldNames.List">
<short>Stringlist in which to return the field names.</short>
</element>

<!-- procedure Visibility: public -->

<element name="TSQLConnection.CreateDB">
<short>Create a new Database on the server</short>
<descr>
<var>CreateDB</var> will create a new database on the server. Whether or not
this functionality is present depends on the type of the connection. The name
for the new database is taken from the <link id="TSQLConnection.DatabaseName"/> property,
the user credentials are taken from the <link id="TSQLConnection.UserName"/>
and <link id="TSQLConnection.Password"/> properties.
</descr>

<errors>
If the connection type does not support creating a database, then an
<var>EDatabaseError</var> exception is raised. Other exceptions may be
raised if the operation fails, e.g. when the user does not have the
necessary access rights.
</errors>

<seealso>
<link id="TSQLConnection.DropDB"/>
</seealso>

</element>


<!-- procedure Visibility: public -->
<element name="TSQLConnection.DropDB">
<short>Procedure to drop or remove a Database</short>
<descr>
<var>DropDB</var> does the opposite of <link id="TSQLConnection.CreateDB">CreateDB</link>. 
It removes the database from the server. 
The database must be connected before this command may be used. Whether or not
this functionality is present depends on the type of the connection.
</descr>
<errors>
If the connection type does not support creating a database, then an
<var>EDatabaseError</var> exception is raised. Other exceptions may be
raised if the operation fails, e.g. when the user does not have the   
necessary access rights.
</errors>
<seealso>
<link id="TSQLConnection.CreateDB"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.Password">
<short>Password used when authenticating on the database server</short>
<descr>
<p>
<var>Password</var> is used when authenticating the user specified in 
<link id="TSQLConnection.username">UserName</link> when connecting to the database server
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
</descr>
<seealso>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.HostName"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.Transaction">
<short>Default transaction to be used for this connection</short>
<descr>
<var>Transaction</var> should be set to a <link id="TSQLTransaction"/>
instance. It is set as the default transaction when a query is connected 
to the database, and is used in several metadata operations such as <link
id="TSQLConnection.GetTableNames"/>
</descr>
<seealso>
<link id="TSQLTransaction"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.UserName">
<short>The username for authentication on the database server</short>
<descr>
<p>
<var>UserName</var> is used to to authenticate on the database server when
the connection to the database is established.
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.HostName"/>
<link id="TSQLConnection.Role"/>
<link id="TSQLConnection.Charset"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.CharSet">
<short>The character set to be used in this database</short>
<descr>
<p>
<var>Charset</var> can be used to tell the user in which character set the
data will be sent to the server, and in which character set the results
should be sent to the client. Some connection types will ignore this
property, and the data will be sent to the client in the encoding used on
the server. 
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
<remark>
SQLDB will not do anything with this setting except pass it on to the server
if a specific connection type supports it. It does not perform any
conversions by itself based on the value of this setting.
</remark>
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.HostName"/>        
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.Role"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.HostName">
<short>The name of the host computer where the database resides</short>
<descr>
<p>
<var>HostName</var> is the the name of the host computer where the 
database server is listening for connection. An empty value means the local
machine is used.
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
</descr>
<seealso>
<link id="TSQLConnection.Role"/>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.DatabaseName"/>
<link id="TSQLConnection.Charset"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.Connected">
<short>Is a connection to the server active or not</short>
<descr>
<p>
<var>Connected</var> indicates whether a connection to the server is active
or not. No queries to this server can be activated as long as the value is
<var>False</var>
</p>
<p>Setting the property to <var>True</var> will attempt a connection to the
database <link id="TSQLConnection.DatabaseName">DatabaseName</link> on host
<link id="TSQLConnection.HostName">HostName</link> using the credentials
specified in  <link id="TSQLConnection.UserName">UserName</link> and 
<link id="TSQLConnection.Password">Password</link>. If the connection or
authentication fails, an exception is raised. This has the same effect as
calling <link id="#fcl.db.TCustomConnection.Open">Open</link>.
</p>
<p>
Setting the property to <var>False</var> will close the connection to the
database. All datasets connected to the database will be closed, all
transactions will be closed as well. This has the same effect as   
calling <link id="Close"/>
</p>
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.DatabaseName"/>
<link id="TSQLConnection.Role"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.Role">
<short>Role in which the user is connecting to the database</short>
<descr>
<p>
<var>Role</var> is used to specify the user's role when connecting to the
database user. Not all connection types support roles, for those that do
not, this property is ignored.
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.DatabaseName"/>
<link id="TSQLConnection.Hostname"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.DatabaseName">
<short>The name of the database to which connection is required.</short>
<descr>
<p>
<var>DatabaseName</var> is the name of the database to which a connection
must be made. Some servers need a complete path to a file, others need a
symbolic name (an alias): the interpretation of this name depends on the
connection type.
</p>
<p>
This property must be set prior to activating the connection. Changing it
while the connection is active has no effect.
</p>
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.Charset"/>
<link id="TSQLConnection.Hostname"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.KeepConnection">
<short>Attempt to keep the connection open once it is established.</short>
<descr>
<var>KeepConnection</var> can be used to attempt to keep the connection open
once it is established. This property is currently not implemented.
</descr>
<seealso/>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.LoginPrompt">
<short>Should SQLDB prompt for user credentials when a connection is activated.</short>
<descr>
<var>LoginPrompt</var> can be set to <var>True</var> to force the system to
get a username/password pair from the user. How these data are fetched from
the used depends on the <link id="TSQLConnection.OnLogin">OnLogin</link> event handler. 
The <link id="TSQLConnection.UserName">UserName</link> and 
<link id="TSQLConnection.Password">Password</link> properties are ignored in
this case.
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.OnLogin">OnLogin</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.Params">
<short>Extra connection parameters</short> 
<descr>
<var>Params</var> can be used to specify extra parameters to use when
establishing a connection to the database. Which parameters can be specified
depends on the connection type.
</descr>
<seealso>
<link id="TSQLConnection.Password"/>
<link id="TSQLConnection.UserName"/>
<link id="TSQLConnection.Hostname"/>
<link id="TSQLConnection.DatabaseName"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.OnLogin">
<short>Event handler for login process</short>
<descr>
<var>OnLogin</var> will be used when <link id="TSQLConnection.LoginPrompt">loginPrompt</link> is
<var>True</var>. It will be called, and can be used to present a user with a
dialog in which the username and password can be asked.
</descr>
<seealso>
<link id="TSQLConnection.LoginPrompt"/>
</seealso>
</element>

<!-- enumeration type Visibility: default -->
<element name="TCommitRollbackAction">
<short>Transaction actions (unused)</short>
<descr>
<var>TCommitRollbackAction</var> is currently unused in SQLDB.
</descr>  
<seealso>
<link id="TSQLTransaction.Action"/>
</seealso>
</element>

<!-- enumeration value Visibility: default -->
<element name="TCommitRollbackAction.caNone">
<short>Do nothing</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TCommitRollbackAction.caCommit">
  <short>Commit transaction</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TCommitRollbackAction.caCommitRetaining">
  <short>Commit transaction, retaining transaction context</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TCommitRollbackAction.caRollback">
<short>Rollback transaction</short>
</element>
<!-- enumeration value Visibility: default -->
<element name="TCommitRollbackAction.caRollbackRetaining">
<short>Rollback transaction, retaining transaction context</short>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.Commit">
<short>Commit the transaction, end transaction context.</short>
<descr>
<p>
<var>Commit</var> commits an active transaction. The changes will be
irreversably written to the database. 
</p>
<p>After this, the transaction is deactivated and must be reactivated with the <link
id="TSQLTransaction.StartTransaction">StartTransaction</link> method.
To commit data while retaining an active transaction, execute <link 
id="TSQLTransaction.CommitRetaining">CommitRetaining</link> instead.
</p>
</descr>
<errors>
Executing <var>Commit</var> when no transaction is active will result in an
exception.  A transaction must be started by calling <link id="TSQLTransaction.StartTransaction">StartTransaction</link>.
If the database backend reports an error, an exception is raised as well.
</errors>
<seealso>
<link id="TSQLTransaction.StartTransaction">StartTransaction</link>
<link id="TSQLTransaction.CommitRetaining">CommitRetaining</link>
<link id="TSQLTransaction.Rollback">Rollback</link>
<link id="TSQLTransaction.RollbackRetaining">RollbackRetaining</link> 
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.CommitRetaining">
<short>Commit the transaction, retain transaction context.</short>
<descr>
<p>
<var>CommitRetaining</var> commits an active transaction. The changes will be
irreversably written to the database. 
</p>
<p>After this, the transaction is still active.
To commit data and deactivate the transaction, execute <link  
id="TSQLTransaction.Commit">Commit</link> instead. 
</p>
</descr>
<errors>
Executing <var>CommitRetaining</var> when no transaction is active will result in an
exception. 
A transaction must be started by calling <link id="TSQLTransaction.StartTransaction">StartTransaction</link>.
If the database backend reports an error, an exception is raised  as well. 
</errors>
<seealso>
<link id="TSQLTransaction.StartTransaction">StartTransaction</link>
<link id="TSQLTransaction.Commit">Retaining</link>  
<link id="TSQLTransaction.Rollback">Rollback</link>
<link id="TSQLTransaction.RollbackRetaining">RollbackRetaining</link> 
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.Rollback">
<short>Roll back all changes made in the current transaction.</short>
<descr>
<p>
<var>Rollback</var> undoes all changes in the databack since the start of
the transaction. It can only be executed in an active transaction. 
</p>
<p>After this, the transaction is no longer active.
To undo changes but keep an active transaction, execute 
<link id="TSQLTransaction.RollbackRetaining">RollbackRetaining</link> instead. 
</p>
<remark>
Changes posted in datasets that are coupled to this transaction will not be undone
in memory: these datasets must be reloaded from the database (using <var>Close</var> and
<var>Open</var> to reload the data as it is in the database.
</remark>
</descr>
<errors>
Executing <var>Rollback</var> when no transaction is active will
result in an exception. 
A transaction must be started by calling <link
id="TSQLTransaction.StartTransaction">StartTransaction</link>.
If the database backend reports an error, an exception is raised  as well. 
</errors>
<seealso>
<link id="TSQLTransaction.StartTransaction">StartTransaction</link>
<link id="TSQLTransaction.CommitRetaining">CommitRetaining</link> 
<link id="TSQLTransaction.Commit">Commit</link> 
<link id="TSQLTransaction.RollbackRetaining">RollbackRetaining</link> 
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.RollbackRetaining">
<short>Roll back changes made in the transaction, keep transaction context.</short>
<descr>
<p>
<var>RollbackRetaining</var> undoes all changes in the databack since the start of
the transaction. It can only be executed in an active transaction. 
</p>
<p>After this, the transaction is kept in an active state.
To undo changes and close the transaction, execute 
<link id="TSQLTransaction.Rollback">Rollback</link> instead. 
</p>
<remark>
Changes posted in datasets that are coupled to this transaction will not be undone
in memory: these datasets must be reloaded from the database (using <var>Close</var> and
<var>Open</var> to reload the data as it is in the database.
</remark>
</descr>
<errors>
Executing <var>RollbackRetaining</var> when no transaction is active will
result in an exception. 
A transaction must be started by calling <link
id="TSQLTransaction.StartTransaction">StartTransaction</link>.
If the database backend reports an error, an exception is raised  as well. 
</errors>
<seealso>
<link id="TSQLTransaction.StartTransaction">StartTransaction</link>
<link id="TSQLTransaction.Commit">Commit</link>  
<link id="TSQLTransaction.Rollback">Rollback</link> 
<link id="TSQLTransaction.CommitRetaining">CommitRetaining</link> 
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.StartTransaction">
<short>Start a new transaction</short>
<descr>
<p>
<var>StartTransaction</var> starts a new transaction context. 
All changes written to the database must be confirmed with a <link
id="TSQLTransaction.Commit">Commit</link> or can be undone with a <link
id="TSQLTransaction.Rollback">Rollback</link> call.
</p>
<p>
Calling <var>StartTransaction</var> is equivalent to setting
<var>Active</var> to <var>True</var>.
</p>
</descr>
<errors>
If <var>StartTransaction</var> is called while the transaction is still
active, an exception will be raised.
</errors>
<seealso>
<link id="TSQLTransaction.StartTransaction">StartTransaction</link>
<link id="TSQLTransaction.Commit">Commit</link>
<link id="TSQLTransaction.Rollback">Rollback</link>
<link id="TSQLTransaction.CommitRetaining">CommitRetaining</link>
<link id="TSQLTransaction.EndTransaction">EndTransaction</link>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TSQLTransaction.Create">
<short>Create a new transaction</short>
<descr>
<var>Create</var> creates a new <var>TSQLTransaction</var> instance, but
does not yet start a transaction context.
</descr>
</element>

<!-- argument Visibility: default -->
<element name="TSQLTransaction.Create.AOwner">
<short>Owner of the transaction component.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TSQLTransaction.Destroy">
<short>Destroy transaction component</short>
<descr>
<var>Destroy</var> will close all datasets connected to it, prior to
removing the object from memory.
</descr>
</element>

<!-- property Visibility: public -->
<element name="TSQLTransaction.Handle">
<short>Low-level transaction handle</short>
<descr>
<var>Handle</var> is the low-level transaction handle object. 
It must not be used in application code. The actual type of this object
depends on the type of <link id="TSQLConnection"/> descendent.
</descr>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLTransaction.EndTransaction">
<short>End the transaction</short>
<descr>
<var>EndTransaction</var> is equivalent to <link id="TSQLTransaction.RollBack">RollBack</link>.
</descr>
<seealso>
<link id="TSQLTransaction.RollBack">RollBack</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLTransaction.Action">
<short>Currently unused in SQLDB</short>
<descr>
<var>Action</var> is currently unused in SQLDB.
</descr>
</element>

<!-- property Visibility: published -->
<element name="TSQLTransaction.Database">
<short>Database for which this component is handling connections</short>
<descr>
<var>Database</var> should be set to the particular <link id="TSQLConnection"/>
instance this transaction is handling transactions in. 
All datasets connected to this transaction component must have the same value 
for their <link id="TSQLQuery.Database">Database</link> property.
</descr>
<seealso>
<link id="TSQLQuery.Database"/>
<link id="TSQLConnection"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLTransaction.Params">
<short>Transaction parameters</short>
<descr>
<var>Params</var> can be used to set connection-specific parameters in the
form of <var>Key=Value</var> pairs. The contents of this property therefor
depends on the type of connection.
</descr>
<seealso>
<link id="TSQLConnection"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLQuery.Prepare">
<short>Prepare a query for execution.</short>
<descr>
<p>
<var>Prepare</var> will prepare the SQL for execution. It will open the
database connection if it was not yet open, and will start a transaction if
none was started yet. It will then determine the statement type. 
Finally, it will pass the statement on to the database engine if it supports
preparing of queries. 
</p>
<p>
Strictly speaking, it is not necessary to call prepare, the component will 
prepare the statement whenever it is necessary. If a query will be executed 
repeatedly, it is good practice to prepare it once before starting to execute it. 
This will speed up execution, since resources must be allocated only once.
</p>   
</descr>
<errors>
If the SQL server cannot prepare the statement, an exception will be raised.
</errors>
<seealso>
<link id="TSQLQuery.StatementType"/>
<link id="TCustomSQLQuery.UnPrepare"/>
<link id="TCustomSQLQuery.ExecSQL"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLQuery.UnPrepare">
<short>Unprepare a prepared query</short>
<descr>
<p>
<var>Unprepare</var> will unprepare a prepared query. This means that server
resources for this statement are deallocated. After a query was unprepared,
any <var>ExecSQL</var> or <var>Open</var> command will prepare the SQL
statement again.  
</p>
<p>
Several actions will unprepare the statement: Setting the <link
id="TSQLQuery.SQL"/> property, setting the <var>Transaction</var> property
or setting the <var>Database</var> property will automaticall call
<var>UnPrepare</var>. Closing the dataset will also unprepare the query.
</p>
</descr>
<errors>
If the SQL server cannot unprepare the statement, an exception may be raised.
</errors>
<seealso>
<link id="TSQLQuery.StatementType"/>
<link id="TCustomSQLQuery.Prepare"/>
<link id="TCustomSQLQuery.ExecSQL"/>  
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLQuery.ExecSQL">
<short>Execute a SQL statement that does not return a result set</short>
<descr>
<p>
<var>ExecSQL</var> will execute the statement in <link id="TSQLQuery.SQL"/>, preparing the statement if necessary.
It cannot be used to get results from the database (such as returned by a <var>SELECT</var> statement): 
for this, the <link id="#fcl.db.TDataset.Open">Open</link> method must be used.
</p>
<p>
The SQL property should be a single SQL command. To execute multiple SQL
statements, use the <link id="TSQLScript"/> component instead.
</p>
<p>
If the statement is a <var>DML</var> statement, the number of
deleted/updated/inserted rows can be determined using <link
id="TCustomSQLQuery.RowsAffected"/>.
</p>
<p>
The <var>Database</var> and <var>Transaction</var> properties must be
assigned before calling <var>ExecSQL</var>. Executing an empty SQL statement
is also an error.
</p>
</descr>
<errors>
If the server reports an error, an exception will be raised.
</errors>
<seealso>
<link id="TCustomSQLQuery.RowsAffected"/>
<link id="#fcl.db.TDataset.Open">TDataset.Open</link>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TCustomSQLQuery.Create">
<short>Create a new instance of <var>TCustomSQLQuery</var>.</short>
<descr>
<var>Create</var> allocates a new instance on the heap and will 
allocate all resources for the SQL statement. After this it calls 
the inherited constructor.
</descr>
<errors>
If not enough memory is available, an exception will be raised.
</errors>
<seealso>
<link id="TCustomSQLQuery.Destroy"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TCustomSQLQuery.Create.AOwner">
<short>Owner for the new <var>TCustomSQLQuery</var> instance.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TCustomSQLQuery.Destroy">
<short>Destroy instance of <var>TCustomSQLQuery</var></short>
<descr>
<var>Destroy</var> cleans up the instance, closing the dataset and freeing
all allocated resources.
</descr>
<seealso>
<link id="TCustomSQLQuery.Create"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLQuery.SetSchemaInfo">
<short>SetSchemaInfo prepares the dataset to retrieve schema info.</short>
<descr>
<p>
<var>SetSchemaInfo</var> will prepare the dataset to retrieve schema
information from the connection, and represents the schema info as a dataset.
</p>
<p>
<var>SetSchemaInfo</var> is used internally to prepare a query to retrieve
schema information from a connection. It will store the 3 passed parameters,
which are then used in the ParseSQL and Prepare stages to optimize the
allocated resources. setting the schema type to anything other than
<var>stNoSchema</var> will also set (or mimic) the SQL statement as soon 
as the query is prepared. For connection types that support this, the 
SQL statement is then set to whatever statement the database connection 
supports to retrieve schema information.
</p>
<p>
This is used internally by <link id="TSQLConnection.GetTableNames"/> and
<link id="TSQLConnection.GetProcedureNames"/> to get the necessary
schema information from the database.
</p>
</descr>
<seealso>
<link id="TSQLConnection.GetTableNames"/>
<link id="TSQLConnection.GetProcedureNames"/>
<link id="RetrievingSchemaInformation"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TCustomSQLQuery.SetSchemaInfo.SchemaType">
<short>Schema to use</short>
</element>

<!-- argument Visibility: default -->
<element name="TCustomSQLQuery.SetSchemaInfo.SchemaObjectName">
<short>Object name for which to search. May be empty to retrieve all objects</short>
</element>

<!-- argument Visibility: default -->
<element name="TCustomSQLQuery.SetSchemaInfo.SchemaPattern">
<short>Currently unused</short>
</element>

<!-- property Visibility: public -->
<element name="TCustomSQLQuery.Prepared">
<short>Is the query prepared ?</short>
<descr>
<var>Prepared</var> is true if <link id="TCustomSQLQuery.Prepare">Prepare</link> was called for this
query, and an <link id="TCustomSQLQuery.UnPrepare">UnPrepare</link> was not
done after that (take care: several actions call <var>UnPrepare</var>
implicitly). Initially, <var>Prepared</var> will be <var>False</var>. 
Calling <var>Prepare</var> if the query was already prepared has no effect.
</descr>
<seealso>
<link id="TCustomSQLQuery.Prepare"/>
<link id="TCustomSQLQuery.UnPrepare"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TCustomSQLQuery.RowsAffected">
<short>Return the number of rows (records) affected by the last DML/DDL statement</short>
<descr>
<var>RowsAffected</var> returns the number of rows affected by the last
statement executed using <link id="TCustomSQLQuery.ExecSQL">ExecSQL</link>.
</descr>
<errors>
If the connection or database type does not support returning this number, -1 is returned.
If the query is not connected to a database, -1 is returned.
</errors>
<seealso>
<link id="TCustomSQLQuery.ExecSQL"/>
<link id="TSQLConnection"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TCustomSQLQuery.RowsAffected.Result">
<short>The number of affected rows or -1 if not supported</short>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.Active" link="#fcl.db.tdataset.active"/>
<element name="TSQLQuery.AutoCalcFields" link="#fcl.db.tdataset.autocalcfields"/>
<element name="TSQLQuery.Filter" link="#fcl.db.tdataset.filter"/>
<element name="TSQLQuery.Filtered"  link="#fcl.db.tdataset.filtered"/>
<element name="TSQLQuery.AfterCancel" link="#fcl.db.tdataset.AfterCancel"/>
<element name="TSQLQuery.AfterClose" link="#fcl.db.tdataset.AfterClose"/>
<element name="TSQLQuery.AfterDelete" link="#fcl.db.tdataset.AfterDelete"/>
<element name="TSQLQuery.AfterEdit" link="#fcl.db.tdataset.AfterEdit"/>
<element name="TSQLQuery.AfterInsert" link="#fcl.db.tdataset.AfterInsert"/>
<element name="TSQLQuery.AfterOpen" link="#fcl.db.tdataset.AfterOpen"/>
<element name="TSQLQuery.AfterPost" link="#fcl.db.tdataset.AfterPost"/>
<element name="TSQLQuery.AfterScroll" link="#fcl.db.tdataset.AfterScroll"/>
<element name="TSQLQuery.BeforeCancel" link="#fcl.db.tdataset.BeforeCancel"/>
<element name="TSQLQuery.BeforeClose" link="#fcl.db.tdataset.BeforeClose"/>
<element name="TSQLQuery.BeforeDelete" link="#fcl.db.tdataset.BeforeDelete"/>
<element name="TSQLQuery.BeforeEdit" link="#fcl.db.tdataset.BeforeEdit"/>
<element name="TSQLQuery.BeforeInsert" link="#fcl.db.tdataset.BeforeInsert"/>
<element name="TSQLQuery.BeforeOpen" link="#fcl.db.tdataset.BeforeOpen"/>
<element name="TSQLQuery.BeforePost" link="#fcl.db.tdataset.BeforePost"/>
<element name="TSQLQuery.BeforeScroll" link="#fcl.db.tdataset.BeforeScroll"/>
<element name="TSQLQuery.OnCalcFields" link="#fcl.db.tdataset.OnCalcFields"/>
<element name="TSQLQuery.OnDeleteError" link="#fcl.db.tdataset.OnDeleteError"/>
<element name="TSQLQuery.OnEditError" link="#fcl.db.tdataset.OnEditError"/>
<element name="TSQLQuery.OnFilterRecord" link="#fcl.db.tdataset.OnFilterRecord"/>
<element name="TSQLQuery.OnNewRecord" link="#fcl.db.tdataset.OnNewRecord"/>
<element name="TSQLQuery.OnPostError" link="#fcl.db.tdataset.OnPostError"/>

<element name="TSQLQuery.Database">
<short>The <var>TSQLConnection</var> instance on which to execute SQL Statements</short>
<descr>
<p>
<var>Database</var> is the SQL connection (of type <link id="TSQLConnection"/>) 
on which SQL statements will be executed, and from which result sets will be retrieved. 
This property must be set before any form of SQL command can be executed, just like the 
<link id="TSQLQuery.Transaction">Transaction</link> property must be set.
</p>
<p>
Multiple <var>TSQLQuery</var> instances can be connected to a database at the same time. 
</p>
</descr>
<seealso>
<link id="TSQLQuery.Transaction"/>
<link id="TSQLConnection"/>
<link id="TSQLTransaction"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.Transaction">
<short>Transaction in which to execute SQL statements</short>
<descr>
<p>
<var>Transaction</var> must be set to a SQL transaction (of type <link id="TSQLTransaction"/>)
component. All SQL statements (<var>SQL</var> / <var>InsertSQL</var> / <var>updateSQL</var> / 
<var>DeleteSQL</var>) etc.) will be executed in the context of this transaction.
</p>
<p>
The transaction must be connected to the same database instance as the query itself.
</p>
<p>
Multiple <var>TSQLQuery</var> instances can be connected to a transaction at the same time.
If the transaction is rolled back, all changes done by all <var>TSQLQuery</var> instances 
will be rolled back.
</p>
</descr>
<seealso>
<link id="TSQLQuery.Database"/>
<link id="TSQLConnection"/>
<link id="TSQLTransaction"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ReadOnly" link="#fcl.db.tdataset.readonly"/>

<!-- property Visibility: published -->
<element name="TSQLQuery.SQL">
<short>The SQL statement to execute</short>
<descr>
<p><var>SQL</var> is the SQL statement that will be executed when <link
id="TCustomSQLQuery.ExecSQL">ExecSQL</link> is called, 
or <link id="#fcl.db.Tdataset.Open">Open</link> is called. It should contain
a valid SQL statement for the connection to which the <link id="TSQLQuery"/>
component is connected. SQLDB will not attempt to modify the SQL statement
so it is accepted by the SQL engine.
</p>
<p>Setting or modifying the SQL statement will call <link
id="TCustomSQLQuery.UnPrepare">UnPrepare</link> 
</p>
<p>
If <link id="TSQLQuery.ParseSQL">ParseSQL</link> is <var>True</var>,
the SQL statement will be parsed and the <link
id="TSQLQuery.Params">Params</link>  property will be updated with the
names of the parameters found in the SQL statement.
</p>
<p>
See also <printshort id="#fcl.sqldb.UsingParams"/>
</p>
</descr>
<seealso>
<link id="TSQLQuery.ParseSQL"/>
<link id="TSQLQuery.Params"/>
<link id="TCustomSQLQuery.ExecSQL"/>
<link id="#fcl.db.Tdataset.Open">TDataset.Open</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.UpdateSQL">
<short>Statement to be used when updating an existing row in the database</short>
<descr>
<p>
<var>UpdateSQL</var> can be used to specify an SQL <var>UPDATE</var>
statement, which is used when an existing record was modified in the dataset, 
and the changes must be written to the database. <var>TSQLQuery</var> can generate
an update statement by itself for many cases, but in case it fails, the
statement to be used for the update can be specified here.
</p>
<p>
The SQL statement should be parametrized according to the conventions 
for specifying parameters. Note that old field values can be specified 
as <var>:OLD_FIELDNAME</var>
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.InsertSQL"/>
<link id="TSQLQuery.DeleteSQL"/>
<link id="TSQLQuery.UpdateMode"/>
<link id="UsingParams"/>
<link id="UpdateSQLS"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.InsertSQL">
<short>Statement to be used when inserting a new row in the database</short>
<descr>
<p>
<var>InsertSQL</var> can be used to specify an SQL <var>INSERT</var>
statement, which is used when a new record was appended to the dataset, 
and the changes must be written to the database. <var>TSQLQuery</var> 
can generate an insert statement by itself for many cases, but in case 
it fails, the statement to be used for the insert can be specified here.
</p>
<p>
The SQL statement should be parametrized according to the conventions 
for specifying parameters. Note that old field values can be specified 
as <var>:OLD_FIELDNAME</var>
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.UpdateSQL"/>
<link id="TSQLQuery.DeleteSQL"/>
<link id="TSQLQuery.UpdateMode"/>
<link id="UsingParams"/>
<link id="UpdateSQLS"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.DeleteSQL">
<short>Statement to be used when inserting a new row in the database</short>
<descr>
<p>
<var>DeleteSQL</var> can be used to specify an SQL <var>DELETE</var>
statement, which is used when an existing record was deleted from the dataset, 
and the changes must be written to the database. <var>TSQLQuery</var> 
can generate a delete statement by itself for many cases, but in case 
it fails, the statement to be used for the insert can be specified here.
</p>
<p>
The SQL statement should be parametrized according to the conventions 
for specifying parameters. Note that old field values can be specified 
as <var>:OLD_FIELDNAME</var>
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.UpdateSQL"/>
<link id="TSQLQuery.DeleteSQL"/>
<link id="TSQLQuery.UpdateMode"/>
<link id="UsingParams"/>
<link id="UpdateSQLS"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.IndexDefs" link="#fcl.bufdataset.TCustomBufDataset.IndexDefs">
<short>List of local index Definitions</short>
<descr>
</descr>
<seealso>
<link id="TCustomBufDataset.IndexDefs"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.Params">
<short>Parameters detected in the SQL statement.</short>
<descr>
<p>
<var>Params</var> contains the parameters used in the SQL statement. This
collection is only updated when <link id="TSQLQuery.ParseSQL">ParseSQL</link>
is <var>True</var>. For each named parameter in the <link id="TSQLQuery.SQL">SQL</link>
property, a named item will appear in the collection, and the collection
will be used to retrieve values from. 
</p>
<p>
When <link id="#fcl.db.TDataset.open">Open</link> or 
<link id="TCustomSQLQuery.ExecSQL">ExecSQL</link> is called, 
and the <link id="TSQLQuery.Datasource">Datasource</link> property is not
<var>Nil</var>,
then for each parameter for which no value was explicitly set (its <link id="#fcl.db.TParam.Bound">Bound</link>
property is <var>False</var>),  the value
will be retrieved from the dataset connected to the datasource. 
</p>
<p>
For each parameter, a field with the same name will be searched, 
and its value and type will be copied to the (unbound) parameter.
The parameter remains unbound.
</p>
<p>
The Update, delete and insert SQL statements are not scanned for parameters.
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.ParseSQL"/>
<link id="#fcl.db.TParam.Bound">TParam.Bound</link>
<link id="UsingParams"/>
<link id="UpdateSQLS"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.UpdateMode">
<short>How to create update SQL statements.</short>
<descr>
<p>
<var>UpdateMode</var> determines how the <var>WHERE</var> clause of the 
<link id="TSQLQuery.UpdateSQL">UpdateSQL</link> and 
<link id="TSQLQuery.DeleteSQL">DeleteSQL</link> statements are
auto-generated.
</p>
<dl>
<dt>upWhereAll</dt>
<dd><printshort id="#fcl.db.TUpdateMode.upWhereAll"/></dd>
<dt>upWhereChanged</dt>
<dd><printshort id="#fcl.db.TUpdateMode.upWhereChanged"/></dd>
<dt>upWhereKeyOnly</dt>
<dd><printshort id="#fcl.db.TUpdateMode.upWhereKeyOnly"/></dd>
</dl>
</descr>
<seealso>
<link id="TSQLQuery.UpdateSQL"/>
<link id="TSQLQuery.InsertSQL"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.UsePrimaryKeyAsKey">
<short>Should primary key fields be marked <var>pfInKey</var></short>
<descr>
<p>
<var>UsePrimaryKeyAsKey</var> can be set to <var>True</var> to let
<var>TSQLQuery</var> fetch all server indexes and if there is a primary key, 
update the <link id="#fcl.db.TField.ProviderFlags">ProviderFlags</link> of the
fields in the primary key with <link id="#fcl.db.TProviderFlag">pfInKey</link>.
</p>
<p>
The effect of this is that when <link id="TSQLQuery.UpdateMode">UpdateMode</link> 
equals <var>upWhereKeyOnly</var>, then only the fields that are part of the primary key
of the table will be used in the update statements. For more information,
see <link id="UpdateSQLs"/>.
</p>
</descr>
<seealso>
<link id="TSQLQuery.UpdateMode"/>
<link id="TCustomBufDataset.Unidirectional"/>
<link id="#fcl.db.TField.ProviderFlags">TField.ProviderFlags</link>
<link id="#fcl.db.TProviderFlag">pfInKey</link>
<link id="UpdateSQLs"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ParseSQL">
<short>Should the SQL statement be parsed or not</short>
<descr>
<p>
<var>ParseSQL</var> can be set to <var>False</var> to prevent <var>TSQLQuery</var>
from parsing the <link id="TSQLQuery.SQL">SQL</link> property and attempting
to detect the statement type or updating the <link id="TSQLQuery.Params">Params</link>
or <link id="TSQLQuery.StatementType">StatementType</link> properties.
</p>
<p> 
This can be used when SQLDB has problems parsing the SQL statement, or when
the SQL statement contains parameters that are part of a DDL statement such
as a <var>CREATE PROCEDURE</var> statement to create a stored procedure.
</p>
<p>
Note that in this case the statement will be passed as-is to the SQL engine,
no parameter values will be passed on.
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.Params"/>
</seealso>
</element>

<element name="TSQLQuery.StatementType">
<short>SQL statement type</short>
<descr>
<p>
<var>StatementType</var> is determined during the <link
id="TCustomSQLQuery.Prepare">Prepare</link> call when 
<link id="TSQLQuery.ParseSQL">ParseSQL</link> is set to <var>True</var>.
It gives an indication of the type of SQL statement that is being executed.
</p>
</descr>
<seealso>
<link id="TSQLQuery.SQL"/>
<link id="TSQLQuery.ParseSQL"/>
<link id="TSQLQuery.Params"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.DataSource">
<short>Source for parameter values for unbound parameters</short>
<descr>
<p>
<var>Datasource</var> can be set to a dataset which will be used to retrieve
values for the parameters if they were not explicitly specified.
</p>
<p>
When <link id="#fcl.db.TDataset.open">Open</link> or 
<link id="TCustomSQLQuery.ExecSQL">ExecSQL</link> is called, 
and the <var>Datasource</var> property is not <var>Nil</var>
then for each parameter for which no value was explicitly set 
(its <link id="#fcl.db.TParam.Bound">Bound</link> 
property is <var>False</var>),  the value
will be retrieved from the dataset connected to the datasource. 
</p>
<p>
For each parameter, a field with the same name will be searched, 
and its value and type will be copied to the (unbound) parameter.
The parameter remains unbound.
</p>
</descr>
<seealso>
<link id="TSQLQuery.Params">Params</link>
<link id="TCustomSQLQuery.ExecSQL">ExecSQL</link> 
<link id="UsingParams"/>
<link id="#fcl.db.TParam.Bound">TParam.Bound</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ServerFilter">
<short>Append server-side filter to SQL statement</short>
<descr>
<p>
<var>ServerFilter</var> can be set to a valid <var>WHERE</var> clause
(without the <var>WHERE</var> keyword). It
will be appended to the <var>select</var>  statement in <link
id="TSQLQuery.SQL">SQL</link>, when <link id="TSQLQuery.ServerFiltered">ServerFiltered</link>
is set to <var>True</var>. if <link id="TSQLQuery.ServerFiltered">ServerFiltered</link>
is set to <var>False</var>, <var>ServerFilter</var> is ignored. 
</p>
<p>
If the dataset is active and <link id="TSQLQuery.ServerFiltered">ServerFiltered</link> is set to
true, then changing this property will re-fetch the data from the server.
</p>
<p>
This property cannot be used when <link id="TSQLQuery.ParseSQL">ParseSQL</link> is <var>False</var>, because the 
statement must be parsed in order to know where the <var>WHERE</var> clause must be
inserted: the <var>TSQLQuery</var> class will intelligently insert the
clause in an SQL select statement.
</p>
</descr>
<errors>
Setting this property when <link id="TSQLQuery.ParseSQL">ParseSQL</link> is <var>False</var>
will result in an exception.
</errors>
<seealso>
<link id="TSQLQuery.ServerFiltered">ServerFiltered</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ServerFiltered">
<short>Should server-side filter be applied</short>
<descr>
<var>ServerFiltered</var> can be set to <var>True</var> to apply <link
id="TSQLQuery.ServerFilter">ServerFilter</link>. 
A change in the value for this property will re-fetch the query results if the dataset is active.
</descr>
<errors>
Setting this property to <var>True</var> when <link id="TSQLQuery.ParseSQL">ParseSQL</link> is <var>False</var>
will result in an exception.
</errors>
<seealso>
<link id="TSQLQuery.ParseSQL">ParseSQL</link>
<link id="TSQLQuery.ServerFilter">ServerFilter</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ServerIndexDefs">
<short>List of indexes on the primary table of the query</short>
<descr>
<var>ServerIndexDefs</var> will be filled - during the <var>Prepare</var> call
-  with the list of indexes defined
on the primary table in the query if 
<link id="TSQLQuery.UsePrimaryKeyAsKey">UsePrimaryKeyAsKey</link> is <var>True</var>.
If a primary key is found, then the fields in it will be marked
</descr>
<seealso>
<link id="TSQLQuery.UsePrimaryKeyAsKey">UsePrimaryKeyAsKey</link>
<link id="TCustomSQLQuery.Prepare">Prepare</link>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TSQLScript.Create">
<short>Create a new <var>TSQLScript</var> instance.</short>
<descr>
<var>Create</var> instantiates a <link id="TSQLQuery"/> instance which
will be used to execute the queries, and then calls the inherited
constructor.
</descr>
<seealso>
<link id="TSQLScript.Destroy"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TSQLScript.Create.AOwner">
<short>Owner for the new instance.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TSQLScript.Destroy">
<short>Remove the <var>TSQLScript</var> instance from memory.</short>
<descr>
<var>Destroy</var> frees the <link id="TSQLQuery"/> instance that was
created during the <var>Create</var> constructor from memory and then calls
the inherited destructor.
</descr>
<seealso>
<link id="TSQLScript.Create"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLScript.ExecuteScript">
<short>Convenience function, simply calls <var>Execute</var></short>
<descr>
<var>ExecuteScript</var> is a convenience function, it simply calls
<var>Execute</var>. The statements in the script will be executed one by
one.
</descr>
</element>

<!-- property Visibility: public -->
<element name="TSQLScript.Script">
<short>The script to execute</short>
<descr>
<p>
<var>Script</var> contains the list of SQL statements to be executed. 
The statements should be separated by the character specified in the 
<link id="TSQLScript.Terminator">Terminator</link> property. Each of the statement will
be executed on the database specified  in <link id="TSQLScript.DataBase">Database</link>.
using the equivalent of the <link id="TCustomSQLQuery.ExecSQL"/> statement.
The statements should not return result sets, but other than that all kind
of statements are allowed. 
</p>
<p>
Comments will be conserved and passed on in the statements to be executed,
depending on the value of the <link id="TSQLScript.CommentsinSQL"/> property.
If that property is <var>False</var>, comments will be stripped prior to executing the
SQL statements.
</p>
</descr>
<seealso>
<link id="TSQLScript.CommentsinSQL"/>
<link id="TSQLScript.Terminator"/>
<link id="TSQLScript.DataBase"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TSQLScript.DataBase">
<short>Database on which to execute the script</short>
<descr>
<var>Database</var> should be set to the <link id="TSQLConnection"/> descendent.
All SQL statements in the <link id="TSQLScript.Script">Script</link>
property will be executed on this database.
</descr>
<seealso>
<link id="TSQLConnection"/>
<link id="TSQLScript.Transaction"/>
<link id="TSQLScript.Script"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TSQLScript.Transaction">
<short>Transaction to use in the script</short>
<descr>
<var>Transaction</var> is the transaction instance to use when executing
statements. If the SQL script contains any <var>COMMIT</var> 
statements, they will be handled using the <link
id="TSQLTRansaction.CommitRetaining"/> method.
</descr>
<seealso>
<link id="TSQLTransaction"/>
<link id="TSQLTransaction.CommitRetaining"/>
<link id="TSQLScript.Database"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TSQLConnector">
<short>Universal connection component</short>
<descr>
<p>
<var>TSQLConnector</var> implements a general connection type. 
When switching database backends, the normal procedure is to replace one instance
of <link id="TSQLConnection"/> descendent with another, and connect all
instances of <link id="TSQLQuery"/> and <link id="TSQLTransaction"/> to the
new connection.
</p>
<p>
Using <var>TSQLConnector</var> avoids this: the type of connection can be set
using the <link id="TSQLConnector.ConnectorType">ConnectorType</link>
property, which is a string property. The <var>TSQLConnector</var> class
will (in the background) create the correct <link id="TSQLConnection"/>
descendent to handle all actual operations on the database.
</p>
<p>
In all other respects, <var>TSQLConnector</var> acts like a regular
<var>TSQLConnection</var> instance. Since no access to the actually used
<var>TSQLConnection</var> descendent is available, connection-specific calls
are not available.
</p>
</descr>
<seealso>
<link id="TSQLConnector.ConnectorType"/>
<link id="UniversalConnectors"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnector.ConnectorType">
<short>Name of the connection type to use</short>
<descr>
<var>ConnectorType</var> should be set to one of the availabe connector
types in the application. The list of possible connector types can be
retrieved using <link id="GetConnectionList"/> call. The
<var>ConnectorType</var> property can only be set when the connection is not
active.
</descr>
<errors>
Attempting to change the <var>ConnectorType</var> property while the
connection is active will result in an exception.
</errors>
<seealso>
<link id="GetConnectionList"/>
</seealso>
</element>

<!-- "class of" type Visibility: default -->
<element name="TSQLConnectionClass">
<short>Class of <var>TSQLConnection</var> type</short>
<descr>
<var>TSQLConnectionClass</var> is used when registering a new connection
type for use in the universal connector <link id="TSQLConnector.ConnectorType"/> 
</descr>
<seealso>
<link id="TSQLConnector.ConnectorType"/> 
<link id="TSQLConnector"/>
<link id="RegisterConnection"/>
<link id="TConnectionDef.ConnectionClass"/>
</seealso>
</element>

<!-- object Visibility: default -->
<element name="TConnectionDef">
<short>Connection type definition class</short>
<descr>
<var>TConnectionDef</var> is an abstract class. When registering a new
connection type for use in the universal connector, a descendent of this
class must be made and registered using <link id="RegisterConnection"/>.
A descendent class should override at least the <link id="TConnectionDef.TypeName"/> 
and <link id="TConnectionDef.ConnectionClass"/> methods to return the
specific name and connection class to use.
</descr>
<seealso>
<link id="TConnectionDef.TypeName"/> 
<link id="TConnectionDef.ConnectionClass"/>
<link id="RegisterConnection"/>
</seealso>
</element>

<!-- function Visibility: default -->
<element name="TConnectionDef.TypeName">
<short>Name of the connection type</short>
<descr>
<p>
<var>TypeName</var> is overridden by descendent classes to return the unique
name for this connection type. It is what the <link id="TSQLConnector.ConnectorType"/>
property should be set to select this connection type for the universal
connection, and is the name that the <link id="GetConnectionDef"/> call will
use when looking for a connection type. It must be overidden by descendents  
of <var>TConnectionDef</var>.
</p>
<p>
This name is also returned in the list returned by <link
id="GetConnectionList"/>
</p>
<p>
This name can be an arbitrary name, no restrictions on the allowed characters exist.
</p>
</descr>
<seealso>
<link id="TSQLConnector.ConnectorType"/>
<link id="GetConnectionDef"/> 
<link id="GetConnectionList"/> 
<link id="TConnectionDef.ConnectionClass"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.TypeName.Result">
<short>Unique name for the connection type</short>
</element>

<!-- function Visibility: default -->
<element name="TConnectionDef.ConnectionClass">
<short>Class to instantiate when this connection is requested</short>
<descr>
<p>
<var>ConnectionClass</var> should return the connection class to use when a
connection of this type is reqested. It must be overidden by descendents
of <var>TConnectionDef</var>.
</p>
<p>
It may not be <var>Nil</var>.
</p>
</descr>
<seealso>
<link id="TConnectionDef.TypeName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.ConnectionClass.Result">
<short>The <var>TSQLConnectionClass</var> for this connection type.</short>
</element>

<!-- function Visibility: default -->
<element name="TConnectionDef.Description">
<short>A descriptive text for this connection type</short>
<descr>
<var>Description</var> should return a descriptive text for this connection
type. It is used for display purposes only, so ideally it should be a
one-liner. It can be used to provide more
information about the particulars of the connection type.
</descr>
<seealso>
<link id="TConnectionDef.TypeName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.Description.Result">
<short>A description of the connection type.</short>
</element>

<!-- procedure Visibility: default -->
<element name="TConnectionDef.ApplyParams">
<short>Apply parameters to an instance of <var>TSQLConnection</var></short>
<descr>
<p>
<var>ApplyParams</var> must be overridden to apply any params specified in
the <var>Params</var> argument to the <link id="TSQLConnection"/> descendent 
in <var>AConnection</var>. It can be used to convert <var>Name=Value</var>
pairs to properties of the actual connection instance. 
</p>
<p>
When called, <var>AConnection</var>  is guaranteed to be of the same type as 
returned by <link id="TConnectionDef.ConnectionClass"/>. 
<var>Params</var> contains the contents of the <link id="TSQLConnection.Params"/>
property of the connector.
</p>
</descr>
<seealso>
<link id="TSQLConnection.Params"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TConnectionDef.ApplyParams.Params">
<short>Parameters to apply in <var>Name=Value</var> form</short>
</element>

<!-- argument Visibility: default -->
<element name="TConnectionDef.ApplyParams.AConnection">
<short>Connection instance to which to apply the parameters</short>
</element>

<!-- "class of" type Visibility: default -->
<element name="TConnectionDefClass">
<short>Class of TConnectionDef</short>
<descr>
<var>TConnectionDefClass</var> is used in the <link
id="RegisterConnection"/> call to register a new <link id="TConnectionDef"/>
instance.
</descr>
<seealso>
<link id="RegisterConnection"/> 
<link id="TConnectionDef"/>
<link id="UnregisterConnection"/> 
</seealso>
</element>

<!-- procedure Visibility: default -->
<element name="RegisterConnection">
<short>Register a new connection type for use in the universal connector</short>
<descr>
<p>
<var>RegisterConnection</var> must be called with a class pointer to a <link
id="TConnectionDef"/> descendent to register the connection type described
in the <link id="TConnectionDef"/> descendent. The connection type is
registered with the name as returned by <link id="TConnectionDef.TypeName"/>.
</p>
<p>
The various connection types distributed by Free Pascal automatically call
<var>RegisterConnection</var> from the <var>initialization</var> section of their unit,
so simply including the unit with a particular connection type is enough to
register it.
</p>
<p>
Connection types registered with this call can be unregistered with 
<link id="UnRegisterConnection"/>.
</p>
</descr>
<errors>
if <var>Def</var> is <var>Nil</var>, access violations will occur.
</errors>
<seealso>
<link id="TConnectionDef"/>
<link id="UnRegisterConnection"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="RegisterConnection.Def">
<short>The connection type definition to register.</short>
</element>

<!-- procedure Visibility: default -->
<element name="UnRegisterConnection">
<short>Unregister a registered connection type</short>
<descr>
<var>UnRegisterConnection</var> will unregister the connection <var>Def</var>. 
If a connection with <var>ConnectionName</var> or with name as returned by
the <link id="TConnectionDef.TypeName">TypeName</link> method from <var>Def</var>  
was previously registered, it will be removed from the list of registered connection types.
</descr>
<errors>
if <var>Def</var> is <var>Nil</var>, access violations will occur.
</errors>
<seealso>
<link id="TConnectionDef"/>
<link id="RegisterConnection"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="UnRegisterConnection.Def">
<short>The connection type definition to unregister.</short>
</element>

<!-- argument Visibility: default -->
<element name="UnRegisterConnection.ConnectionName">
<short>The name of the connection type definition to unregister.</short>
</element>

<!-- function Visibility: default -->
<element name="GetConnectionDef">
<short>Search for a connection definition by name</short>
<descr>
<p>
<var>GetConnectionDef</var> will search in the list of connection type
definitions, and will return the one definition with the name that 
matches <var>ConnectorName</var>. The search is case insensitive.
</p>
<p>
If no definition is found, <var>Nil</var> is returned.
</p>
</descr>
<seealso>
<link id="RegisterConnection"/>
<link id="TConnectionDef"/>
<link id="TConnectionDef.TypeName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="GetConnectionDef.Result">
<short>The connection type definition, <var>Nil</var> if not found.</short>
</element>

<!-- argument Visibility: default -->
<element name="GetConnectionDef.ConnectorName">
<short>The name of the connection type to search</short>
</element>

<!-- procedure Visibility: default -->
<element name="GetConnectionList">
<short>Return a list of connection definition names.</short>
<descr>
<var>GetConnectionList</var> clears <var>List</var> and fills it with the
list of currently known connection type names, as registered with <link
id="RegisterConnection"/>. The names are the names as returned by 
<link id="TConnectionDef.TypeName"/>
</descr>
<seealso>
<link id="RegisterConnection"/>
<link id="TConnectionDef.TypeName"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="GetConnectionList.List">
<short>List to fill with connection names. Will be cleared</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citAll">
<short>All connection information</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citServerType">
<short>Server type description</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citServerVersion">
<short>Server version as an integer number</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citServerVersionString">
<short>Server version as a string</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citClientName">
<short>Client library name</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TConnInfoType.citClientVersion">
<short>Client library version</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TStatementType.stUnknown">
<short>Unknown (other) information</short>
</element>

<!-- enumeration type Visibility: default -->
<element name="TDBEventType">
<short>Type of database event</short>
<descr>
<var>TDBEventType</var> describes the type of a database event message as generated
by <link id="TSQLConnection"/> through the <link id="TSQLConnection.OnLog"/>
event.
</descr>
<seealso>
<link id="TSQLConnection"/>
<link id="TDBLogNotifyEvent"/>
<link id="TSQLConnection.OnLog"/>
</seealso>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detCustom">
<short>Custom event message</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detPrepare">
<short>SQL prepare message</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detExecute">
<short>SQLExecute message</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detFetch">
<short>Fetch data message</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detCommit">
<short>Transaction Commit message</short>
</element>

<!-- enumeration value Visibility: default -->
<element name="TDBEventType.detRollBack">
<short>Transaction rollback message</short>
</element>

<!-- set type Visibility: default -->
<element name="TDBEventTypes">
<short>Set of database event types</short>
<descr>
<var>TDBEventTypes</var> is a set of <link id="TDBEventType"/> values, which
is used to filter the set of event messages that should be sent. The
<link id="TSQLConnection.LogEvents"/> property determines which events a
particular connection will send.
</descr>
<seealso>
<link id="TSQLConnection.LogEvents"/>
<link id="TDBLogNotifyEvent"/>
<link id="GlobalDBLogHook"/>
</seealso>
</element>

<!-- procedure type Visibility: default -->
<element name="TDBLogNotifyEvent">
<short>Event handler prototype for handling events</short>
<descr>
<var>TDBLogNotifyEvent</var> is the prototype for the
<link id="TSQLConnection.OnLog"/> event handler and for the global <link id="GlobalDBLogHook"/> event handling hook.
<var>Sender</var> will contain the <link id="TSQLConnection"/> instance that
caused the event, <var>EventType</var> will contain the event type, and
<var>Msg</var> will contain the actual message: the content depends on the
type of the message.
</descr>
<seealso>
<link id="TSQLConnection.OnLog"/>
<link id="GlobalDBLogHook"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TDBLogNotifyEvent.Sender">
<short><var>TSQLConnection</var> instance that sent the event.</short>
</element>

<!-- argument Visibility: default -->
<element name="TDBLogNotifyEvent.EventType">
<short>Event type</short>
</element>

<!-- argument Visibility: default -->
<element name="TDBLogNotifyEvent.Msg">
<short>Event message. Actual content depends on the type of message.</short>
</element>

<!-- variable Visibility: public -->
<element name="TSQLCursor.FSelectable">
<short>Selectable query or not</short>
<descr>
<var>FSelectable</var> exists for internal use. It should not be used by
applications.
</descr>
</element>

<!-- variable Visibility: public -->
<element name="TSQLCursor.FSchemaType">
<short>Schema type requested</short>
<descr>
<var>FSchemaType</var> exists for internal use. It should not be used by
applications.
</descr>
</element>

<!-- array type Visibility: default -->
<element name="TQuoteChars">
<short>Type to describe quote characters.</short>
<descr>
<var>TQuoteChars</var> is an array of characters that describes the used delimiters
for string values.
</descr>
<seealso>
<link id="SingleQuotes"/>
<link id="DoubleQuotes"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="SingleQuotes">
<short>Single quote delimiters</short>
<descr>
<var>SingleQuotes</var> is the set of delimiters used when using single
quotes for string literals.
</descr>
<seealso>
<link id="DoubleQuotes"/>
<link id="TQuoteChars"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="DoubleQuotes">
<short>Double quote delimiters</short>
<descr>
<var>DoubleQuotes</var> is the set of delimiters used when using double
quotes for string literals.
</descr>
<seealso>
<link id="SingleQuotes"/>
<link id="TQuoteChars"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="LogAllEvents">
<short>Constant that can be used to select all events.</short>
<descr>
<var>LogAllEvents</var> is a constant that contains the full set of
available event types. It can be used to set <link id="TSQLConnection.LogEvents"/>.
</descr>
<seealso>
<link id="TSQLConnection.LogEvents"/>
<link id="TDBLogNotifyEvent"/>
<link id="GlobalDBLogHook"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TSQLConnection.FieldNameQuoteChars">
<short>Characters used to quote field names.</short>
<descr>
<var>FieldNameQuoteChars</var> can be set to specify the characters that
should be used to delimit field names in SQL statements generated by SQLDB.
It is normally initialized correctly by the
<link id="TSQLConnection"/> descendent to the default for that particular
connection type.
</descr>
<seealso>
<link id="TSQLConnection"/>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TSQLConnection.Create">
<short>Create a new instance of <var>TSQLConnection</var></short>
<descr>
<var>Create</var> initialized a new instance of <link id="TSQLconnection"/>.
After calling the inherited constructor, it will initialize the <link
id="TSQLConnection.FieldNameQuoteChars">FieldNameQuoteChars</link> property
and some other fields for internal use.
</descr>
<seealso>
<link id="TSQLConnection.FieldNameQuoteChars">FieldNameQuoteChars</link>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TSQLConnection.Create.AOwner">
<short>Owner for the new <var>TSQLConnection</var>instance</short>
</element>

<!-- function Visibility: public -->
<element name="TSQLConnection.GetConnectionInfo">
<short>Return some information about the connection</short>
<descr>
<var>GetConnectionInfo</var> can be used to return some information about
the connection. Which information is returned depends on the <var>InfoType</var>
parameter. The information is returned as a string. If <var>citAll</var> is
passed, then the result will be a comma-separated list of values, each of
the values enclosed in double quotes.
</descr>
<seealso>
<link id="TConnInfoType"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TSQLConnection.GetConnectionInfo.Result">
<short>Requested information as a string value.</short>
</element>

<!-- argument Visibility: public -->
<element name="TSQLConnection.GetConnectionInfo.InfoType">
<short>Connection information to be returned.</short>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.OnLog">
<short>Event handler for logging events</short>
<descr>
<p>
<var>TSQLConnection</var> can send events for all the actions that it
performs: executing SQL statements, committ and rollback of transactions
etc. This event handler must be set to react on these events: they can for
example be written to a log file. Only events specified in the <link
id="TSQLConnection.LogEvents">LogEvents</link> property will be logged.
</p>
<p>
The events received by this event handler are specific for this connection. 
To receive events from all active connections in the application, set the
global <link id="GlobalDBLogHook"/> event handler.
</p>
</descr>
<seealso>
<link id="GlobalDBLogHook"/>
<link id="TSQLConnection.LogEvents"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLConnection.LogEvents">
<short>Filter for events to log</short>
<descr>
<var>LogEvents</var> can be used to filter the events which should be sent
to the <link id="TSQLConnection.OnLog">OnLog</link> and <link id="GlobalDBLogHook"/> event handlers. 
Only event types that are listed in this property will be sent.
</descr>
<seealso>
<link id="GlobalDBLogHook"/>
<link id="TSQLConnection.OnLog"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLQuery.SetSchemaInfo.ASchemaType">
<short>Schema type to use</short>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLQuery.SetSchemaInfo.ASchemaObjectName">
<short>Name of Object for which to return schema information. </short>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLQuery.SetSchemaInfo.ASchemaPattern">
<short>Pattern for schema information</short>
</element>

<!-- function Visibility: public -->
<element name="TCustomSQLQuery.ParamByName">
<short>Return parameter by name</short>
<descr>
<p>
<var>ParamByName</var> is a shortcut for <link
id="#fcl.db.TParams.ParamByName">Params.ParamByName</link>. The 2 following
pieces of code are completely equivalent:
</p>
<code>
Qry.ParamByName('id').AsInteger:=123;
</code>
<p>
and
</p>
<code>
Qry.Params.ParamByName('id').AsInteger:=123;
</code>
</descr>
<seealso>
<link id="#fcl.db.TParams.ParamByName">Params.ParamByName</link>
<link id="TSQLQuery.Params"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TCustomSQLQuery.ParamByName.Result">
<short>Resulting <var>TParam</var> instance.</short>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLQuery.ParamByName.AParamName">
<short>Name of parameter to look for. Case insensitive.</short>
</element>

<!-- property Visibility: public -->
<element name="TSQLQuery.SchemaType">
<short>Schema type</short>
<descr>
<var>SchemaType</var> is the schema type set by <link
id="TCustomSQLQuery.SetSchemaInfo"/>. It determines what kind of schema
information will be returned by the <var>TSQLQuery</var> instance.
</descr>
<seealso>
<link id="TCustomSQLQuery.SetSchemaInfo"/>
<link id="RetrievingSchemaInformation"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.MaxIndexesCount">
<short>Maximum allowed number of indexes.</short>
<descr>
<p>
<var>MaxIndexesCount</var> determines the number of index entries that the
dataset will reserve for indexes. No more indexes than indicated here can be
used. The property must be set before the dataset is opened. The minimum 
value for this property is 1. The default value is 2.
</p>
<p> 
If an index is added and the current index count equals
<var>MaxIndexesCount</var>, an exception will be raised.
</p>
</descr>
<errors>
Attempting to set this property while the dataset is active will raise an
exception.
</errors>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.FieldDefs" link="#fcl.db.tdataset.fielddefs">
<short>List of field definitions.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLScript.Execute">
<short>Execute the script.</short>
<descr>
<p>
<var>Execute</var> will execute the statements specified in <link
id="TSQLScript.Script">Script</link> one by one, till the last statement is
processed or an exception is raised.
</p>
<p> 
If an error occurs during execution, normally an exception is raised. 
If the <link id="TSQLScript.OnException"/> event handler is set, it may 
stop the event handler.
</p>
</descr>
<errors>
Handle errors using <link id="TSQLScript.OnException"/>.
</errors>
<seealso>
<link id="TSQLScript.Script">Script</link>
<link id="TSQLScript.OnException"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.OnDirective">
<short>Event handler if a directive is encountered</short>
<descr>
<var>OnDirective</var> is called when a directive is encountered. When
parsing the script, the script engine checks the first word of the statement.
If it matches one of the words in <link id="TSQLScript.Directives">Directives</link> property then
the <var>OnDirective</var> event handler is
called with the name of the directive and the rest of the statement as
parameters. This can be used to handle all kind of pre-processing actions
such as <var>Set term \^ ;</var>
</descr>
<seealso>
<link id="TSQLScript.Directives">Directives</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.Directives">
<short>List of directives</short>
<descr>
<var>Directives</var> is a stringlist with words that should be recognized as directives.
They will be handled using the <link id="TSQLScript.OnDirective">OnDirective</link>
event handler. The list should contain one word per line, no spaces allowed.
</descr>
<seealso>
<link id="TSQLScript.OnDirective">OnDirective</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.Defines">
<short>Defined macros</short>
<descr>
<var>Defines</var> contains the list of defined macros for use with the
<link id="TSQLScript.UseDefines"/> property. Each line should contain a 
macro name. The names of the macros are case insensitive. The
<var>#DEFINE</var> and <var>#UNDEFINE</var> directives will add or remove
macro names from this list.
</descr>
<seealso>
<link id="TSQLScript.UseDefines"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.Terminator">
<short>Terminator character.</short>
<descr>
<var>Terminator</var> is the character used by <var>TSQLScript</var> to
delimit SQL statements. By default it equals the semicolon (;), which is the
customary SQL command terminating character.
By itself <var>TSQLScript</var> does not recognize complex
statements such as <var>Create Procedure</var> which can contain terminator
characters such as ";". Instead, <var>TSQLScript</var> will scan the script
for the <var>Terminator</var> character. Using directives such as <var>SET TERM</var>
the terminator character may be changed in the script.
</descr>
<seealso>
<link id="TSQLScript.OnDirective">OnDirective</link>
<link id="TSQLScript.Directives">Directives</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.CommentsinSQL">
<short>Should comments be passed to the SQL engine ?</short>
<descr>
<p>
<var>CommentsInSQL</var> can be set to <var>True</var> to let
<var>TSQLScript</var> preserve any comments it finds in the script. 
The comments will be passed to the SQLConnection as part of the commands.
If the property is set to <var>False</var> the comments are discarded.
</p>
<p>
By default, <var>TSQLScript</var> discards comments.
</p>
</descr>
<seealso>
<link id="TSQLScript.Script"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.UseSetTerm">
<short>Should the SET TERM directive be recognized</short>
<descr>
<p>
<var>UseSetTerm</var> can be set to <var>True</var> to let
<var>TSQLScript</var> automatically handle the <var>SET TERM</var> directive
and set the <link id="TSQLSCript.Terminator"/> character based on the value
specified in the <var>SET TERM</var> directive. This means that the
following directive:
</p>
<code>
SET TERM ^ ;
</code>
<p>
will set the terminator to the caret character. Conversely, the
</p>
<code>
SET TERM ; ^
</code>
<p>
will then switch the terminator character back to the commonly used
semicolon (;).
</p>
</descr>
<seealso>
<link id="TSQLSCript.Terminator"/>
<link id="TSQLSCript.Script"/>
<link id="TSQLSCript.Directives"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.UseCommit">
<short>Control automatic handling of the <var>COMMIT</var> command.</short>
<descr>
<p>
<var>UseCommit</var> can be set to <var>True</var> to let <var>TSQLScript</var> 
automatically handle the commit command as a directive. If it is set,
the <var>COMMIT</var> command is registered as a directive, and 
the <link id="TSQLScript.Transaction"/> will be commited and restarted
at once whenever the <var>COMMIT</var> directive appears in the script. 
</p>
<p>
If this property is set to <var>False</var> then the commit command will be
passed on to the SQL engine like any other SQL command in the script.
</p>
</descr>
<seealso>
<link id="TSQLScript.Transaction"/>
<link id="TSQLScript.Directives"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.UseDefines">
<short>Automatically handle pre-processor defines</short>
<descr>
<p>
<var>UseDefines</var> will automatically register the following
pre-processing directives:
</p>
<code>
#IFDEF
#IFNDEF
#ELSE
#ENDIF
#DEFINE
#UNDEF
#UNDEFINE
</code>
<p>
Additionally, these directives will be automatically handled by the
<var>TSQLScript</var> component. This can be used to add conditional execution
of the SQL script: they are treated as the conditional compilation
statements found in the C macro preprocessor or the FPC conditional
compilation features. The initial list of defined macros can be specified in
the <link id="TSQLScript.Defines">Defines</link> property, where one define
per line can be specified.
</p>
<p>
In the following example, the correct statement to create a sequence is
selected based on the presence of the macro <var>FIREBIRD</var> in the list
of defines:
</p>
<code>
#IFDEF FIREBIRD
CREATE GENERATOR GEN_MYID;
#ELSE
CREATE SEQUENCE GEN_MYID;
#ENDIF
</code>
</descr>
<seealso>
<link id="TSQLScript.Script"/>
<link id="TSQLScript.Defines"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLScript.OnException">
<short>Exception handling event</short>
<descr>
<var>OnException</var> can be set to handle an exception during the
execution of a statement or directive when the script is executed.
The exception is passed to the handler in the <var>TheException</var>
parameter. On return, the value of the <var>Continue</var> parameter is
checked: if it is set to <var>True</var>, then the exception is ignored. If
it is set to <var>False</var> (the default), then the exception is
re-raised, and script execution will stop.
</descr>
<seealso>
<link id="TSQLScript.Execute"/>
</seealso>
</element>

<!-- function type Visibility: default -->
<element name="TLibraryLoadFunction">
<short>Library loading function prototype</short>
<descr>
<var>TLibraryLoadFunction</var> is the function prototype for dynamically
loading a library when the universal connection component is used. It
receives the name of the library to load (<var>S</var>), and should return
<var>True</var> if the library was succesfully loaded. It is used in the
connection definition.
</descr>
<seealso>
<link id="TConnectionDef"/>
<link id="TConnectionDef.DefaultLibraryName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TLibraryLoadFunction.Result">
<short><var>True</var> if the library was succesfully loaded</short>
</element>

<!-- argument Visibility: default -->
<element name="TLibraryLoadFunction.S">
<short>Name of the library to load.</short>
</element>

<!-- procedure type Visibility: default -->
<element name="TLibraryUnLoadFunction">
<short>Library unloading function prototype</short>
<descr>
<var>TLibraryUnLoadFunction</var> is the function prototype for dynamically
unloading a library when the universal connection component is used. It has
no parameters, and should simply unload the library loaded with <link
id="TLibraryLoadFunction"/>
</descr>
<seealso>
<link id="TLibraryLoadFunction"/>
<link id="TConnectionDef"/>
<link id="TConnectionDef.DefaultLibraryName"/>
</seealso>
</element>

<!-- class function Visibility: default -->
<element name="TConnectionDef.DefaultLibraryName">
<short>Default library name</short>
<descr>
<var>DefaultLibraryName</var> should be set to the default library name for
the connection. This can be used to let SQLDB automatically load the library
needed when a connection of this type is requested.
</descr>
<seealso>
<link id="TLibraryLoadFunction"/>
<link id="TConnectionDef"/>
<link id="TLibraryUnLoadFunction"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.DefaultLibraryName.Result">
<short>Name of the library to load</short>
</element>

<!-- class function Visibility: default -->
<element name="TConnectionDef.LoadFunction">
<short>Return a function to call when the client library must be loaded</short>
<descr>
<var>LoadFunction</var> must return the function that will be called when the client
library for this connection type must be loaded. This method must be
overridden by descendent classes to return a function that will correctly 
load the client library when a connection of this type is used.
</descr>
<seealso>
<link id="TLibraryLoadFunction"/>
<link id="TConnectionDef.UnLoadFunction"/>
<link id="TConnectionDef.DefaultLibraryName"/>
<link id="TConnectionDef.LoadedLibraryName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.LoadFunction.Result">
<short>The function to call when the client library must be loaded </short>
</element>

<!-- class function Visibility: default -->
<element name="TConnectionDef.UnLoadFunction">
<short>Return a function to call when the client library must be unloaded</short>
<descr>
<var>UnLoadFunction</var> must return the function that will be called when
the client library for this connection type must be unloaded. This method must be
overridden by descendent classes to return a function that will correctly
unload the client library when a connection of this type is no longer used.
</descr>
<seealso>
<link id="TLibraryUnLoadFunction"/>
<link id="TConnectionDef.LoadFunction"/>
<link id="TConnectionDef.DefaultLibraryName"/>
<link id="TConnectionDef.LoadedLibraryName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.UnLoadFunction.Result">
<short>The function to call when the client library must be unloaded</short>
</element>

<!-- class function Visibility: default -->
<element name="TConnectionDef.LoadedLibraryName">
<short>Currently loaded library.</short>
<descr>
<var>LoadedLibraryName</var> must be overridden by descendents to return the
filename of the currenly loaded client library for this connection type. 
If no library is loaded, an empty string must be returned.
</descr>
<seealso>
<link id="TLibraryLoadFunction"/>
<link id="TLibraryUnLoadFunction"/>
<link id="TConnectionDef.LoadFunction"/>
<link id="TConnectionDef.UnLoadFunction"/>
<link id="TConnectionDef.DefaultLibraryName"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TConnectionDef.LoadedLibraryName.Result">
<short>Name of the currently loaded library</short>
</element>

<!-- variable Visibility: default -->
<element name="GlobalDBLogHook">
<short>Global logging hook</short>
<descr>
<var>GlobalDBLogHook</var> can be set in addition to local <link
id="TSQLConnection.Onlog"/> event handlers. All connections will report
events through this global event handler in addition to their
<var>OnLog</var> event handlers. The global log event handler can be set
only once, so when setting the handler, it is important to set up chaining:
saving the previous value, and calling the old handler (if it was set) in
the new handler.
</descr>
<seealso>
<link id="TSQLConnection.Onlog"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="DefaultSQLFormatSettings">
<short>Default settings to be used in SQL </short>
<descr>
<var>DefaultSQLFormatSettings</var> contains the default settings used when
formatting date/time and other special values in Update SQL statements generated by
the various <link id="TSQLConnection"/> descendents.
</descr>
<seealso>
</seealso>
</element>

<!-- enumeration value Visibility: default -->
<element name="TSchemaType.stSchemata">
<short>List of schemas in database(s)</short>
</element>

<!-- record type Visibility: default -->
<element name="TSQLStatementInfo">
<short>Record to describe a SQL statement</short>
<descr>
<p>
<var>TSQLStatementInfo</var> is a record used to describe an SQL statement.
It is used internally by the <link id="TSQLStatement"/> and <link
id="TSQLQuery"/> objects to analyse SQL statements.
</p>
<p>
It is used to be able to modify the SQL statement (for additional filtering)
or to determine the table to update when applying dataset updates to the
database.
</p>
</descr>
<seealso>
<link id="TSQLStatement"/>
<link id="TSQLQuery"/>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TSQLStatementInfo.StatementType">
<short>Type of SQL statement</short>
</element>

<!-- variable Visibility: default -->
<element name="TSQLStatementInfo.TableName">
<short>Tablename to be used in updates</short>
</element>

<!-- variable Visibility: default -->
<element name="TSQLStatementInfo.Updateable">
<short>Updateable SQL result set ?</short>
</element>

<!-- variable Visibility: default -->
<element name="TSQLStatementInfo.WhereStartPos">
<short>Where clause start position</short>
</element>

<!-- variable Visibility: default -->
<element name="TSQLStatementInfo.WhereStopPos">
<short>Where clause end position</short>
</element>

<!--
  ********************************************************************
    #fcl.sqldb.TCustomSQLStatement
  ********************************************************************
-->

<!-- class Visibility: default -->
<element name="TCustomSQLStatement">
<short>Object to execute SQL statements without result set.</short>
<descr>
<p>
<var>TCustomSQLStatement</var> is a light-weight object that can be used to
execute SQL statements on a database. It does not support result sets, and
has none of the methods that a <link id="TDataset"/> component has. It can
be used to execute SQL statements on a database that update data, execute
stored procedures and DDL statements etc. 
</p>
<p>
The <var>TCustomSQLStatement</var> is equivalent to <link id="TSQLQuery"/>
in that it supports transactions (in the <link
id="TSQLConnection.Transaction">Transaction</link> property)
and parameters (in the <link id="TSQLConnection.Params">Params</link> property) and as such is a more
versatile tool than executing queries using <link id="TSQLConnection.ExecuteDirect"/>.
</p>
<p>
To use a <var>TCustomSQLStatement</var> is simple and similar to the use of
<link id="TSQLQuery"/>: set the <link
id="TSQLStatement.Database">Database</link> property to an existing connection component, and set the
<link id="TSQLStatement.Transaction">Transaction</link> property. After setting the <link
id="TSQLStatement.SQL">SQL</link>
property and filling <link id="TSQLStatement.Params">Params</link>, the SQL statement can be executed
with the <link id="Execute"/> method.
</p>
<p>
<var>TCustomSQLStatement</var> is a parent class. Many of the properties are
only made public (or published) in the <link id="TSQLStatement"/> class, which 
should be instantiated instead of the <var>TCustomSQLStatement</var> class.
</p>
</descr>
<seealso>
<link id="TSQLStatement"/>
<link id="TDataset"/>
<link id="TSQLQuery"/>
<link id="TSQLStatement.Transaction"/>
<link id="TSQLStatement.Params"/>
<link id="Execute"/>
<link id="TSQLStatement.Database"/>
<link id="TSQLConnection.ExecuteDirect"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TSQLConnection.GetSchemaNames">
<short>Get database schema names</short>
<descr>
<var>GetSchemaNames</var> returns a list of schemas defined in the database.
</descr>
<seealso>
<link id="TSQLConnection.GetTableNames"/>
<link id="TSQLConnection.GetProcedureNames"/>
<link id="TSQLConnection.GetFieldNames"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TSQLConnection.GetSchemaNames.List">
<short>On return, filled with schema names, one per line</short>
</element>

<!-- constructor Visibility: public -->
<element name="TCustomSQLStatement.Create">
<short>Create a new instance of <var>TCustomSQLStatement</var></short>
<descr>
<var>Create</var> initializes a new instance of
<var>TCustomSQLStatement</var> and sets the <link
id="TSQLStatement.SQL">SQL</link>
<link id="TSQLStatement.Params">Params</link>, <link
id="TSQLStatement.ParamCheck">ParamCheck</link> and 
<link id="TSQLStatement.ParseSQL">ParseSQL</link> to
their initial values.
</descr>
<seealso>
<link id="TSQLStatement.SQL"/>
<link id="TSQLStatement.Params"/>
<link id="TSQLStatement.ParamCheck"/> 
<link id="TSQLStatement.ParseSQL"/> 
<link id="Destroy"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLStatement.Create.AOwner">
<short>Owner of the new <var>TCustomSQLStatement</var> instance.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TCustomSQLStatement.Destroy">
<short>Destroy a <var>TCustomSQLStatement</var> instance.</short>
<descr>
<var>Destroy</var> disconnects the <var>TCustomSQLStatement</var> instance
from the transaction and database, and then frees the memory taken by the
instance and its properties.
</descr>
<seealso>
<link id="TSQLStatement.Database"/>
<link id="TSQLStatement.Transaction"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLStatement.Prepare">
<short>Prepare the statement for execution</short>
<descr>
<var>Prepare</var> prepares the SQL statement for execution. It is called
automatically if <link id="Execute"/> is called and the statement was not yet
prepared. Depending on the database engine, it will also allocate the necessary 
resources on the database server.
</descr>
<errors>
An exception is raised if there is no <link id="TSQLStatement.SQL">SQL</link> statement set or the
<link id="TSQLStatement.Database">Database</link> or <link id="TSQLStatement.Transaction">Transaction</link> properties are empty.
</errors>
<seealso>
<link id="TSQLStatement.SQL"/>
<link id="TSQLStatement.Database"/>
<link id="TSQLStatement.Transaction"/>
<link id="Execute"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLStatement.Execute">
<short>Execute the SQL statement.</short>
<descr>
<var>Execute</var> executes the <link id="SQL"/> statement on the database.
If necessary, it will first open the connection and start a transaction,
followed by a call to <var>Prepare</var>.
</descr>
<errors>
<p>
An exception is raised if there is no <link id="TSQLStatement.SQL">SQL</link> statement set or the
<link id="TSQLStatement.Database">Database</link> or <link id="TSQLStatement.Transaction">Transaction</link> properties are empty.
</p>
<p>
If an error occurs at the database level (the SQL failed to execute
properly) then an exception is raised as well.
</p>
</errors>
<seealso>
<link id="TSQLStatement.SQL"/>
<link id="TSQLStatement.Database"/> 
<link id="TSQLStatement.Transaction"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TCustomSQLStatement.Unprepare">
<short>Unprepare a previously prepared statement</short>
<descr>
<var>Unprepare</var> unprepares a prepared SQL statement. It is called
automatically when the SQL statement is changed. Depending on the database
engine, it will also de-allocate any allocated resources on the database server.
if the statement is not in a prepared state, nothing happens.
</descr>
<errors>
If an error occurs at the database level (the unprepare operation failed to execute
properly) then an exception is raised.
</errors>
<seealso>
<link id="TSQLStatement.SQL"/>
<link id="TSQLStatement.Database"/>
<link id="TSQLStatement.Transaction"/>
<link id="Prepare"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TCustomSQLStatement.ParamByName">
<short>Find a parameter by name</short>
<descr>
<var>ParamByName</var> finds the parameter <var>AParamName</var> in the
<link id="TSQLStatement.Params">Params</link> property.
</descr>
<errors>
If no parameter with the given name is found, an exception is raised.
</errors>
<seealso>
<link id="TSQLStatement.Params"/>
<link id="TParams.ParamByname"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TCustomSQLStatement.ParamByName.Result">
<short>The parameter with name <var>AParamName</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TCustomSQLStatement.ParamByName.AParamName">
<short>Parameter to search for.</short>
</element>

<!-- function Visibility: public -->
<element name="TCustomSQLStatement.RowsAffected">
<short>Number of rows affected by the SQL statement.</short>
<descr>
<var>RowsAffected</var> is set to the number of affected rows after <link id="Execute"/> was called.
Not all databases may support this.
</descr>
<seealso>
<link id="Execute"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TCustomSQLStatement.RowsAffected.Result">
<short>The number of affected rows by the last executed SQL command.</short>
</element>

<!-- property Visibility: public -->
<element name="TCustomSQLStatement.Prepared">
<short>Is the statement prepared or not</short>
<descr>
<var>Prepared</var> equals <var>True</var> if <link id="Prepare"/> was
called (implicitly or explictly), it returns <var>False</var> if not. 
It can be set to <var>True</var> or <var>False</var> to call <link
id="Prepare"/> or <link id="UnPrepare"/>, respectively.
</descr>
<seealso>
<link id="Prepare"/>
<link id="UnPrepare"/>
</seealso>
</element>

<!--
  ********************************************************************
    #fcl.sqldb.TSQLStatement
  ********************************************************************
-->

<!-- class Visibility: default -->
<element name="TSQLStatement">
<short>Class to execute non-select SQL statements.</short>
<descr>
<var>TSQLStatement</var> is a descendent of <link id="TCustomSQLStatement"/>
which simply publishes the protected properties of that component.
</descr>
<seealso>
<link id="TCustomSQLStatement"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.Database">
<short>Database instance to execute statement on.</short>
<descr>
<var>Database</var> must be set to an instance of a <link id="TSQLConnection"/>
descendent. It must be set, together with <link id="Transaction"/> in order to be able to call <link
id="TCustomSQLStatement.Prepare">Prepare</link> or <link
id="TCustomSQLStatement.Execute">Execute</link>.
</descr>
<seealso>
<link id="Transaction"/> 
<link id="TCustomSQLStatement.Prepare">Prepare</link>
<link id="TCustomSQLStatement.Execute">Execute</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.DataSource">
<short>Datasource to copy parameter values from</short>
<descr>
<var>Datasource</var> can be set to a <link id="#fcl.db.TDatasource"/> instance. 
When <link id="TCustomSQLStatement.Execute">Execute</link> is called, any
unbound parameters remain empty, but if <var>DataSource</var> is set, the
value of these parameters will be searched in the fields of the associated
dataset. If a field with a name equal to the parameter is found, the value
of that field is copied to the parameter. No such field exists, an exception
is raised.
</descr>
<seealso>
<link id="#fcl.db.TDatasource"/>
<link id="TCustomSQLStatement.Execute">Execute</link>
<link id="#fcl.db.TParam.Bound"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.ParamCheck">
<short>Should SQL be checked for parameters</short>
<descr>
<p>
<var>ParamCheck</var> must be set to <var>False</var> to disable the
parameter check. The default value <var>True</var> indicates that the SQL
statement should be checked for parameter names (in the form
<var>:ParamName</var>), and corresponding <link
id="#fcl.db.TParam">TParam</link> instances should be added to the <link
id="Params">Params</link> property.
</p>
<p> 
When executing some DDL statements, e.g. a "create procedure" SQL 
statement can contain parameters. These parameters should not be converted
to <var>TParam</var> instances.
</p>
</descr>
<seealso>
<link id="#fcl.db.TParam">TParam</link>
<link id="Params"/>
<link id="TSQLQuery.ParamCheck"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.Params">
<short>List of parameters.</short>
<descr>
<var>Params</var> contains an item for each of the parameters in the <link id="SQL"/>
statement (in the form <var>:ParamName</var>). The collection is filled
automatically if the <link id="ParamCheck"/> property is <var>True</var>.
</descr>
<seealso>
<link id="SQL"/>
<link id="ParamCheck"/>
<link id="ParseSQL"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.ParseSQL">
<short>Parse the SQL statement</short>
<descr>
<var>ParseSQL</var> can be set to <var>False</var> to disable parsing of the
<link id="SQL"/> property when it is set. The default behaviour
(<var>ParseSQL=True</var>) is to parse the statement
and detect what kind of SQL statement it is.
</descr>
<seealso>
<link id="SQL"/>
<link id="ParamCheck"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.SQL">
<short>The SQL statement to execute</short>
<descr>
<p>
<var>SQL</var> must be set to the SQL statement to execute. It must not be a
statement that returns a result set. This is the statement that will be
passed on to the database engine when <link id="TCustomSQLStatement.Prepare">Prepare</link> is called.
</p>
<p>
If <link id="ParamCheck"/> equals <var>True</var> (the default), the SQL statement can contain 
parameter names where literal values can occur, in the form <var>:ParamName</var>. 
Keywords or table names cannot be specified as parameters.
If the underlying database engine supports it, the parameter support of 
the database will be used to transfer the values from the <link id="Params"/> collection. If not, it will be emulated.
The <var>Params</var> collection is automatically populated when the SQL statement is set.
</p>
<p>
Some databases support executing multiple SQL statements in 1 call.
Therefor, no attempt is done to ensure that <var>SQL</var> contains a single
SQL statement. However, error reporting and the <link
id="TCustomSQLStatement.RowsAffected">RowsAffected</link> function may be
wrong in such a case.
</p>
</descr>
<seealso>
<link id="ParseSQL"/>
<link id="CheckParams"/>
<link id="Params"/>
<link id="TCustomSQLStatement.Prepare">Prepare</link>
<link id="TCustomSQLStatement.RowsAffected">RowsAffected</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLStatement.Transaction">
<short>The transaction in which the SQL statement should be executed.</short>
<descr>
<var>Transaction</var> should be set to a transaction connected to the
instance of the database set in the <link id="Database"/> property. This
must be set before <link id="TCustomSQLStatement.Prepare">Prepare</link> is
called.
</descr>
<seealso>
<link id="Database"/>
<link id="TCustomSQLStatement.Prepare">Prepare</link>
<link id="TSQLTransaction"/>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TSQLQuery.ParamCheck">
<short>Should the SQL statement be checked for parameters</short>
<descr>
<p>
<var>ParamCheck</var> must be set to <var>False</var> to disable the
parameter check. The default value <var>True</var> indicates that the SQL
statement should be checked for parameter names (in the form
<var>:ParamName</var>), and corresponding <link
id="#fcl.db.TParam">TParam</link> instances should be added to the <link
id="Params">Params</link> property.
</p>
<p> 
When executing some DDL statements, e.g. a "create procedure" SQL 
statement can contain parameters. These parameters should not be converted
to <var>TParam</var> instances.
</p>
</descr>
<seealso>
<link id="#fcl.db.TParam">TParam</link>
<link id="Params"/>
<link id="TSQLStatement.ParamCheck"/>
</seealso>
</element>

</module>
    <!-- sqldb -->
  </package>
</fpdoc-descriptions>