Share this page

# lr_start_transaction_instance

Starts a transaction instance.

    long lr_start_transaction_instance( char *transaction_name, long handle );

Alphabetical Listing - C Language Utility Functions

## Arguments

Name | Comments
--- | ---
transaction_name | The name of the transaction.
handle | The parent transaction's handle. A value of 0 instructs VuGen to create a new parent transaction.

The lr_start_transaction_instance function marks the beginning of a transaction instance. A transaction instance is an occurrence of a transaction with transaction_name. Instances are identified by their handle which distinguishes them from other instances of the same transaction.

This function enables multiple instances of a transaction to be created. Use transaction instances when the same transaction is required to be performed under different circumstances and an analysis of each circumstance is required.

By passing the handle of a parent transaction instance, the new instance will be considered a sub-transaction instance of the parent. Pass zero as the handle if there is no parent. For more information on sub-transactions, see lr_start_sub_transaction.

The function returns the handle of the transaction instance which identifies the instance. Note that each lr_start_transaction_instance statement must be matched with an lr_end_transaction_instance statement or it will be interpreted as an illegal command.

Note: For information on allowed characters and maximum length for transaction names, see Transaction guidelines in the Virtual User Generator Help Center.

## Return Values

This function returns a unique long number which identifies the specific transaction instance. On error, a negative number is returned.

## Parameterization

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

## Example

## Example 1:

In the following example,lr_start_transaction measures the time of a transaction that performs a withdrawal from a bank server. Once the server API call is completed and returns a value to the status variable, the transaction is complete. However the test also wants to verify how long an unsuccessful withdrawal transaction will take if the customer is over the withdrawal limit. An instance of the transaction "withdraw" is created with lr_start_transaction_instance for this purpose.

    long id;
    int status;
    int amount_overdrawn = get_amount_overdrawn(); /* Call to server API */
    while (amount_overdrawn < LIMIT) {

         /* Notify that a transaction is starting */

        id = lr_start_transaction("withdraw");
        status = bank_withdraw(500); /* Call to server API */

         /* End transaction with operation result - pass or fail */

        if (status == 0)
            lr_end_transaction("withdraw", LR_PASS);
        else
            lr_end_transaction("withdraw", LR_FAIL);
        amount_overdrawn = get_amount_overdrawn();
    }

         /* The client is unable to withdraw anymore as the overdraft
        limit has been reached. Try to withdraw anyway to record
        the server response time */

        id = lr_start_transaction_instance("withdraw", 0);
        status = bank_withdraw(500); /* This call will fail, but we want to time it */
        lr_end_transaction_instance(id, LR_PASS);

## Example 2:

This example demonstrates nesting of parent and child transaction instances.

    #include "as_web.h"
    Action() {
        long parent_trans_handle;
        long child1_handle;
        long child2_handle;
        double trans_time;
        int rc;

        /* Start the main transaction instance.
            Passing 0 as the parent handle indicates that
            the transaction has no parent.
            The function return value is the handle used in other
            transaction instance functions.     */

        parent_trans_handle = lr_start_transaction_instance("ParentTransaction",0);

        lr_output_message("Parent transaction instance handle is %ld.", parent_trans_handle);

        /*Perform the business process, represented here with a single web_url call. */

        web_url("web_url", "URL=http://www.ABC.com",LAST );
        rc = lr_get_trans_instance_status(parent_trans_handle);
        lr_output_message("Parent Transaction status is %d.", rc);
        if (rc == LR_FAIL) {

         /* web_url has failed the transaction.
            No point in continuing, because
            future calls will probably fail too */

         lr_end_transaction_instance(parent_trans_handle, LR_FAIL);
         return;
        }
        /* Start the child transaction instance.
            Passing the handle returned from another
            lr_start_transaction_instance call as the
            handle argument makes this transaction a
            child instance.     */

        child1_handle = lr_start_transaction_instance("ChildTransInstance", parent_trans_handle);
        lr_output_message("First child transaction instance handle is %ld.", child1_handle);

        // Perform the business process

        web_url("web_url",
            "URL=http://www.ABC.com/services/index.html",LAST );
        /* Get the child transaction instance durations.
            Pass the instance handle.
            The duration in seconds is the return value. */

        //Total duration

        trans_time =
            lr_get_trans_instance_duration(child1_handle);
        lr_output_message
            ("First child instance time is %lf seconds.",
                trans_time);

        //Think time

        trans_time = lr_get_trans_instance_think_time(child1_handle);
        lr_output_message("First child instance think time is %lf seconds.", trans_time);

        //Wasted time

        trans_time = lr_get_trans_instance_wasted_time (child1_handle);
        lr_output_message("First child instance waste time is %lf seconds.", trans_time);

        /*Start a second child transaction of the same name.
        This is possible even though the first is still active
        because we are using handles, not names.
        In a real script you would use instances with the
        same name to track the same process under
        different conditions.
        This example, showing that transaction instances
        can be nested, is to caution you that this is technically
        possible, so that you take care to avoid doing it.
        The transaction times with nested transactions
        of the same name are not data you can analyze in any
        meaningful way. */

        // Start second instance of the same name

        child2_handle = lr_start_transaction_instance("ChildTransInstance",parent_trans_handle);

        lr_output_message("Second child instance handle is %ld.",
                child2_handle);

        // Perform the business process

        web_url("web_url", "URL=http://ABC.com",LAST );
        trans_time = lr_get_trans_instance_duration(child2_handle);
        lr_output_message("Second child instance duration is %lf seconds.",trans_time );

        // End the second child transaction instance

        lr_end_transaction_instance(child2_handle, LR_PASS);

        // End the first child transaction instance

        lr_end_transaction_instance(child1_handle, LR_PASS);

        /* Get the Parent transaction instance duration. */

        trans_time = lr_get_trans_instance_duration(parent_trans_handle);
        lr_output_message("Parent Transaction duration is %lf seconds.", trans_time );

        //End the parent transaction instance

        lr_end_transaction_instance(parent_trans_handle, LR_PASS);
        return 0;
    }

Tips to improve your search results... VuGen Function Reference Version 26.1 Function Reference 26.1 All View Local Help Center View Online Help Center Version: