Mercury Virtual Table Server

This describes how to use Mercury's Virtual Table Server (VTS) from within WinRunner and LoadRunner computer system performance testing

Topics this page:

Site Map  
About this site  

Virtual Table Server (VTS)

Get this print framed for your wall!

The Virtual Table Server (VTS) Windows service maintains a virtual (in-memory) database accessible by several load generators on a network.

With VTS, several load generators can obtain values from a single common pool of values. One Vuser can create key values (such as a new customer ID), and any number of other Vusers can immediately use that value.

Sure, a Vuser can make requests to obtain values, but that may impose a different load profile that may not be realistic.

Without VTS, a single Vuser can only act on values it creates. As of LR8.0 and 9.10, LoadRunner is limited to having each load generator refer to its own parameter files, which means the same static values are used by multiple load generators. VTS provides a way for load generators to communicate with each other in real time.

If the script "marks" each value as being used, VTS provides a mechanism for allocating unique values among load generators.

If the script is written to act according to data obtained from VTS, the behavior of load generators can be controlled in real time.

An alternative to VTS is making calls to a MySQL C API dll and this VuGen code. But beware that call dll's is not thread safe, which requires running as a process rather than thread and thus drastically reducing the number of Vusers which can be run from each load generator machine.

Versions & Requirements

VTS has been tested to hold up to 1 million entries per row since the total amount of data the VTS can support is only limited by the OS's maximum limit on process memory (ie. 2GB - 3GB).
However, VTS only allows users to scroll to the 32,767th row.

At minimum, use at least a 300Mhz+ Windows NT/2000 to run the Virtual Table Server. Since the VTS server component is single threaded, a multi-CPU processor is unnecessary.

In VTS version 2 “Data extraction and communication was simplified but limited to column/queue level operations. The new Virtual Table Server II provides a higher degree of data manipulation and 5-10 times better performance. From row level queries, retrievals, updates, insertions, unqueue entries, to database access, VTS II provides the functionality and ease for enhanced inter-process, inter-virtual user communication.”

An alternative to VTS is open-source STAF (Software Testing Automation Framework) infrastructure, as described in my page on Automated Testing Frameworks

Installation

1. Email me to request the folders and files described at the right. (This gives me a way to notify you of future updates).

2. Unzip into the directory where you want to run VTS.
   My preference is to install where LoadRunner is installed (to avoid messing with PATH variables). The installation zip file's bin contents should go into LoadRunner's bin folder. The same goes for files in the classes, include, and lib folders.

3. Right-click the vts_start.bat here and save the target file to a local folder, then right-click on it and "Run as Administrator" to register the dlls and invoke vtsconsole. Here are the steps it performs:
   1. In Start > Run enter cmd
      If you're running Windows Vista, Run as Administrator or you'll get error messages about not being able to register.

   2. Navigate your VTS \bin directory, such as:
      cd \
      cd "Program Files\HP\Loadrunner\bin" (V9)

   3. Enter these commands:
      regsvr32.exe vtsctls.ocx
      regsvr32.exe msflxgrd.ocx (MS Flex grid).

      Hopefully, you should see a pop-up "DllRegisterServer in ....ocx succeeded." for each of these commands executed. If instead you get:

      "DllRegisterServer in vtsctls.ocx failed. Return code was: 0x80040200." or
      "DllRegisterServer in msflxgrd.ocx failed. Return code was: 0x8002801c.",
      right-click on it and Run as Administrator.

   4. Before invoking vtsconsole.exe, find its IPv4 address using
      ipconfig /all

   An IP address needs to be specified in the script code calling the vtsconsole. Use "127.0.0.1" if it's on the same machine as the script.
   Another address is needed if VTSConsole is on a different machine.

4. After you upgrade to a new folder holding LoadRunner (LR7.8 to LR8.0, etc.),
   copy to every LoadRunner host load generator these files:
   • vtclient.dll
     from the VTS \bin folder
     to LoadRunner's \bin folder on the load generator.

   • vts2.h
     from the VTS \include folder
     to LoadRunner's \include folder on the load generator.

Within the zip file:

• bin
  • comctl32.dll
  • msfixgrd.ocx
  • vtclient32.dll
  • vtclient.dll
  • vtconsole.ext
  • vtsctls.ocx
  • vtserver.dll
  • vtstest.exe
• classes
  • lrapi
    • lrvtc.class
    • vtc.class
• dat
  • wrun
    • vtclient
      • db
        • vtclient
        • vtc.class
      • header
      • script
• doc
  • VTS 2.doc document contains Function references and general usage.
• include
  • vts2.h
• info
  • ...
• lib
  • vtclient32.lib
  • vtclient.lib
  • vtserver.lib
• VTS_Example_Scripts.zip

VTS Service Invocation

Invoke and lauch the VTS Server Component from Start > Run > navigate to your VTS \bin folder and
vtconsole.exe -port 8888 -launch

Optionally, -file C:\xxx specifies a file to be loaded upon invocation. This could be repeated to load several files.

This should result in this Control screen. If not, to see if the port (by default 8888) is used by another application, run:

netstat -an

Exiting vtconsole erases its data in memory. Toggling between Shutdown and Start does not reset values.

Make this invocation automatic everytime you login by right-clicking on the vtconsole.exe, then pasting it within folder Documents and Settings > your userid > Start Menu > Programs > Startup.

