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 LoadRunner Professional 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.

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 (select the relevant version).

Back to top

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;

Back to top