Important LoadRunner Functions used mainly in VuGen Scripts with Syntax and Examples:
VuGen Scripting Challenges were explained in detail in our earlier tutorial in the Online Free LoadRunner Training Series.
In our journey with the LoadRunner VuGen, so far we came across many pre-defined functions (and of course we also saw how to write our own functions).
In this tutorial, we will list and talk briefly about the important ‘pre-defined’ LoadRunner, Protocol specific and C-language functions that we mostly use in VuGen scripts/scenarios.
=> Click Here For Complete Series of LoadRunner Tutorials
Let’s classify these functions into three categories:
- LoadRunner (LR) functions
- Protocol specific (Web – HTTP/HTML) functions
- C language functions
Let’s explore one by one!
Table of Contents:
LoadRunner (LR) Functions
These functions are the general LoadRunner functions that are common for all protocols:
1) lr_eval_string(): As already seen, this function returns the input string after evaluating any embedded parameters.
2) lr_eval_string_ext(): This function creates a buffer and assigns it to the input string after evaluating the embedded parameters.
3) lr_save_string(): As already seen, this function assigns a value to the LR parameter/variable.
4) lr_save_int(): This function assigns an integer to an LR parameter as shown below:
Example:
int number; number=8; lr_save_int(number,”numparam”);
The parameter ‘numparam’ can now be used as any other LR parameter.
5) lr_paramarr_random(): As already seen, this function randomly selects one of the values from a parameter array.
6) lr_paramarr_len(): This function returns the number of elements in a parameter array.
Assume ‘cFlight’ is the parameter array having flight values, the example below shows how the number of elements of this array can be copied into a variable.
Example:
int arrLen;
arrLen = lr_paramarr_len("cFlight");
7) lr_paramarr_idx(): This function gives the value of the parameter at a specified location in a parameter array. An example shown below saves the third value of the parameter array to a variable.
Example:
char * flightVal;
flightVal = lr_paramarr_idx("cFlight", 3);
8) lr_db_connect(): This is a database function that is used to connect to a database.
9) lr_db_disconnect(): This is a database function that is used to disconnect from a database.
10) lr_start_transaction() and lr_end_transaction(): As already seen, these functions are used to start and end (respectively) a transaction.
11) lr_message(): This is a message function that is used to send a message(s) to the log and the output window.
12) lr_output_message(): This is a message function that is used to send the message(s) with details like the script section and line number to output windows, log files and other test report summaries.
13) lr_log_message(): This is a message function that is used to send a message(s) to the Vuser or agent log file and not to the output window.
14) lr_error_message(): This is a message function that is used to send a message(s) to the output windows, log files and other test report summaries.
15) lr_save_datetime(): This function saves the current date and time (or the date and time with the specified offset) into a parameter that can be used in our script as and when required.
Example:
lr_save_datetime("Today’s date is %B %d %Y", DATE_NOW, "today");
lr_output_message(lr_eval_string("{today}"));
Action.c(4): Today’s date is June 09 2018
Given below is another Example where the offset of one day is used:
lr_save_datetime("Tomorrow's date is %B %d %Y", <strong>DATE_NOW</strong> + <strong>ONE_DAY</strong>, "tomorrow");
lr_output_message(lr_eval_string("{tomorrow}"));
Action.c(4): Tomorrow’s date is June 10, 2018
16) lr_set_debug_message(): This function changes the message logging level (for a part of the script) from what is set in the Run-Time settings. As shown below, a full trace is enabled only for the ‘index.htm’ request (even if the log level is set to ‘Standard log’ in Run-Time settings).
Example:
lr_set_debug_message(LR_MSG_CLASS_EXTENDED_LOG | LR_MSG_CLASS_FULL_TRACE, LR_SWITCH_ON );
web_url("index.htm",
"URL=http://127.0.0.1:1080/WebTours/index.htm",
"TargetFrame=",
"Resource=0",
"RecContentType=text/html",
"Referer=",
"Snapshot=t8.inf",
"Mode=HTML",
LAST);
lr_set_debug_message(LR_MSG_CLASS_EXTENDED_LOG | LR_MSG_CLASS_FULL_TRACE, LR_SWITCH_OFF );
17) lr_abort(): This function aborts the execution of the script after executing the ‘vuser_end’ section. This function is useful when we need to manually abort the script because of a specific error condition.
18) lr_exit(): This function instructs Vuser to exit from the script run during execution and continue as per the ‘Script Continuation Options’ specified.
In the following Example, this function instructs Vuser to stop the current global script run iteration and start the next iteration.
lr_exit(LR_EXIT_MAIN_ITERATION_AND_CONTINUE, LR_AUTO);
Here is a list of other script continuation options:
- LR_EXIT_VUSER – Exit without any condition and go directly to vuser_end action.
- LR_EXIT_ACTION_AND_CONTINUE – Stop current action and go to the next action.
- LR_EXIT_ITERATION_AND_CONTINUE – Stop the current iteration and go to the next iteration.
- LR_EXIT_VUSER_AFTER_ITERATION – Exit after the current iteration run is completed.
- LR_EXIT_VUSER_AFTER_ACTION – Exit after the current action run is completed.
19) lr_think_time(): This function allows a Vuser to pause for a defined time between steps/actions on the VuGen script. This is to simulate the real user behavior of thinking for some time between actions/steps on an application.
For Example, the following makes a Vuser wait for 10 seconds…
lr_think_time(10);
20) lr_rendezvous(): As already seen, this function instructs the LoadRunner to wait at a specified step in the script till all the Vusers come to that step so that subsequent request can be executed simultaneously.
21) lr_load_dll(): This function is used to load an external dll allowing a Vuser to call an external function when replaying the script.
22) lr_save_searched_string(): This function searches for an occurrence of a string in a buffer and saves a portion of the buffer after that string to a parameter.
In the following Example, third occurrence (number defined in the third attribute plus 1) of the string “all” is searched in the buffer and the next 14 characters (sixth attribute) are saved in a parameter (fifth attribute ‘1’ skips the space after the search).
char cBuffer[] = "all the King's horses and all the King's elephants and all the King's men";
lr_save_searched_string(cBuffer,strlen(cBuffer),2,"all",1,14,"parameter");
lr_output_message("The searched sub-string is %s",lr_eval_string("{parameter}"));
Action.c(7): The searched sub-string is the King’s men.
23) lr_vuser_status_message(): This function sends a message to the Vuser status area of the Controller and to the Vuser log.
24) lr_next_row(): This function works on the specified parameter data file and is used to advance an active row to the next row.
25) lr_advance_param(): This function makes the script to use the next available value of the parameter by working on column names.
26) lr_start_timer() and lr_end_timer(): These functions are used to start and stop a timer in a VuGen script that calculates the passage of time in seconds.
27) lr_whoami(): This function returns information about the Vuser (like Vuser id, Vuser group).
28) lr_get_vuser_ip(): This function returns the IPv4 address of a Vuser.
29) lr_get_host_name(): This function returns the name of the machine executing the script.
30) lr_get_master_host_name(): This function returns the name of the machine running the Controller.
31) lr_decrypt(): This function decrypts an encoded string. It is generally used to decrypt passwords.
32) lr_continue_on_error(): This function specifies how to handle errors to continue running if an error occurs or to abort the script execution.
***********************************
In this section, we discussed more on ‘pre-defined’ functions and ‘LoadRunner’ functions in detail.
In our next section, we will talk about the LoadRunner ‘Protocol Specific’ and ‘C-Language’ functions.
Protocol Specific Functions
These functions are specific to a protocol, in our discussion, we will restrict ourselves to discussing ‘Web-HTTP/HTML’ protocol or simply ‘Web’ protocol specific functions.
1) web_url(): This function loads the Web page specified by the URL argument.
2) web_submit_form(): This function submits a form. And this function is recorded only in the HTML mode and submits a context-sensitive request (we already talked about context sensitive and contextless requests).
See Example below:
web_submit_form("login.pl",
"Snapshot=t2.inf",
ITEMDATA,
"Name=username", "Value=jojo", ENDITEM,
"Name=password", "Value=bean", ENDITEM,
"Name=login.x", "Value=51", ENDITEM,
"Name=login.y", "Value=13", ENDITEM,
LAST);
3) web_submit_data(): This function submits a ‘context-less’ form. This function is recorded only in URL–based recording mode or in the HTML–based recording mode with ‘A script containing explicit URLs only’ option checked.
See the Example below:
web_submit_data("login.pl",
"Action=http://127.0.0.1:1080/cgi-bin/login.pl",
"Method=POST",
"RecContentType=text/html",
"Referer=http://127.0.0.1:1080/cgi-bin/nav.pl?in=home",
"Snapshot=t12.inf",
"Mode=HTTP",
ITEMDATA,
"Name=userSession", "Value=123342.854353989zDttttipAHAiDDDDDiAzzpziitcf", ENDITEM,
"Name=username", "Value=jojo", ENDITEM,
"Name=password", "Value=bean", ENDITEM,
"Name=JSFormSubmit", "Value=off", ENDITEM,
"Name=login.x", "Value=51", ENDITEM,
"Name=login.y", "Value=13", ENDITEM)
4) web_custom_request(): This function is used to create a custom HTTP request using any method or body.
5) web_concurrent_start() and web_concurrent_end(): These functions are used to mark the beginning and end (respectively) of a concurrent group. All the functions within a group (enclosed between these functions) are executed concurrently.
6) web_reg_save_param(): As already seen, this is a boundary based correlation function.
7) web_reg_save_param_ex(): This is also a boundary based correlation function which is a improved version of the web_reg_save_param function.
8) web_reg_find(): As already seen, this function is used for text check.
9) web_image_check(): As already seen, this function is used for image check.
10) web_convert_param(): This function is used to convert HTML text to plain text or URL, or plain text to URL. In the below Example, these functions convert the content of parameter ‘ParamName’ from the HTML format to URL format.
Example:
web_convert_param(“ParamName”, “SourceEncoding=HTML”, “TargetEncoding=URL”, LAST );
11) web_get_int_property(): This function returns specific information (like the status code, download size etc.) about the previous HTTP request. In the example shown below, this function is used to return HTTP status code and download size.
Example:
int statusCode, downloadSize;
web_url("index.htm",
"URL=http://127.0.0.1:1080/WebTours/index.htm",
"Resource=0",
"RecContentType=text/html",
"Referer=",
"Snapshot=t1.inf",
"Mode=HTML",
EXTRARES,
"Url=../favicon.ico", "Referer=", ENDITEM,
"Url=https://www.bing.com/favicon.ico", "Referer=", ENDITEM,
LAST);
statusCode = web_get_int_property(HTTP_INFO_RETURN_CODE);
lr_output_message("The HTTP status code is %d",statusCode);
downloadSize = web_get_int_property(HTTP_INFO_DOWNLOAD_SIZE);
lr_output_message("The download size is %d bytes",downloadSize);
Action.c(17): web_get_int_property started [MsgId: MMSG-26355]
Action.c(17): web_get_int_property was successful [MsgId: MMSG-26392]
Action.c(18): The HTTP status code is 200
Action.c(20): web_get_int_property started [MsgId: MMSG-26355]
Action.c(20): web_get_int_property was successful [MsgId: MMSG-26392]
Action.c(21): The download size is 12891 bytes
12) web_set_max_html_param_len(): This function is used to set the maximum length of any HTML string that can be retrieved and saved in a parameter. The default value for the maximum length of a parameter that can be captured during correlation is 256 characters. This function is used to retrieve a string longer than 256 characters.
13) web_cache_cleanup(): This function is used to clear the cache. In the runtime settings-Browser Emulation tab, if ‘Simulate a new user each iteration’ is enabled, then this function is automatically called at the beginning of each iteration.
14) web_cleanup_cookies(): This function clears all the cookies that are currently stored by the Vuser.
15) web_add_cookie(): This function adds a new cookie.
16) web_add_header(): This function adds a user–defined header to the next HTTP request.
17) web_save_timestamp_param(): This function saves the current local timestamp of the computer running the script. This is a 13 digit number and the value is the number of milliseconds since midnight January 1st, 1970.
Example:
web_save_timestamp_param("currentTimeStamp", LAST );
lr_output_message(lr_eval_string("Timestamp: {currentTimeStamp}"));
Action.c(5): Timestamp: 1529249235582
18) web_set_user(): This function specifies a login value and password for a Web server or a proxy server. When we log in to a server that requires username and password, this function is generated.
19) web_set_proxy(): This function is used to instruct Vuser to direct all HTTP requests to the specified Proxy Server.
20) web_set_certificate(): This function is used to instruct Vuser to use a specific certificate from the internet explorer registry (whenever a secure Web server requires the client to present a certificate).
For Example, the following function instructs the Vuser to use the second certificate from the internet explorer registry.
web_set_certificate("2");
21) web_set_sockets_option(): This function is used to configure various options for sockets on the client machine.
SSL_VERSION – SSL version: ‘2’, ‘3’, ‘2&3’, ‘TLS’, ‘TLS1.1’, or ‘TLS1.2’.
MAX_CONNECTIONS_PER_HOST– The maximum number of concurrent connections per host.
CLOSE_KEEPALIVE_CONNECTIONS – Closes all open connections.
C Language Functions
These are the ‘C’ functions that are used to enhance the VuGen scripts for specific scenarios.
1) strcpy(): This function copies one string to another.
Example:
char String[100];
strcpy(String,"This is a string");
lr_output_message("The content in String is : %s", String);
Action.c(8): The content in String is: This is a string
2) strcmp(): This function compares two strings and returns a value that indicates the lexicographical relation between them (‘=0’ if strings are same, ‘<0’ if the first string is less than second string and ‘>0’ if the first string is greater than a second string).
Example:
char String1[100]= "The first string";
char String2[100]= "The second string";
if(strcmp(String1,String2)==0)
{
lr_output_message("Strings are same");
}
else
{
lr_output_message("Strings are not same");
}
Action.c(14): Strings are not the same.
3) strlen(): This function returns the length of a string in bytes.
4) strcat(): This function concatenates two strings.
Example:
char String[100]= "Star";
strcat(String,"Wars");
lr_output_message("The final string is: %s",String);
Action.c(10): The final string is StarWars.
5) strtok(): As already seen, this function returns a token from a string delimited by specified characters.
6) atoi(): As already seen, this function converts a C string into a C integer.
7) atof(): This function converts a C string into a C float.
8) itoa(): This function converts a C integer to a C string.
Example:
int x=1;
char y[100];
itoa(x,y,10);
lr_output_message("The string is: %s",y);
Action.c(8): The string is: 1
9) fopen(): This function is used to open a file pointer.
10) fclose(): This function is used to close a file pointer.
11) fread(): This function reads unformatted data from a stream into a buffer.
12) fwrite(): This function writes unformatted data from a buffer to a stream.
13) fprintf(): As already seen, this function writes formatted output to a file.
14) sprint(): This function writes formatted output to a string.
Example:
int arg = 84;
char filename[64], * filetype = "txt";
sprintf(filename, "log_%d.%s", arg, filetype);
lr_output_message ("The new file name is %s", filename);
Action.c(7): The new file name is log_84.txt
Conclusion
From this tutorial, we learned more about the important pre-defined LoadRunner functions.
These functions take care of almost all the important scenarios that we generally come across in real-time applications. It is advised to refer ‘Function Reference’ in VuGen help for additional details on these functions.
In our upcoming tutorial, you will learn more about Web Services Scripting Using LoadRunner.
=> Visit Here For Complete Series of LoadRunner Tutorials