TruClient functions

The below functions can be used in every field in TruClient that can evaluate JavaScript, such as in Step arguments, Objects, and descriptor fields.

Note:  

  • Use escape backslashes in path arguments. For example, c:\\temp\\myFile.ps1.

  • Support for using synchronous APIs in JavaScript code will soon be deprecated in TruClient and we recommend using Generic API Action steps instead. Click here for the full list of synchronous APIs.

Vuser
Browser
VTS
Environment

Tip: The following arguments can be used with any method:

  • object. The step's object as defined in the application.

  • AUT.window. Points to the global window object within the active window or tab of the application. Note that AUT.window.location cannot be used with Internet Explorer. Use AUT.document.URL instead.

  • AUT.document. The global document object within the active window or tab of the application.

The AUT API provides a common mechanism for handing the AUT window and AUT document for all TruClient protocols. For details, see Using JavaScript in the AUT window.

 

IO.createDir(path)

Creates the specified folder. If needed, creates all the folders necessary to complete the path.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

path. The absolute path of the folder (string).

Return value (void)

undefined

Example

IO.createDir(TC.outputDir + "mydir");

Back to top

IO.delete(path)

Deletes the specified folder or file. If a folder is specified, deletes all the files in the folder, including sub-directories.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

path. The absolute path of the folder or file (string).

Return value (void)

undefined

Example

IO.delete(TC.outputDir + "mydir") 

Back to top

IO.isExist(path)

Returns true if the specified folder or file exists, and false if it does not, or for a disconnected or unauthenticated mapped drive.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

path. The absolute path of the folder or file (string).

Return value (boolean)

True if file exists, and false if it does not.

Example

IO.is Exist(TC.outputDir + "mydir")

Back to top

IO.read(filename, charset)

Returns all the data from the specified file. Converts the data from the specified charset to unicode.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

filename. The absolute path of the file (string).

charset. The charset of the file, if it is not UTF-8 (string).

Return value (string)

All the data from the specified file.

Example

var log = IO.read(TC.scriptDir + "mylog.txt");
TC.log(log);

Back to top

IO.write(filename, input, append, charset)

Writes the string to the specified file. If the file does not exist it is created.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

filename. The absolute path to the file (string).

input. The string to write to the file (string).

append. (boolean)

  • true. Append the string to the end of the file (default).
  • false. Overwrite the file with the string.

charset. The charset of the file, if it is not UTF-8 (string).

Return value (boolean)

Always returns true.

Example

IO.write(TC.scriptDir + "mylog.txt", "first msg\n", false);

IO.write(TC.scriptDir + "mylog.txt", "second msg");

The result content in the mylog.txt file:

first msg

second msg

Back to top

TC.addNetworkFilter(filters, include, applyTo)

Adds a filter for URL requests.

Note:  

  • Relevant only for steps that have a network-related end event, or that do not have any end event.

  • Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

filters. Filter representing one or more URLs (string). Separate multiple URLs with a semi-colon (;). The URL can have the wildcard (*) which can match 0 or more characters.

include. True to include URL requests that match the filter; otherwise false (default). Optional argument (boolean) .

applyTo. (Optional argument) Specify the type of request the filter applies to:

  • Xhr. Filters XHR requests only.

  • NonXhr. Filters non-XHR requests only.

  • All. Filters all requests (default).

Note: You cannot use exclude and include filters at the same time.

Return value (void)

undefined

Example:

TC.addNetworkFilter("http://www.myco.com/*", true, "All")

From the point that you add this API call, until you call the remove filter or the end of the iteration, TruClient will not wait for requests to get a response unless the URL has a http://www.myco.com/ prefix.

Back to top

TC.clearNetworkFilters()

Removes all URL request filters.

Note:  

  • Relevant only for steps that have a network-related end event, or that do not have any end event.

    • Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

None

Back to top

TC.startLogRequests()

Starts logging URL requests.

Note:  

  • Relevant only for steps that have a Step completed or Step synchronous network completed end event, or that do not have any end event.

  • Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

None

Back to top

TC.stopLogRequests()

Stops logging URL requests.

Note:  

  • Relevant only for steps that have a Step completed or Step synchronous network completed end event, or that do not have any end event.

  • Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

None

Back to top

TC.advanceParam(name)

