Programming Guide

Saves the changes made on the screen to the database

int sm_tm_command ("SAVE [ tableViewName [ tableViewScope ] ]");

tableViewName

The name of a table view in the current transaction. This parameter is case sensitive.

If tableViewName is specified, the command is applied according to the tableViewScope parameter. Since the entire table view tree might not be included, this is known as a partial command, and sm_tm_command sets TM_FULL to 0. Refer to the description for more information about partial commands.

If tableViewName is not specified, the command is applied for each table/server view, starting with the root table view. This is known as a full command, and sm_tm_command sets TM_FULL to 1.

tableViewScope

One of the following parameters, which must be preceded by a table view name.

• TV_AND_BELOW which applies the command to the specified table view and all table views below it on the tree. If no parameter is specified, the transaction manager acts as though TV_AND_BELOW was supplied.

• BELOW_TV which applies the command to the table views below the specified table view.

• TV_ONLY which applies the command to the specified table view only.

• SV_ONLY which applies the command only to the table views of the specified server view.

SAVE compares the current screen to the before image data and generates the necessary statements needed to update the database.

After you select SAVE, the following steps occur:

1. The transaction manager checks to see that the mode is not initial or view.
2. For engines requiring it, the transaction model starts a database transaction.
3. The transaction model calls the SQL generator to execute the necessary statements according to the changes that were entered on the screen. Statements can only be generated for updatable table views.

   Note: Some database engines discard the select set when a commit or rollback is performed. For those engines, the distributed transaction models give up the select cursor after a commit or rollback.

4. If an error is encountered, the database transaction is rolled back. If no errors are reported and the SAVE command has been specified as a full command, the transaction model commits the database transaction.

Push buttons and menu selections for the SAVE command can choose to set the class property to save_button. By default, save_button is active in new and update modes.

The transaction manager is aware of any primary key changes. If the primary key is updated, the common transaction model deletes the row containing the old value of the primary key and inserts a row contains the new value of the primary key. If the primary key is cleared, the common transaction model deletes the row corresponding to the cleared key fields.

When a table view is specified for a command, the transaction manager considers it to be a partial command since the command may not apply to the entire tree. In the standard transaction models, the processing for partial SAVE commands does not commit the database transaction. Therefore, you must perform an explicit DBMS COMMIT. Otherwise, the changes could be rolled back if a later rollback is performed or if the database engine automatically performs a rollback when the connection is closed.

The following request events can be generated by the SAVE command:

• TM_PRE_SAVE

• TM_SAVE

• TM_DELETE

• TM_UPDATE

• TM_INSERT

• TM_SAVE_ENDING

