Application Development


Chapter 34 . Specifying Transaction Manager Commands

The transaction manager is controlled by a set of high-level instructions, referred to as transaction manager commands, that are called from the application's event functions. After a command is invoked, the transaction manager traverses the table views involved in your application, doing the appropriate processing at each table view it reaches.

This chapter describes:


Transaction Manger Commands

Transaction manger commands (listed in Table 34-1) are used in JPL procedures and C functions (automatically provided by the screen wizard) and are invoked from your application's event functions to execute different types of database operations. For example, there is a command that selects data from the database and a command that clears data from the screen. When a user of your application chooses a command, for instance, via a push button, the transaction manager executes the transaction events associated with the command.

While developing your application with the screen editor, you can access a subset of transaction manager commands via the Transaction menu available in test mode.

A transaction manager transaction must be in progress in order to call a command. A transaction is automatically started on screen entry at which time the transaction manager also verifies that a transaction tree can be built.

Refer to "Screen Entry" for a list of events that occur when a screen is opened.

Warning: A transaction manager command cannot be called in the screen's unnamed JPL procedure. The transaction manager has not yet been initialized. However, a command can be called as part of a screen entry procedure.

Table 34-1 Transaction manager commands and the associated transaction mode change

Command Description Mode change

CHANGE

Change to another transaction.

CLEAR

Clear the data from the screen.

CLOSE

Abort the current processing.

initial

CONTINUE

Fetch the next group of selected rows (two-tier only).

CONTINUE_BOTTOM

Fetch the last set of rows using a continuation file (two-tier only).

CONTINUE_DOWN

Fetch the group set of rows using a continuation file (two-tier only).

CONTINUE_TOP

Fetch the first set of rows using a continuation file (two-tier only).

CONTINUE_UP

Fetch the previous set of rows using a continuation file (two-tier only).

COPY

Copy the data currently on the screen, allowing the user to change it in order to enter a new row.

new

COPY_FOR_UPDATE

Change the transaction mode to update, allowing the user to change the data currently on the screen.

update

COPY_FOR_VIEW

Change the transaction mode to view so the data is for viewing purposes only.

view

FETCH

Retrieve one or more rows for a single table view (not recommended).

FINISH

End the current transaction.

FORCE_CLOSE

Abort the current processing.

NEW

Clear the screen so that the user can enter new data.

new

REFRESH

Reapply the styles and classes to the screen.

RELEASE

Release transaction manager cursors.

SAVE

Update the database with the new or edited information.

SELECT

Retrieve one or more rows from the database for possible updates.

update

START

Start a new transaction.

initial

VIEW

Retrieve one or more rows from the database for viewing purposes only.

view

WALK_DELETE

Traverse the transaction tree using the order specified in the Delete Order property.

WALK_INSERT

Traverse the transaction tree using the order specified in the Insert Order property.

WALK_SELECT

Traverse the transaction tree by server view.

WALK_UPDATE

Traverse the transaction tree in using the order specified in the Update Order property.

Command Syntax

Transaction manager commands are called using the function sm_tm_command. The syntax for sm_tm_command varies slightly depending upon the command being called. Common syntax is:

sm_tm_command ("commandName [ tableView [ tableViewScope ] ]")

commandName—one of the following (other commands, not included here, use a slightly different syntax):

CLEAR

CONTINUE_UP

VIEW

CLOSE

COPY

WALK_DELETE

CONTINUE

FORCE_CLOSE

WALK_INSERT

CONTINUE_BOTTOM

NEW

WALK_SELECT

CONTINUE_DOWN

SAVE

WALK_UPDATE

CONTINUE_TOP

SELECT

Refer to page 8-3 in the Programming Guide for syntax and detailed information on all of the transaction manager commands.

tableView (optional)—Name of a table view on the screen; it must be the first table view in a server view.

tableViewScope (optional)—Generally one of the following values:

Limiting the Number of Table Views

