VTS 2.

11
Last Updated: August 19, 2004

Introduction
Virtual Table Server (VTS) first edition, introduced the capability for LoadRunner virtual users, WinRunner
and XRunner, to communicate in real time. 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.

System Requirements
A 1-CPU 300Mhz+ Windows NT/2000 should be used to run the Virtual Table Server. Since the server is
single threaded, a multi-cpu processor is unnecessary.
The total amount of data the VTS can support is limited by the OSs maximum limit on process memory
(ie. 2GB - 3GB). It has been tested for 1 million entries per row, however the VTSs table will only allow
the user to scroll to 32,767th row.

Installation
1) Obtain VTS2 from Mercury Support Representatives. (Downloadable Binaries)
2) Unzip the file into the main LoadRunner directory (using the directory structure provided).
(eg. \Mercury Interactive\LoadRunner)
3) Register vtsctls.ocx in the \LoadRunner\bin directory.
(eg. regsvr32 c:\Program Files\Mercury Interactive\LoadRunner\bin\vtsctls.ocx)

Server Startup
To bring up the Server Component of VTS, execute the command vtconsole. You can do this in the Run
Box, double clicking on vtconsole.exe in the \LoadRunner\bin directory, or use vtconsole with
command line parameters.

Command Line Parameters

-file < FileName > []
[-table|-queue] [-unique] [ -delimiter <tab|colon|semicolon|
comma|???> ]
If table is specified (default), each column value even if empty is
treated as an entry. If queue is specifed, empty values are ignored.
(The file option, used to load data files, can be specified multiple
times to load multiple data files consecutively.)
- port <####>
(default = 8888)
- launch
(Starts the VTS server upon launch, thus user interaction to active the

server is not required.)

Client Side Setup

In addition to following the installation instructions, two addition steps must be performed in order to gain
table access by the Client (C Program/Script).
1) #include "vts2.h"
(All Init, Action, and End sections that use the Client API Functions).
2) lr_load_dll("vtclient.dll");
(In the Init section)

Table Server Interface

Once the VTS is activated, you will be
presented with the following interface.
From here you can import/export data from
database/files, manually modify data,
configure the server, and start/stop the
server.

Data Manipulation
Through the use of cursor positioning and the provided operators, you will be able to modify the table to
your liking.
Operation Type
Insert data
element
Insert unique data
Update data
element
Increment data
element
Query data
element
Clear data value

Operation Description
Inserts Operation Data into the column
specified by Column Name.
Inserts Operation Data into the column
specified by Column Name only if it is
unique within the target column.
Updates value of the data element in
Column Name at the selected Location
with new value of Operation Data
Increments the numerical value of the data
element by Operation Data at the selected
Location in column specified by Column
Name.
Obtains the value of the data element in
Column Name at selected Location.
Clears the selected data element at

Location under column specified by

Column Name.
Clears the entire column.

Clear entire
column

Import/Export From/To Database/Files

File Import/Export
Importing from text files should be self-explanatory. Make sure the input file has the right
formatting with recognized column delimiters (eg. tab, semicolon, comma, etc). Also, note that
the first row of the column in the file represents the column name in the table. Think of it like a
parameter data file in LoadRunner. The following additional options are available:
Treat data within the file as either a table - every entry is inserted -- or a queue only
non-blank entries are inserted.
Import only unique data from file for each column

Database Import/Export
Database access is performed with ADO-DB. With the appropriate connection string, the user can
import or export data to any type of database. The following connection-string samples, below,
show how various types of databases can be accessed.
Provider for SQL Server
Provider=SQLOLEDB; Data Source=Tigger; Initial Catalog=pubs; User ID=sa;
Password=mypass
Provider for Oracle
Provider=MSDAORA; Data Source=2:; User Id=scott; Password=tiger
Provider for ODBC
DSN=PersonalTours
Driver={SQL Server}; Server=Tigger; Database=pubs; UID=sa; PWD=mypass
Driver={Microsoft ODBC Driver for Oracle; Server=2:; UID=scott; PWD=tiger
From more examples and details on connection strings please consult Microsofts OLEDB or
ADODB manuals (http://msdn.microsoft.com).

Database Import Examples

Flights
1)
2)
3)
4)
5)
6)
7)