Data Loading

Add data to the VTS in-core table. Optionally, Execute commands to insert your data values into the VTS database.

operation name in VTS Command Console	Operation Description
Insert data element	Inserts value in 'Operation Data' field into the column specified by 'Column Name' field.
Insert unique data	Inserts 'Operation Data' into the column specified by 'Column Name' only if it is unique within the target column.
Update data element	Updates value of the data element in 'Column Name' at the selected 'Location' with new value of 'Operation Data'
Increment data element	Increments the numerical value of the data element by 'Operation Data' at the selected 'Location' in column specified by 'Column Name.'
Query data element	Obtains the value of the data element in 'Column Name' at selected 'Location.'
Clear data value	Clears the selected data element at 'Location' under column specified by 'Column Name.'
Clear entire column	Clears the entire column.

Scripting Basics

1. Modify each Vu script that accesses VTS so that the connection to VTS is made only once in the init and end section.
   • Add to the top of every vuser_init, action, and vuser_end section of scripts that use Client VTS API functions
     #include "vts2.h"

   • In the vuser_init section of the script, load the VTS dll, connect to VTS, and specify the column names:

   	PVCI pvci = 0; 
   	int rc = 0;
   	char *VtsServer = "127.0.0.1"; // loopback on the same machine
   	lr_load_dll("vtclient.dll");
   	// Time out if VtsServer isn't found:
   	pvci = lrvtc_connect( VtsServer,8888,0); 
   	rc = vtc_get_last_error(pvci);
   	if( rc != 0 ) {
   		lr_message("*** rc = %d for VTC connection to %s.", rc, VtsServer);
   		return -1;
   	}
   

   • In the vuser_end section of the script:

   	PVCI pvci = 0; 
   	pvci = lrvtc_disconnect(); 
   

   Some LoadRunner examples in the VTS 2.doc VTS User Guide are incorrect!
   The sample script uses "raw" C function calls prefixed with "vtc_" rather than equivalent Loadrunner Vu function calls prefixed with "lrvtc_".

2. In Action sections of scripts that use VTS, make lrvtc_ function calls. VTC automatically creates column names, so lrvtc_create_column functions are not necessary.

   	int rc = 0;
   
   // Insert into the next row the value of a single cell: 
   	rc = lrvtc_send_message("Col1", "2"); 
   // Insert into the next row data to several columns:
   	rc = lrvtc_send_row1("Col1;Col2;Col3", "1;John;Me", ";", VTSEND_SAME_ROW );
   	rc = lrvtc_send_row1("Col1;Col2;Col3", "3;Mary;Too", ";", VTSEND_SAME_ROW );
   // Add value into the next column if the value does not already exist:
   	rc = lrvtc_send_if_unique("Col2", "4"); 
   // increments value in Col1 row 2 by 3 (row num starts at 0):
   	rc = lrvtc_increment("Col1", 1, 9); 
   	

   Each function call only replaces the parameters relevant to it, so you may have to clear out parameters if necessary before making different function calls.

   	rc = lrvtc_clear_column("Col3");
   	rc = lrvtc_clear_row(4);
   

   VTS provides no indexes, so search though the key column to get its index (variable iRow) then use it to obtain data from other columns in the same row:

   	int colSize;
   	int iRow;
   	char *LookFor = "Pam";
   
   	// Obtain the count of rows populated for column named "Col1":
   	colSize = lrvtc_column_size("Col1");
   	lr_message("*** Col1 size = %d",colSize); 
   
   	for( iRow = 1; iRow <= colSize; iRow ++ ) {
   		// Retrieve, for the physical row index given, all columns:
   		rc = lrvtc_query_row( iRow );
   		lr_message("Row %d Col1=%s", iRow, lr_eval_string({Col1}));
   		if (LookFor == lr_eval_string({Col1})){
   			// Update columns, given the physical row index number:
   			rc = lrvtc_update_row1("Col1;Col2",iRow,"Any;Some",";");
   			// Retrieve, for the column name given, rows:
   			rc = lrvtc_query_column("Col3", 3);
   			// Update the value in the Column and Row specified:
   			rc = lrvtc_update_message("Col1", iRow , "20"); 
   			// Clear value in specified cell given its Column name & Row: 
   			rc = lrvtc_clear_message("Col2",iRow); 
   		}
   	}
   

3. Run the script.

   Error return codes are described biefly in vts2.h are:

   #define VTCERR_INVALID_CONNECTION_INFO -10000 > verify the server name attribute.
   #define VTCERR_FAILED_TO_RESOLVE_ADDR -10001
   #define VTCERR_FAILED_TO_CREATE_SOCKET -10002
   #define VTCERR_FAILED_TO_CONNECT -10003 > the vtconsole is not running.
   #define VTCERR_INCOMPLETE_REQUEST -10100
   #define VTCERR_FAILED_TO_RECV_RESPONSE -10101
   #define VTCERR_INCOMPLETE_RESPONSE -10102
   #define VTCERR_RESPONSE_ARGS_UNMATCH -10103
   #define VTCERR_OPERATION_ERROR_BASE -11000

4. If VTS has accumulated a set of data you want to keep, from vtsconsole export them to a text file which you can import again later.

VTS Library Functions

In calls to VTS, it helps to have code to generalize the assembly of data, code to format display descriptions of return codes, etc. I have written such functions as part of my LoadRunner Framework.