Advances the specified parameter to the next value in the file. This must be a parameter of type file or unique number; this is the argument type set in VuGen.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

name. The name of the parameter to advance (string) .

Return value (void)

undefined

Example

TC.advanceParam("multi_row_param");

Back to top

TC.getAttr(name)

Returns the value of the command line parameter passed to the test or the default value set for it.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

name. The name of the command-line parameter (string).

The command-line parameter name is generally assigned by the user in the Additional Attributes tab in VuGen > Runtime Settings or in the Controller in the group command line argument.

When the test is run, the additional attribute or the group command line argument is passed to the test as a parameter in the command line. During test run, the value can be accessed with this function.

Return value (string)

Returns the value of the command line parameter passed to the test or the default value set for it.

Example

To get the Controller command line argument, -MyServerURL http://myserver.com, call:

TC.getAttr(“MyServerURL”);

Back to top

TC.getUserIP()

Returns the IP address when IP spoofing is enabled and the script is running in load mode in Controller.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (string)

Returns the IP address when IP spoofing is enabled and the script is running in load mode in Controller.

Example

None

Back to top

TC.setParam(name, value)

Saves a string to a parameter, creating a temporary parameter value in the memory if it does not exist (it does not create a parameter that can be read in the next run).

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

name. The name of the parameter in which to save the value (string).

value. The parameter value (string).

Note: Only alphanumeric and the underscore character ("_") are supported.

Return value (void)

undefined

Example

TC.setParam("myparam", "paramVal");

Back to top

TC.crossTransactionStart(name, identifier)

Begins a transaction in a Vuser script that will be ended in another Vuser script.

Arguments

name. The name of the transaction (string).

identifier. The identifier of the transaction (string). The same value is used by TC.crossTransactionEnd(name, identifier, type) to identify the transaction.

Return value (void)

undefined

Example

None

Back to top

TC.outputMessage(text)

Same as TC.log at the Standard log level with the additional ability to show the message in the Controller's Output window as a notification.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

text. The message text (string).

Return value (void)

undefined

Example

TC.outputMessage("My output message");

Back to top

TC.crossTransactionEnd(name, identifier, type)

Ends a transaction in a Vuser script that has been started in another Vuser script.

Arguments

name. The name of the transaction (string).

identifier. The identifier of the transaction (string). The value of the parameter must be identical to the value of the identifier param that the Vuser initiating the transaction used in TC.crossTransactionStart(name, identifier).

type. One of the following: "Pass", "Fail", "Auto", "Abort", or "Stop".

Return value (void)

undefined

Example

None

Back to top

TC.transactionDuration(name)

Returns the duration of a specific transaction, in seconds.

Note: This API must be used within the scope of the transaction.

Arguments

name. The name of the transaction (string).

Return value (string)

Returns the duration of a specific transaction, in seconds.

Example

None

Back to top

TC.getParam(name)

Returns the value of the specified parameter.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

name. The parameter name (string).

Return value (string)

Returns the value of the specified parameter.

Example

Note: You can also use parameters in the Step Arguments section of a TruClient script. For details, see Use parameters to vary arguments.

Back to top

TC.evalC(funcname, functimeout)

Runs a specific function in C language, defined in the C-functions.c file.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

funcname. The function name (string).

Note: Use the #include command to include the file where the function is defined.

functimeout. The maximum expected runtime, in seconds, of the function called by the step (number) .

Return value (void)

undefined

Example

TC.evalC("myFunc", 20);

Back to top

TC.log(text, level)

Logs a message as a line in TruClient ’s interactive/load log.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

text. The message (string).

level. Optional argument. One of the following:

  • "Error"
  • "Warning"
  • "Standard" (default)
  • "Extended"
  • "Status" - sends a string to the Status area of the Controller. It also sends the string to the Vuser log. When run from VuGen, the message is sent to output.txt.
  • "Status_msg"

Return value (void)

undefined

Example

TC.log("my warning", "Warning");

Back to top

TC.unmask(text)

Returns the text after unmasking.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

text. The masked text (string).

Return value (string)

Returns the text after unmasking.

Example

TC.unmask(str);

Back to top

TC.userDataPoint(name, value)

Records a user-defined data point for analysis.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

name. The name of the data point (string). Do not begin a data-point name with any of these strings: HTTP, NON_HTTP, RETRY, mic_, stream_, mms_

value. The numeric value (number).