• TM_POST_SAVE

  Table 8-28 Request events for SAVE

  Request	Traversal	Typical Processing
  TM_PRE_SAVE	By table/server view from the specified table view	Note that SAVE/CLOSE processing is beginning. (Processing is identical for TM_PRE_CLOSE.) close_or_save_started flag is set to 1, discard flag is set to 0, and reuse_cursor flag is set to 0.
  TM_SAVE	By table/server view from the specified table view	Do nothing
  TM_DELETE	Modify table views in the order specified in the link properties, with one request in each table view for each row in that table view that has changed	Slices: TM_DELETE, TM_GET_SAVE_CURSOR, TM_DELETE_DECLARE, TM_DELETE_EXEC
  TM_UPDATE	Modify table views in the order specified in the link properties, with one request in each table view for each row in that table view that has changed	Slices: TM_UPDATE, TM_GET_SAVE_CURSOR, TM_UPDATE_DECLARE, TM_UPDATE_EXEC
  TM_INSERT	Modify table views in the order specified in the link properties, with one request in each table view for each row in that table view that has changed	Slices: TM_INSERT, TM_GET_SAVE_CURSOR, TM_INSERT_DECLARE, TM_INSERT_EXEC
  TM_SAVE_ENDING	By table/server view from the specified table view	Call sm_tm_handling to invoke an appropriate function.
  TM_POST_SAVE	By table/server view from the specified table view	Slices: TM_POST_SAVE, TM_POST_SAVE1, TM_GIVE_UP_SAVE_CURSOR, TM_POST_SAVE2

  Table 8-29 Slice event processing for SAVE

  Slices	Typical Processing
  TM_DELETE	Find out what type of change was made to the current occurrence by checking the return code from sm_bi_compare. If the return code is BI_KEY_CHANGED, BI_KEY_NULLED, or BI_DELETED, push the TM_GET_SAVE_CURSOR, TM_DELETE_DECLARE and TM_DELETE_EXEC events onto the stack.
  TM_GET_SAVE_CURSOR	If a name does not exist for the save cursor, generate it. For some engines, push the TM_SAVE_BEGIN event onto the stack.
  TM_SAVE_BEGIN	For some engines, start a database transaction with DBMS BEGIN or a savepoint with DBMS SAVE.
  TM_DELETE_DECLARE	For some engines, give up any select cursor relating to this table view. Call dm_exec_sql to declare the save cursor for this deletion, unless the occurrence is part of an array and previously generated SQL is being reused.
  TM_DELETE_EXEC	Call dm_exec_sql to execute the save cursor for this deletion. The return value is TM_CHECK_ONE_ROW which tests that only one row was deleted.
  TM_UPDATE	Find out what type of change was made to the current occurrence by checking the return code from sm_bi_compare. If the return code is BI_UPDATED, push the TM_GET_SAVE_CURSOR, TM_UPDATE_DECLARE and TM_UPDATE_EXEC events onto the stack.
  TM_UPDATE_DECLARE	For some engines, give up any select cursor relating to this table view. Call dm_exec_sql to declare the save cursor for this update, unless the occurrence is part of an array and previously generated SQL is being reused.
  TM_UPDATE_EXEC	Call dm_exec_sql to execute the save cursor for this update. The return value is TM_CHECK_ONE_ROW which tests that only one row was updated.
  TM_INSERT	Find out what type of change was made to the current occurrence by checking the return code from sm_bi_compare. If the return code is BI_KEY_CHANGED or BI_INSERTED, push the TM_GET_SAVE_CURSOR, TM_INSERT_DECLARE and TM_INSERT_EXEC events on the stack.
  TM_INSERT_DECLARE	For some engines, give up any select cursor relating to this table view. Call dm_exec_sql to declare the cursor for this insertion, unless the occurrence is part of an array and previously generated SQL is being reused.
  TM_INSERT_EXEC	Call dm_exec_sql to execute the save cursor for this insertion. The return value is TM_CHECK_ONE_ROW which tests that only one row was inserted.
  TM_POST_SAVE	If this is the first TM_POST_SAVE event since the last TM_PRE_CLOSE or TM_PRE_SAVE, push the TM_POST_SAVE1 event on the stack. Otherwise, if TM_DISCARD or TM_POST_SAVE1 set the saving worked flag, push the TM_POST_SAVE2 event on the stack.
  TM_POST_SAVE1	The existence of a save cursor indicates that SQL statements were executed so the saving worked flag is set to 1. If there is a save cursor and if TM_STATUS is equal to 0 (indicating that the statements executed successfully) and if TM_FULL is equal to 1 (indicating a full SAVE command), the TM_SAVE_COMMIT event is pushed onto the stack. If there is a save cursor and if TM_STATUS is non-zero (indicating that the statements failed), the TM_SAVE_ROLLBACK is pushed onto the stack. For rollbacks, the saving worked flag is reset to 0 since no changes were actually made.
  TM_SAVE_ROLLBACK	Push the TM_SAVE_SET_MODE event onto the stack. Do a DBMS ROLLBACK.
  TM_SAVE_COMMIT	For full SAVE commands (when TM_FULL is set to 1), do a DBMS COMMIT. If it fails, push the TM_SAVE_ROLLBACK event onto the stack. If it succeeds, push the TM_SAVE_SET_MODE event onto the stack. If the saving worked flag is set to 1, push the TM_GIVE_UP_SAVE_CURSOR and TM_POST_SAVE2 events on the stack and set the discard flag.
  TM_SAVE_SET_MODE	Some engine-specific models set TM_VALUE to TM_INITIAL_MODE to indicate that processing should resume in initial mode. (These engines discard the select set when commits and roll backs are performed.)
  TM_GIVE_UP_SAVE_CURSOR	Give up the save cursor.
  TM_POST_SAVE2	Call sm_bi_initialize. Set TM_OCC to 1 and TM_OCC_COUNT to -1; then, call sm_bi_copy.

---

---