Most transaction manager commands let you to limit the scope of the transaction by specifying a table view or server view from which to begin the traversal. In this case, the portion of the transaction tree over which the command operates begins with the specified table or server view, rather than the default. If a table view is specified, it must be the first table view in a server view.

Consider the transaction tree in Figure 34-1, the command:

sm_tm_command("VIEW tapes")

limits the VIEW operation to the table view tapes and any other table views below it in the transaction tree, in this case, titles and pricecats.

Figure 34-1 Limit the scope of a transaction by identifying the table view in the transaction tree.

Refer to page 31-10 to learn more about how transaction trees are used during event generation.

Implementing Full and Partial Commands

The transaction models use the concept of full and partial commands to determine how to process certain commands. A full command is applied to all table views on the screen and is issued with a single argument, the commandName. For example:

sm_tm_command("VIEW")

In this case, the variable TM_FULL is set to 1.

A partial command is applied to a limited number of table views and is issued by a command statement that includes a table view or server view parameter. For example:

sm_tm_command("VIEW roles TV_ONLY")

In this case, TM_FULL is set to 0.

In the transaction tree (in Figure 34-1), the following two commands would be equivalent since the partial command specifies the root table view:

sm_tm_command("VIEW")
sm_tm_command("VIEW rentals")

In this case, TM_FULL is set to 1 for the full command and to 0 for the partial (second) command.

All models use the variable TM_FULL to determine when to fully commit a save operation (in two-tier only). Some models use TM_FULL to determine the transaction mode after a SAVE command.

You can query for the current value of TM_FULL using sm_tm_inquire.

When executing partial SELECT and VIEW commands (and related FETCH and CONTINUE commands), specify the first table view of the server view as the table view. Otherwise, testing for the parent table view is performed on the first table of the server view instead of on a table view at a higher level.


Setting the Transaction Mode

When a transaction manager command is executed, the transaction mode for the screen is also defined. The transaction mode defines the protection settings and display attributes of widgets on the screen. For more information about transaction modes and how they give visual and application behavioral cues to users of your application, refer to page 31-14

Table 34-2 lists the transaction modes set by the transaction manager and the commands that initiate those modes.

Table 34-2 Transaction modes and the commands that initiate them

Mode Description Command selection

initial

Indicates that no processing is in progress.

START, CLOSE and FORCE_CLOSE

new

Allows new data to be entered.

NEW and COPY

update

Allows existing data to be modified.

SELECT and COPY_FOR_UPDATE

view

Allows existing data to be displayed.

VIEW and COPY_FOR_VIEW

Table 34-3 shows which transaction manager commands are available in each mode.

Table 34-3 Transaction manager commands available for each transaction mode

Command Initial New Update View

CHANGE

Y

Y

Y

Y

CLEAR

Y

Y

Y

Y

CLOSE

Y

Y

Y

Y

CONTINUE

N

P

Y

Y

CONTINUE_BOTTOM

N

P

Y

Y

CONTINUE_DOWN

N

P

Y

Y

CONTINUE_TOP

N

P

Y

Y

CONTINUE_UP

N

P

Y

Y

COPY

Y

Y

Y

Y

COPY_FOR_UPDATE

F

F

F

F

COPY_FOR_VIEW

F

F

F

F

FETCH

N

N

Y

Y

FINISH

Y

Y

Y

Y

FORCE_CLOSE

Y

Y

Y

Y

NEW

F

Y

F

F

REFRESH

Y

Y

Y

Y

RELEASE

Y

Y

Y

Y

SAVE

N

Y

Y

N

SELECT

Y

Y

Y

Y

START

Y

Y

Y

Y

VIEW

Y

Y

Y

Y

WALK_DELETE

Y

Y

Y

Y

WALK_INSERT

Y

Y

Y

Y

WALK_SELECT

Y

Y

Y

Y

WALK_UPDATE

Y

Y

Y

Y

Y=Available; N=Not available; F=Valid for full commands only; P=Valid for partial commands only.