Return value (void)

undefined

Example

TC.userDataPoint("myDP", 1);

Back to top

evalXPath(xpath)

Returns an array of the objects defined by the XPath in the argument.

Arguments

xpath. The xpath query (string).

Return value (void)

undefined

Example

evalXPath("//a[text()=\" New Mercury Tours \"]");

Back to top

TC.startTransaction(name)

Starts a LoadRunner transaction.

Arguments

name. (String) The name of the transaction to start.

Return value (void)

undefined

Example

TC.startTransaction("login_tr1");

Back to top

TC.endTransaction(name, type)

Ends a LoadRunner transaction.

Arguments

name. The name of the transaction to end (string).

type. One of the following status values: “Pass”, “Fail”, “Auto”

Return value (void)

undefined

Example

TC.endTransaction("login_tr1", status);

Back to top

TC.vuserStatusMessage(text)

Indicates which Vuser is handling a specific script.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

text. Any text string (string).

Return value (void)

Undefined.

Example

TC.vuserStatusMessage("FlightStatus");

Back to top

Utils.clearCookies()

Removes all cookies currently stored by the Vuser.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

None

Back to top

Utils.clearCache()

Clears the cache of a single Vuser; the content of the whole cache simulator is unaffected.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

None

Back to top

Utils.getEnv(name)

Returns the value of the specified environment variable. Returns an empty string if the specified variable does not exist.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

name. The name of the environment variable (string).

Return value (string)

Value of the specified environment variable. Returns an empty string if the specified variable does not exist.

Example

var path = Utils.getEnv("PATH");

Back to top

Utils.import(filename)

Evaluates the specified JavaScript file in the arguments context.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

filename. The absolute path to the JavaScript file (string).

Return value (void)

undefined

Example

Utils.import(TC.scriptDir + "myjs.js");

Back to top

Utils.isEnvExists(name)

Returns true if the specified environment variable exists and false if it does not exist.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

name. The name of the environment variable (string).

Return value (boolean)

True if the specified environment variable exists, and false if it does not exist.

Example

Utils.isEnvExists("PATH"); // returns true
Utils.isEnvExists("TC_kukuku"); // returns false

Back to top

Utils.setEnv(name, value)

Sets the named environment variable to the specified value. If the variable already has a value it is overwritten.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

name. The name of the environment variable (string).

value. The value to which to set the environment variable (string).

Return value (void)

undefined

Example

Utils.setEnv("PATH", "C:\\loadrunner\\");

Back to top

Utils.addAutoFilter(url, isIncluded)

Adding a filter to one of the black list or white list lists of URLs. The URL of each HTTP request will be checked first against the black list, and then the white list. HTTP requests that do not pass the check will be blocked.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

url. String or regular expression representing the URL (string).

isIncluded. True to add the URL to white list, or false to add the URL to black list (boolean).

Return value (void)

undefined

Example

Set only the allowed domain on the white list. All other domains are blocked.

String example:

Utils.addAutoFilter("http://www.myco.com/*", true);

Regular expression example:

Utils.addAutoFilter(/^http:\/\/www\.myco\.com\/.*/, true);

Back to top

Utils.cleanupAutoFilters()

Remove all filters from both the black list and white list lists of URLs.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

Utils.cleanupAutoFilters();

Back to top

Utils.addAutoHeader(header, value, merge)

Adding an HTTP header to every consecutive HTTP requests following this function call.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

header. The name of the header to be added (string).

value. The value of the header to be added (string).

merge. "True" indicates to merge the value with an existing header by the same name; "false" indicates to overwrite it (boolean).

Note: Merge does not support modifying the following headers: "content-type", "content-disposition", "content-length", "user-agent", "referer", "host", "authorization", "proxy-authorization", "if-modified-since", "if-unmodified-since", "from", "location", "max-forwards"

Return value (void)

undefined

Example

Utils.addAutoHeader("someCustomHeader", "someValue", true);

Back to top

Utils.cleanupAutoHeaders()

Removes all HTTP headers and stops adding HTTP headers to every consecutive HTTP request following this function call.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

None

Return value (void)

undefined

Example

Utils.cleanupAutoHeaders();

Back to top

Utils.removeAutoHeader(header)

Removes an HTTP header added with Utils.addAutoHeader and stops adding this HTTP header to every consecutive HTTP request following this function call.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