Install Flights Database Application

Startup the Quadbase Server
Start Menu Settings Control Panel Data Sources (ODBC) <<WinNT>>
Make sure flight32lr is listed in the DSN
Start vtconsole
Options Import Data
Connection :
DSN=flight32lr;
8) SQL :
select * from AGENTS
9) Import from Database
10) Close

Client Side API

For simplicity, the API has been divided into categories. Also, there are functions specific to LoadRunner
which allow for integration with parameters. All functions and examples can be found in the vts2.h
header file as well as the in the following function reference section.

Initialization / Termination
vtc_connect
lrvtc_connect
vtc_disconnect
lrvtc_disconnect
vtc_get_last_error

vtc_query_column
vtc_query_row

vtc_send_message
vtc_send_if_unique
vtc_send_row1

Queries
lrvtc_query_column
lrvtc_query_row

Submissions
lrvtc_send_message
lrvtc_send_if_unique
lrvtc_send_row1

Updates
vtc_update_message
lrvtc_update_message
vtc_update_message_ifequa lrvtc_update_message_ifeq
ls
uals
vtc_update_row1
lrvtc_update_row1
vtc_increment
lrvtc_increment
vtc_clear_message
lrvtc_clear_message
vtc_clear_column
lrvtc_clear_column
vtc_clear_row
lrvtc_clear_row
Retrievals
vtc_retrieve_message
lrvtc_retrieve_message
vtc_retrieve_messages1
lrvtc_retrieve_messages1
vtc_retrieve_row
lrvtc_retrieve_row

vtc_create_column
vtc_column_size
vtc_free
vtc_free_list
vtc_noop

Miscellaneous
lrvtc_create_column
lrvtc_column_size
lrvtc_noop

API Details
VTS functions that begin with vtc_ prefix are raw and application independent
functions. Functions that being with lrvtc_ prefix are LoadRunner integrated calls
that automatically equalute LoadRunner parameters and store results into
LoadRunner parameters, for convenience. Any string data or array returned by a
vtc_* call should be freed with vtc_free or vtc_free_list, respectively.

vtc_connect

Initialization/Termination

Generate a VTS Connection Descriptor. A connection to the VTS is not established until
it is needed for message exchange. In case a connection fails during an operation, the
VTS will either retry or return an appropriate error message.
(Raw)

(LR)

PVCI vtc_connect(

char
Int
Int

*servername,
portnum,
options)

PVCI lrvtc_connect(

char
Int
Int

*servername,
portnum,
options)

Parameters:
servername
portnum
options

The name of the server host (ie. wizard.merc-int.com, 10.1.2.3,

etc)
The port address at which VTS is listenning (ie. 8888, 9000, etc)
Connection options
0 = None
VTOPT_KEEP_ALIVE = Keep connection alive

Remarks:

lrvtc_connect() stores the connection handle internally, thus obviating

the need to specify the handle in any of the lrvtc_* function calls. Note, if
a connection already exists, it is automatically disconnected, and cleared.
Only vtc_* functions allow for multiple connection handles to be used
concurrently.

Examples:

<Raw Sample>
PVCI pvci = 0;
char **columns = NULL;
char **values = NULL;
pvci = vtc_connect(wizard,8888,VTOPT_KEEP_ALIVE);
//

vtc_retrieve_row(pvci,&columns,&values);
//
<LR Sample>
PVCI pvci = 0;
pvci = lrvtc_connect(VtsServer,8888,0);
//
lrvtc_retrieve_row();
//

vtc_disconnect

Initialization/Termination

Disconnects descriptor from VTS Server, and clears the connection handle, thus
becoming obsolete and un-usable.
(Raw)
(LR)

VTCERR vtc_disconnect(

pvci)

