All opened
databases and recordsets are referenced by a so called "handle";
when you open a database you specify the handle, which is a string
by which you can later reference the database and it's recordset
(which contains the actual data).
This means
a handle is both a reference to an open database and to the recordset
which is linked to the database and contains the result of the
query. The "CloseHandle" command will close the database
referenced by "handle" as well as the associated recordset.
Example:
Use the OpenDatabase command to open an MS-Access database and
specify handle "DBTEST". When the Daemon executes the
"OpenDatabase"
command it will open the specified database and create an empty
recordset. As long as the database is open, you can now reference
the database and the recordset by the handle "DBTEST".
To query the database use the "QueryDatabase"
command and specify handle "DBTEST". When the "QueryDatabase"
command is executed, the handle "DBTEST" will be used
to execute the query on the referenced database and the query-result
will be put in a recordset which is also reference by handle "DBTEST".
NOTE: Running queries which don't return any data will leave the
recordset empty.
There are
now several ways you can retrieve and use the result of the query;
you can use the "rsOuput2...." commands to output the
complete recordset to a text file, excel file, word file or to
another (or the same) database. Or you can use the internal
variables to reference individual records or columns of the
current record of the recordset. You can use the "rsMove..."
commands to move the pointer in the recordset.
Apart from
the database plugins, other plugins can also make use of "handles"
to store data in a recordset. The "ReadEventLog"
plugin for example stores it's data in a recordset. In that case
the handle only references a recordset and not an open database.