header. The name of the header to be stopped from being added.

Return value (void)

undefined

Example

Utils.removeAutoHeader("someCustomHeader");

Back to top

Utils.removeAutoFilter(filter, isInclude)

Remove a filter that was added using Utils.addAutoFilter from the black list or white list of URLs.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

filter. String representing the URL.

isInclude. True value indicates the white list, false otherwise.

Remarks

Use the exact same filter URL value that was added to the list.

Return value (void)

undefined

Example

Utils.removeAutoFilter("http://www.myco.com/*", true);

Back to top

TC.setProxy(option, settings)

Enables you to set a proxy address manually in the script.

Arguments

option. Specify the type of proxy you want to use.

  • "PROXY_NONE". No proxy
  • "PROXY_SYSTEM". Use system proxy; settingsString will be ignored.
  • "PROXY_MANUAL". Manually set proxy.
  • "PROXY_PAC". Use a proxy auto-config (PAC) file.

settings. The details of the proxy setting (string).

Return value (void)

undefined

Example

  • Use system proxy settings. The second argument is ignored, so it can be any string value, usually empty.

    Note: Because schema needs two arguments, the second one cannot be omitted.

    TC.setProxy("PROXY_SYSTEM", "");

  • Manually set proxy and set separate proxy for different protocols (http & https)

    TC.setProxy("PROXY_MANUAL", '{"proxyShare":false,"proxyHttp":" proxy.xxx.com ","proxyHttpPort":8080,"proxySsl":" proxy.yyy.com ","proxySslPort":8080}');

  • Manually set proxy and share the proxy settings for all protocols (http, https, …)

    Note: If you also specify an address for “proxySsl”, it will be ignored because “proxyShare” is set to true.

    TC.setProxy("PROXY_MANUAL", '{"proxyShare":true,"proxyHttp":"proxy.xxx.com","proxyHttpPort":8080}');

  • Use manually set proxy which is already in memory (maybe set previously, maybe nothing is set).

    Note: If you are not sure which setting is in memory, it is recommended that you explicitly specify the proxy settings you want to use every time.

    TC.setProxy("PROXY_MANUAL ", "");

  • Do not use any proxy.

    Note: The proxy address/port that are set in the options sections are not removed. The settings in memory can be activated in another call (refer to the next example).

    TC.setProxy("PROXY_NONE", "");

  • Use PAC.

    TC.setProxy("PROXY_PAC",'{"proxyPAC":"http://autocache.xyzcorp.net/"}')

Back to top

TC.setLogLevel(level, log_flags)

Enables you to change the log level during script replay. To restore initial log level setting, use TC.restoreLogLevel.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

level. Specify the log level:

  • "Disabled". Disables the log level. It still captures a log including the error level.
  • "Standard". Standard log captured.
  • "Extended". Extended log file captured.

log_flags. (Object) If the log level is set to extended, you can specify which data is captured using Boolean(true/false) flags as properties of json_object.

Any flag which is omitted will be considered as “false”.

  • log_http
  • log_AUT
  • log_parameters

Return value (void)

undefined

Example

  • Disable the log level:

    TC.setLogLevel(“Set the log level to “Disabled”);

  • Enable the standard log:

    TC.setLogLevel(“Standard”);

  • Enable the extended log:

    TC.setLogLevel(“Extended”);

  • Enable the extended log, and specify which logs to capture:

    TC.setLogLevel(“Extended”,{ log_http : true, log_AUT: true, log_parameters: true});

Back to top

TC.restoreLogLevel()

Restore log level to the initial setting.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using the Evaluate C step instead.

Arguments

None

Return value (void)

undefined

Example

TC.restoreLogLevel();

Back to top

TC.vtcAddCell(colName, value, vtsName)

Adds a new cell as the last field of a column to a value.

Equivalent method in LoadRunner: lrvtc_send_message

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

value. The value as a string (string).

vtsName. The alias of the VTS server (string).

Remarks

If the column specified in the argument does not exist, the column will be created and the cell content is set to the argument value.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcAddCell("MyColumn","myValue","MyVts");

Back to top

TC.vtcAddCells(colNames, values, option, vtsName)

Sets the data in multiple columns.

Equivalent method in LoadRunner: lrvtc_send_row1

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colNames. The column names delimited by a semi-colon (string).

