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.
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.
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;