VTCERR lrvtc_disconnect()

Parameters:
pvci
Examples:

PVCI

VTS Connection Handle

<Raw Sample>
PVCI pvci = 0;
pvci = vtc_connect(wizard,8888,VTOPT_KEEP_ALIVE);
//
vtc_disconnect(pvci);
<LR Sample>
PVCI pvci = 0;
pvci = lrvtc_connect(<VtsServer>,8888,0);
//
lrvtc_disconnect();

vtc_get_last_error

Initialization/Termination

Returns the last error specific to a connection given its Connection Handle.
Query column data at index 10 and free data after use.
(Raw)
(LR)

VTCERR vtc_get_last_error(PVCI pvci)

<None>

Parameters:
pvci

VTS Connection Handle

Remarks:

Valid only when utilizing Raw VTS functions.

Examples:

<Raw Sample>
PVCI pvci = 0;
int rc = 0;
pvci = vtc_connect(wizard,8888,VTOPT_KEEP_ALIVE);
//
rc = vtc_get_last_error(pvci);
//

vtc_query_column

Queries

Retrieves data from a column in the VTS at the specified index (row).
(Raw)

(LR)

VTCERR vtc_query_column( PVCI

char
int
char

pvci,
*columnName,
columnIndex,
**outvalue)

VTCERR lrvtc_query_column(
int

char *columnName,
columnIndex)

Parameters:
pvci
columnName
columnIndex
outvalue

VTS Connection Handle

String containing the name of the column to query from.
Integer representing the index of the column data to be queried.
Pointer to string in which to store the queried value.

Remarks:

Remember to free the pointer to string after use (Raw Fuction). LR

function will automatically store the return value in a parameter using the
columnName.

Examples:

<Raw Sample>
//
int rc = 0;
char *value = NULL;
rc = vtc_query_column(pvci, "Col1", 1, &value);
lr_output_message("Query Column 1 Result = %s", value);
vtc_free(value);
//
<LR Sample>
int rc = 0;
rc = lrvtc_query_column("Col1", 1);
lr_output_message("Query Column 1 Result = %s",
lr_eval_string("{Col1}"));
//

vtc_query_row

Queries

Retrieves all data for an entire row in the VTS. Also retrieves the corresponding names
of each column (Raw Function).
(Raw)

(LR)

VTCERR vtc_query_row(

PVCI
Int
char
char

pvci,
columnIndex,
***outcolumns,
***outvalues)

VTCERR lrvtc_query_row(

int

columnIndex)

Parameters:
pvci
columnIndex
outcolumns
outvalue

VTS Connection Handle

Integer representing the index of the column data to be queried.
Pointer to array of strings in which to store the column names.
Pointer to array of strings in which to store the row data.

Remarks:

Remember to free the lists after use (Raw Fuction). LR functions will
automatically store the return value in a parameters using the name of
the column.

Examples:

<Raw Sample>
//
int
char
char

rc
**colnames
**rowdata

= 0;
= NULL;
= NULL;

rc = vtc_query_row(pvci, 1, &colnames, &rowdata)

lr_output_message("Query Row Names : %s , %s", colnames[0],
colnames[1]);
lr_output_message("Query Row Data : %s , %s", rowdata[0], rowdata[1]);
vtc_free_list(colnames);
vtc_free_list(rowdata);
//
<LR Sample>
int rc = 0;
rc = lrvtc_query_row(1);
lr_output_message("%s, %s", lr_eval_string("{Col1}"),
lr_eval_string("{Col2}"));
//

vtc_send_message

Submissions

Sends data into the next row of a column in the VTS.

(Raw)

(LR)

VTCERR vtc_send_message( PVCI

pvci,
char
*columnName,
char
*message,
unsigned short
*outRc)
VTCERR lrvtc_send_message(
Char

Parameters:
pvci
columnName
message
outRc

char *columnName,
*message)

VTS Connection Handle