values. The values as a string delimited by a semi-colon (string).

option. Define how the values are added (integer).

  • 0. Add as same row in all columns based on the column with the highest row count. The created row will be n+1 for all columns.
  • 1. Add as stack - last row in every column.
  • 2. Add as unique stack - last row in every column only if the value is unique in the column.

vtsName. The alias of the VTS server (string).

Remarks

If the columns specified in the argument do not exist, the columns will be created and the cell contents are set to the argument values.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcAddCells( "MyColumn1;MyColumn2;MyColumn2", "MyValue1;MyValue2;MyValue3", 0, "MyVts");

Back to top

TC.vtcAddUniqueCell(colName, value, vtsName)

Sets the last field of a column to a value if the value does not exist in the column.

Equivalent method in LoadRunner: lrvtc_send_if_unique

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

value. The value (string).

vtsName. The alias of the VTS server (string).

Remarks

If the column specified in the argument does not exist, the column will be created and the cell content is set to the argument value.

Return value (boolean)

True if the value exists in the column, and false if the value does not.

Example

TC.vtcAddUniqueCel("MyColumn",1,"MyVts");

Back to top

TC.vtcClearColumn(colName, vtsName)

Clears all data in a column.

Equivalent method in LoadRunner: lrvtc_clear_column

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string).

Remarks

If the column specified in the argument does not exist, the step will run without returning an error and no data in the VTS is changed.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcClearColumn("MyColumn","MyVts");

Back to top

TC.vtcClearCell(colName, rowIndex, vtsName)

Clears the data in a field.

Equivalent method in LoadRunner: lrvtc_clear_message

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

vtsName. The alias of the VTS server (string).

Remarks

If the column or the row index specified in the argument does not exist, the step will run without returning an error and no data in the VTS will be changed.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcClearCell("MyColumn",1,"MyVts");

Back to top

TC.vtcClearRow(rowIndex, vtsName)

Clears the values from all fields in a row.

Equivalent method in LoadRunner: lrvtc_clear_row

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

rowIndex. The index number of the field (integer). 1 is the first field in the column.

VtsName. The alias of the VTS server (string).

Remarks

If the row index specified in the argument does not exist, the step will run without returning an error and no data will be changed in the VTS.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcClearRow(1,"MyVts");

Back to top

TC.vtcCreateColumn(colName, vtsName)

Creates a column.

Equivalent method in LoadRunner: lrvtc_create_column

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

VtsName. The alias of the VTS server (string).

Remarks

If a column of the same name already exists, the function does nothing.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcCreateColumn("MyColumn","MyVTS")

Back to top

TC.vtcColumnSize(colName, vtsName)

Returns the number of fields that contain data in a column.

Equivalent method in LoadRunner: lrvtc_column_size

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string).

Return value (number)

Returns the number of fields in the column, or 0 if the column does not exist.

Example

TC.vtcColumnSize("MyColumn","MyVts");

Back to top

TC.vtcConnect(serverName, port, vtsName)

Creates a connection to the server (supports HTTP).

Equivalent method in LoadRunner: lrvtc_connect

Note:  

  • To connect using HTTPS, basic or NTLM authentication, use TC.vtcConnectEx.

  • Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

serverName. Either the IP or server name (string).

port. The port number (integer).

vtsName. The alias of the VTS server (string).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcConnect("MyServer", 8888, "MyVts");

Back to top

TC.vtcConnectEx(serverName, port, userName, password, domain, vtsName)

Creates a connection to the server (supports HTTP, HTTPS version VTS server, basic authentication based on user name and password entered by the user, and NTLM authentication).

Equivalent method in LoadRunner: lrvtc_connect_ex

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

serverName. Either the IP or server domain name (string). The protocol can be omitted; the default protocol is “https://”.

port. The port number (integer). The available range is 1-65535.

userName. The user name for basic or NTLM authentication (string, optional).

password. The password for basic or NTLM authentication (string, optional).

domain. The domain name for NTLM authentication (string, optional).

vtsName. The name of the VTS connection (string, optional).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcConnectEx("MyServer", 8888, "MyUser", "MyPW", "MyDomain", "MyVts");

Back to top

TC.vtcDisconnect(vtsName)

Disconnects from the server.

Equivalent method in LoadRunner: lrvtc_disconnect

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

