Share this page

# User handlers

VuGen provides several advanced capabilities that allow you to customize the way your script behaves. These capabilities include user handlers and configuration files.

This topic describes user handler implementation.

In this topic:

## About user handlers

User handlers are open APIs through which you can perform the following operations:

- Get and set the request/response SOAP envelopes

- Override the transport layer

- Get and set the request/response content type

- Get and Set values for parameters

- Retrieve a configuration argument from the script

- Issue messages to the execution log

- Fail an execution

You can set up a user handler directly in a script, or implement it through a DLL. You can apply the handler locally or globally.

For task details, see Create a user handler.

For sample user handlers, see User handler examples.

## Handler function definitions

For basic implementation of a user handler, you define a user handler function within your Vuser script with the following syntax:

    int MyScriptFunction(const char* pArgs, int isRequest)

The pArgs argument contains the string that is specified in UserHandlerArgs argument of web_service_call function.

The isRequest argument indicates whether the function is being called during processing of a Request (1) or Response (0) SOAP envelope.

The content of SOAP envelope is passed to a parameter called SoapEnvelopeParam for both requests and responses. After the function processes the SOAP envelope, make sure to store it in the same parameter.

To call the handler function, use the function name as a value for the UserHandlerFunction argument in the relevant Web Service Call step. For more information, see the Function Reference.

## Event handler return codes

VuGen recognizes the following return codes for the handler function.

Return Code |  | Description
--- | --- | ---
LR_HANDLER_SUCCEEDED | 0 | The Handler succeeded, but the SOAP envelope did not change.
LR_HANDLER_FAILED | 1 | The Handler failed and further processing should be stopped.
LR_HANDLER_SUCCEEDED_AND_MODIFIED | 2 | The Handler succeeded and the updated SOAP envelope is stored in SoapEnvelopeParam.

In the following example, a script handler manipulates the outgoing envelope:

    //This function processes the SOAP envelope before sending it to the server.
    int MyScriptFunction(const char* pArgs, int isRequest)
    {
        if (isRequest == 1) {
            //Get the request that is going to be sent
            char* str = lr_eval_string("{SoapEnvelopeParam}");
            //Manipulate the string...
            //Assign the new request content
            lr_save_string(str, "SoapEnvelopeParam");
            return LR_HANDLER_SUCCEEDED_AND_MODIFIED;
        }
        return LR_HANDLER_SUCCEEDED;
    }
    Action()
    {
        //Instruct the web_service_call to use the handler
        web_service_call( "StepName=EchoAddr_102",
            "SOAPMethod=SpecialCases.SpecialCasesSoap.EchoAddr",
            "ResponseParam=response",
            "userHandlerFunction=MyScriptFunction",
            "Service=SpecialCases",
            "Snapshot=t1174304648.inf",
            BEGIN_ARGUMENTS,
            "xml:addr="
                "<addr>"
                    "<name>abcde</name>"
                    "<street>abcde</street>"
                    "<city>abcde</city>"
                    "<state>abcde</state>"
                    "<zip>abcde</zip>"
                "</addr>",
            END_ARGUMENTS,
            BEGIN_RESULT,
            END_RESULT,
            LAST);
        return 0;

## See also

- Customize configuration files

https://admhelp.microfocus.com VuGen,Professional Performance Engineering,Performance Engineering for Developers 8942
Tips to improve your search results... OpenText™ Virtual User Generator Help Center OpenText™ VuGen Help 26.1-26.3 All View Local Help Center View Online Help Center Version: