sm_bi_initialize

Programming Guide

Initializes before-image data for widgets in the current table view
#include <tmusubs.h>
int sm_bi_initialize(void);

Returns

· 0: Success. Before-image successfully initialized for the table view or the table view has the updatable property (under Transaction) set to PV_NO.

· DM_TM_ERR_TBLNAME: Table view did not have table property set.

· DM_TM_ERR_PRIMARY_KEY: Table view did not have a primary_key property set.

· DM_TM_ERR_COL_NOT_FOUND: Widget not found for primary key column.

· DM_TM_ERR_MALLOC: Memory allocation error.

· DM_TM_ERR_GENERAL: No transaction or table view is available.

Description

sm_bi_initialize initializes or reinitializes before-image data for the widgets in the current table view. Before-image describes the state of transaction data before the user or program changes it.
The transaction commands NEW and SELECT call sm_bi_initialize. For the NEW command, the before-image for the table view is empty. For the SELECT command, a before-image is defined for each row in the select set.
To initialize the before-image structures, the function first examines the properties of the current table view and the table view's members. It builds the table view's insert list and update list and it verifies that the current table view can participate in the before-image. If a table view has the updatable property set to PV_YES, it must also have values in the table and primary_key properties (under Database).
If the Table and Primary Key properties are not set, sm_bi_initialize returns an error. Furthermore, sm_bi_initialize verifies that a widget exists for each column named by the table view's primary_key property. If the widget does not exist in the current table view, the transaction manager looks for a link that names the current table view as a child. The criteria is satisfied if the primary key column is named in the relations property of the link and that property points to an onscreen widget, a literal, or to a widget in the link's parent table view (or the parent of the server view). Otherwise, sm_bi_initialize returns an error.
The standard transaction models call sm_bi_initialize as part of the processing for the TM_POST_SAVE request. If an application has saved data while in new or update mode, the models call sm_bi_initialize after the save completes. This allows the application to use the current screen data as the starting point for the next save.
For example, assume the application executes sm_tm_command("NEW") to enter new customer data. The user enters the data and the application executes sm_tm_command("SAVE"). If the save is successful (e.g., it generates and executes a SQL INSERT statement), the standard model calls sm_bi_initialize before returning control to Panther. To enter the customer's spouse, the user can change the appropriate fields and call sm_tm_command("SAVE") again. This is also equivalent to calling sm_tm_command("COPY") after a SAVE.
Similarly, for the SELECT command, the use of sm_bi_initialize in the standard models allows the application to continue updating the screen data after a save. If customer data is fetched with sm_tm_command("SELECT") and the user changes the customer's phone number and calls sm_tm_command("SAVE"), the model performs save processing (e.g., generates and executes a SQL UPDATE statement) and, by default, calls sm_bi_initialize. The user can continue updating the onscreen data without re-selecting it. If the user enters a comment and calls sm_tm_command("SAVE") again, the transaction manager performs save processing for all changes since the last call to sm_bi_initialize. Therefore, it might generate and execute a SQL UPDATE statement for the comment; it does not repeat save processing for the earlier phone number change.
This function operates on the current table view. It is intended to be called from a transaction model or event function.