vtsName. The alias of the VTS server (string).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcDisconnect( "MyVts");

Back to top

TC.vtcDropIndex(colName, vtsName)

Deletes the index on a column.

Equivalent method in LoadRunner: lrvtc_drop_index

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The column name (string).

vtsName. The alias of the VTS server (string).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcDropIndxe("MyColumn","MyVts");

Back to top

TC.vtcEnsureIndex(colName, vtsName)

Creates an index on a column.

Equivalent method in LoadRunner: lrvct_ensure_index

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcEnsureIndex("MyColumn","MyVts");

Back to top

TC.vtcIncrement(colName, rowIndex, value, vtsName)

Increments a counter stored in a field.

Equivalent method in LoadRunner: lrvtc_increment

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

value. The value.

vtsName. The alias of the VTS server (string).

Remarks

If the column name specified in the argument does not exist, the column will be created and the cell referenced by the index will be set to the argument value.

If the index specified in the argument exceeds the column size, the cell is created by the specified index and the cell contents is set to the argument value.

If the column referenced by the index contains a string, the cell contents are replaced with the value argument.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcIncrement("MyColumn",1,1,"MyVTS");

Back to top

TC.vtcGetCell(colName, rowIndex, vtsName)

Returns the data in a field.

Equivalent method in LoadRunner: lrvtc_query_column

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

vtsName. The alias of the VTS server (string).

Return value (string or undefined or null)

String if data exist in the column and row specified. Undefined if specified index does not exist. Null if specified column does not exist.

Example

TC.vtcGetCell("MyColumn",1,"MyVts");

Back to top

TC.vtcGetRowCells(rowIndex, vtsName)

Returns the data in a row as a JavaScript object. The properties of the object will be set to the column names

Equivalent method in LoadRunner: lrvtc_query_row

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

rowIndex. The index number of the field (integer). 1 is the first field in the column.

vtsName. The alias of the VTS server (string).

Remarks

If the column specified in the argument does not exist, a null value will be returned for every column.

Return value (object)

Returns the field from the specified index in all columns. If the column does not have a value in the specified index, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TC.vtcGetRowCells(1,"MyVTS");

Back to top

TC.vtcPopCell(colName, vtsName)

Pops the first field from a column.

Equivalent method in LoadRunner: lrvtc_retrieve_message

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string).

Return value (string or null)

The value of the first index in the column row. Returns null if the column is empty or does not exist.

Example

TC.vtcPopCell("MyColumn","MyVts");

Back to top

TC.vtcPopCells(vtsName)

Pops the data in a row as a JavaScript object.

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

vtsName. The alias of the VTS server (string).

Return value (object)

Returns the first field from the columns. If the column is empty, the value is null. Example: {col1:”larry”,col2:null}

Example

TC.vtcPopCells( "MyVts");

Back to top

TC.vtcPopMultipleCells(colNames, vtsName)

Pops the first fields from specified columns. Returned as a JavaScript object. The properties of the object will be set to the column names.

Equivalent method in LoadRunner: lrvtc_retrieve_messages1

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colNames. The names of the columns (string).

vtsName. The alias of the VTS server (string).

Return value (object)

Returns the first field from the specified columns. If the column is empty, the value is null. Example: {col1:”larry”,col2:null}

Example

TC.vtcPopMultipleCells("MyColumn","MyVts");

Back to top

TC.vtcRotateCells(option, vtsName)

Retrieves the first field from all columns and moves the values to the bottom.

Equivalent method in LoadRunner: lrvtc_rotate_row

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

option. Define how the values are rotated (integer).

  • 0. Same row – Retrieve data from all columns and move it to the bottom for all columns, based on the column with the highest row count. The created row will be n+1 for all columns.
  • 1. Add as stack - Retrieve data from all columns and move it to the bottom to the last valid row of every column.
  • 2. Add as unique stack - Retrieve data from all columns and move it to the bottom to the last valid row of every column only if the data is unique.

vtsName. The alias of the VTS server (string).

Remarks

If there is no data in a row, null value will be retrieved.

Return value (object)

Returns the first field from the columns. If column is empty, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TC.vtcRotateCells (0, "MyVts");

Back to top

TC.vtcRotateCell(colName, option, vtsName)

Retrieves the first field from the specified column and moves the values to the bottom.