String containing the name of the column to query from.
String containing the data to send to the column.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_send_message(pvci, "Col1", "1234", &status);
lr_output_message("Send Message Status = %d", status);
//
<LR Sample>
int rc = 0;
rc = lrvtc_send_message("Col1", "1234");
//

vtc_send_if_unique

Submissions

Sends data into a column in the VTS, provided that the value does not already exist.
(Raw)

(LR)

VTCERR vtc_send_if_unique( PVCI

pvci,
char
*columnName,
char
*message,
unsigned short
*outRc)
VTCERR lrvtc_send_if_unique(
char

Parameters:
pvci
columnName
message
outRc

char *columnName,
*message)

VTS Connection Handle

String holding the name of the column to query from.
String to send to the column.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_send_if_unique(pvci, "Col1", "1234", &status);
lr_output_message("Send Message Status = %d", status);
//
<LR Sample>
int rc = 0;
rc = lrvtc_send_if_unique("Col1", "1234");
//

vtc_send_row1

Submissions

Sends data into a row in the VTS with given column names.
(Raw)

(LR)

VTCERR vtc_send_row1(

PVCI
pvci,
char
*columnNames,
char
*messages,
char
*delimiter,
unsigned char
sendflag,
unsigned short
*outUpdates)

VTCERR lrvtc_send_row1(

char
*columnNames,
char
*messages,
char
*delimiter,
unsigned char
sendflag)

Parameters:
pvci
columnNames
messages
delimeter
sendflag

outUpdates
-

VTS Connection Handle

String containing the names of the columns (separated by
delimeter).
String containing the data to send to the columns (separated by
delimeter).
String containing the delimiter to use in columnNames and
messages.
Can be :
1) VTSEND_SAME_ROW
- send all data to the same row
2) VTSEND_STACKED
- send data to next row
3) VTSEND_STACKED_UNIQUE
- send data to next row if not already there
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_send_row1( pvci,
";",
//
<LR Sample>
int rc = 0;

"Name;Password",
"John;LetMeIn",
VTSEND_SAME_ROW, &status);

rc = lrvtc_send_row1(
;,
//

"Name;Password",
"John;LetMeIn",
VTSEND_SAME_ROW);

vtc_update_message

Updates

Update data on the VTS at Column and Index.

(Raw)

(LR)

VTCERR vtc_update_message(
PVCI
pvci,
char
*columnName,
int
index ,
char
*message,
unsigned short
*outRc)
VTCERR lrvtc_update_message(
int
char

Parameters:
pvci
columnName
index
message
outRc

char *columnName,
index ,
*message)

VTS Connection Handle

String containing the name of the column to update.
Integer representing the index of the column to update.
String containing the data to update the column with.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_update_message(pvci, "Col1", 1, 1234, &status);
//
<LR Sample>
int rc = 0;
rc = lrvtc_update_message(Col1, 1 , 1234);
//

vtc_update_message_ifequals

Updates

Update data on the VTS at Column and Index only if current value matches conditional
message.
(Raw)

(LR)

VTCERR vtc_update_message_ifequals(
PVCI
pvci,
char
*columnName,
int
index ,
char
*message,
char
*ifmessage,
unsigned short
*outRc)
VTCERR lrvtc_update_message(
int
char
char

Parameters:
pvci
columnName
index
message
ifmessage
outRc

char *columnName,
index ,
*message,
*ifmessage)

VTS Connection Handle

String containing the name of the column to update.
Integer representing the index of the column to update.
String containing the data to update the column with if condition
is met.
String containing the matching condition (case-sensitive)
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_update_message_ifequals(pvci, "Col1", 1, 1234, changeme
&status);
if (status == 1) {
// success: value changed to 1234
} else {
// failure: value did not change.
}
//
<LR Sample>
int rc = 0;
rc = lrvtc_update_message(Col1, 1 , 1234,changeme);
if (rc == 1) {
// success: value was changed to 1234
} else {
// failure: valid did not change (either condition did not meet, or
error occurred)
}

//

vtc_update_row1

Updates

Update row data on the VTS at a Column Index.

