Programming Guide



CLOSE

Closes the current database transaction, allowing you to discard or save your changes

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

Arguments

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.

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.

Description

If changes are made in table views on which CLOSE operates after a SELECT, NEW, COPY, or COPY_FOR_UPDATE command, CLOSE displays a dialog box which allows users to discard any changes entered. If the user chooses OK, changes are discarded; choosing Cancel, returns the user to the current screen so changes can be saved. In Web applications, this command is the same as the FORCE_CLOSE command.

CLOSE sets the transaction mode to initial unless a table view is specified. In the default styles file (style.sty), the style assigned to initial mode clears any protections on the widgets.

Push buttons and menu selections for the CLOSE command can choose to set the class property to close_button. By default, close_button is inactive in initial mode but active in all other modes.

For some database engines, such as SYBASE CT-Lib, the CLOSE command does not release the database locks when a SELECT command is not followed by a SAVE command. In this case, follow the CLOSE with the RELEASE command which gives up the locks on the database.

Sequence

The CLOSE command is useful after SELECT, NEW, COPY, or COPY_FOR_UPDATE in order to discard your changes.

Events

Table 8-5 Request events for CLOSE (if there are screen changes)

Request Traversal Typical Processing

TM_PRE_CLOSE

By table/server view from the specified table view

CLOSE or SAVE processing is beginning. (Processing identical for TM_PRE_SAVE)

TM_CLOSE

By table/server view from the specified table view. Traversal ends if TM_VALUE is set to TM_DISCARD_ACTION or TM_EXIT_ACTION.

Appropriate responses are those listed for TM_QUERY below, but typical processing is to do nothing.

TM_QUERY

By table/server view from the specified table view, but restricted to table views, if any, in which there has been a change that would entail a SAVE command. Traversal ends if TM_VALUE is set to TM_DISCARD_ACTION or TM_EXIT_ACTION

A message is chosen according to the value of TM_FULL. If 1, the displayed message is for the complete transaction tree. If 0, the message is for a portion of the tree. sm_message_box, which displays the message, gives a choice of OK and Cancel. TM_DISCARD_ACTION and TM_EXIT_ACTION are the corresponding values passed back to TM_VALUE.

TM_DISCARD

By table/server view from the specified table view

Set a discard flag, consulted by TM_POST_SAVE1

TM_POST_CLOSE

By table/server view from the specified table view

Generates slice events: TM_POST_CLOSE, TM_POST_SAVE1, TM_POST_SAVE2 (described under SAVE, but no save cursor exists.

The TM_CLOSE and TM_QUERY requests have four possible return values: TM_NO_ACTION, TM_DISCARD_ACTION, TM_SAVE_ACTION, and TM_EXIT_ACTION. The distributed transaction models use two of these return values:

If TM_SAVE_ACTION is used as a return value, all the requests associated with the SAVE command (except TM_PRE_SAVE and TM_POST_SAVE) are completed, but this processing is not used in the distributed transaction models.

Table 8-6 Slice event processing for CLOSE

Slices Typical Processing

TM_POST_CLOSE

Processing is identical to that of TM_POST_SAVE described under SAVE.

TM_POST_SAVE1

Described under SAVE, but no save cursor exists.

TM_POST_SAVE2

Described under SAVE.