=======
Dataset
=======

Jam.py framework uses a dataset concept that is very close to 
datasets of `Embarcadero Delphi`_.

.. _Embarcadero Delphi: https://en.wikipedia.org/wiki/Delphi_(programming_language)

.. note::

    There are other ways to read and modify the database data. You can use the
    :doc:`connect </refs/server/task/m_connect>` 
    method of the task to get a connection from the connection pool and use 
    the connection to get access to the database using Python Database API.
    

All items with ``item_type`` "item" or "table" as well as their details (see
:doc:`Task tree </programming/task_tree>`)
can access data from associated tables from the project database and write 
changes to it. They all are objects of 
the Item class

* :doc:`Item class </refs/client/item_api>` (on the client)
* :doc:`Item class </refs/server/item_api>` (on the server)

Both of these classes have the same attributes, methods, and events associated 
with the data handling.

To get a dataset (a set of records) from the project dataset table, use the open
method. This method, based on parameters, generates an SQL query to get a 
dataset.

After dataset is opened, the application can navigate it, change its records or 
insert new ones and write changes to the item's database table.

For example, the following functions will set *support_rep_id* field values to
the values of the *id* field on the client and server respectively:

.. code-block:: js

    function set_support_id(customers) {
        customers.open();
        while (!customers.eof()) {
            customers.edit();
            customers.support_rep_id.value = customers.id.value;
            customers.post();
            customers.next();
        }
        customers.apply();
    }
    
.. code-block:: py

    def set_support_id(customers):
        customers.open()
        while not customers.eof():
            customers.edit()
            customers.support_rep_id.value = customers.id.value
            customers.post()
            customers.next()
        customers.apply();

These functions get the **customers** item as a parameter. Then the *open* 
method is used to get a list of records from the customers table and each 
record is modified. In the end the changes are saved in the database table, using
the apply method (see
:doc:`Modifying datasets <modifying_datasets>`
).

.. note::

    There is a shorter way to navigate a dataset (see 
    :doc:`Navigating datasets <navigating_datasets>`
    ). For example, in python, the following loops are equivalent:
    
    .. code-block:: py
    
        while not customers.eof():
            print customers.firstname.value
            customers.next()
        
        for c in customers:
            print c.firstname.value
        
Videos
======

`Datasets`_ and `Datasets Part 2`_ demonstrate almost all methods of working with 
datasets on specific examples

.. _`Datasets`: https://youtu.be/gHTYj7h9ljI
.. _`Datasets Part 2`: https://youtu.be/1bUGmgBfrNw