(Raw)

(LR)

VTCERR vtc_update_row1( PVCI

pvci,
char
*columnNames,
int
index ,
char
*messages,
char
*delimiter,
unsigned short
*outUpdates)
VTCERR lrvtc_update_row1( char
int
char
char

Parameters:
pvci
columnNames
index
messages
delimeter
outUpdates

*columnNames,
index ,
*messages,
*delimiter)

VTS Connection Handle

String containing the names of the columns (separated by
delimeter).
Integer representing the index of the column to update.
String containing the data to update the columns with (separated
by delimeter).
String containing the delimiter to use in columnNames and
messages.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_update_row1(pvci,"OrderNumber;Quantity",4321,"8293-OR253;10",";",&status);
//
<LR Sample>
int rc = 0;
rc = lrvtc_update_row1("OrderNumber;Quantity",4321,"8293-OR253;10",";");
//

vtc_increment

Updates

Increments a counter at a specified column and index and returns the new number.
(Raw)

(LR)

VTCERR vtc_increment(
char
int
int
int

PVCI pvci,
*columnName,
index ,
incrValue,
*outValue)

int

char *columnName,
index ,
incrValue)

Parameters:
pvci
columnName
index
incrValue
outValue

lrvtc_increment(
int
int
-

VTS Connection Handle

String containing the name of the column.
Integer representing the index of the column to increment.
Integer representing the amount to increment the counter by.
Integer to hold the new value.

Remarks:

Note that the LR function returns the new value via the function return
mechanism while the raw function returns the value through an argument.

Examples:

<Raw Sample>
//
int
int

rc = 0;
newValue = 0;

// Increment Col1 row#1 by 1

rc = vtc_increment(pvci, "Col1", 1, 1, &newValue);
//
<LR Sample>
int
rc = 0;
rc = lrvtc_increment("Col1", 1, 1);
//

vtc_clear_message

Updates

Clears the data in a specified column and index.

(Raw)

(LR)

VTCERR vtc_clear_message(
PVCI
pvci,
char
*columnName,
int
index ,
unsigned short
*outRc)
VTCERR lrvtc_clear_message(
int

Parameters:
pvci
columnName
index
outRc

char *columnName,
index)

VTS Connection Handle

String containing the name of the column.
Integer representing the index of the column to increment.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_clear_message(pvci,"Col1",1,&status);
<LR Sample>
int
rc = 0;
rc = lrvtc_clear_message("Col1",1);
//

vtc_clear_column

Updates

Clears all data in a column given the column name.

(Raw)

(LR)

VTCERR vtc_clear_column( int

pvci,
char
*columnName,
unsigned short
*outRc)
VTCERR lrvtc_clear_column(char

Parameters:
pvci
columnName
outRc

*columnName)

VTS Connection Handle

String containing the name of the column.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_clear_column(pvci,"Col1",&status);
<LR Sample>
int
rc = 0;
rc = lrvtc_clear_column("Col1");
//

vtc_clear_row

Updates

Clears all data in a row given the row index.

(Raw)

(LR)

VTCERR vtc_clear_row(

int
pvci,
int
rowIndex,
unsigned short
*outRc)

VTCERR lrvtc_clear_row(

int

Parameters:
pvci
rowIndex
outRc

rowIndex)

VTS Connection Handle

Integer representing the row index to clear.
Status Code : 1 = Pass, 0 = Fail

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_clear_row(pvci, 1, &status);
<LR Sample>
int
rc = 0;
rc = lrvtc_clear_row(1);
//

vtc_retrieve_message

Retrievals

Retrieves and clears the first data element from a column.

(Raw)

(LR)

VTCERR vtc_retrieve_message(
char
char

int
pvci,
*columnName,
**outvalue)

VTCERR lrvtc_retrieve_message(

char

Parameters:
Pvci
ColumnName
Outvalue

*columnName)

VTS Connection Handle

String containing the name of the column.
String to hold the retrieved data value.

Remarks:

Note that outValue should be freed after use.

Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
char
*outvalue = NULL;
rc = vtc_retrieve_message(pvci, Col1, &outvalue);
//
vtc_free(outvalue);
//
<LR Sample>
//
int

rc = 0;

rc = lrvtc_retrieve_message("Col1");
lr_output_message ("Retrieved value is : %s", lr_eval_string ("Col1"));
//

vtc_retrieve_messages1

Retrievals

Retrieves and clears the first data element from multiple rows as specified by Column
Names.
(Raw)

(LR)

VTCERR vtc_retrieve_messages1(
char
char
char

int
pvci,
*columnNames,
*delimiter
***outvalues)

VTCERR lrvtc_retrieve_messages1(char
*columnNames,
char *delimiter)

Parameters:
Pvci
ColumnNames
Delimiter
Outvalues

VTS Connection Handle

String containing the names of the columns (separated by
delimeter).
A delimiter to separate the columns from the columnNames
parameter
Array of strings containing the value of the data elements
retrieved.

Remarks:

Note that outvalues should be freed after use.

Examples:

<Raw Sample>
//
int
char
char

rc = 0;
delimiter = '$';
**outvalues = NULL;

rc = vtc_retrieve_messages1(pvci, Col1;Col2, ;, &outvalues);

//
vtc_free_list(outvalues);
//
<LR Sample>
//
int

rc = 0;

rc = lrvtc_retrieve_messages1(Col1;Col2, ";");
lr_output_message ("Col1 : %s", lr_eval_string("{Col1}"));
lr_output_message ("Col2 : %s", lr_eval_string("{Col2}"));

//

vtc_create_column

Miscellaneous

Creates a column in VTS with default size of 4096 rows.

(Raw)

(LR)

VTCERR vtc_create_column( PVCI

pvci,
char
*columnName,
unsigned short
* outRC)
VTCERR lrvtc_create_column(

Parameters:
pvci
columnName
outRC

char

*columnName)

VTS Connection Handle

String containing the name of the column to create.
Status Code : 1 = Pass, 0 = Fail

Remarks:

vtc_create_column() does not create the new column if the name

already exists.

Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
rc = vtc_create_column (pvci, NewCol, &status);
//
<LR Sample>
//
int rc = 0;
rc = lrvtc_create_column ("NewCol");
//

vtc_column_size

Miscellaneous

Queries the size of the column.

(Raw)

(LR)

VTCERR vtc_column_size(

int
char
int

pvci,
*columnName,
*size)

int lrvtc_column_size(

char

*columnName)

Parameters:
pvci
columnName
size

VTS Connection Handle

String containing the name of the column to create.
Integer containing the size of the column returned.

Remarks:
Examples:

<Raw Sample>
//
int
int

rc = 0;
colSize;

rc = vtc_column_size (pvci, Col1, &size);

//
<LR Sample>
int
int

rc = 0;
colSize;

colSize = lrvtc_column_size("Col1");
//

vtc_free

Miscellaneous

Frees memory allocated by the Raw VTS functions.

(Raw)
(LR)

Void vtc_free( char

*msg)

<None>

Parameters:
msg

The name of the variable passed into the Raw VTS functions
which allocated memory for a return value.

Remarks:
Examples:

<Raw Sample>
//
int
rc = 0;
unsigned short
status;
char
*outvalue = NULL;
rc = vtc_retrieve_message(pvci, Col1, &outvalue);
//
vtc_free(outvalue);
//

vtc_free_list

Miscellaneous

Frees an array of strings created by RAW VTS functions.

(Raw)
(LR)

Void vtc_free_list (

char

**msglist)

<None>

Parameters:
Msglist

The name of the array of strings created by Raw VTS functions.

Remarks:
Examples:

<Raw Sample>
//
int
char
char

rc = 0;
delimiter = '$';
**outvalues = NULL;

rc = vtc_retrieve_messages1(pvci, Col1;Col2, ;, &outvalues);

//
vtc_free_list(outvalues);
//