Application Development

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:

• How to specify transaction manager commands.

• How to apply a transaction manager command to a portion of the transaction tree.

• How to change transaction modes using the commands.

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.

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):

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:

• TV_AND_BELOW—Applies the command to the specified table view and all server views below it in the tree. This is the default setting if no tableViewScope parameter is supplied.

• BELOW_TV—Applies the command to the server views below the specified table view.

• TV_ONLY—Applies the command to the specified table view only.

• SV_ONLY—Applies the command to the specified server view only.

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")

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-3 shows which transaction manager commands are available in each mode.