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 data methods

set_name(n)

sets the name of the datasource

name()

returns the name of the datasource

set_sql(statement [,rawsql [,registerchange]])

set your own SQL statement, that will be executed when you enable the datasource. If this datasource is of type "table" the SQL statement will be automatically created. Parameters:

's' is the sql statement, 'rawsql': if true the sql statement will used unmodified (otherwise it may be changed,e.g identifier delimiters, text delimiters etc. ), '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. sorting, filtering or depending on statements). So it is possible to execute driver specific Returns true, if it is a valid SQL-Select statement and false if it is a query which does not contain the "SELECT" statement, i.e. SHOW FIELDS in Mysql.

sql()

returns the name of the datasource

backendsql()

returns the SQL statement as it is sent to the SQL server

is_rawsql()

returns true if the SQL statement is used unmodified

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

datasource_used()

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

setmode_insertrow()

brings the datasource in insertmode. To add a new row call this function, set the data of the new row as usual in the columns (i.e.with hk_column::as_string ) and finally call either setmode_normal or store_changed_data.

setmode_normal()

This is the usual mode, where you can browse the data and if the data is not readonly change the data.

is_readonly()

Returns True if the datasource is read-only. If data can be written this function returns False.

set_readonly(r)

If the datasource is of type ds_table you can allow or disallow data changes.

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

ds=hk_this.datasource()
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

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

Figure 2.6. hk_datasource filter and sorting methods

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="Mnchen", so you would call set_filter("city=\"Mnchen\"");

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()

Figure 2.7. hk_datasource structure definition methods

setmode_createtable

If you want to create a new table first bring the table in createmode. Define new columns with new_column. Afterwards you can create the table by calling create_table_now

setmode_altertable

If you want to alter an existing table first bring the table in altermode. Define new columns with new_column. Alter it with alter_column and delete a column by calling alter_column. Afterwards you can alter the table by calling @ref alter_table_now

new_column

if this datasource is of type "table" and in mode "create" or "alter" you can create a new column to define its parameters.

alter_column(col [, name=NULL [,hk_column::enum_columntype* newtype=NULL [,long* size=NULL [,const hk_string* defaultvalue=NULL [,const bool* primary=NULL, [const bool* notnull=NULL ]]]]]])

if this datasource is of type "table" and in mode "alter" you can alter an existing column. NULL values mean, that this part will not be changed

delete_column(col)

if this datasource is of type "table" and in mode "alter" you can delete an existing column.Just enter the name here.

create_table_now(void);

After defining a new table with setmode_createtable and new_column this function creates physically the table

alter_table_now()

After altering an existing table with setmode_altertable, new_column ,alter_column and delete_column this function alters physically the table

mode()

returns the mode in which the datasource is. Valid values are:{mode_normal,mode_createtable,mode_altertable,mode_disabled,mode_insertrow,mode_deleterow,mode_unknown}

To create a table, first get a new table object, set a name and set the mode to "createtable".

After that you can define new columns. First create it with new_column() and then set the type, name etc. When finished, create the table with create_table_now().

Example 2.8. create table

>>> table = db.new_table()
>>> table.set_name("my new table")
>>> table.setmode_createtable()
>>> col=table.new_column()
>>> col.set_columntype(hk_column.auto_inccolumn)
>>> col.set_name("id")
>>> col=table.new_column()
>>> col.set_name("name")
>>> table.create_table_now()
CREATE TABLE `my new table` ( `id` BIGINT(1) NOT NULL AUTO_INCREMENT ,
 BIGINT, PRIMARY KEY ( `id` ) )
Table created
1

Figure 2.8. hk_datasource Index definition methods

create_index(name [,unique [, list<hk_string>& fields]])

Creates an index of a table. returns true if successful otherwise false. Make sure you have set the tablename first. 'name' is the name of the new index, if 'unique' the index will be a unique index, and finally 'fields' is a string list of the field names, this index uses. Function returns True if successful otherwise False;

alter_index(name [,unique [,list<hk_string>& fields]])

Alters an existing index by first dropping it with drop_index() and then by trying to recreate it with create_index().

drop_index(name)

Deletes an index of a table. Returns true if successful otherwise false;