Equivalent method in LoadRunner: lrvtc_rotate_messages

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

option. Define how the values are rotated (integer).

  • 1. Add as stack - Retrieve data from column, and move it to the bottom to the last valid row of every column.

  • 2. Add as unique stack - Retrieve data from column, and move it to the bottom to the last valid row if the data is unique.

vtsName. The alias of the VTS server (string).

Remarks

If the column name does not exist, null value will be retrieved.

Return value (object)

Returns the first field from the specified column. If the column is empty, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TC.vtcRotateCell("MyColumn1", 0, "MyVts");

Back to top

TC.vtcUpdateAllMessageIfequals(colNames, Message, Ifmessage, Delimiter)

Replaces a specific value inside a set of columns with a new value.

Equivalent method in LoadRunner: lrvtc_update_all_message_ifequals

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

ColNames. The column names delimited by a semi-colon (string).

Message. New value inside a set of columns (string).

Ifmessage. Original value inside a set of columns (string).

Delimiter. Delimiter to separate column names. By default, the separator value is a semi-colon (;).

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcUpdateAllMessageIfequals("MyColumn1;MyColumn2;MyColumn3", "NewVal1;NewVal2;NewVal3", "OldVal1;OldVal2;OldVal3");

Back to top

TC.vtcRotateMultipleCells(colNames, option, vtsName)

Retrieves the first field from the specified columns and moves the values to the bottom.

Equivalent method in LoadRunner: lrvtc_rotate_messages1

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

ColNames. The column names delimited by a semi-colon (string).

option. Define how the values are rotated (integer).

  • 0. Same row – Retrieve data from all columns and move it to the bottom for all columns based on the column with the highest row count. The created row will be n+1 for all columns.

  • 1. Add as stack - Retrieve data from all columns, and move it to the bottom to the last valid row of every column.

  • 2. Add as unique stack - Retrieve data from all columns, and move it to the bottom to the last valid row of every column if the data is unique.

vtsName. The alias of the VTS server (string).

Remarks

If the column name does not exist, null value will be retrieved.

Return value (object)

Returns the first field from the specified columns. If the column is empty, the value will be an empty string. Example: {col1:”larry”,col2:””}

Example

TC.vtcRotateMultipleCells("MyColumn1;MyColumn2;MyColumn2", 0, "MyVts");

Back to top

TC.vtcUpdateRowCells(colNames, rowIndex, values, vtsName)

Replaces the data in multiple fields.

Equivalent method in LoadRunner: lrvtc_update_row1

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

ColNames. The column names delimited by a semi-colon (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

values. The values as a string delimited by a semi-colon (string).

vtsName. The alias of the VTS server (string).

Remarks

If the column name or index does not exist, the column and/or the cell referenced by the index will be created, and the cell contents set to the argument value.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcUpdateRowCells("MyColumn1;MyColumn2;MyColumn2", 0, "MyNewValue1;MyNewValue2;MyNewValue3", "MyVts");

Back to top

TC.vtcUpdateCell(colName, rowIndex, value, vtsName)

Replaces the data in a field.

Equivalent method in LoadRunner: lrvtc_update_message

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

value. The value (string).

vtsName. The alias of the VTS server (string).

Remarks

If the column name or index does not exist, the column and/or the cell referenced by the index will be created and the cell contents set to the argument value.

Return value (number)

0 if completed successfully; on error returns undefined.

Example

TC.vtcUpdateCell("MyColumn",1,"MyValue","MyVTS");

Back to top

TC.vtcUpdateEqualsCell(colName, rowIndex, value, comparedValue, vtsName)

Replaces the data in a field if the current data equals a given value.

Equivalent method in LoadRunner: lrvtc_update_message_ifequals

Note: Support for using this API in JavaScript code will soon be deprecated in TruClient. We recommend using Generic API Action steps instead.

Arguments

colName. The name of the column (string).

rowIndex. The index number of the field (integer). 1 is the first field in the column.

value. The replacement value (string).

comparedValue. If the current cell contents are the same as the comparedValue, the cell contents are replaced with value (string).

vtsName. The alias of the VTS server (string).

Return value (boolean)

False if a field with the same value exists; true if there is no field with the same value in the column.

Example

TC.vtcUpdateEqualsCell("MyColumn",1,"MyValue","MyCompareValue",MyVTS");

Back to top

See also: