Jam.py documentation

Modifying datasets

When an application opens an item dataset, the dataset automatically enters browse state. Browsing enables you to view records in a dataset, but you cannot edit records or insert new records. You mainly use browse state to scroll from record to record in a dataset.

For more information about scrolling from record to record, see Navigating datasets.

From browse state all other dataset states can be set. For example, calling the insert or append methods changes its state from browse to insert.

Two methods can return a dataset to browse state. Cancel ends the current edit, insert, and returns a dataset to browse state. Post writes changes to the dataset, and if successful, also returns a dataset to browse state. If this operations fail, the current state remains unchanged.

To check an item dataset state use item_state attribute or is_new is_edited or is_changing methods:

Client	Server	Description
item_state	item_state	Indicates the current operating state of the item dataset.
is_new	is_new	Returns true if the item dataset is in insert state.
is_edited	is_edited	Returns true if the item dataset is in edit state.
is_changing	is_changing	Returns true if the item dataset is in insert or edit state.

You can use the following item methods to insert, update, and delete data in dataset:

Client	Server	Description
edit	edit	Puts the item dataset into edit state.
append	append	Appends a record to the end of the dataset, and puts the dataset in insert state.
insert	insert	Inserts a record at the beginning of the dataset, and puts the dataset in insert state.
post	post	Saves the new or altered record, and puts the dataset in browse state.
cancel	cancel	Cancels the current operation and puts the dataset in browse state.
delete	delete	Deletes the current record and puts the dataset in browse state.

All changes made to the dataset are stored in memory, the item records changes to change log. Thus, after all the changes have been made, they can be stored in the associated database table by calling the apply method. The apply method generates and executes SQL query to save changes to the database.

Client	Server	Description
log_changes	log_changes	Indicates whether to log data changes.
apply	apply	Sends all updated, inserted, and deleted records from the item dataset to the server for writing to the database.