lr_start_sub_transaction

Starts a sub-transaction specified by its parent's name.

int lr_start_sub_transaction( char *sub_transaction, char *parent_transaction  );

Arguments

The lr_start_sub_transaction function marks the beginning of a sub-transaction. To mark the end of the sub-transaction, use lr_end_sub_transaction. You insert these functions immediately before and after the sub-transaction actions.

Sub-transactions are used for isolating parts of a business process. For example, a sub-transaction "electrical_purchases" may be nested within the larger transaction "purchases." The transaction "purchases" is the parent transaction and "electrical_purchases" the sub-transaction.

Multiple sub-transactions can be nested within a parent transaction. A sub-transaction may also be a parent to a smaller sub–transaction.

The duration of a transaction or sub-transaction is the sum of the durations of all steps between its start and end, including the steps that are included in sub-transactions.

Each lr_start_sub_transaction statement must be matched with an lr_end_sub_transaction statement within the script or it will be interpreted as an illegal command.

Return Values

This function returns 0 if it succeeds. It returns -1 if the transaction name is illegal or if there is no prior call to lr_start_transaction with a transaction of the same name.

Parameterization

All string arguments (char type) can be parameterized using standard parameterization.

Example

Example 1

In the following example, lr_start_sub_transaction begins a transaction that performs purchases of six electrical items. The parent transaction is purchases and the sub-transaction is electrical_purchases.

 /* Notify that a transaction is starting */
lr_start_transaction("purchases");
 /* Breakdown the transaction into a smaller transaction */
lr_start_sub_transaction("electrical_purchases", "purchases");
status = purchase_electrical_items(6); /* call to Server API */
/* End transaction with operation result - pass or fail */

if (status == 0)
    lr_end_sub_transaction("electrical_purchases", LR_PASS);
else
    lr_end_sub_transaction("electrical_purchases", LR_FAIL);

Example 2

This example shows how the durations of nested sub-transactions are reported.

SubTransactions() { 
    int i, baseIter = 1000;
    char dude[1000];
//Start Parent
    lr_start_transaction("Master");
//Start first sub transaction
    lr_start_sub_transaction("FirstT", "Master");
//Start nested child of first sub transaction
    lr_start_sub_transaction("FirstT_Child1", "FirstT");
 // Artificially create some elapsed time
        for (i=0; i<(20 * baseIter); ++i)
            sprintf(dude, 
                "This is the way we kill time in a script = %d", i);
            
    lr_end_sub_transaction("FirstT_Child1",LR_AUTO);

// Start second nested child
    lr_start_sub_transaction("FirstT_Child2", "FirstT");  
// Artificially create some elapsed time

        for (i=0; i<(20 * baseIter); ++i)
            sprintf(dude, 
                "This is the way we kill time in a script = %d", i);
	lr_end_sub_transaction("FirstT_Child2",LR_AUTO);
    lr_end_sub_transaction("FirstT",LR_AUTO);
    //Start a second sub transaction
    lr_start_sub_transaction("SecondT", "Master");    
        for (i=0; i< (20 * baseIter); ++i)
            sprintf(dude, 
                "This is the way we kill time in a script = %d", i);            
    lr_end_sub_transaction("SecondT",LR_AUTO);
    lr_end_transaction("Master", LR_AUTO);
    return 0;
}

Example: Output:
Note that FirstT duration is the sum of its nested sub transactions: FirstT_Child1 and FirstT_Child2.
Master duration is the sum of its nested sub transactions: FirstT and SecondT.
Notify: Transaction FirstT_Child1 ended with Pass status (Duration: 0.1250).    
Notify: Transaction FirstT_Child2 ended with Pass status (Duration: 0.1250).
Notify: Transaction FirstT ended with Pass status (Duration: 0.2656).
Notify: Transaction SecondT ended with Pass status (Duration: 0.1406).
Notify: Transaction Master ended with Pass status (Duration: 0.4063).