System Requirements

VTS 2

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 OS’s maximum limit on process memory (ie. 2GB - 3GB). It has been tested for 1 million entries per row, however the VTS’s 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 > [ -delimiter <tab|colon|semicolon|comma|???> ]

(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

/

Operation Description

Insert data element

/ Inserts ‘Operation Data’ into the column specified by ‘Column Name.’
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.

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.

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 Microsoft’s OLEDB or ADODB manuals (http://msdn.microsoft.com).

Database Import Examples

Flights

1)  Install Flights Database Application

2)  Startup the Quadbase Server

3)  Start Menu à Settings à Control Panel à Data Sources (ODBC) <WinNT>

4)  Make sure flight32lr is listed in the DSN

5)  Start vtconsole

6)  Options à Import Data

7)  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
vtc_disconnect
vtc_get_last_error / lrvtc_connect
lrvtc_disconnect

Queries

vtc_query_column
vtc_query_row / lrvtc_query_column
lrvtc_query_row

Submissions

vtc_send_message
vtc_send_if_unique
vtc_send_row1 / lrvtc_send_message
lrvtc_send_if_unique
lrvtc_send_row1

Updates

vtc_update_message
vtc_update_row1
vtc_increment
vtc_clear_message
vtc_clear_column
vtc_clear_row / lrvtc_update_message
lrvtc_update_row1
lrvtc_increment
lrvtc_clear_message
lrvtc_clear_column
lrvtc_clear_row

Retrievals

vtc_retrieve_message
vtc_retrieve_messages1
vtc_retrieve_row / lrvtc_retrieve_message
lrvtc_retrieve_messages1
lrvtc_retrieve_row

Miscellaneous

vtc_create_column
vtc_column_size
vtc_free
vtc_free_list
vtc_noop / 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) / PVCI vtc_connect( char *servername,
Int portnum,
Int options)
(LR) / PVCI lrvtc_connect( char *servername,
Int portnum,
Int 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) / VTCERR vtc_disconnect( PVCI pvci)
(LR) / VTCERR lrvtc_disconnect()
Parameters:
pvci / -  VTS Connection Handle
Examples: / <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) / VTCERR vtc_get_last_error(PVCI pvci)
(LR) / <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) / VTCERR vtc_query_column( PVCI pvci,
char *columnName,
int columnIndex,
char **outvalue)
(LR) / VTCERR lrvtc_query_column( char *columnName,
int 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) / VTCERR vtc_query_row( PVCI pvci,
Int columnIndex,
char ***outcolumns,
char ***outvalues)
(LR) / 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 rc = 0;
char **colnames = NULL;
char **rowdata = 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) / VTCERR vtc_send_message( PVCI pvci,
char *columnName,
char *message,
unsigned short *outRc)
(LR) / VTCERR lrvtc_send_message( char *columnName,
Char *message)
Parameters:
pvci
columnName
message
outRc / -  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) / VTCERR vtc_send_if_unique( PVCI pvci,
char *columnName,
char *message,
unsigned short *outRc)
(LR) / VTCERR lrvtc_send_if_unique( char *columnName,
char *message)
Parameters:
pvci
columnName
message
outRc / -  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) / VTCERR vtc_send_row1( PVCI pvci,
char *columnNames,
char *messages,
char *delimiter,
unsigned char sendflag,
unsigned short *outUpdates)
(LR) / 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, "Name;Password", "John;LetMeIn",
";", VTSEND_SAME_ROW, &status);
// …
<LR Sample>
int rc = 0;
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) / VTCERR vtc_update_message( PVCI pvci,
char *columnName,
int index ,
char *message,
unsigned short *outRc)
(LR) / VTCERR lrvtc_update_message( char *columnName,
int index ,
char *message)
Parameters:
pvci
columnName
index
message
outRc / -  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_row1 Updates
Update row data on the VTS at a Column Index.
(Raw) / VTCERR vtc_update_row1( PVCI pvci,
char *columnNames,
int index ,
char *messages,
char *delimiter,
unsigned short *outUpdates)
(LR) / VTCERR lrvtc_update_row1( char *columnNames,
int index ,
char *messages,
char *delimiter)
Parameters:
pvci
columnNames
index
messages
delimeter
outUpdates / -  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-OR-253;10",";",&status);
// …
<LR Sample>
int rc = 0;
rc = lrvtc_update_row1("OrderNumber;Quantity",4321,"8293-OR-253;10",";");
//…
vtc_increment Updates
Increments a counter at a specified column and index and returns the new number.