| Programming Guide | |
Executes a transaction command
#include <tmusubs.h>int sm_tm_command (cmd_string);
STATUSof the current transaction.
sm_tm_commandexecutes the specified transaction manager command.When specifying a command, the table view name is case sensitive; however, the command name and the optional parameters following the table view name are not case sensitive.
By definition, a command is in progress from the moment
sm_tm_commandis called until the moment it returns. As it processes most commands,sm_tm_commandinvokes transaction event functions and transaction models. These, in turn, should not invoke transaction manager commands, because the transaction manager cannot process its commands recursively. This implies that they should not close the active screen (which triggers aFINISHcommand), or cause any other screen to be displayed that contains table views (which triggers aCHANGEcommand).
After recognizing a transaction command, the transaction manager either sets the transaction mode or checks the transaction mode to see if the specified command is available with the current mode. If the command is not supported in the current mode, or if the command is not recognized, then the transaction manager displays an error message that the mode does not permit the specified command. It also sets the value of
TM_STATUSto -1, which causessm_tm_commandto return a value of -1. For more information on command availability in transaction modes, refer to "Setting the Transaction Mode" in Application Development Guide.
The transaction tree is the group of linked table views that are part of the current transaction manager transaction. After a command is issued, the transaction manager traverses the transaction tree, issuing the request and slice events defined for that command for each table view and performing the processing defined for each event in transaction event functions and transaction models. The most common order is referred to as table/server view order. A server view is defined as:
- A single table view having no server links to other table views.
A transaction manager transaction must be in progress in order to call commands. Transactions are created with the
STARTcommand which is called automatically on screen entry. However, the Panther events that occur on screen entry call the unnamed JPL procedure before calling theSTARTcommand. Therefore, transaction manager commands cannot be invoked in the unnamed procedure.
int sm_tm_command ("SELECT titles BELOW_TV");
Errors in the transaction manager set
TM_STATUSto-1.In addition, there are return values for transaction models or transaction event functions that set the value of
TM_STATUS. Table 8-2 lists the return codes, the events that get generated for each return code, and the processing that occurs for the event.
Once you select a transaction command, the transaction manager generates the transaction events defined for that command. These events are defined to perform the processing needed for the command. The major events for each command are called requests. Some requests are further subdivided into more events, called slices. As the transaction manager traverses the tree, it looks for the processing for each event first in a transaction manager event function, then in an engine-specific transaction model, and then in the common transaction model.
The transaction manager has an event stack, onto which the transaction events are pushed. As the events are processed, they are popped from the stack. For more information on the event stack, refer to Chapter 35, "Generating Transaction Manager Events," in Application Development Guide.
Table 8-3 lists all the transaction manager events. A description of the general processing performed by each request or slice is part of the documentation for a command in which it is used. To see the processing done for a particular database engine, refer to the transaction model for that engine. For a summary list of the commands, requests, and slices, refer to Chapter 9, "Transaction Model Events."