2.9. hk_datasource

hk_datasource is the basic class which represents a resultquery or a table of a database. Never create this table directly. Use the hk_database.new_table() method instead.

Inherits from hk_data.

Two types of this class can be distinguished. Tables and resultqueries.

Resultqueries are queries with a SELECT - SQL-statement. The resulting data is readonly.

Tables are a special form of resultqueries. The SQL-statement is fixed ("SELECT * FROM <tablename>), but the resulting dataset can be edited. To reduce the number of rows you can use the function set_filter() and set_temporaryfilter(). To order the rows use the functions set_sorting() and set_temporarysorting().

A datasource manages hk_column objects, which allows you to modify the data of the datasource. See function column_by_name() for more information.

The datasource can be enabled with enable() and disabled by calling disable().


Figure 2-5. hk_datasource methods

name()

returns the name of the datasource

goto_row(rownumber)

moves the row selector (row cursor) to 'rownumber'

goto_first()

move the row selector to the first row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.

goto_last()

move the row selector to the last row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.

goto_next()

move the row selector to the next row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.

goto_previous()

move the row selector to the previous row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.

row_position()

returns the row number of the current row

max_rows()

returns the total number of existing rows

enable()

If hk_connection is connected, this method will enable the datasource. The SQL-Statement in @ref SQL will be executed. If the SQL-statement is ok, the resulting data can be reached via the columns returned by columns(). You can browse the data by using the methods goto_row(), goto_first(), goto_last(), goto_next() and goto_previous(). returns True if enable() was successful.

disable()

if the datasource is enabled, this function will disable it. The columnlist will be deleted.

set_enabled(e)

convenience function: if e is true the datasource will be enabled by calling enable() else it will disable the datasource by calling disable().

is_enabled()

returns True if the datasource is enabled.

column_by_name(name)

returns an hk_column object of the column with the name 'name'

store_changed_data()

if the data of the actual row has changed you can manually send the changes to the SQL Server by calling this function. The function will be called automatically before the datasource disables or the row selector will be moved to another row.

database()

returns the hk_database object, to which this datasource belongs

set_filter(filter[,registerchange])

It is possible to filter only specific rows from a datasource by setting this filter. just add the conditions with this function. The parameter 'filter has the same syntax as a SQL statement in the 'WHERE' section, but without the word 'WHERE'

The parameter 'registerchange' : if this class is part of a hk_presentation object (i.e. a form or a report) and registerchange is True, then the changes will be stored when the hk_presentation object is closed.

Example: SELECT * from addresses WHERE city="München", so you would call set_filter("city=\"München\"");

filter()

returns the filter string set with set_filter()

set_temporaryfilter(temporaryfilter)

a temporary filter just work like a normal filter (see set_filter() ), but have to be manually activated with set_use_temporaryfilter(). When the datasource is loaded with loaddata() temporaryfilters are deactivated by default.

temporaryfilter()

returns the temporary filter string

set_use_temporaryfilter(use)

If 'use' is set to True the temporary filter is used, else it it is not used. Attention: this will be only used next time when the datasource will be enabled. If the datasource is already enabled, first disable() the datasource and then enable() it again.

use_temporaryfilter()

returns True if the temporary filter is used, else False is returned

clear_filter([registerchange])

deletes the filter, which was set with set_filter()

set_sorting(order[,registerchange])

It is possible to sort the datasource. Just add the conditions with this function. 'order' has the same syntax as a SQL statement in the "ORDER BY" section, but without the words "ORDER BY".

'registerchange': if this class is part of a hk_presentation object (i.e. a form or a report) and registerchange is true, then the changes will be stored when the hk_presentation object is closed.

Example: SELECT * from addresses ORDER BY city DESC , so you would call set_sorting("city DESC");

sorting()

returns the sorting string set with set_sorting()

set_temporarysorting(temporarysorting)

temporary sorting just works like normal sorting (see set_sorting() ), but has to be manually activated with set_use_temporarysorting().

temporarysorting()

returns the temporary sorting string set with set_temporarystring()

set_use_temporarysorting(use)

If 'use' is set to True the temporary sorting string is used, else it it is not used. Attention: this will be only used next time when the datasource will be enabled. If the datasource is already enabled, first disable() the datasource and then enable() it again.

use_temporarysorting()

returns True if the temporary sorting string is used, else False is returned

clear_sorting([registerchange])

deletes the sorting order, which was set with set_order()

datasource_used()

returns True if a hk_visible object or a depending datasource is using this datasource, else returns False


The following example shows how to move between rows in a datasource. For this, create a button in the form and set a datasource. Add the script to the "On click"-action.

Example 2-6. rowposition

   1 ds=hk_this.datasource()
   2 ds.goto_row(ds.row_position() + 2)

How to get a specific hk_column object can be seen in the following example. For what you can do with this object, please see the next chapter.

Example 2-7. find a specific column

   1 col=hk_this.datasource().column_by_name("author")